The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.
JavaScript
Split the files that had outgrown a single reading (#56)
OsintMeThat6f57bafcde9c
diff --git a/docs/ONTOLOGY.md b/docs/ONTOLOGY.mdindex 0f8bce9..6f324e5 100644--- a/docs/ONTOLOGY.md+++ b/docs/ONTOLOGY.md@@ -242,7 +242,7 @@ once.**The declared `text`, `longtext` and `url` fields are what a case search matcheson**, beside the label, the type, the folder and the notes — a vehicle is looked forby its plate. Numbers, shapes and stored grades stay out of the index. One predicate-serves both sides: `sqlite_backend._entity_search_text` for the server,+serves both sides: `store/rows.py::_entity_search_text` for the server,`lib/entitySearch.js` for the lists that filter a small case in memory.### When the case already holds the value ✅diff --git a/docs/SPEC.md b/docs/SPEC.mdindex 9e03f71..c8d47f4 100644--- a/docs/SPEC.md+++ b/docs/SPEC.md@@ -160,8 +160,9 @@ Each version delivers one complete daily workflow. Firm ideas move here from| Tool | What it does ||------|--------------|| **Case Sheet** | Adds editable free columns and CSV/GeoJSON round trips to the shipped Board. Imported loose rows stay outside the graph until promoted. |-| **Camera Resection (GCP)** | Marks matching points photo↔map, then solves camera position, viewing azimuth and rough FOV (OpenCV `solvePnP`) and saves the match as evidence. Its photo canvas and pixel↔angle camera frame are built for two callers: Sky Clock fills the same frame by hand. || **Command palette** | Ctrl+K reaches a tool, a case or an artifact. |+| **Saved view management** | Renames and sorts Board, Graph and Timeline views, with their surface and last modification clearly shown. |+| **Analysis view export** | Copies or exports the visible Graph or Timeline as a PNG with its lens, question, time window, clock and legend. |Toward v2: split Satellite.svelte into `lib/` modules, before the map enginechanges under it.@@ -172,6 +173,7 @@ changes under it.|------|--------------|| **Map engine (MapLibre)** | Replaces Leaflet with MapLibre GL at 2D parity: same providers, same captures, and the capture tests still verify the pixels. Ships before the 3D map, which builds on it. || **3D map** | Pitch, public DEM terrain and extruded OSM buildings on the MapLibre map. An oblique capture records its pitch beside the bearing, so the view can be reproduced. |+| **Camera Resection (GCP)** | Marks matching points photo↔map, then solves camera position, viewing azimuth and rough FOV (OpenCV `solvePnP`) and saves the match as evidence. Its photo canvas and pixel↔angle camera frame are built for two callers: Sky Clock fills the same frame by hand. || **Capture scale and north** | Preference-controlled scale bar, north arrow and graticule on app and extension captures. Follows the map engine, which redraws what a capture is made of. || **Footprint tracing** | Draws a place's uncertainty as the shape it really is, for a quay, a treeline or an L-shaped block the circle describes badly. The field, its validation and its drawing already ship; only the gesture is missing, and it follows the map engine rather than being written twice. || **Satellite Compare** | Same coords across providers (Esri / Sentinel-2 date slider / Bing / keyed), synced pan/zoom. Copernicus easy link. |@@ -273,6 +275,7 @@ stops making sense.- **Count a statement's independence by origin, not by wrapper:** three collages made from one video are three sources today, and are arguably one. The graph already answers this for a place; changing it for a statement changes a published number.- **Free-form montage editor:** consider only if it stays distinct from Geo Proof and Inspect collage.- **In-app OSINT assistant:** local chat and vision suggestions for analyst confirmation, with no cloud or API key by default.+- **Guided companion:** a mark the analyst clicks for a legend of the open tool, covering what it is for and the controls whose icon does not say it. Clicking an entry points at the real button.- **Geographic playback:** step through dated case items on the map instead of showing one fixed Timeline window.## 8. Explicit non-goalsdiff --git a/docs/STORAGE_AND_PERFORMANCE.md b/docs/STORAGE_AND_PERFORMANCE.mdindex ddc78f1..538bcdb 100644--- a/docs/STORAGE_AND_PERFORMANCE.md+++ b/docs/STORAGE_AND_PERFORMANCE.md@@ -246,8 +246,18 @@ uses to read and mutate a case's graph, catalog and jobs. Nothing outside theimplementation reaches into a raw `case.json` shape. `workspace.Case` is thefilesystem shell (manifest, notes, media, lifecycle, path resolution) anddelegates every graph, catalog and job method to a `SqliteCase`-(`sqlite_backend.py`) over `case.db`. `engine/links.py` and `api/cases.py` read-through `get_entity` / `links_of` / `snapshot`, never the file.+(`sqlite_backend.py`) over `case.db`. That delegation is `casestore.CaseStore`,+mixed into `Case`: every method there forwards and does nothing else, so what+stays on `Case` is the half that also has a folder to keep in step. `engine/links.py`+and the `api/cases/` routers read through `get_entity` / `links_of` / `snapshot`,+never the file.++`sqlite_backend.py` owns the schema, the connection and `SqliteCase`. What that+class is built out of lives in `store/`, one module per concern: statement shaping+(`sql`), the predicates a case is narrowed by (`filters`), keyset cursors+(`cursors`), the denormalised columns a record is indexed on (`rows`), the derived+temporal projection (`temporal`) and the versioned schema upgrades (`migrations`).+The case-folder reshaping pass is `caselayout.py`, beside `workspace.py`.`snapshot()` returns the whole graph for delete planning, export, migration checksand test assertions.diff --git a/frontend/src/app.css b/frontend/src/app.cssindex b9dad70..e703aed 100644--- a/frontend/src/app.css+++ b/frontend/src/app.css@@ -595,3 +595,143 @@ a:hover {.markdown > :last-child {margin-bottom: 0;}++/* ============================================================+ Settings pane+ The layout vocabulary the Settings tabs are written in. Global rather than+ scoped because the tabs are seven components (`tools/settings/`) rendering+ into one pane, and seven copies of the same group/row/segmented-control+ rules would drift. Every selector is under `.settings-pane`, which only+ `Settings.svelte` puts on the page.+ ============================================================ */++.settings-pane .group {+ padding: 14px 0 18px;+ border-bottom: 1px solid var(--border);+}++.settings-pane .group:last-child {+ border-bottom: 0;+}++.settings-pane h3 {+ display: flex;+ align-items: center;+ gap: 7px;+ font-size: var(--fs-xs);+ font-weight: 700;+ text-transform: uppercase;+ letter-spacing: 0.06em;+ color: var(--text-3);+ margin-bottom: 12px;+}++.settings-pane .row {+ display: flex;+ align-items: center;+ justify-content: space-between;+ gap: 18px;+ margin-bottom: 8px;+}++.settings-pane .row-label {+ display: flex;+ flex-direction: column;+ gap: 2px;+ font-size: var(--fs-sm);+ color: var(--text-1);+}++.settings-pane .row-hint {+ color: var(--text-3);+ font-size: var(--fs-xs);+ line-height: 1.4;+}++.settings-pane .scraper-actions {+ display: flex;+ align-items: center;+ gap: 6px;+}++/* One-row segmented control. */+.settings-pane .seg {+ display: flex;+ flex-shrink: 0;+ border: 1px solid var(--border);+ border-radius: var(--r-md);+ overflow: hidden;+}++.settings-pane .seg-btn {+ padding: 5px 12px;+ border: 0;+ border-left: 1px solid var(--border);+ background: var(--bg-2);+ color: var(--text-2);+ font: inherit;+ font-size: var(--fs-xs);+ cursor: pointer;+ transition: background 0.12s var(--ease), color 0.12s var(--ease);+}++.settings-pane .seg-btn:first-child {+ border-left: 0;+}++.settings-pane .seg-btn:hover {+ background: var(--bg-3);+ color: var(--text-1);+}++.settings-pane .seg-btn.on {+ background: var(--accent);+ color: var(--accent-text);+ font-weight: 600;+}++.settings-pane .note {+ color: var(--text-3);+ font-size: var(--fs-xs);+ line-height: 1.5;+ margin-top: 8px;+}++.settings-pane .note.warn {+ color: var(--warn, #d8a03d);+}++/* same voice as .note, but leading a group instead of trailing one */+.settings-pane .intro {+ color: var(--text-3);+ font-size: var(--fs-xs);+ line-height: 1.5;+ margin: 0 0 14px;+}++.settings-pane .field {+ display: flex;+ flex-direction: column;+ gap: 4px;+ font-size: var(--fs-xs);+ color: var(--text-2);+ font-weight: 600;+}++.settings-pane .links {+ display: flex;+ gap: 8px;+ margin-top: 14px;+ flex-wrap: wrap;+}++.settings-pane .links .btn {+ gap: 6px;+ text-decoration: none;+}++.settings-pane .empty {+ color: var(--text-3);+ font-size: var(--fs-sm);+ font-style: italic;+}diff --git a/frontend/src/lib/graphArrangement.js b/frontend/src/lib/graphArrangement.jsnew file mode 100644index 0000000..a6d63c9--- /dev/null+++ b/frontend/src/lib/graphArrangement.js@@ -0,0 +1,56 @@+/**+ * Where the analyst put the nodes, as the undo stack has to see it.+ *+ * A pin is presentation, not a fact about the case: it says the analyst decided+ * this node belongs *there*, and the layout arranges everything else around it.+ * Two sources hold pins at once — the ones the server sent with the drawing, and+ * the ones a drag has moved but not filed yet — and the undo stack needs the one+ * merged answer. Getting that merge wrong is invisible until an undo silently+ * drops a node the analyst had placed, or resurrects one they let go of.+ *+ * `graph.js` already owns `arrangementDiff`, which turns two of these into the+ * pins to write and the pins to drop. This owns the reading side.+ */++/**+ * Every pin in the active arrangement, as a sorted list of `{ id, x, y }`.+ *+ * `held` is the set that is actually pinned right now, and it is the filter+ * rather than a hint: a node whose pin was dropped can still be sitting in either+ * source, and carrying it into a snapshot would put it back on the next undo.+ *+ * A named view retains its own off-screen pins, so when it owns the arrangement+ * the drawn nodes contribute nothing — the case-wide undo stays limited to what+ * is on screen, and a view's pins are not rewritten by an undo taken in it.+ */+export function mergedArrangement({ nodes = [], pins = [], held = [], fromView = false }) {+ const at = new Map();+ if (!fromView) {+ for (const node of nodes) {+ if (Array.isArray(node?.pin)) at.set(node.id, { x: node.pin[0], y: node.pin[1] });+ }+ }+ for (const [id, spot] of pins) at.set(id, { x: spot.x, y: spot.y });+ const keep = new Set(held);+ return [...at.entries()]+ .filter(([id]) => keep.has(id))+ .map(([id, spot]) => ({ id, x: spot.x, y: spot.y }));+}++/**+ * The pins a snapshot can be trusted with, as a Map.+ *+ * A snapshot is JSON that has been round-tripped through the history stack and,+ * for a saved view, through the server and back. A spot with a missing id or a+ * coordinate that is not finite would place a node at `NaN`, which Konva draws+ * nowhere and no later drag can recover — so it is dropped rather than repaired.+ */+export function validPins(wanted) {+ const pins = new Map();+ for (const spot of wanted ?? []) {+ if (typeof spot?.id !== 'string') continue;+ if (!Number.isFinite(spot.x) || !Number.isFinite(spot.y)) continue;+ pins.set(spot.id, { x: spot.x, y: spot.y });+ }+ return pins;+}diff --git a/frontend/src/lib/graphArrangement.test.js b/frontend/src/lib/graphArrangement.test.jsnew file mode 100644index 0000000..5e579d6--- /dev/null+++ b/frontend/src/lib/graphArrangement.test.js@@ -0,0 +1,82 @@+import { describe, expect, it } from 'vitest';+import { arrangementDiff } from './graph.js';+import { mergedArrangement, validPins } from './graphArrangement.js';++const at = (id, x, y) => ({ id, x, y });++describe('mergedArrangement', () => {+ it('reads the pins the drawing arrived with', () => {+ const nodes = [{ id: 'a', pin: [10, 20] }, { id: 'b' }];+ expect(mergedArrangement({ nodes, held: ['a'] })).toEqual([at('a', 10, 20)]);+ });++ it('lets an unfiled drag win over the pin the drawing carried', () => {+ const nodes = [{ id: 'a', pin: [10, 20] }];+ const pins = new Map([['a', { x: 99, y: 99 }]]);+ expect(mergedArrangement({ nodes, pins, held: ['a'] })).toEqual([at('a', 99, 99)]);+ });++ it('drops a node that is no longer pinned, whichever source still holds it', () => {+ // Let go of a pin and the node may sit in both maps for a moment; carrying it+ // into a snapshot would put it back on the next undo.+ const nodes = [{ id: 'a', pin: [1, 2] }];+ const pins = new Map([['a', { x: 3, y: 4 }], ['b', { x: 5, y: 6 }]]);+ expect(mergedArrangement({ nodes, pins, held: ['b'] })).toEqual([at('b', 5, 6)]);+ });++ it('ignores a drawn node with no pin at all', () => {+ expect(mergedArrangement({ nodes: [{ id: 'a' }], held: ['a'] })).toEqual([]);+ });++ it('keeps a view own pins to itself, ignoring what the drawing carried', () => {+ // A named view holds off-screen pins; an undo taken in it must not rewrite+ // the case-wide arrangement with the subset that happens to be on screen.+ const nodes = [{ id: 'a', pin: [1, 2] }];+ const pins = new Map([['b', { x: 7, y: 8 }]]);+ expect(mergedArrangement({ nodes, pins, held: ['a', 'b'], fromView: true }))+ .toEqual([at('b', 7, 8)]);+ });++ it('answers with nothing when nothing is pinned', () => {+ expect(mergedArrangement({ nodes: [{ id: 'a', pin: [1, 2] }], held: [] })).toEqual([]);+ });++ it('answers something arrangementDiff can compare against itself', () => {+ const nodes = [{ id: 'a', pin: [1, 2] }];+ const now = mergedArrangement({ nodes, held: ['a'] });+ const { place, drop } = arrangementDiff(now, now);+ expect(place).toEqual([]);+ expect(drop).toEqual([]);+ });+});++describe('validPins', () => {+ it('takes the spots a snapshot states properly', () => {+ expect([...validPins([at('a', 1, 2)])]).toEqual([['a', { x: 1, y: 2 }]]);+ });++ it('drops a spot with no id, rather than pinning nothing', () => {+ expect(validPins([{ x: 1, y: 2 }]).size).toBe(0);+ expect(validPins([at(7, 1, 2)]).size).toBe(0);+ });++ it('drops a coordinate that is not finite, which Konva would draw nowhere', () => {+ expect(validPins([at('a', NaN, 2)]).size).toBe(0);+ expect(validPins([at('a', 1, Infinity)]).size).toBe(0);+ expect(validPins([at('a', null, 2)]).size).toBe(0);+ });++ it('keeps the good spots in a list that also holds a bad one', () => {+ const pins = validPins([at('a', 1, 2), at('b', NaN, 0), at('c', 3, 4)]);+ expect([...pins.keys()]).toEqual(['a', 'c']);+ });++ it('reads zero as a position, not as missing', () => {+ expect(validPins([at('a', 0, 0)]).get('a')).toEqual({ x: 0, y: 0 });+ });++ it('answers empty for a snapshot that carries no arrangement', () => {+ expect(validPins(undefined).size).toBe(0);+ expect(validPins(null).size).toBe(0);+ });+});diff --git a/frontend/src/lib/graphViewport.js b/frontend/src/lib/graphViewport.jsnew file mode 100644index 0000000..12882f6--- /dev/null+++ b/frontend/src/lib/graphViewport.js@@ -0,0 +1,73 @@+/**+ * The camera over the graph canvas: what a screen point means, and what a zoom+ * does to where you were looking.+ *+ * Konva owns the stage; these are the four bits of arithmetic that decide what it+ * is pointed at. They are here rather than in the tool because each of them is a+ * claim that is easy to get subtly wrong and impossible to see: a zoom that does+ * not hold its anchor drifts the case out from under the cursor a few pixels at a+ * time, and a cull margin that is too tight pops cards in at the edge of a pan.+ * Neither shows up in a screenshot; both show up here.+ *+ * Everything is in canvas units unless it says screen.+ */++/** How far in and out the canvas may be taken. */+export const ZOOM_MIN = 0.12;+export const ZOOM_MAX = 3.2;++/** Clamp a wanted scale into the range the canvas allows. */+export function clampZoom(scale) {+ return Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, scale));+}++/**+ * A screen point in canvas units, given where the group sits and how far it is+ * zoomed. The inverse of what Konva does when it draws.+ */+export function toCanvasPoint(point, { x, y, scale }) {+ const factor = scale || 1;+ return { x: (point.x - x) / factor, y: (point.y - y) / factor };+}++/**+ * Where the group has to move so a zoom leaves one point where it was.+ *+ * The anchor is the whole of it: zoom around the middle of the window and the+ * node under the cursor slides away, which turns "look closer at this" into+ * "look closer, then go find it again". Returns null when the scale is already+ * at the bound, so a caller can skip a redraw that would change nothing.+ */+export function zoomAround(factor, anchor, { x, y, scale }) {+ const next = clampZoom(scale * factor);+ if (next === scale) return null;+ const local = toCanvasPoint(anchor, { x, y, scale });+ return {+ scale: next,+ x: anchor.x - local.x * next,+ y: anchor.y - local.y * next,+ };+}++/**+ * The rectangle on screen, in canvas units, grown by a margin.+ *+ * The margin is slack for panning: cards are only built once they are in view, so+ * without it a drag would reveal the bare dots that sit under cards which do not+ * exist yet — the scene is only redressed when the drag ends.+ */+export function visibleRect({ x, y, scale }, width, height, margin = 0) {+ const left = -x / scale;+ const top = -y / scale;+ return {+ left: left - margin,+ top: top - margin,+ right: left + width / scale + margin,+ bottom: top + height / scale + margin,+ };+}++/** Whether a canvas point falls inside a rect from `visibleRect`. */+export function within(rect, x, y) {+ return x > rect.left && x < rect.right && y > rect.top && y < rect.bottom;+}diff --git a/frontend/src/lib/graphViewport.test.js b/frontend/src/lib/graphViewport.test.jsnew file mode 100644index 0000000..c2ca62e--- /dev/null+++ b/frontend/src/lib/graphViewport.test.js@@ -0,0 +1,114 @@+import { describe, expect, it } from 'vitest';+import {+ clampZoom,+ toCanvasPoint,+ visibleRect,+ within,+ zoomAround,+ ZOOM_MAX,+ ZOOM_MIN,+} from './graphViewport.js';++describe('clampZoom', () => {+ it('leaves a scale inside the range alone', () => {+ expect(clampZoom(1)).toBe(1);+ });++ it('stops at both bounds rather than letting the canvas run away', () => {+ expect(clampZoom(50)).toBe(ZOOM_MAX);+ expect(clampZoom(0.0001)).toBe(ZOOM_MIN);+ });+});++describe('toCanvasPoint', () => {+ it('undoes the group offset and the scale', () => {+ expect(toCanvasPoint({ x: 130, y: 60 }, { x: 30, y: 20, scale: 2 })).toEqual({ x: 50, y: 20 });+ });++ it('is the identity when the camera has not moved', () => {+ expect(toCanvasPoint({ x: 7, y: 9 }, { x: 0, y: 0, scale: 1 })).toEqual({ x: 7, y: 9 });+ });++ it('treats a zero scale as one, rather than dividing by it', () => {+ expect(toCanvasPoint({ x: 4, y: 4 }, { x: 0, y: 0, scale: 0 })).toEqual({ x: 4, y: 4 });+ });+});++describe('zoomAround', () => {+ it('leaves the anchor pointing at the same canvas point', () => {+ const camera = { x: 40, y: -15, scale: 0.8 };+ const anchor = { x: 220, y: 130 };+ const before = toCanvasPoint(anchor, camera);+ const after = zoomAround(1.12, anchor, camera);+ expect(toCanvasPoint(anchor, after).x).toBeCloseTo(before.x, 9);+ expect(toCanvasPoint(anchor, after).y).toBeCloseTo(before.y, 9);+ });++ it('holds the anchor zooming out as well as in', () => {+ const camera = { x: -300, y: 220, scale: 2.1 };+ const anchor = { x: 15, y: 480 };+ const before = toCanvasPoint(anchor, camera);+ const after = zoomAround(1 / 1.12, anchor, camera);+ expect(toCanvasPoint(anchor, after).x).toBeCloseTo(before.x, 9);+ expect(toCanvasPoint(anchor, after).y).toBeCloseTo(before.y, 9);+ });++ it('applies the factor to the scale', () => {+ expect(zoomAround(2, { x: 0, y: 0 }, { x: 0, y: 0, scale: 1 }).scale).toBe(2);+ });++ it('says nothing when the canvas is already at the bound', () => {+ expect(zoomAround(2, { x: 0, y: 0 }, { x: 0, y: 0, scale: ZOOM_MAX })).toBeNull();+ expect(zoomAround(0.5, { x: 0, y: 0 }, { x: 0, y: 0, scale: ZOOM_MIN })).toBeNull();+ });++ it('still moves when the factor only partly fits, and stops at the bound', () => {+ const near = ZOOM_MAX / 1.05;+ const moved = zoomAround(1.5, { x: 100, y: 100 }, { x: 0, y: 0, scale: near });+ expect(moved.scale).toBe(ZOOM_MAX);+ });+});++describe('visibleRect', () => {+ it('states the window in canvas units', () => {+ const rect = visibleRect({ x: 0, y: 0, scale: 1 }, 800, 600);+ expect(rect.left).toBeCloseTo(0);+ expect(rect.top).toBeCloseTo(0);+ expect(rect.right).toBe(800);+ expect(rect.bottom).toBe(600);+ });++ it('shrinks with the zoom, because a zoomed-in window sees less of the case', () => {+ const rect = visibleRect({ x: 0, y: 0, scale: 2 }, 800, 600);+ expect(rect.right).toBe(400);+ expect(rect.bottom).toBe(300);+ });++ it('follows a pan', () => {+ const rect = visibleRect({ x: -200, y: -100, scale: 1 }, 800, 600);+ expect(rect.left).toBe(200);+ expect(rect.top).toBe(100);+ });++ it('grows by the margin on every side', () => {+ const rect = visibleRect({ x: 0, y: 0, scale: 1 }, 800, 600, 50);+ expect(rect).toEqual({ left: -50, top: -50, right: 850, bottom: 650 });+ });+});++describe('within', () => {+ const rect = visibleRect({ x: 0, y: 0, scale: 1 }, 800, 600, 20);++ it('keeps a node in the window', () => {+ expect(within(rect, 400, 300)).toBe(true);+ });++ it('keeps a node just off screen, so a pan reveals a card and not a dot', () => {+ expect(within(rect, 810, 300)).toBe(true);+ });++ it('drops a node past the margin', () => {+ expect(within(rect, 900, 300)).toBe(false);+ expect(within(rect, 400, -100)).toBe(false);+ });+});diff --git a/frontend/src/lib/mapMarkers.js b/frontend/src/lib/mapMarkers.jsnew file mode 100644index 0000000..05cd17f--- /dev/null+++ b/frontend/src/lib/mapMarkers.js@@ -0,0 +1,47 @@+/**+ * The two marks the map can put on a point, as plain SVG.+ *+ * A capture is a document: whatever the analyst saw on screen is what the PNG+ * has to show, so these strings are the same ones the server draws into a+ * capture. Kept out of the tool because a marker is a picture with a claim in it+ * — the pin's tip is the location, the crosshair's centre is — and an anchor+ * that disagrees with the drawing puts the mark somewhere the point is not.+ */++/** Size and anchor per style, in CSS pixels. The anchor is the point itself. */+export const MARKER_GEOMETRY = {+ // The tip at the bottom of the teardrop is what points at the location.+ pin: { size: [30, 42], anchor: [15, 42] },+ // Centred: the gap between the four arms is the point.+ crosshair: { size: [46, 46], anchor: [23, 23] },+};++const PIN = `<svg width="30" height="42" viewBox="0 0 30 42">+ <path d="M15 41 C15 41 27 24 27 14 A12 12 0 1 0 3 14 C3 24 15 41 15 41 Z"+ fill="#e5484d" stroke="#3c0c0e" stroke-width="1.5"/>+ <circle cx="15" cy="14" r="4.5" fill="#fff" stroke="#3c0c0e" stroke-width="1"/>+ </svg>`;++// Drawn twice: a heavy dark pass under a light one, so the arms stay legible on+// bright sand and on dark water without a halo box around them.+const CROSSHAIR = `<svg width="46" height="46" viewBox="0 0 46 46">+ <g stroke="#000" stroke-width="4" opacity="0.55">+ <line x1="1" y1="23" x2="16" y2="23"/><line x1="30" y1="23" x2="45" y2="23"/>+ <line x1="23" y1="1" x2="23" y2="16"/><line x1="23" y1="30" x2="23" y2="45"/>+ </g>+ <g stroke="#fff" stroke-width="2">+ <line x1="1" y1="23" x2="16" y2="23"/><line x1="30" y1="23" x2="45" y2="23"/>+ <line x1="23" y1="1" x2="23" y2="16"/><line x1="23" y1="30" x2="23" y2="45"/>+ <circle cx="23" cy="23" r="2.5" fill="none"/>+ </g>+ </svg>`;++/** The marker SVG for a style. Anything but `pin` draws the crosshair. */+export function markerSvg(style) {+ return style === 'pin' ? PIN : CROSSHAIR;+}++/** Size and anchor for a style, matching what `markerSvg` returns. */+export function markerGeometry(style) {+ return style === 'pin' ? MARKER_GEOMETRY.pin : MARKER_GEOMETRY.crosshair;+}diff --git a/frontend/src/lib/mapMarkers.test.js b/frontend/src/lib/mapMarkers.test.jsnew file mode 100644index 0000000..ec3fb82--- /dev/null+++ b/frontend/src/lib/mapMarkers.test.js@@ -0,0 +1,53 @@+import { describe, expect, it } from 'vitest';+import { markerGeometry, markerSvg, MARKER_GEOMETRY } from './mapMarkers.js';++describe('markerSvg', () => {+ it('draws the pin as a teardrop with an eye in it', () => {+ const svg = markerSvg('pin');+ expect(svg).toContain('<path d="M15 41');+ expect(svg).toContain('<circle cx="15" cy="14"');+ });++ it('draws the crosshair twice, dark under light, so it reads on any imagery', () => {+ const svg = markerSvg('crosshair');+ expect(svg).toContain('stroke="#000"');+ expect(svg).toContain('stroke="#fff"');+ });++ it('leaves the centre of the crosshair open, because that gap is the point', () => {+ // The arms stop short of 23 on both sides; nothing is drawn across it.+ expect(markerSvg('crosshair')).toContain('x1="1" y1="23" x2="16" y2="23"');+ expect(markerSvg('crosshair')).toContain('x1="30" y1="23" x2="45" y2="23"');+ });++ it('falls back to the crosshair for a style it does not know', () => {+ expect(markerSvg('something-else')).toBe(markerSvg('crosshair'));+ });+});++describe('markerGeometry', () => {+ it('anchors the pin at its tip, not its centre', () => {+ const { size, anchor } = markerGeometry('pin');+ expect(anchor).toEqual([size[0] / 2, size[1]]);+ });++ it('anchors the crosshair at its centre', () => {+ const { size, anchor } = markerGeometry('crosshair');+ expect(anchor).toEqual([size[0] / 2, size[1] / 2]);+ });++ it('gives every style an anchor inside its own box', () => {+ for (const style of Object.keys(MARKER_GEOMETRY)) {+ const { size, anchor } = markerGeometry(style);+ expect(anchor[0]).toBeLessThanOrEqual(size[0]);+ expect(anchor[1]).toBeLessThanOrEqual(size[1]);+ }+ });++ it('matches the box the SVG actually declares', () => {+ for (const style of Object.keys(MARKER_GEOMETRY)) {+ const [w, h] = markerGeometry(style).size;+ expect(markerSvg(style)).toContain(`width="${w}" height="${h}"`);+ }+ });+});diff --git a/frontend/src/lib/proofEdits.js b/frontend/src/lib/proofEdits.jsnew file mode 100644index 0000000..2e0d3a5--- /dev/null+++ b/frontend/src/lib/proofEdits.js@@ -0,0 +1,108 @@+/**+ * Edits to what a proof holds, as arithmetic over the document.+ *+ * `composer.js` answers where panels land and what the legend says. This answers+ * the smaller question beside it: given the document and one act — nudge this,+ * delete that, drag this panel to a new row, drop the resize handle here — what+ * does the document become?+ *+ * They are apart from the tool because each is a rule with an edge nobody sees+ * until it is wrong: a nudge that moves a freehand stroke's origin instead of its+ * vertices, a colour whose legend note outlives the last element that used it, a+ * resize that rounds a panel to a scale the buttons cannot get back to. Konva and+ * Svelte are not involved — these take plain objects and answer with plain values,+ * so the caller decides what to write.+ */++import { PANEL_H } from './composer.js';++/** How small and how large a panel may be dragged or stepped. */+export const PANEL_SCALE_MIN = 0.25;+export const PANEL_SCALE_MAX = 2.5;++/**+ * A shape moved by (dx, dy), in panel-natural pixels.+ *+ * Points-based kinds carry their geometry in a flat `[x, y, x, y, …]` list and+ * have no origin to move, so every vertex shifts; everything else moves its+ * corner. Returns the patch to apply rather than mutating, so an undo step can+ * hold the before and after of the same act.+ */+export function nudgeShape(shape, dx, dy) {+ if (Array.isArray(shape.points)) {+ return { points: shape.points.map((v, i) => v + (i % 2 === 0 ? dx : dy)) };+ }+ return { x: (shape.x ?? 0) + dx, y: (shape.y ?? 0) + dy };+}++/**+ * The legend after an element is deleted.+ *+ * A note is written against a colour, not against the element that first used+ * it, so it survives deleting one of three red arrows and goes with the last one.+ * A legend line naming a colour nothing on the picture carries is a claim about+ * the proof that the proof does not make.+ */+export function notesAfterRemoval(notes, remaining, gone) {+ if (!gone || remaining.some((s) => s.color === gone.color)) return notes;+ const kept = { ...notes };+ delete kept[gone.color];+ return kept;+}++/**+ * The row a panel moves to, or null when the move is refused.+ *+ * One past the last row is allowed and starts a fresh one — that is how a row is+ * created. Two past is not: it would leave an empty row between, and a grid with+ * a hole in it is a layout nobody asked for.+ */+export function nextPanelRow(panels, index, delta) {+ const panel = panels[index];+ if (!panel) return null;+ const maxRow = Math.max(...panels.map((p) => p.row ?? 0));+ const next = (panel.row ?? 0) + delta;+ if (next < 0 || next > maxRow + 1) return null;+ return next;+}++/**+ * An array with one entry moved by `delta`, or null when it would fall off.+ *+ * In free mode the array order *is* the z-order, front to back, so this is what+ * "bring forward" and "send backward" do.+ */+export function movedBy(list, index, delta) {+ const target = index + delta;+ if (index < 0 || index >= list.length || target < 0 || target >= list.length) return null;+ const next = [...list];+ const [item] = next.splice(index, 1);+ next.splice(target, 0, item);+ return next;+}++/**+ * The scale a dropped resize handle means, clamped and rounded.+ *+ * The transformer scales the Konva group, and a group's scale is+ * `(PANEL_H · panelScale) / naturalHeight` — so the panel scale is read back out+ * of it. Rounded to a hundredth so a drag lands on a value the step buttons can+ * also reach; without that, a resized panel can never be stepped back to 1.+ */+export function scaleFromNode(nodeScale, naturalHeight, min = PANEL_SCALE_MIN, max = PANEL_SCALE_MAX) {+ const wanted = (nodeScale * naturalHeight) / PANEL_H;+ return Math.round(Math.min(max, Math.max(min, wanted)) * 100) / 100;+}++/**+ * The document point at the centre of what the analyst is looking at.+ *+ * Where a pasted overlay lands: in the middle of the view rather than the middle+ * of the document, which on a zoomed-in proof is off screen entirely.+ */+export function viewCentrePoint(view, stage) {+ return {+ x: (view.width / 2 - stage.x) / stage.scaleX,+ y: (view.height / 2 - stage.y) / stage.scaleY,+ };+}diff --git a/frontend/src/lib/proofEdits.test.js b/frontend/src/lib/proofEdits.test.jsnew file mode 100644index 0000000..8142f48--- /dev/null+++ b/frontend/src/lib/proofEdits.test.js@@ -0,0 +1,164 @@+import { describe, expect, it } from 'vitest';+import { PANEL_H } from './composer.js';+import {+ movedBy,+ nextPanelRow,+ notesAfterRemoval,+ nudgeShape,+ PANEL_SCALE_MAX,+ PANEL_SCALE_MIN,+ scaleFromNode,+ viewCentrePoint,+} from './proofEdits.js';++describe('nudgeShape', () => {+ it('moves a boxed shape by its corner', () => {+ expect(nudgeShape({ x: 10, y: 20 }, 3, -4)).toEqual({ x: 13, y: 16 });+ });++ it('treats a shape with no position as sitting at the origin', () => {+ expect(nudgeShape({}, 2, 2)).toEqual({ x: 2, y: 2 });+ });++ it('moves every vertex of a points-based shape, not its origin', () => {+ // A freehand stroke carries its geometry in the list; shifting an x/y it does+ // not have would leave the drawing exactly where it was.+ const stroke = { points: [0, 0, 10, 5, 20, 15] };+ expect(nudgeShape(stroke, 2, -1)).toEqual({ points: [2, -1, 12, 4, 22, 14] });+ });++ it('does not write to the shape it was handed', () => {+ const shape = { x: 1, y: 1 };+ nudgeShape(shape, 5, 5);+ expect(shape).toEqual({ x: 1, y: 1 });+ });+});++describe('notesAfterRemoval', () => {+ const notes = { '#ff5252': 'the vehicle', '#40c4ff': 'the mast' };++ it('keeps the note while another element still carries the colour', () => {+ const remaining = [{ color: '#ff5252' }];+ const kept = notesAfterRemoval(notes, remaining, { color: '#ff5252' });+ expect(kept['#ff5252']).toBe('the vehicle');+ });++ it('drops the note with the last element of its colour', () => {+ const kept = notesAfterRemoval(notes, [{ color: '#40c4ff' }], { color: '#ff5252' });+ expect(kept).toEqual({ '#40c4ff': 'the mast' });+ });++ it('leaves the other colours alone', () => {+ const kept = notesAfterRemoval(notes, [], { color: '#ff5252' });+ expect(kept['#40c4ff']).toBe('the mast');+ });++ it('answers with the same legend when nothing was deleted', () => {+ expect(notesAfterRemoval(notes, [], null)).toBe(notes);+ });++ it('does not write to the legend it was handed', () => {+ notesAfterRemoval(notes, [], { color: '#ff5252' });+ expect(notes['#ff5252']).toBe('the vehicle');+ });+});++describe('nextPanelRow', () => {+ const panels = [{ row: 0 }, { row: 0 }, { row: 1 }];++ it('moves a panel down a row', () => {+ expect(nextPanelRow(panels, 0, 1)).toBe(1);+ });++ it('lets a panel start a fresh row one past the last', () => {+ expect(nextPanelRow(panels, 2, 1)).toBe(2);+ });++ it('refuses two past the last, which would leave an empty row behind', () => {+ expect(nextPanelRow([{ row: 0 }], 0, 2)).toBeNull();+ });++ it('refuses to move above the first row', () => {+ expect(nextPanelRow(panels, 0, -1)).toBeNull();+ });++ it('treats a panel with no row as being on the first one', () => {+ expect(nextPanelRow([{}], 0, 1)).toBe(1);+ });++ it('says nothing about a panel that is not there', () => {+ expect(nextPanelRow(panels, 9, 1)).toBeNull();+ });+});++describe('movedBy', () => {+ const list = ['a', 'b', 'c'];++ it('brings an entry forward', () => {+ expect(movedBy(list, 2, -1)).toEqual(['a', 'c', 'b']);+ });++ it('sends an entry backward', () => {+ expect(movedBy(list, 0, 1)).toEqual(['b', 'a', 'c']);+ });++ it('refuses a move off either end', () => {+ expect(movedBy(list, 0, -1)).toBeNull();+ expect(movedBy(list, 2, 1)).toBeNull();+ });++ it('does not write to the list it was handed', () => {+ movedBy(list, 0, 1);+ expect(list).toEqual(['a', 'b', 'c']);+ });+});++describe('scaleFromNode', () => {+ it('reads a panel scale of one back out of an untouched group', () => {+ // group scale = (PANEL_H · 1) / naturalHeight+ const natural = 1080;+ expect(scaleFromNode(PANEL_H / natural, natural)).toBe(1);+ });++ it('doubles the panel when the group is dragged to twice its scale', () => {+ const natural = 1080;+ expect(scaleFromNode((PANEL_H / natural) * 2, natural)).toBe(2);+ });++ it('stops at both bounds rather than letting a drag shrink a panel away', () => {+ expect(scaleFromNode(100, 1080)).toBe(PANEL_SCALE_MAX);+ expect(scaleFromNode(0.0001, 1080)).toBe(PANEL_SCALE_MIN);+ });++ it('rounds to a hundredth, so the step buttons can reach the value again', () => {+ const natural = 1080;+ const scale = scaleFromNode((PANEL_H / natural) * 1.23456, natural);+ expect(scale).toBe(1.23);+ });+});++describe('viewCentrePoint', () => {+ it('is the middle of the document when nothing is panned or zoomed', () => {+ const point = viewCentrePoint(+ { width: 800, height: 600 },+ { x: 0, y: 0, scaleX: 1, scaleY: 1 }+ );+ expect(point).toEqual({ x: 400, y: 300 });+ });++ it('follows the pan, so a paste lands where the analyst is looking', () => {+ const point = viewCentrePoint(+ { width: 800, height: 600 },+ { x: -1000, y: -500, scaleX: 1, scaleY: 1 }+ );+ expect(point).toEqual({ x: 1400, y: 800 });+ });++ it('accounts for the zoom', () => {+ const point = viewCentrePoint(+ { width: 800, height: 600 },+ { x: 0, y: 0, scaleX: 2, scaleY: 2 }+ );+ expect(point).toEqual({ x: 200, y: 150 });+ });+});diff --git a/frontend/src/lib/skyOverlay.js b/frontend/src/lib/skyOverlay.jsnew file mode 100644index 0000000..b78517f--- /dev/null+++ b/frontend/src/lib/skyOverlay.js@@ -0,0 +1,136 @@+/**+ * The geometry behind the sun/moon overlay drawn on the map.+ *+ * The overlay answers one question — *where was the light coming from, and how+ * high was it* — by drawing each body's track as an arc around the anchor point.+ * Leaflet owns the drawing; what is here is everything that decides *what* to+ * draw, kept apart because it is arithmetic over a day's samples and nothing+ * else. That makes it checkable: an arc that closes through the hours a body+ * spends below the horizon, or an hour tick on a sample that is under it, is a+ * picture that lies about the sky, and neither is visible in a screenshot.+ *+ * The radial convention matches the compass rosette in Coords & Sky: the anchor+ * stands for the zenith, the arc for the horizon, so a body high in the sky sits+ * close to the centre.+ */++import { glyphRotation, litPath } from './moonphase.js';++/**+ * Runs of consecutive samples with the body above the horizon.+ *+ * The arc the body actually sweeps, not the whole 24 hours: drawn end to end,+ * the line would close the circle through the bearings the body holds while it+ * is down, which says nothing about where the light came from. A run of one+ * sample is dropped because a polyline needs two points to exist.+ */+export function upRuns(altitudes) {+ const runs = [];+ let run = null;+ altitudes.forEach((altitude, i) => {+ if (altitude >= 0) {+ run = run ?? [];+ run.push(i);+ } else if (run) {+ runs.push(run);+ run = null;+ }+ });+ if (run) runs.push(run);+ return runs.filter((r) => r.length > 1);+}++/**+ * The sample closest to a wall clock, matched against the day's own labels.+ *+ * Not minutes divided by 60: on the two days a year daylight saving moves, the+ * clock skips or repeats an hour, and arithmetic over the sample index lands an+ * hour off the time the analyst typed.+ */+export function nearestSample(clock, wanted) {+ const target = minutesOf(wanted);+ let best = 0;+ let closest = Infinity;+ clock.forEach((stamp, i) => {+ const gap = Math.abs(minutesOf(stamp) - target);+ if (gap < closest) {+ closest = gap;+ best = i;+ }+ });+ return best;+}++function minutesOf(stamp) {+ return Number(stamp.slice(0, 2)) * 60 + Number(stamp.slice(3, 5));+}++/**+ * Which samples carry an hour tick, and which of those are the long ones.+ *+ * On the hour, and only while the body is up — a tick under the horizon would+ * mark a bearing nothing was shining from. Every third hour is drawn longer, so+ * the arc can be read at a glance without labelling all of them.+ */+export function hourTicks(minutes, altitudes) {+ const ticks = [];+ minutes.forEach((minute, i) => {+ if (minute % 60 || altitudes[i] < 0) return;+ ticks.push({ index: i, long: minute % 180 === 0 });+ });+ return ticks;+}++/**+ * Where the body's mark rides on its ray, as a fraction of the arc's radius.+ *+ * At the horizon it sits on the arc, at the zenith on the anchor, so how far up+ * the body is reads as how close to you it is.+ */+export function markScale(altitude) {+ return (90 - altitude) / 90;+}++/** Whether the body is below the horizon, i.e. drawn as a dashed ray and no mark. */+export function isBelow(altitude) {+ return altitude < 0;+}++/**+ * The phase angle a lit fraction implies.+ *+ * `k = (1 + cos i) / 2` by definition, so the illuminated fraction the server+ * already sends is enough to draw the moon — nothing extra is fetched.+ */+export function phaseAngleOf(illuminated) {+ const clamped = Math.min(1, Math.max(-1, 2 * illuminated - 1));+ return (Math.acos(clamped) * 180) / Math.PI;+}++/**+ * The body as an SVG string: a disc for the sun, a phase for the moon.+ *+ * The bright-limb angle belongs to a view of the sky and says nothing in a plan+ * view, so this uses the table convention instead: lit side right when waxing.+ */+export function bodySvg(kind, colour, illuminated, waxing, size = 20) {+ const r = size / 2 - 2;+ let inner = `<circle r="${r}" fill="${colour}" />`;+ if (kind === 'moon') {+ inner =+ `<circle r="${r}" fill="${colour}" opacity="0.25" />` ++ `<g transform="rotate(${glyphRotation(waxing)})">` ++ `<path d="${litPath(r, illuminated, phaseAngleOf(illuminated))}" fill="${colour}" /></g>`;+ }+ return (+ `<svg width="${size}" height="${size}" viewBox="${-size / 2} ${-size / 2} ${size} ${size}">` ++ `<circle r="${r + 1.5}" fill="rgba(0,0,0,0.45)" />${inner}` ++ `<circle r="${r}" fill="none" stroke="#fff" stroke-opacity="0.85" stroke-width="1.5" />` ++ `</svg>`+ );+}++/** One body's reading, as the tooltip states it. */+export function bodyReading(label, clock, azimuth, altitude) {+ return `${label} ${clock} · az ${Math.round(azimuth)}° · alt ${Math.round(altitude)}°`;+}diff --git a/frontend/src/lib/skyOverlay.test.js b/frontend/src/lib/skyOverlay.test.jsnew file mode 100644index 0000000..2f5080f--- /dev/null+++ b/frontend/src/lib/skyOverlay.test.js@@ -0,0 +1,147 @@+import { describe, expect, it } from 'vitest';+import {+ bodyReading,+ bodySvg,+ hourTicks,+ isBelow,+ markScale,+ nearestSample,+ phaseAngleOf,+ upRuns,+} from './skyOverlay.js';++describe('upRuns', () => {+ it('keeps only the stretches the body spends above the horizon', () => {+ expect(upRuns([-5, -1, 3, 9, 12, 4, -2, -8])).toEqual([[2, 3, 4, 5]]);+ });++ it('splits a day the body rises twice in, rather than joining the two arcs', () => {+ // A polar-summer day: down for a few samples around local midnight.+ expect(upRuns([4, 9, 2, -1, -3, 2, 8, 5])).toEqual([+ [0, 1, 2],+ [5, 6, 7],+ ]);+ });++ it('drops a lone sample, because a polyline needs two points', () => {+ expect(upRuns([-2, 1, -2, 4, 6])).toEqual([[3, 4]]);+ });++ it('treats the horizon itself as up, so a grazing pass is still drawn', () => {+ expect(upRuns([-1, 0, 0, -1])).toEqual([[1, 2]]);+ });++ it('says nothing for a body that never rises', () => {+ expect(upRuns([-9, -12, -30])).toEqual([]);+ });++ it('closes a run that is still open at the end of the day', () => {+ expect(upRuns([-1, 2, 3])).toEqual([[1, 2]]);+ });+});++describe('nearestSample', () => {+ const clock = ['00:00', '00:30', '01:00', '01:30', '02:00'];++ it('finds the sample a wall clock lands on', () => {+ expect(nearestSample(clock, '01:00')).toBe(2);+ });++ it('rounds to the closest label rather than interpolating', () => {+ expect(nearestSample(clock, '01:20')).toBe(3);+ expect(nearestSample(clock, '01:10')).toBe(2);+ });++ it('reads the day own labels, so a repeated hour is not an hour off', () => {+ // The night daylight saving ends: 02:00 comes round twice, and dividing the+ // sample index by two would land on the wrong one.+ const dst = ['01:00', '01:30', '02:00', '02:30', '02:00', '02:30', '03:00'];+ expect(nearestSample(dst, '02:00')).toBe(2);+ expect(nearestSample(dst, '03:00')).toBe(6);+ });++ it('falls on the first sample when asked for something before the day starts', () => {+ expect(nearestSample(clock, '00:00')).toBe(0);+ });+});++describe('hourTicks', () => {+ const minutes = [0, 30, 60, 90, 120, 150, 180, 210];++ it('ticks on the hour and never between', () => {+ const up = minutes.map(() => 10);+ expect(hourTicks(minutes, up).map((t) => t.index)).toEqual([0, 2, 4, 6]);+ });++ it('draws every third hour longer', () => {+ const up = minutes.map(() => 10);+ expect(hourTicks(minutes, up).filter((t) => t.long).map((t) => t.index)).toEqual([0, 6]);+ });++ it('leaves the hours the body is under the horizon unmarked', () => {+ const altitudes = [-3, 0, 5, 0, 8, 0, -1, 0];+ expect(hourTicks(minutes, altitudes).map((t) => t.index)).toEqual([2, 4]);+ });+});++describe('the mark on the ray', () => {+ it('sits on the arc at the horizon and on the anchor at the zenith', () => {+ expect(markScale(0)).toBe(1);+ expect(markScale(90)).toBe(0);+ });++ it('rides closer to the anchor the higher the body is', () => {+ expect(markScale(60)).toBeLessThan(markScale(30));+ });++ it('calls a body below the horizon below, and the horizon itself up', () => {+ expect(isBelow(-0.1)).toBe(true);+ expect(isBelow(0)).toBe(false);+ });+});++describe('phaseAngleOf', () => {+ it('reads a full moon as no phase angle, and a new one as half a turn', () => {+ expect(phaseAngleOf(1)).toBeCloseTo(0);+ expect(phaseAngleOf(0)).toBeCloseTo(180);+ });++ it('reads a half moon as a quarter turn', () => {+ expect(phaseAngleOf(0.5)).toBeCloseTo(90);+ });++ it('never goes imaginary on a fraction just outside the range', () => {+ expect(Number.isNaN(phaseAngleOf(1.0001))).toBe(false);+ expect(Number.isNaN(phaseAngleOf(-0.0001))).toBe(false);+ });+});++describe('bodySvg', () => {+ it('draws the sun as one filled disc', () => {+ const svg = bodySvg('sun', '#bd8721', 1, true);+ expect(svg).toContain('fill="#bd8721"');+ expect(svg).not.toContain('<path');+ });++ it('draws the moon as a lit path over a dimmed disc', () => {+ const svg = bodySvg('moon', '#4a93cc', 0.4, true);+ expect(svg).toContain('opacity="0.25"');+ expect(svg).toContain('<path d="');+ });++ it('turns the lit side with the phase, so waxing and waning differ', () => {+ const waxing = bodySvg('moon', '#fff', 0.3, true);+ const waning = bodySvg('moon', '#fff', 0.3, false);+ expect(waxing).not.toBe(waning);+ });++ it('scales the whole glyph off one size', () => {+ expect(bodySvg('sun', '#fff', 1, true, 40)).toContain('width="40"');+ });+});++describe('bodyReading', () => {+ it('states the body, the time, the bearing and the height, rounded', () => {+ expect(bodyReading('Sun', '14:30', 213.4, 27.6)).toBe('Sun 14:30 · az 213° · alt 28°');+ });+});diff --git a/frontend/src/tools/Graph.svelte b/frontend/src/tools/Graph.svelteindex ad746ba..6fca653 100644--- a/frontend/src/tools/Graph.svelte+++ b/frontend/src/tools/Graph.svelte@@ -50,6 +50,14 @@*/import Konva from 'konva';import { fileUrl } from '../lib/fileUrl.js';+ import { mergedArrangement, validPins } from '../lib/graphArrangement.js';+ import {+ clampZoom,+ toCanvasPoint,+ visibleRect,+ within,+ zoomAround,+ } from '../lib/graphViewport.js';import { tick, untrack } from 'svelte';import { api } from '../lib/api.js';import {@@ -157,8 +165,6 @@/** Below this scale a label is noise, so only the node in hand keeps one. */const LABEL_SCALE = 0.62;- const ZOOM_MIN = 0.12;- const ZOOM_MAX = 3.2;/** Pointer travel that turns a click into a pan, so a hand tremor still selects. */const DRAG_SLOP = 4;/** How long a drag waits before it is filed, so a flurry of them is one request. */@@ -2051,14 +2057,7 @@function replaceViewArrangement(wanted, owner = arrangementOwner) {pins.clear();settled.clear();- for (const spot of wanted ?? []) {- if (- typeof spot?.id !== 'string' ||- !Number.isFinite(spot.x) ||- !Number.isFinite(spot.y)- ) continue;- pins.set(spot.id, { x: spot.x, y: spot.y });- }+ for (const [id, spot] of validPins(wanted)) pins.set(id, spot);arrangementOwner = owner;pinnedIds = [...pins.keys()];pinCount = pinnedIds.length;@@ -2079,17 +2078,12 @@/** Where every pin in the active arrangement stands. A named view retains local* off-screen pins; the case-wide undo remains limited to nodes currently drawn. */function arrangementNow() {- const at = new Map();- if (!ownsViewArrangement()) {- for (const node of payload?.nodes ?? []) {- if (node.pin) at.set(node.id, { x: node.pin[0], y: node.pin[1] });- }- }- for (const [id, spot] of pins) at.set(id, { x: spot.x, y: spot.y });- const held = new Set(pinnedIds);- return [...at.entries()]- .filter(([id]) => held.has(id))- .map(([id, spot]) => ({ id, x: spot.x, y: spot.y }));+ return mergedArrangement({+ nodes: payload?.nodes ?? [],+ pins,+ held: pinnedIds,+ fromView: ownsViewArrangement(),+ });}function snapshotNow() {@@ -3933,18 +3927,11 @@* requests for cards nobody can see.*/function onScreen(scale) {- const left = -group.x() / scale;- const top = -group.y() / scale;// Two cards of slack, so a normal drag reveals cards that already exist rather// than the dots underneath them: the scene is only redressed when the drag ends.const margin = CARD.w * 2 * cardFactor(scale);- const right = left + width / scale;- const bottom = top + height / scale;- return (shape) => {- const x = shape.x();- const y = shape.y();- return x > left - margin && x < right + margin && y > top - margin && y < bottom + margin;- };+ const rect = visibleRect({ x: group.x(), y: group.y(), scale }, width, height, margin);+ return (shape) => within(rect, shape.x(), shape.y());}/**@@ -4244,22 +4231,23 @@* The same inverse `zoomBy` already takes to keep the pointer over the same spot* while zooming, said once so a dropped file and a new entity land where the* gesture aimed. */+ /** Where the camera stands, as `lib/graphViewport.js` states it. */+ function camera() {+ return { x: group.x(), y: group.y(), scale: group.scaleX() || 1 };+ }+function toCanvas(point) {if (!group) return { x: point.x, y: point.y };- const scale = group.scaleX() || 1;- return { x: (point.x - group.x()) / scale, y: (point.y - group.y()) / scale };+ return toCanvasPoint(point, camera());}function zoomBy(factor, anchor) {if (!group || !stage) return;- const old = group.scaleX();- const next = Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, old * factor));- if (next === old) return;- const point = anchor ?? { x: width / 2, y: height / 2 };- const local = { x: (point.x - group.x()) / old, y: (point.y - group.y()) / old };- group.scale({ x: next, y: next });- group.position({ x: point.x - local.x * next, y: point.y - local.y * next });- zoom = next;+ const moved = zoomAround(factor, anchor ?? { x: width / 2, y: height / 2 }, camera());+ if (!moved) return; // already at the bound; nothing to redraw+ group.scale({ x: moved.scale, y: moved.scale });+ group.position({ x: moved.x, y: moved.y });+ zoom = moved.scale;cameraRevision += 1;restyle();}@@ -4611,7 +4599,7 @@rereads += 1;await tick();if (saved.camera && group) {- const scale = Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, Number(saved.camera.zoom) || 1));+ const scale = clampZoom(Number(saved.camera.zoom) || 1);group.position({ x: Number(saved.camera.x) || 0, y: Number(saved.camera.y) || 0 });group.scale({ x: scale, y: scale });zoom = scale;diff --git a/frontend/src/tools/Graph.test.js b/frontend/src/tools/Graph.test.jsindex 23d0781..3386c77 100644--- a/frontend/src/tools/Graph.test.js+++ b/frontend/src/tools/Graph.test.js@@ -3,6 +3,7 @@ import { readFileSync } from 'node:fs';const source = readFileSync(new URL('./Graph.svelte', import.meta.url), 'utf8');const layout = readFileSync(new URL('../lib/graph.js', import.meta.url), 'utf8');+const viewport = readFileSync(new URL('../lib/graphViewport.js', import.meta.url), 'utf8');const css = readFileSync(new URL('../app.css', import.meta.url), 'utf8');describe('the graph answers what the table cannot', () => {@@ -170,9 +171,13 @@ describe('the interaction', () => {});it('clamps the zoom so a case cannot be lost off-screen', () => {- expect(source).toContain('ZOOM_MIN');- expect(source).toContain('ZOOM_MAX');- expect(source).toContain('Math.min(ZOOM_MAX, Math.max(ZOOM_MIN');+ // The bound and the anchored zoom live in `lib/graphViewport.js`, which is+ // where they are exercised (`graphViewport.test.js`); the tool only calls them.+ expect(viewport).toContain('export const ZOOM_MIN');+ expect(viewport).toContain('export const ZOOM_MAX');+ expect(viewport).toContain('Math.min(ZOOM_MAX, Math.max(ZOOM_MIN');+ expect(source).toContain("from '../lib/graphViewport.js'");+ expect(source).toContain('zoomAround(factor,');});it('gives the whole screen to the drawing, toolbar included', () => {diff --git a/frontend/src/tools/ProofComposer.svelte b/frontend/src/tools/ProofComposer.svelteindex 384ef7f..77bcbcf 100644--- a/frontend/src/tools/ProofComposer.svelte+++ b/frontend/src/tools/ProofComposer.svelte@@ -42,6 +42,16 @@PASTE_SCALE_MIN, PASTE_SCALE_MAX,filterProofPanelItems, hasProofCanvasContent, proofExportOptions, panelPreview,} from '../lib/composer.js';+ import {+ movedBy,+ nextPanelRow,+ notesAfterRemoval,+ nudgeShape,+ PANEL_SCALE_MAX,+ PANEL_SCALE_MIN,+ scaleFromNode,+ viewCentrePoint,+ } from '../lib/proofEdits.js';import {assetName, base64Of, PASTE_TYPES, MAX_PASTES, MAX_PASTE_BYTES,} from '../lib/pasteAsset.js';@@ -51,8 +61,6 @@import { createHistory } from '../lib/history.js';import { pollWhile } from '../lib/poll.js';- const SCALE_MIN = 0.25;- const SCALE_MAX = 2.5;const SCALE_STEP = 0.05;const DRAW_TOOLS = [@@ -821,11 +829,9 @@// Move a panel up/down a row; going past the last row starts a fresh row.function movePanelRow(index, delta) {- const panel = proof.panels[index];- const maxRow = Math.max(...proof.panels.map((p) => p.row ?? 0));- const next = (panel.row ?? 0) + delta;- if (next < 0 || next > maxRow + 1) return;- panel.row = next;+ const next = nextPanelRow(proof.panels, index, delta);+ if (next === null) return;+ proof.panels[index].row = next;normalizeRows();selectedId = null;dirty = true;@@ -840,7 +846,7 @@function scalePanel(index, delta) {const p = proof.panels[index];const cur = p.scale ?? 1;- const next = clampPanelScale(cur, delta, SCALE_MIN, SCALE_MAX);+ const next = clampPanelScale(cur, delta, PANEL_SCALE_MIN, PANEL_SCALE_MAX);if (next === cur) return;if (proof.layout === 'free') materializeFreePositions(); // others must not reflowp.scale = next;@@ -878,9 +884,7 @@function commitPanelNode(panel, node, { resized = false } = {}) {materializeFreePositions();if (resized) {- // transformer scales the group; group scale = (PANEL_H·scale)/naturalH- const next = (node.scaleX() * panel.natural[1]) / PANEL_H;- panel.scale = Math.round(Math.min(SCALE_MAX, Math.max(SCALE_MIN, next)) * 100) / 100;+ panel.scale = scaleFromNode(node.scaleX(), panel.natural[1]);}panel.x = node.x();panel.y = node.y();@@ -899,10 +903,9 @@// Free mode: array order is the z-order, front→back (Z1 = foreground), so// "bring forward" swaps toward index 0 and "send backward" toward the end.function movePanelZ(index, delta) {- const target = index + delta;- if (target < 0 || target >= proof.panels.length) return;- const [panel] = proof.panels.splice(index, 1);- proof.panels.splice(target, 0, panel);+ const next = movedBy(proof.panels, index, delta);+ if (!next) return;+ proof.panels = next;dirty = true;}@@ -949,10 +952,10 @@/** Doc-space centre of what the analyst is looking at. */function viewCentre() {if (!stage || !containerEl) return { x: 0, y: 0 };- return {- x: (containerEl.clientWidth / 2 - stage.x()) / stage.scaleX(),- y: (containerEl.clientHeight / 2 - stage.y()) / stage.scaleY(),- };+ return viewCentrePoint(+ { width: containerEl.clientWidth, height: containerEl.clientHeight },+ { x: stage.x(), y: stage.y(), scaleX: stage.scaleX(), scaleY: stage.scaleY() },+ );}async function addPastedImage(file) {@@ -1419,8 +1422,7 @@// grid: corner-drag only changes the panel's scale — the grid decides// where it sits, so the row re-flows around the new sizegroup.on('transformend', () => {- const next = (group.scaleX() * panel.natural[1]) / PANEL_H;- panel.scale = Math.round(Math.min(SCALE_MAX, Math.max(SCALE_MIN, next)) * 100) / 100;+ panel.scale = scaleFromNode(group.scaleX(), panel.natural[1]);dirty = true;requestAnimationFrame(fit);});@@ -1653,7 +1655,7 @@if (!boundPanel) return newBox;const impliedScale =(newBox.width / stage.scaleX()) * (boundPanel.natural[1] / (boundPanel.natural[0] * PANEL_H));- return impliedScale < SCALE_MIN || impliedScale > SCALE_MAX ? oldBox : newBox;+ return impliedScale < PANEL_SCALE_MIN || impliedScale > PANEL_SCALE_MAX ? oldBox : newBox;});transformer.keepRatio(!!sigNode || !!pasteNode);transformer.nodes(@@ -2063,10 +2065,7 @@function deleteShape(id) {const gone = proof.shapes.find((s) => s.id === id);proof.shapes = proof.shapes.filter((s) => s.id !== id);- // drop the legend note if this was the last element of its color- if (gone && !proof.shapes.some((s) => s.color === gone.color)) {- delete proof.notes[gone.color];- }+ proof.notes = notesAfterRemoval(proof.notes, proof.shapes, gone);if (selectedId === id) selectedId = null;dirty = true;}@@ -2127,12 +2126,7 @@function nudgeSelected(dx, dy) {const s = selectedShape;if (!s) return;- if (Array.isArray(s.points)) {- s.points = s.points.map((v, i) => v + (i % 2 === 0 ? dx : dy));- } else {- s.x = (s.x ?? 0) + dx;- s.y = (s.y ?? 0) + dy;- }+ Object.assign(s, nudgeShape(s, dx, dy));dirty = true;}@@ -2854,8 +2848,8 @@bind:selectedId{activeColor}caseId={caseState.current?.id}- scaleMin={SCALE_MIN}- scaleMax={SCALE_MAX}+ scaleMin={PANEL_SCALE_MIN}+ scaleMax={PANEL_SCALE_MAX}scaleStep={SCALE_STEP}frameWidthMax={FRAME_WIDTH_MAX}frameColor={FRAME_COLOR}diff --git a/frontend/src/tools/Satellite.svelte b/frontend/src/tools/Satellite.svelteindex 1430c3f..2bf7491 100644--- a/frontend/src/tools/Satellite.svelte+++ b/frontend/src/tools/Satellite.svelte@@ -13,7 +13,16 @@} from '../lib/state.svelte.js';import { mapLinks } from '../lib/maplinks.js';import * as measure from '../lib/measure.js';- import { litPath, glyphRotation } from '../lib/moonphase.js';+ import { markerGeometry, markerSvg } from '../lib/mapMarkers.js';+ import {+ bodyReading,+ bodySvg,+ hourTicks,+ isBelow,+ markScale,+ nearestSample,+ upRuns,+ } from '../lib/skyOverlay.js';import * as gridSearch from '../lib/gridSearch.js';import { dragBearing, pivotPanOffset } from '../lib/satRotate.js';import { clampSize, scaledCapture } from '../lib/captureSize.js';@@ -1442,73 +1451,20 @@});});- // Match a wall clock against the day's own labels rather than dividing minutes- // by 60, which is wrong by an hour on the days daylight saving moves.- function nearestSample(clock, wanted) {- const target = Number(wanted.slice(0, 2)) * 60 + Number(wanted.slice(3, 5));- let best = 0;- let closest = Infinity;- clock.forEach((stamp, i) => {- const minutes = Number(stamp.slice(0, 2)) * 60 + Number(stamp.slice(3, 5));- const gap = Math.abs(minutes - target);- if (gap < closest) {- closest = gap;- best = i;- }- });- return best;- }-function themeColour(name, fallback) {const value = getComputedStyle(document.documentElement).getPropertyValue(name).trim();return value || fallback;}- // Runs of consecutive samples with the body above the horizon: the arc it- // actually sweeps in the sky. Drawing the whole 24 hours would close the circle- // through the bearings it holds while it is down, which says nothing.- function upRuns(altitudes) {- const runs = [];- let run = null;- altitudes.forEach((altitude, i) => {- if (altitude >= 0) {- run = run ?? [];- run.push(i);- } else if (run) {- runs.push(run);- run = null;- }- });- if (run) runs.push(run);- return runs.filter((r) => r.length > 1);- }-// The body itself, as a mark on its own ray: it rides between the anchor, which// stands for the zenith, and the arc, which stands for the horizon, so how far- // up it is reads as how close to you it is. The same radial convention as the- // compass rosette in Coords & Sky.+ // up it is reads as how close to you it is. The geometry and the glyph are in+ // `lib/skyOverlay.js`; this only hands them to Leaflet.function bodyIcon(kind, colour, illuminated, waxing) {const size = 20;- const r = size / 2 - 2;- let inner = `<circle r="${r}" fill="${colour}" />`;- if (kind === 'moon') {- // Phase angle back out of the lit fraction: k = (1 + cos i) / 2 by- // definition, so nothing extra has to be fetched to draw it.- const phaseAngle = (Math.acos(Math.min(1, Math.max(-1, 2 * illuminated - 1))) * 180) / Math.PI;- // The bright-limb angle belongs to a view of the sky and says nothing in a- // plan view, so the map uses the table convention: lit side right when waxing.- inner =- `<circle r="${r}" fill="${colour}" opacity="0.25" />` +- `<g transform="rotate(${glyphRotation(waxing)})">` +- `<path d="${litPath(r, illuminated, phaseAngle)}" fill="${colour}" /></g>`;- }return L.divIcon({className: 'sky-body', // replaces Leaflet's boxed default- html:- `<svg width="${size}" height="${size}" viewBox="${-size / 2} ${-size / 2} ${size} ${size}">` +- `<circle r="${r + 1.5}" fill="rgba(0,0,0,0.45)" />${inner}` +- `<circle r="${r}" fill="none" stroke="#fff" stroke-opacity="0.85" stroke-width="1.5" />` +- `</svg>`,+ html: bodySvg(kind, colour, illuminated, waxing, size),iconSize: [size, size],iconAnchor: [size / 2, size / 2],});@@ -1556,9 +1512,7 @@{ color: body.colour, weight: 2.5, opacity: 0.9 }).addTo(sunLayer);}- curve.minutes.forEach((minute, i) => {- if (minute % 60 || body.altitude[i] < 0) return;- const long = minute % 180 === 0; // longer every three hours+ for (const { index: i, long } of hourTicks(curve.minutes, body.altitude)) {L.polyline([at(body.azimuth[i], 0.94), at(body.azimuth[i], long ? 1.1 : 1.03)], {color: body.colour,weight: 2.5,@@ -1566,10 +1520,12 @@}).bindTooltip(`${body.label} ${curve.clock[i]} · az ${Math.round(body.azimuth[i])}°`).addTo(sunLayer);- });+ }const altitude = body.altitude[sunIndex];- const below = altitude < 0;- const reading = `${body.label} ${curve.clock[sunIndex]} · az ${Math.round(body.azimuth[sunIndex])}° · alt ${Math.round(altitude)}°`;+ const below = isBelow(altitude);+ const reading = bodyReading(+ body.label, curve.clock[sunIndex], body.azimuth[sunIndex], altitude+ );L.polyline([[origin.lat, origin.lon], at(body.azimuth[sunIndex])], {color: body.colour,weight: 3.5,@@ -1581,7 +1537,7 @@// Nothing rides the ray while the body is under the horizon: the dashed// ray already says where it is, and a mark on it would claim it is visible.if (!below) {- L.marker(at(body.azimuth[sunIndex], (90 - altitude) / 90), {+ L.marker(at(body.azimuth[sunIndex], markScale(altitude)), {icon: bodyIcon(body.key,body.colour,@@ -1705,33 +1661,12 @@let selRect = $state(null); // live marquee { x0, y0, x1, y1 } in map-container pxfunction markerIcon(style) {- if (style === 'pin') {- return L.divIcon({- className: 'sat-marker',- iconSize: [30, 42],- iconAnchor: [15, 42], // tip points at the location- html: `<svg width="30" height="42" viewBox="0 0 30 42">- <path d="M15 41 C15 41 27 24 27 14 A12 12 0 1 0 3 14 C3 24 15 41 15 41 Z"- fill="#e5484d" stroke="#3c0c0e" stroke-width="1.5"/>- <circle cx="15" cy="14" r="4.5" fill="#fff" stroke="#3c0c0e" stroke-width="1"/>- </svg>`,- });- }+ const { size, anchor } = markerGeometry(style);return L.divIcon({className: 'sat-marker',- iconSize: [46, 46],- iconAnchor: [23, 23],- html: `<svg width="46" height="46" viewBox="0 0 46 46">- <g stroke="#000" stroke-width="4" opacity="0.55">- <line x1="1" y1="23" x2="16" y2="23"/><line x1="30" y1="23" x2="45" y2="23"/>- <line x1="23" y1="1" x2="23" y2="16"/><line x1="23" y1="30" x2="23" y2="45"/>- </g>- <g stroke="#fff" stroke-width="2">- <line x1="1" y1="23" x2="16" y2="23"/><line x1="30" y1="23" x2="45" y2="23"/>- <line x1="23" y1="1" x2="23" y2="16"/><line x1="23" y1="30" x2="23" y2="45"/>- <circle cx="23" cy="23" r="2.5" fill="none"/>- </g>- </svg>`,+ iconSize: size,+ iconAnchor: anchor,+ html: markerSvg(style),});}diff --git a/frontend/src/tools/Satellite.test.js b/frontend/src/tools/Satellite.test.jsindex 4c49c3a..b33a5de 100644--- a/frontend/src/tools/Satellite.test.js+++ b/frontend/src/tools/Satellite.test.js@@ -6,6 +6,9 @@ const cluster = readFileSync(new URL('./satellite/MapToolCluster.svelte', import.meta.url),'utf8');+// The sky overlay's geometry moved to `lib/skyOverlay.js`, where it is exercised+// against real numbers (`skyOverlay.test.js`); the tool hands it to Leaflet.+const sky = readFileSync(new URL('../lib/skyOverlay.js', import.meta.url), 'utf8');describe('Satellite saved work', () => {it('opens the case on one compact index, not on every capture row', () => {@@ -285,20 +288,23 @@ describe('sun and moon mode', () => {});it('draws only the arc the body sweeps while it is up', () => {- expect(source).toContain('function upRuns(altitudes)');- expect(source).toContain('if (altitude >= 0)');+ expect(sky).toContain('export function upRuns(altitudes)');+ expect(sky).toContain('if (altitude >= 0)');+ expect(source).toContain('for (const run of upRuns(body.altitude))');expect(source).toContain('measure.destination(origin, azimuth, reach * scale)');});it('ticks the arc hourly, longer every three hours', () => {- expect(source).toContain('if (minute % 60 || body.altitude[i] < 0) return');- expect(source).toContain('const long = minute % 180 === 0');+ expect(sky).toContain('if (minute % 60 || altitudes[i] < 0) return');+ expect(sky).toContain('long: minute % 180 === 0');+ expect(source).toContain('hourTicks(curve.minutes, body.altitude)');});it('rides the body along its own ray, as close to the anchor as it is high', () => {// the anchor stands for the zenith and the arc for the horizon, the same// radial convention as the compass rosette- expect(source).toContain('at(body.azimuth[sunIndex], (90 - altitude) / 90)');+ expect(sky).toContain('return (90 - altitude) / 90;');+ expect(source).toContain('at(body.azimuth[sunIndex], markScale(altitude))');expect(source).toContain('function bodyIcon(kind, colour, illuminated, waxing)');});@@ -308,27 +314,29 @@ describe('sun and moon mode', () => {});it('draws the moon mark at its phase, worked out of the lit fraction', () => {- expect(source).toContain('Math.acos(Math.min(1, Math.max(-1, 2 * illuminated - 1)))');- expect(source).toContain('litPath(r, illuminated, phaseAngle)');+ expect(sky).toContain('Math.acos(clamped) * 180) / Math.PI');+ expect(sky).toContain('litPath(r, illuminated, phaseAngleOf(illuminated))');// a plan view has no vertical, so the bright-limb angle is not used here- expect(source).toContain('glyphRotation(waxing)');- expect(source).not.toContain('glyphRotation(waxing, ');+ expect(sky).toContain('glyphRotation(waxing)');+ expect(sky).not.toContain('glyphRotation(waxing, ');});it('names the altitude on the mark and on the ray', () => {- expect(source).toContain('alt ${Math.round(altitude)}°');+ expect(sky).toContain('alt ${Math.round(altitude)}°');+ expect(source).toContain('bodyReading(');expect(source).toContain("bindTooltip(body.key === 'moon'");});it('keeps a body below the horizon on the map, dashed', () => {expect(source).toContain('const altitude = body.altitude[sunIndex]');- expect(source).toContain('const below = altitude < 0');+ expect(sky).toContain('return altitude < 0;');+ expect(source).toContain('const below = isBelow(altitude)');expect(source).toContain("dashArray: below ? '6 6' : null");});it('scrubs the hour without asking the backend again', () => {// the whole day arrived in one response, so the slider reads an array- expect(source).toContain('function nearestSample(clock, wanted)');+ expect(sky).toContain('export function nearestSample(clock, wanted)');expect(source).toContain('onindex={(value) => (sunIndex = value)}');expect(source).toMatch(/if \(sunDay\) params\.set\('date', sunDay\)/);});diff --git a/frontend/src/tools/Settings.render.test.js b/frontend/src/tools/Settings.render.test.jsnew file mode 100644index 0000000..25dac9f--- /dev/null+++ b/frontend/src/tools/Settings.render.test.js@@ -0,0 +1,158 @@+// @vitest-environment happy-dom+/**+ * Settings, actually mounted, on every one of its seven sections.+ *+ * The sections are separate components now (`tools/settings/`), wired to the+ * shell by props. Reading the source proves a tab exists; it cannot prove the+ * tab mounts, that a `bind:` prop the shell passes is one the section declares,+ * or that the pane still carries the class its shared layout rules hang off.+ * A section that throws on mount would otherwise reach a release green.+ */+import { describe, expect, it, afterEach, beforeEach, vi } from 'vitest';+import { flushSync, mount, unmount } from 'svelte';++// The template editors reach Konva through the composer; nothing here draws.+vi.mock('konva', () => ({ default: {} }));++vi.mock('../lib/api.js', () => ({+ api: {+ get: vi.fn(async (path) => {+ if (path.startsWith('/api/settings/scrapers')) return { scrapers: [] };+ if (path.startsWith('/api/settings/ffmpeg')) {+ return { available: true, version: '7.1', source: 'bundled', path: '/x/ffmpeg' };+ }+ if (path.startsWith('/api/settings/diagnostics')) {+ return { kind: 'bug', title: 't', report: 'body', url: 'https://example.invalid/new' };+ }+ return settingsBlob();+ }),+ put: vi.fn(async () => settingsBlob()),+ post: vi.fn(async () => ({ ingest_token: 'tok' })),+ del: vi.fn(async () => ({})),+ },+}));++function settingsBlob() {+ return {+ version: '0.2.8',+ workspace_root: '/home/analyst/Azimut',+ extension_version: '1.0',+ signature: false,+ signature_handle: '',+ api_keys: {},+ usage: {},+ month: '2026-08',+ providers_enabled: {},+ usage_overrides: {},+ provider_status: {},+ eco_zoom_fallback: true,+ eco_max_zoom: 12,+ eco_max_zooms: {},+ free_tier: {},+ free_tiers: {},+ export_dirs: { notes: '', media: '', proofs: '' },+ ingest_token: '',+ home_view: { lat: 48.85, lon: 2.29, zoom: 12 },+ post_mention: '',+ post_target: 'x',+ update_check_on_start: true,+ proof_place_auto: true,+ };+}++const { default: Settings } = await import('./Settings.svelte');++const TABS = ['general', 'publishing', 'imagery', 'templates', 'extension', 'storage', 'system'];++let live = null;++beforeEach(() => {+ const target = document.createElement('div');+ target.id = 'root';+ document.body.append(target);+ live = mount(Settings, { target });+ flushSync();+});++afterEach(() => {+ if (live) unmount(live);+ live = null;+ document.body.innerHTML = '';+});++const rail = () => [...document.querySelectorAll('.rail-tab')];+const pane = () => document.querySelector('.pane');++describe('the settings pane', () => {+ it('offers every section in the rail', () => {+ expect(rail()).toHaveLength(TABS.length);+ });++ it('carries the class its shared layout rules hang off', () => {+ // `.group`, `.row` and the segmented control live in app.css under+ // `.settings-pane`; drop the class and all seven sections lose their layout.+ expect(pane().classList.contains('settings-pane')).toBe(true);+ });++ it('mounts each section without throwing, and shows only that one', () => {+ for (const [index] of TABS.entries()) {+ rail()[index].click();+ flushSync();+ expect(pane().querySelectorAll('section.group, .workspace-folder').length).toBeGreaterThan(0);+ }+ });+});++describe('each section', () => {+ const show = (id) => {+ rail()[TABS.indexOf(id)].click();+ flushSync();+ return pane().textContent;+ };++ it('General states the coordinate and unit choices', () => {+ const text = show('general');+ expect(text).toContain('Coordinates');+ expect(text).toContain('MGRS');+ expect(text).toContain('Satellite home view');+ });++ it('Publishing states the mention and signature controls', () => {+ const text = show('publishing');+ expect(text).toContain('Geo Report');+ expect(text).toContain('Signature');+ });++ it('Imagery draws one card per keyed provider', () => {+ show('imagery');+ expect(pane().querySelectorAll('.cards .card').length).toBe(4);+ expect(pane().textContent).toContain('Eco mode');+ });++ it('Templates says when there is nothing stored yet', () => {+ const text = show('templates');+ expect(text).toContain('No proof templates yet.');+ expect(text).toContain('No post templates yet.');+ });++ it('Extension offers the download and the pairing token', () => {+ const text = show('extension');+ expect(text).toContain('Pairing');+ expect(pane().querySelector('a[href="/api/ingest/extension.zip"]')).not.toBeNull();+ });++ it('Storage manages all three export folders and the backup', () => {+ const text = show('storage');+ expect(text).toContain('Note PDFs');+ expect(text).toContain('Media copies');+ expect(text).toContain('Proof PNGs');+ expect(pane().querySelector('a[href="/api/settings/export"]')).not.toBeNull();+ });++ it('System reports the version and what ffmpeg it found', () => {+ const text = show('system');+ expect(text).toContain('0.2.8');+ expect(text).toContain('bundled');+ expect(text).toContain('Report an issue');+ });+});diff --git a/frontend/src/tools/Settings.svelte b/frontend/src/tools/Settings.svelteindex d9123b7..c2771f1 100644--- a/frontend/src/tools/Settings.svelte+++ b/frontend/src/tools/Settings.svelte@@ -7,20 +7,9 @@templatesState, loadTemplates, saveTemplate, deleteTemplate,} from '../lib/state.svelte.js';import { templateFromProof, textSignatureStyle } from '../lib/composer.js';- import { POST_TARGETS, templateFromPost } from '../lib/post.js';+ import { templateFromPost } from '../lib/post.js';import { formatCoords, parseHomeView } from '../lib/coords.js';- import { formatDistance, formatArea } from '../lib/measure.js';- import {- monthCount,- tilesOfFree,- freeTierShare,- usageBlocked,- providerStatus,- USAGE_LINKS,- BLOCK_SHARE,- ECO_MAX_ZOOM,- FREE_TIER,- } from '../lib/usage.js';+ import { USAGE_LINKS, ECO_MAX_ZOOM } from '../lib/usage.js';import { probeKey, googleMapsLoadedKey } from '../lib/gmaps.js';import { extensionVersion } from '../lib/extBridge.js';import { CASE_FOLDER_LABEL, saveDestination } from '../lib/exportDest.js';@@ -29,7 +18,13 @@import ProofTemplateEditor from '../components/ProofTemplateEditor.svelte';import PostTemplateEditor from '../components/PostTemplateEditor.svelte';import ConfirmDialog from '../components/ConfirmDialog.svelte';- import WorkspaceFolder from '../components/WorkspaceFolder.svelte';+ import ExtensionTab from './settings/ExtensionTab.svelte';+ import GeneralTab from './settings/GeneralTab.svelte';+ import ImageryTab from './settings/ImageryTab.svelte';+ import PublishingTab from './settings/PublishingTab.svelte';+ import StorageTab from './settings/StorageTab.svelte';+ import SystemTab from './settings/SystemTab.svelte';+ import TemplatesTab from './settings/TemplatesTab.svelte';// Keep workflow choices above app maintenance in the settings rail.const TABS = [@@ -135,21 +130,7 @@/** Build the per-provider shape used by key and preference state. */const perProvider = (value) => Object.fromEntries(KEYED.map((k) => [k.id, value(k)]));- const COORD_CHOICES = [- { id: 'dd', label: 'Decimal' },- { id: 'dms', label: 'DMS' },- { id: 'mgrs', label: 'MGRS' },- ];- const UNIT_CHOICES = [- { id: 'metric', label: 'Metric' },- { id: 'imperial', label: 'Imperial' },- ];-let keys = $state(perProvider(() => ''));- let shown = $state(perProvider(() => false));- // Start cards closed so setup details appear only for the selected provider.- let open = $state(perProvider(() => false));- let termsOpen = $state(false);let usage = $state({});let month = $state('');let testing = $state(perProvider(() => false));@@ -267,8 +248,6 @@}}- // Downloaders can be refreshed from PyPI between Azimut releases.- const SCRAPER_LABELS = { 'yt-dlp': 'yt-dlp', 'gallery-dl': 'gallery-dl' };let scrapers = $state([]);let checking = $state(false);let updating = $state({}); // { [dist]: true } while its request is in flight@@ -693,819 +672,117 @@{/each}</nav>- <div class="pane">+ <div class="pane settings-pane">{#if tab === 'general'}- <section class="group">- <h3>Coordinates</h3>- <div class="row">- <div class="row-label">- <span>Format</span>- <span class="row-hint">How every tool prints a latitude/longitude.</span>- </div>- <div class="seg" role="group" aria-label="Coordinate format">- {#each COORD_CHOICES as c (c.id)}- <button- class="seg-btn"- class:on={prefs.coordFormat === c.id}- onclick={() => savePrefs({ coord_format: c.id })}- >{c.label}</button>- {/each}- </div>- </div>- <p class="sample mono">{coordSample}</p>- <p class="note">- Changes display only; case data stays in decimal degrees.- </p>- </section>-- <section class="group">- <h3>Measurements</h3>- <div class="row">- <div class="row-label">- <span>Units</span>- <span class="row-hint">The Satellite ruler, area and readouts.</span>- </div>- <div class="seg" role="group" aria-label="Units">- {#each UNIT_CHOICES as c (c.id)}- <button- class="seg-btn"- class:on={prefs.units === c.id}- onclick={() => savePrefs({ units: c.id })}- >{c.label}</button>- {/each}- </div>- </div>- <p class="sample mono">- {formatDistance(1234, prefs.units)} · {formatArea(52000, prefs.units)}- </p>- </section>-- <section class="group">- <h3>Satellite home view</h3>- <p class="intro">- Default opening position for Satellite; case navigation still takes priority.- </p>- <div class="grid-3">- <label class="field">- <span>Latitude</span>- <input class="input mono" bind:value={home.lat} onchange={saveHome} inputmode="decimal" spellcheck="false" />- </label>- <label class="field">- <span>Longitude</span>- <input class="input mono" bind:value={home.lon} onchange={saveHome} inputmode="decimal" spellcheck="false" />- </label>- <label class="field">- <span>Zoom</span>- <input class="input mono" bind:value={home.zoom} onchange={saveHome} type="number" min="1" max="21" />- </label>- </div>- </section>-- <section class="group">- <h3>Proofs</h3>- <p class="intro">- Saving a proof turns the coordinates it carries into a place on the map, and- says the proof shows it.- </p>- <div class="row">- <div class="row-label">- <span>Save the point without asking</span>- <span class="row-hint">- Off, the composer asks each time. A point already saved is never asked about.- </span>- </div>- <input- type="checkbox"- bind:checked={proofPlaceAuto}- onchange={() => savePrefs({ proof_place_auto: proofPlaceAuto })}- aria-label="Save a proof's point without asking"- />- </div>- </section>+ <GeneralTab+ {prefs}+ {home}+ {coordSample}+ {savePrefs}+ {saveHome}+ bind:proofPlaceAuto+ />{/if}{#if tab === 'publishing'}- <section class="group">- <h3>Geo Report</h3>- <div class="row">- <div class="row-label">- <span>Default mention</span>- <span class="row-hint">Pre-filled on a new draft. Leave empty for none.</span>- </div>- <input- class="input mention"- bind:value={mention}- onchange={() => savePrefs({ post_mention: mention })}- placeholder="@GeoConfirmed"- spellcheck="false"- />- </div>- <div class="row">- <div class="row-label">- <span>Preferred platform</span>- <span class="row-hint">Used for new Geo Report drafts.</span>- </div>- <div class="seg" role="group" aria-label="Preferred platform">- {#each Object.values(POST_TARGETS) as option (option.id)}- <button- class="seg-btn"- class:on={postTarget === option.id}- onclick={() => {- postTarget = option.id;- savePrefs({ post_target: option.id });- }}- >{option.label}</button>- {/each}- </div>- </div>- </section>-- <section class="group">- <h3>Signature</h3>- <div class="row">- <div class="row-label">- <span>Your account handle</span>- <span class="row-hint">Shown on proofs that enable “Add account handle”.</span>- </div>- <input- class="input mention"- bind:value={signatureHandle}- onchange={() => savePrefs({ signature_handle: signatureHandle })}- placeholder="@my_handle"- maxlength="64"- spellcheck="false"- />- </div>- <div class="row">- <div class="row-label">- <span>Your logo</span>- <span class="row-hint">- Transparent PNG, up to 2 MB, used only on signed proofs.- </span>- </div>- <div class="sig-side">- {#if signature}- <img class="sig-preview" src={`/api/settings/signature.png?v=${sigBust}`} alt="Your signature" />- {/if}- <div class="sig-buttons">- <button class="btn btn-sm" onclick={() => sigInput?.click()}>- {signature ? 'Replace…' : 'Choose PNG…'}- </button>- {#if signature}- <button class="btn btn-danger btn-sm" onclick={removeSignature}>Remove</button>- {/if}- </div>- </div>- <input- bind:this={sigInput}- class="sig-file"- type="file"- accept="image/png"- onchange={uploadSignature}- />- </div>- </section>+ <PublishingTab+ {signature}+ {sigBust}+ {savePrefs}+ {removeSignature}+ {uploadSignature}+ bind:mention+ bind:postTarget+ bind:signatureHandle+ bind:sigInput+ />{/if}{#if tab === 'imagery'}- <section class="group">- <h3>Providers</h3>- <p class="intro">- Add provider keys to unlock more Satellite basemaps; usage appears on each card.- </p>-- <div class="cards">- {#each KEYED as k (k.id)}- {@const count = monthCount(usage, k.id, month)}- {@const share = freeTierShare(count, k.id, tiers)}- {@const st = providerStatus({- key: keys[k.id],- enabled: enabled[k.id],- status: testResult[k.id],- count,- meter: k.id,- overrides,- tiers,- })}- <div class="card" class:open={open[k.id]}>- <div class="card-head">- <button- class="card-toggle"- onclick={() => (open[k.id] = !open[k.id])}- aria-expanded={open[k.id]}- >- <Icon name={open[k.id] ? 'chevronDown' : 'chevronRight'} size={13} />- <span class="card-name">{k.label}</span>- <span class="card-gives">{k.gives}</span>- </button>- <span- class="chip {st.tone}"- title={st.tone === 'bad' ? testResult[k.id]?.detail : undefined}- >{st.label}</span>- {#if keys[k.id]}- <input- class="card-enable"- type="checkbox"- bind:checked={enabled[k.id]}- onchange={saveProviderPrefs}- title="Show or hide this basemap in the Satellite tab"- aria-label="Show {k.label} in the Satellite tab"- />- {/if}- </div>-- <!-- one line either way: what it would cost, or what it has cost -->- {#if keys[k.id] || count}- <div class="card-meter">- <div class="meter-track" aria-hidden="true">- <div- class="meter-fill"- class:hot={share >= BLOCK_SHARE}- style="width:{Math.min(share * 100, 100)}%"- ></div>- </div>- <span class="mono meter-read">{tilesOfFree(count, k.id, tiers)}</span>- </div>- {:else if !open[k.id]}- <!-- open, the body's overage already leads with the cost -->- <p class="card-cost">{k.cost}</p>- {/if}-- {#if open[k.id]}- <div class="card-body">- {#if k.warning}- <p class="key-warning"><Icon name="alert" size={12} /> {k.warning}</p>- {/if}- {#if k.steps}- <ol class="key-steps">- {#each k.steps as step (step)}- <li>{step}</li>- {/each}- </ol>- {/if}-- <label class="key-label" for="key-{k.id}">- {k.field}- <a href={k.help} target="_blank" rel="noreferrer" title="How to get one">- how to get one <Icon name="external" size={11} />- </a>- </label>- <div class="key-line">- <input- id="key-{k.id}"- class="input"- type={shown[k.id] ? 'text' : 'password'}- placeholder={k.placeholder}- bind:value={keys[k.id]}- onchange={() => saveKey(k.id)}- autocomplete="off"- spellcheck="false"- />- <button- class="btn btn-ghost btn-sm"- onclick={() => (shown[k.id] = !shown[k.id])}- title={shown[k.id] ? 'Hide key' : 'Show key'}- aria-label={shown[k.id] ? 'Hide key' : 'Show key'}- >- <Icon name={shown[k.id] ? 'eyeOff' : 'eye'} size={14} />- </button>- <button- class="btn btn-sm"- onclick={() => testKey(k.id)}- disabled={testing[k.id] || !keys[k.id].trim()}- title="Exercise this key against the real service"- >- {testing[k.id] ? 'Testing…' : 'Test'}- </button>- </div>- {#if testResult[k.id] && !testResult[k.id].ok}- <p class="verdict bad">- <Icon name="alert" size={12} />- {testResult[k.id].detail}- </p>- {/if}-- <p class="overage">{k.cost}. {k.overage}</p>-- {#if keys[k.id] || count}- {#if usageBlocked(count, k.id, overrides, tiers)}- <p class="blocked">- <Icon name="alert" size={12} />- Paused at {Math.round(BLOCK_SHARE * 100)}% of the free tier. The map and- captures fall back to free imagery until next month, or:- </p>- {/if}- {#if share >= BLOCK_SHARE || overrides[k.id]}- <label- class="toggle override"- title="Serve past the pause (extra tiles are billed)"- >- <input- type="checkbox"- bind:checked={overrides[k.id]}- onchange={saveProviderPrefs}- />- keep serving past {Math.round(BLOCK_SHARE * 100)}% (billed)- </label>- {/if}-- <div class="card-controls">- <label- class="ctrl"- title={k.tierNote ??- "This account's monthly free allowance. Check the provider dashboard"}- >- <span>Free allowance</span>- <input- class="input num mono"- type="number"- min="1"- step="1000"- placeholder={String(FREE_TIER[k.id] ?? '')}- bind:value={tierEdits[k.id]}- onchange={saveFreeTier}- />- <span class="ctrl-note">- {tierEdits[k.id].trim() === ''- ? 'blank = the documented default'- : `default is ${(FREE_TIER[k.id] ?? 0).toLocaleString('en-US')}`}- </span>- </label>-- {#if k.browserTest}- <p class="ctrl-note">- Eco mode is unavailable because reopening this widget starts another billed map load.- </p>- {:else}- <label- class="ctrl"- title="Blank uses global; 0 disables eco mode"- >- <span>Eco below z ≤</span>- <input- class="input num mono"- type="number"- min="0"- max="21"- placeholder={k.id === 'sentinelhub' ? '11' : String(ecoMaxZoom)}- bind:value={ecoZooms[k.id]}- onchange={saveEcoZoom}- disabled={!eco}- aria-label="Eco threshold for {k.label}"- />- <span class="ctrl-note">- {k.id === 'sentinelhub'- ? 'blank = 11 (it caps at z14)'- : 'blank = the global threshold'}- </span>- </label>- {/if}- </div>-- <a class="card-link" href={k.usage} target="_blank" rel="noreferrer">- {k.label} usage & limits <Icon name="external" size={11} />- </a>- {/if}- </div>- {/if}- </div>- {/each}- </div>-- <div class="cards-foot">- <span class="row-hint">Counters for {month}. Stored locally.</span>- <button class="btn btn-ghost btn-sm" onclick={() => load()} title="Refresh counters">- <Icon name="reset" size={13} /> Refresh- </button>- </div>- </section>-- <section class="group">- <h3>Eco mode</h3>- <label- class="toggle eco"- title="Zoomed out this far, billed basemaps swap to free imagery"- >- <input type="checkbox" bind:checked={eco} onchange={saveEcoZoom} />- Use free imagery when zoomed out, up to z ≤- <input- class="input num mono"- type="number"- min="1"- max="21"- bind:value={ecoMaxZoom}- onchange={saveEcoZoom}- disabled={!eco}- aria-label="Eco mode zoom threshold"- />- </label>- <p class="note">- Applies while zoomed out; provider cards can override it.- </p>- </section>-- <section class="group">- <div class="card">- <div class="card-head">- <button- class="card-toggle"- onclick={() => (termsOpen = !termsOpen)}- aria-expanded={termsOpen}- >- <Icon name={termsOpen ? 'chevronDown' : 'chevronRight'} size={13} />- <span class="card-name">Provider terms</span>- <span class="card-gives">Applied automatically</span>- </button>- </div>- {#if termsOpen}- <ul class="rules">- <li>Google tiles are not cached; captures are screenshots with attribution.</li>- <li>Mapbox attribution remains attached to captures.</li>- <li>Provider keys stay outside cases and exports.</li>- </ul>- {/if}- </div>- </section>+ <ImageryTab+ {KEYED}+ {keys}+ {usage}+ {month}+ {tiers}+ {tierEdits}+ {enabled}+ {overrides}+ {testResult}+ {testing}+ {ecoZooms}+ {load}+ {saveKey}+ {testKey}+ {saveProviderPrefs}+ {saveEcoZoom}+ {saveFreeTier}+ bind:eco+ bind:ecoMaxZoom+ />{/if}{#if tab === 'extension'}- <section class="group">- <h3>Capture extension</h3>- <p class="note">- Captures supported map sites and powers the Google basemap Capture button.- </p>- <div class="row">- <div class="row-label">- <span>Status in this browser</span>- <span class="row-hint">- {#if extDetected}- detected · <span class="mono">v{extDetected}</span>- {#if extOutdated}- · update bundled (<span class="mono">v{about.extension_version}</span>)- {/if}- {:else}- not detected. After installing, reload this tab- {/if}- </span>- </div>- <a class="btn btn-sm btn-primary dotted" href="/api/ingest/extension.zip" download>- <Icon name="download" size={13} />- {extOutdated ? 'Download update (.zip)' : 'Download extension (.zip)'}- {#if badges.extension}- <span- class="update-dot"- aria-label={extOutdated ? 'an update is waiting' : 'not installed yet'}- ></span>- {/if}- </a>- </div>- {#if extOutdated}- <p class="note warn">- Bundled v{about.extension_version} is newer than installed v{extDetected}; replace- the unpacked folder and reload the extension.- </p>- {/if}- <p class="note">- Unzip it, load it as an unpacked extension, then reload this tab.- </p>- </section>-- <section class="group">- <h3>Pairing</h3>- <p class="note">- Paste this token into the extension options; rotating it unpairs existing extensions.- </p>- <div class="row">- <div class="row-label">- <span>Pairing token</span>- <span class="row-hint mono">{tokenShown ? ingestToken : '•'.repeat(24)}</span>- </div>- <div class="scraper-actions">- <button class="btn btn-sm" onclick={async () => { await ensureToken(); tokenShown = !tokenShown; }}>- {tokenShown ? 'Hide' : 'Show'}- </button>- <button class="btn btn-sm btn-primary" onclick={copyToken}>- <Icon name="copy" size={13} /> Copy- </button>- <button class="btn btn-sm" onclick={rotateToken}>Rotate</button>- </div>- </div>- <p class="note">- The extension can file one user-requested map capture through this local app.- </p>- </section>+ <ExtensionTab+ {about}+ {badges}+ {extDetected}+ {extOutdated}+ {ingestToken}+ {copyToken}+ {ensureToken}+ {rotateToken}+ bind:tokenShown+ />{/if}{#if tab === 'storage'}- <WorkspaceFolder onchange={(status) => (about.workspace_root = status.root)} />-- <section class="group">- <h3>Export folders</h3>- <p class="note">Choose a folder for each export type.</p>- {#each EXPORT_KINDS as kind (kind.id)}- <div class="row">- <div class="row-label">- <span>{kind.label}</span>- <span class="row-hint mono export-path" title={exportDirs[kind.id] || CASE_FOLDER_LABEL}>- {exportDirs[kind.id] || CASE_FOLDER_LABEL}- </span>- </div>- <div class="scraper-actions">- <button class="btn btn-sm" onclick={() => (exportPickerKind = kind.id)}>Change…</button>- <button- class="btn btn-ghost btn-sm"- onclick={() => resetExportDestination(kind.id)}- disabled={!exportDirs[kind.id]}- >Reset</button>- </div>- </div>- {/each}- </section>-- <section class="group">- <h3>Settings backup</h3>- <p class="note">- Carries settings, keys, templates and your signature; export folders and- download logins stay here, so keep this backup private.- </p>- <div class="links">- <a class="btn btn-sm" href="/api/settings/export" download>- <Icon name="save" size={13} /> Export backup- </a>- <button class="btn btn-sm" onclick={() => settingsFile?.click()}>- <Icon name="file" size={13} /> Import backup- </button>- <input- type="file"- accept="application/json,.json"- bind:this={settingsFile}- onchange={importSettings}- hidden- />- </div>- </section>+ <StorageTab+ {about}+ {exportDirs}+ {EXPORT_KINDS}+ {importSettings}+ {resetExportDestination}+ bind:exportPickerKind+ bind:settingsFile+ />{/if}{#if tab === 'system'}- <section class="group">- <h3>Azimut</h3>- <dl class="facts">- <dt>Version</dt>- <dd class="mono">{about.version || '—'}</dd>- <dt>ffmpeg</dt>- <dd class="mono" title={ffmpeg.path || ''}>- {#if ffmpeg.available}- {ffmpeg.version || 'installed'}- <span class="sub">· {ffmpeg.source === 'bundled' ? 'bundled' : 'system PATH'}</span>- {:else}- not found <span class="sub">· install ffmpeg on your PATH</span>- {/if}- </dd>- <dt>License</dt>- <dd>AGPL-3.0-only</dd>- </dl>- <p class="note">- Case data stays in the workspace; network access is limited to requested features- and the automatic GitHub update check.- </p>- <div class="links">- <a class="btn btn-sm" href={REPO_URL} target="_blank" rel="noreferrer">- <Icon name="link" size={13} /> Source & issues <Icon name="external" size={11} />- </a>- <a class="btn btn-sm" href={SITE_URL} target="_blank" rel="noreferrer">- <Icon name="globe" size={13} /> osintmethat.com <Icon name="external" size={11} />- </a>- </div>- </section>-- <section class="group">- <h3>Updates</h3>- <div class="row">- <div class="row-label">- <span>Check for a newer release</span>- <span class="row-hint">- {#if appUpdate?.update_available}- <span class="mono">{appUpdate.latest}</span> is out. You have- <span class="mono">{about.version}</span>- {:else if appUpdate && !appUpdate.error}- you're on the latest (<span class="mono">{about.version}</span>)- {:else}- {updateOnStart- ? 'checks GitHub on startup and when requested'- : 'checks GitHub when requested'}- {/if}- </span>- </div>- {#if appUpdate?.update_available}- <a class="btn btn-sm btn-primary dotted" href={appUpdate.url} target="_blank" rel="noreferrer">- <Icon name="download" size={13} /> Get {appUpdate.latest} <Icon name="external" size={11} />- {#if badges.app}- <span class="update-dot" aria-label="an update is waiting"></span>- {/if}- </a>- {:else}- <button class="btn btn-sm" onclick={checkAppUpdate} disabled={checkingApp}>- {checkingApp ? 'Checking…' : 'Check for updates'}- </button>- {/if}- </div>- <div class="row">- <div class="row-label">- <span>Tell me on startup</span>- <span class="row-hint">- Asks GitHub and PyPI once when the app opens, and marks what is behind.- </span>- </div>- <input- type="checkbox"- bind:checked={updateOnStart}- onchange={() => savePrefs({ update_check_on_start: updateOnStart })}- aria-label="Check for updates on startup"- />- </div>- <p class="note">- Update with <span class="mono">pipx upgrade azimut</span>; standalone users replace- the downloaded binary.- </p>- </section>-- <section class="group">- <h3>Report an issue</h3>- <p class="note">- Opens a new issue on the public GitHub tracker; anyone can read it.- </p>- <div class="report-kind">- <label>- <input- type="radio"- value="bug"- bind:group={reportKind}- onchange={loadReport}- /> Something is broken- </label>- <label>- <input- type="radio"- value="idea"- bind:group={reportKind}- onchange={loadReport}- /> Something is missing- </label>- </div>- <textarea- class="report-summary"- rows="3"- maxlength="2000"- placeholder={reportKind === 'bug'- ? 'What you did, what you expected, what you got'- : 'What you would like Azimut to do'}- bind:value={reportSummary}- oninput={refreshReport}- ></textarea>- {#if report}- <details class="report-preview">- <summary>What gets sent</summary>- <pre class="mono">{report.report}</pre>- </details>- {/if}- <div class="links">- <a- class="btn btn-sm btn-primary"- href={report?.url || `${REPO_URL}/issues/new`}- target="_blank"- rel="noreferrer"- >- <Icon name="link" size={13} /> Open a GitHub issue <Icon name="external" size={11} />- </a>- <button class="btn btn-sm" onclick={copyReport} disabled={!report}>- <Icon name="copy" size={13} /> Copy report- </button>- </div>- <p class="note">- Your text, the version, the OS and the last warnings of this run, with your- paths, account name, case names and any keys removed. Nothing leaves the app- until you open the issue.- </p>- </section>-- <section class="group">- <h3>Downloaders</h3>- <p class="note">- Update these tools if a media link stops resolving.- </p>- {#each scrapers as s (s.dist)}- <div class="row">- <div class="row-label">- <span>{SCRAPER_LABELS[s.dist] ?? s.dist}</span>- <span class="row-hint">- <span class="mono">{s.version || 'not installed'}</span>- {#if s.source === 'runtime'}- · updated in place{#if s.bundled_version}, shipped with {s.bundled_version}{/if}- {:else}- · as shipped- {/if}- {#if s.restart_required}- · <span class="stale">restart to apply</span>- {:else if s.outdated}- · <span class="stale">{s.latest} available</span>- {:else if s.latest}- · up to date- {/if}- </span>- </div>- <div class="scraper-actions">- {#if s.source === 'runtime'}- <button class="btn btn-sm" onclick={() => resetScraper(s.dist)}>Revert</button>- {/if}- <button- class="btn btn-sm dotted"- class:btn-primary={s.outdated}- disabled={updating[s.dist]}- onclick={() => updateScraper(s.dist)}- >- {updating[s.dist] ? 'Updating…' : 'Update'}- {#if s.outdated && !updating[s.dist]}- <span class="update-dot" aria-label="an update is waiting"></span>- {/if}- </button>- </div>- </div>- {/each}- <div class="links">- <button class="btn btn-sm" disabled={checking} onclick={checkScrapers}>- <Icon name="download" size={13} />- {checking ? 'Checking…' : 'Check for updates'}- </button>- </div>- <p class="note">- Updates are hash-verified from PyPI when requested; Revert restores the bundled version.- </p>- </section>+ <SystemTab+ {about}+ {ffmpeg}+ {badges}+ {appUpdate}+ {checkingApp}+ {checkAppUpdate}+ {scrapers}+ {checking}+ {checkScrapers}+ {updating}+ {updateScraper}+ {resetScraper}+ {savePrefs}+ {report}+ {loadReport}+ {refreshReport}+ {copyReport}+ {REPO_URL}+ {SITE_URL}+ bind:updateOnStart+ bind:reportKind+ bind:reportSummary+ />{/if}{#if tab === 'templates'}- <section class="group">- <h3>Geo Proof templates</h3>- <p class="note">- Reusable proof styles shared across cases.- </p>- <div class="tpl-list">- {#each templatesState.proof as t (t.id)}- <div class="tpl-row">- <span class="tpl-name">{t.name}</span>- <div class="tpl-actions">- <button class="btn btn-sm" onclick={() => editTemplate('proof', t)}>- <Icon name="edit" size={13} /> Edit- </button>- <button class="btn btn-sm" title="Delete"- onclick={() => (deleteTpl = { kind: 'proof', id: t.id, name: t.name })}>- <Icon name="trash" size={13} />- </button>- </div>- </div>- {/each}- {#if !templatesState.proof.length}- <p class="empty">No proof templates yet.</p>- {/if}- </div>- <button class="btn btn-sm" onclick={() => newTemplate('proof')}>- <Icon name="plus" size={13} /> New proof template- </button>- </section>-- <section class="group">- <h3>Geo Report templates</h3>- <p class="note">- Reusable thread structures for new Geo Reports.- </p>- <div class="tpl-list">- {#each templatesState.post as t (t.id)}- <div class="tpl-row">- <span class="tpl-name">{t.name}</span>- <div class="tpl-actions">- <button class="btn btn-sm" onclick={() => editTemplate('post', t)}>- <Icon name="edit" size={13} /> Edit- </button>- <button class="btn btn-sm" title="Delete"- onclick={() => (deleteTpl = { kind: 'post', id: t.id, name: t.name })}>- <Icon name="trash" size={13} />- </button>- </div>- </div>- {/each}- {#if !templatesState.post.length}- <p class="empty">No post templates yet.</p>- {/if}- </div>- <button class="btn btn-sm" onclick={() => newTemplate('post')}>- <Icon name="plus" size={13} /> New post template- </button>- </section>+ <TemplatesTab {newTemplate} {editTemplate} bind:deleteTpl />{/if}</div></div></div>+{#if exportPickerKind}<ExportFolderPickerkind={exportPickerKind}@@ -1555,25 +832,25 @@/>{/if}+<style>.tool {height: 100%;display: flex;flex-direction: column;}+.tool-header {display: flex;align-items: baseline;gap: 12px;padding: 14px 18px 10px;}+.tool-header h2 {font-size: var(--fs-lg);}- .sub {- color: var(--text-3);- font-size: var(--fs-sm);- }+/* Settings use a section rail and one scrolling pane. */.split {@@ -1581,6 +858,7 @@display: flex;min-height: 0;}+.rail {width: 168px;flex-shrink: 0;@@ -1590,6 +868,7 @@padding: 4px 8px 8px 12px;border-right: 1px solid var(--border);}+.rail-tab {display: flex;align-items: center;@@ -1605,22 +884,18 @@cursor: pointer;transition: background 0.12s var(--ease), color 0.12s var(--ease);}- /* A rail tab is a full-width row, not a control with a corner, so its dot- sits at the end of the line instead of hanging off it. */- .rail-tab .update-dot {- top: 50%;- right: 9px;- transform: translateY(-50%);- }+.rail-tab:hover {background: var(--bg-2);color: var(--text-1);}+.rail-tab.active {background: var(--accent-soft);color: var(--accent);font-weight: 600;}+.rail-tab.rail-break {margin-top: 8px;padding-top: 10px;@@ -1629,541 +904,16 @@border-top-right-radius: 0;}+.pane {flex: 1;overflow-y: auto;padding: 6px 18px 32px;max-width: 640px;}- .group {- padding: 14px 0 18px;- border-bottom: 1px solid var(--border);- }- .group:last-child {- border-bottom: 0;- }- h3 {- display: flex;- align-items: center;- gap: 7px;- font-size: var(--fs-xs);- font-weight: 700;- text-transform: uppercase;- letter-spacing: 0.06em;- color: var(--text-3);- margin-bottom: 12px;- }-- .row {- display: flex;- align-items: center;- justify-content: space-between;- gap: 18px;- margin-bottom: 8px;- }- .row-label {- display: flex;- flex-direction: column;- gap: 2px;- font-size: var(--fs-sm);- color: var(--text-1);- }- .row-hint {- color: var(--text-3);- font-size: var(--fs-xs);- line-height: 1.4;- }- .export-path {- display: block;- max-width: min(380px, 48vw);- overflow: hidden;- text-overflow: ellipsis;- white-space: nowrap;- }- /* Recipe for a provider whose "key" is a configuration you build yourself */- .key-steps {- margin: 4px 0 8px;- padding-left: 18px;- color: var(--text-3);- font-size: var(--fs-xs);- line-height: 1.5;- }- .key-steps li {- margin: 1px 0;- }- .key-warning {- display: flex;- align-items: baseline;- gap: 5px;- margin: 4px 0 8px;- color: var(--warn, #d8a03d);- font-size: var(--fs-xs);- line-height: 1.45;- }- .scraper-actions {- display: flex;- align-items: center;- gap: 6px;- }- /* the one state worth pulling the eye: this downloader will fail on real links */- .stale {- color: var(--warn, var(--text-1));- font-weight: 500;- }- .sig-side {- display: flex;- align-items: center;- gap: 10px;- }- .sig-preview {- /* Checkerboard preview for transparent logos. */- max-width: 88px;- max-height: 44px;- padding: 4px;- border: 1px solid var(--border);- border-radius: var(--r-sm);- background-color: var(--bg-2);- background-image:- linear-gradient(45deg, var(--bg-3) 25%, transparent 25% 75%, var(--bg-3) 75%),- linear-gradient(45deg, var(--bg-3) 25%, transparent 25% 75%, var(--bg-3) 75%);- background-size: 10px 10px;- background-position: 0 0, 5px 5px;- }- .sig-buttons {- display: flex;- gap: 6px;- }- .sig-file {- display: none;- }-- /* One-row segmented control. */- .seg {- display: flex;- flex-shrink: 0;- border: 1px solid var(--border);- border-radius: var(--r-md);- overflow: hidden;- }- .seg-btn {- padding: 5px 12px;- border: 0;- border-left: 1px solid var(--border);- background: var(--bg-2);- color: var(--text-2);- font: inherit;- font-size: var(--fs-xs);- cursor: pointer;- transition: background 0.12s var(--ease), color 0.12s var(--ease);- }- .seg-btn:first-child {- border-left: 0;- }- .seg-btn:hover {- background: var(--bg-3);- color: var(--text-1);- }- .seg-btn.on {- background: var(--accent);- color: var(--accent-text);- font-weight: 600;- }-- .sample {- color: var(--text-2);- font-size: var(--fs-sm);- padding: 6px 9px;- border-radius: var(--r-sm);- background: var(--bg-2);- border: 1px solid var(--border);- display: inline-block;- margin-top: 4px;- }- .note {- color: var(--text-3);- font-size: var(--fs-xs);- line-height: 1.5;- margin-top: 8px;- }- .note.warn {- color: var(--warn, #d8a03d);- }- /* same voice as .note, but leading a group instead of trailing one */- .intro {- color: var(--text-3);- font-size: var(--fs-xs);- line-height: 1.5;- margin: 0 0 14px;- }-- .grid-3 {- display: grid;- grid-template-columns: 1fr 1fr 90px;- gap: 10px;- }- .field {- display: flex;- flex-direction: column;- gap: 4px;- font-size: var(--fs-xs);- color: var(--text-2);- font-weight: 600;- }- .mention {- width: 200px;- flex-shrink: 0;- }- .facts {- display: grid;- grid-template-columns: max-content 1fr;- gap: 6px 18px;- margin: 0;- font-size: var(--fs-sm);- }- .facts dt {- color: var(--text-3);- font-size: var(--fs-xs);- align-self: center;- }- .facts dd {- margin: 0;- color: var(--text-1);- overflow-wrap: anywhere;- }/* The path can be long, so the button sits after it and never squeezes it. */- .workspace-fact {- display: flex;- align-items: center;- gap: 8px;- flex-wrap: wrap;- }- .links {- display: flex;- gap: 8px;- margin-top: 14px;- flex-wrap: wrap;- }- /* Report an issue: kind, the user's words, then the report itself folded away. */- .report-kind {- display: flex;- gap: 16px;- margin: 10px 0 8px;- font-size: var(--fs-xs);- color: var(--text-2);- }- .report-kind label {- display: flex;- align-items: center;- gap: 6px;- }- .report-summary {- width: 100%;- resize: vertical;- font: inherit;- font-size: var(--fs-sm);- }- .report-preview {- margin-top: 10px;- font-size: var(--fs-xs);- }- .report-preview summary {- color: var(--text-3);- cursor: pointer;- }- .report-preview pre {- margin: 8px 0 0;- padding: 8px 10px;- max-height: 240px;- overflow: auto;- white-space: pre-wrap;- overflow-wrap: anywhere;- background: var(--bg-2);- border: 1px solid var(--border);- border-radius: var(--r-sm);- color: var(--text-2);- }- .links .btn {- gap: 6px;- text-decoration: none;- }-- /* Provider cards show a summary until opened for setup. */- .cards {- display: flex;- flex-direction: column;- gap: 6px;- }- .card {- border: 1px solid var(--border);- border-radius: var(--r-md);- padding: 8px 10px;- background: var(--bg-2);- transition: border-color 0.12s var(--ease);- }- .card.open {- border-color: var(--text-3);- background: none;- }- .card-head {- display: flex;- align-items: center;- gap: 10px;- }- .card-toggle {- flex: 1;- min-width: 0;- display: flex;- align-items: center;- gap: 8px;- padding: 0;- border: 0;- background: none;- color: var(--text-3);- font: inherit;- text-align: left;- cursor: pointer;- }- .card-name {- font-size: var(--fs-sm);- font-weight: 600;- color: var(--text-1);- flex-shrink: 0;- }- .card-gives {- font-size: var(--fs-xs);- color: var(--text-3);- overflow: hidden;- text-overflow: ellipsis;- white-space: nowrap;- }- .card-enable {- accent-color: var(--accent);- margin: 0;- flex-shrink: 0;- cursor: pointer;- }- /* One-word verdict; the tooltip carries the detail. */- .chip {- flex-shrink: 0;- padding: 1px 7px;- border-radius: 999px;- border: 1px solid var(--border);- font-size: var(--fs-xs);- color: var(--text-3);- white-space: nowrap;- }- .chip.ok {- color: var(--ok);- border-color: color-mix(in srgb, var(--ok) 40%, transparent);- }- .chip.bad {- color: var(--danger);- border-color: color-mix(in srgb, var(--danger) 40%, transparent);- }- .chip.warn {- color: var(--warn, #d8a03d);- border-color: color-mix(in srgb, var(--warn, #d8a03d) 40%, transparent);- }- .card-meter {- display: flex;- align-items: center;- gap: 9px;- margin: 7px 0 1px;- }- .card-meter .meter-track {- flex: 1;- }- .meter-read,- .card-cost {- font-size: var(--fs-xs);- color: var(--text-3);- white-space: nowrap;- }- .card-cost {- margin: 5px 0 1px 21px; /* aligned under the name, past the chevron */- }- .card-body {- margin-top: 12px;- padding-top: 12px;- border-top: 1px solid var(--border);- }- .card-controls {- display: flex;- flex-direction: column;- gap: 7px;- margin-top: 9px;- }- .ctrl {- display: flex;- align-items: center;- gap: 8px;- font-size: var(--fs-xs);- color: var(--text-3);- }- /* Align provider control fields in one column. */- .ctrl > span:first-child {- min-width: 104px;- color: var(--text-2);- }- .ctrl-note {- opacity: 0.8;- }- .card-link {- display: inline-flex;- align-items: center;- gap: 4px;- margin-top: 10px;- color: var(--accent);- font-size: var(--fs-xs);- }- .cards-foot {- display: flex;- align-items: center;- justify-content: space-between;- gap: 12px;- margin-top: 12px;- }- .key-label {- display: flex;- align-items: baseline;- gap: 10px;- font-size: var(--fs-xs);- color: var(--text-2);- font-weight: 600;- margin-bottom: 5px;- }- .key-label a {- color: var(--accent);- font-weight: 400;- display: inline-flex;- align-items: center;- gap: 3px;- }- .key-line {- display: flex;- gap: 6px;- align-items: center;- }- .key-line .input {- flex: 1;- font-family: var(--font-mono);- }- .verdict {- display: flex;- align-items: center;- gap: 4px;- margin-top: 5px;- font-size: var(--fs-xs);- line-height: 1.4;- }- .verdict.bad {- color: var(--danger);- }- .meter-track {- height: 5px;- border-radius: var(--r-sm);- background: var(--bg-2);- border: 1px solid var(--border);- overflow: hidden;- }- .meter-fill {- height: 100%;- background: var(--accent);- border-radius: inherit;- transition: width 0.3s var(--ease);- }- .meter-fill.hot {- background: var(--danger);- }- .overage {- margin-top: 9px;- color: var(--text-3);- font-size: var(--fs-xs);- line-height: 1.45;- }- .toggle {- display: inline-flex;- align-items: center;- gap: 6px;- font-size: var(--fs-xs);- color: var(--text-2);- cursor: pointer;- user-select: none;- }- .toggle input {- accent-color: var(--accent);- margin: 0;- }- .toggle.override {- margin-top: 6px;- color: var(--danger);- }- .toggle.eco {- display: flex;- margin: 2px 0;- }- /* every small numeric box in this tab: eco thresholds, free allowances */- .num {- width: 92px;- padding: 2px 6px;- flex-shrink: 0;- }- .blocked {- margin-top: 6px;- color: var(--danger);- font-size: var(--fs-xs);- display: flex;- align-items: center;- gap: 5px;- line-height: 1.4;- }- .rules {- margin: 12px 0 2px;- padding-left: 18px;- color: var(--text-2);- font-size: var(--fs-xs);- display: flex;- flex-direction: column;- gap: 6px;- line-height: 1.45;- }-- /* --- templates tab ------------------------------------------------------ */- .tpl-list {- display: flex;- flex-direction: column;- gap: 6px;- margin-bottom: 12px;- }- .tpl-row {- display: flex;- align-items: center;- justify-content: space-between;- gap: 12px;- padding: 7px 10px;- border: 1px solid var(--border);- border-radius: var(--r-md);- background: var(--bg-2);- }- .tpl-name {- font-size: var(--fs-sm);- color: var(--text-1);- overflow: hidden;- text-overflow: ellipsis;- white-space: nowrap;- }- .tpl-actions {- display: flex;- gap: 6px;- flex-shrink: 0;- }- .empty {- color: var(--text-3);- font-size: var(--fs-sm);- font-style: italic;- }.tpl-modal-overlay {position: fixed;@@ -2175,6 +925,7 @@justify-content: center;padding: 24px;}+.tpl-modal {width: min(920px, 100%);max-height: 88vh;@@ -2185,6 +936,7 @@border-radius: var(--r-lg, 12px);box-shadow: 0 20px 60px rgba(0, 0, 0, 0.4);}+.tpl-modal-head {display: flex;align-items: center;@@ -2192,6 +944,7 @@padding: 12px 14px;border-bottom: 1px solid var(--border);}+.tpl-title {flex: 1;background: var(--bg-2);@@ -2202,10 +955,12 @@font: inherit;font-weight: 600;}+.tpl-modal-body {padding: 16px;overflow-y: auto;}+.tpl-modal-foot {display: flex;justify-content: flex-end;diff --git a/frontend/src/tools/Settings.test.js b/frontend/src/tools/Settings.test.jsindex 18f5384..6c8c89f 100644--- a/frontend/src/tools/Settings.test.js+++ b/frontend/src/tools/Settings.test.js@@ -1,98 +1,126 @@import { describe, expect, it } from 'vitest';import { readFileSync } from 'node:fs';-const source = readFileSync(new URL('./Settings.svelte', import.meta.url), 'utf8');+const read = (name) => readFileSync(new URL(name, import.meta.url), 'utf8');++const shell = read('./Settings.svelte');+const storage = read('./settings/StorageTab.svelte');+const system = read('./settings/SystemTab.svelte');+const general = read('./settings/GeneralTab.svelte');++// The tabs are seven components rendering into one pane, so an assertion about a+// section reads that section's file. Assertions about the load/save side read the+// shell, which still owns every request.+const family = [shell, storage, system, general].join('\n');describe('Report an issue', () => {it('lets the user say what happened, bug or request', () => {- expect(source).toContain("let reportKind = $state('bug')");- expect(source).toContain('bind:value={reportSummary}');- expect(source).toContain('maxlength="2000"');- expect(source).toContain('Something is broken');- expect(source).toContain('Something is missing');+ expect(shell).toContain("let reportKind = $state('bug')");+ expect(system).toContain('bind:value={reportSummary}');+ expect(system).toContain('maxlength="2000"');+ expect(system).toContain('Something is broken');+ expect(system).toContain('Something is missing');});it('asks the server for the report and debounces typing', () => {- expect(source).toContain("api.get(`/api/settings/diagnostics?${params}`)");- expect(source).toContain('clearTimeout(reportTimer)');- expect(source).toContain('setTimeout(loadReport, 400)');- expect(source).toContain("if (tab === 'system' && !report) loadReport()");+ expect(shell).toContain("api.get(`/api/settings/diagnostics?${params}`)");+ expect(shell).toContain('clearTimeout(reportTimer)');+ expect(shell).toContain('setTimeout(loadReport, 400)');+ expect(shell).toContain("if (tab === 'system' && !report) loadReport()");});it('files through a real anchor, so no popup blocker sees a deferred open', () => {- expect(source).toContain('href={report?.url || `${REPO_URL}/issues/new`}');- expect(source).not.toContain('window.open(report');+ expect(system).toContain('href={report?.url || `${REPO_URL}/issues/new`}');+ expect(family).not.toContain('window.open(report');});it('shows the exact report before it is filed, and can copy it whole', () => {- expect(source).toContain('<summary>What gets sent</summary>');- expect(source).toContain('<pre class="mono">{report.report}</pre>');- expect(source).toContain('navigator.clipboard.writeText(report.report)');+ expect(system).toContain('<summary>What gets sent</summary>');+ expect(system).toContain('<pre class="mono">{report.report}</pre>');+ expect(shell).toContain('navigator.clipboard.writeText(report.report)');});it('warns that the tracker is public', () => {- expect(source).toContain('public GitHub tracker; anyone can read it');+ expect(system).toContain('public GitHub tracker; anyone can read it');});});describe('Backup', () => {it('posts the bundle as-is, and wraps a pre-bundle settings file', () => {- expect(source).toContain('const bundle = parsed.settings ? parsed : { settings: parsed }');- expect(source).toContain("api.post('/api/settings/import', bundle)");+ expect(shell).toContain('const bundle = parsed.settings ? parsed : { settings: parsed }');+ expect(shell).toContain("api.post('/api/settings/import', bundle)");});it('reloads what a restore can change, logo included', () => {- expect(source).toContain('await loadTemplates()');- expect(source).toContain('sigBust += 1');+ expect(shell).toContain('await loadTemplates()');+ expect(shell).toContain('sigBust += 1');});it('says what the file holds, and what it leaves behind', () => {- expect(source).toContain('settings, keys, templates and your signature');- expect(source).toContain('export folders and');- expect(source).toContain('download logins stay here');- expect(source).toContain('keep this backup private');- expect(source).toContain('Export backup');- expect(source).toContain('Import backup');+ expect(storage).toContain('settings, keys, templates and your signature');+ expect(storage).toContain('export folders and');+ expect(storage).toContain('download logins stay here');+ expect(storage).toContain('keep this backup private');+ expect(storage).toContain('Export backup');+ expect(storage).toContain('Import backup');});it('keeps the download and import controls wired after moving to Storage', () => {- expect(source).toContain("{#if tab === 'storage'}");- expect(source).toContain('href="/api/settings/export" download');- expect(source).toContain('onchange={importSettings}');+ expect(shell).toContain("{#if tab === 'storage'}");+ expect(storage).toContain('href="/api/settings/export" download');+ expect(storage).toContain('onchange={importSettings}');});});describe('Workspace folder', () => {it('keeps workspace management in Storage', () => {- expect(source).toContain("{#if tab === 'storage'}");- expect(source).toContain('<WorkspaceFolder onchange={(status) => (about.workspace_root = status.root)} />');+ expect(shell).toContain("{#if tab === 'storage'}");+ expect(storage).toContain(+ '<WorkspaceFolder onchange={(status) => (about.workspace_root = status.root)} />'+ );});});describe('Settings sections', () => {it('separates workflow preferences from app maintenance', () => {for (const id of ['general', 'publishing', 'imagery', 'templates', 'extension', 'storage', 'system']) {- expect(source).toContain(`id: '${id}'`);+ expect(shell).toContain(`id: '${id}'`);+ }+ expect(shell).toContain("let tab = $state('general')");+ });++ it('gives each section its own file, and renders every one of them', () => {+ for (const [id, component] of [+ ['general', 'GeneralTab'],+ ['publishing', 'PublishingTab'],+ ['imagery', 'ImageryTab'],+ ['templates', 'TemplatesTab'],+ ['extension', 'ExtensionTab'],+ ['storage', 'StorageTab'],+ ['system', 'SystemTab'],+ ]) {+ expect(shell).toContain(`import ${component} from './settings/${component}.svelte'`);+ expect(shell).toContain(`{#if tab === '${id}'}`);+ expect(shell).toContain(`<${component}`);}- expect(source).toContain("let tab = $state('general')");});it('keeps old direct links useful while callers migrate', () => {- expect(source).toContain("const aliases = { preferences: 'general', about: 'system' }");+ expect(shell).toContain("const aliases = { preferences: 'general', about: 'system' }");});it('offers the proof point as save-or-ask, never as a status', () => {- expect(source).toContain('proof_place_auto: proofPlaceAuto');- expect(source).toContain('proofPlaceAuto = s.proof_place_auto ?? true');- expect(source).toContain('Save the point without asking');- expect(source).toContain('Off, the composer asks each time.');+ expect(general).toContain('proof_place_auto: proofPlaceAuto');+ expect(shell).toContain('proofPlaceAuto = s.proof_place_auto ?? true');+ expect(general).toContain('Save the point without asking');+ expect(general).toContain('Off, the composer asks each time.');});it('manages all three export folders from Storage', () => {- expect(source).toContain("{ id: 'notes', label: 'Note PDFs' }");- expect(source).toContain("{ id: 'media', label: 'Media copies' }");- expect(source).toContain("{ id: 'proofs', label: 'Proof PNGs' }");- expect(source).toContain('<ExportFolderPicker');- expect(source).toContain("await saveDestination(kind, '')");+ expect(shell).toContain("{ id: 'notes', label: 'Note PDFs' }");+ expect(shell).toContain("{ id: 'media', label: 'Media copies' }");+ expect(shell).toContain("{ id: 'proofs', label: 'Proof PNGs' }");+ expect(shell).toContain('<ExportFolderPicker');+ expect(shell).toContain("await saveDestination(kind, '')");});});diff --git a/frontend/src/tools/settings/ExtensionTab.svelte b/frontend/src/tools/settings/ExtensionTab.sveltenew file mode 100644index 0000000..7b6a3dc--- /dev/null+++ b/frontend/src/tools/settings/ExtensionTab.svelte@@ -0,0 +1,88 @@+<script>+ /**+ * The capture extension: whether this browser has it, and the token that pairs+ * it with this app.+ *+ * The token is minted on first reveal rather than on mount, so an installation+ * that never pairs never has one (spec's lazy-token rule).+ */+ import Icon from '../../components/Icon.svelte';++ let {+ about,+ badges,+ extDetected,+ extOutdated,+ ingestToken,+ copyToken,+ ensureToken,+ rotateToken,+ tokenShown = $bindable(),+ } = $props();+</script>++<section class="group">+ <h3>Capture extension</h3>+ <p class="note">+ Captures supported map sites and powers the Google basemap Capture button.+ </p>+ <div class="row">+ <div class="row-label">+ <span>Status in this browser</span>+ <span class="row-hint">+ {#if extDetected}+ detected · <span class="mono">v{extDetected}</span>+ {#if extOutdated}+ · update bundled (<span class="mono">v{about.extension_version}</span>)+ {/if}+ {:else}+ not detected. After installing, reload this tab+ {/if}+ </span>+ </div>+ <a class="btn btn-sm btn-primary dotted" href="/api/ingest/extension.zip" download>+ <Icon name="download" size={13} />+ {extOutdated ? 'Download update (.zip)' : 'Download extension (.zip)'}+ {#if badges.extension}+ <span+ class="update-dot"+ aria-label={extOutdated ? 'an update is waiting' : 'not installed yet'}+ ></span>+ {/if}+ </a>+ </div>+ {#if extOutdated}+ <p class="note warn">+ Bundled v{about.extension_version} is newer than installed v{extDetected}; replace+ the unpacked folder and reload the extension.+ </p>+ {/if}+ <p class="note">+ Unzip it, load it as an unpacked extension, then reload this tab.+ </p>+</section>++<section class="group">+ <h3>Pairing</h3>+ <p class="note">+ Paste this token into the extension options; rotating it unpairs existing extensions.+ </p>+ <div class="row">+ <div class="row-label">+ <span>Pairing token</span>+ <span class="row-hint mono">{tokenShown ? ingestToken : '•'.repeat(24)}</span>+ </div>+ <div class="scraper-actions">+ <button class="btn btn-sm" onclick={async () => { await ensureToken(); tokenShown = !tokenShown; }}>+ {tokenShown ? 'Hide' : 'Show'}+ </button>+ <button class="btn btn-sm btn-primary" onclick={copyToken}>+ <Icon name="copy" size={13} /> Copy+ </button>+ <button class="btn btn-sm" onclick={rotateToken}>Rotate</button>+ </div>+ </div>+ <p class="note">+ The extension can file one user-requested map capture through this local app.+ </p>+</section>diff --git a/frontend/src/tools/settings/GeneralTab.svelte b/frontend/src/tools/settings/GeneralTab.sveltenew file mode 100644index 0000000..f816e4f--- /dev/null+++ b/frontend/src/tools/settings/GeneralTab.svelte@@ -0,0 +1,137 @@+<script>+ /**+ * How every tool prints a coordinate, a distance and an area, plus the map's+ * opening position and what saving a proof does with its point.+ *+ * Preferences save on change and the server answers with the canonical value,+ * so nothing here keeps a draft the rest of the app cannot see.+ */+ import { formatDistance, formatArea } from '../../lib/measure.js';++ let {+ prefs,+ home,+ coordSample,+ savePrefs,+ saveHome,+ proofPlaceAuto = $bindable(),+ } = $props();++ const COORD_CHOICES = [+ { id: 'dd', label: 'Decimal' },+ { id: 'dms', label: 'DMS' },+ { id: 'mgrs', label: 'MGRS' },+ ];+ const UNIT_CHOICES = [+ { id: 'metric', label: 'Metric' },+ { id: 'imperial', label: 'Imperial' },+ ];+</script>++<section class="group">+ <h3>Coordinates</h3>+ <div class="row">+ <div class="row-label">+ <span>Format</span>+ <span class="row-hint">How every tool prints a latitude/longitude.</span>+ </div>+ <div class="seg" role="group" aria-label="Coordinate format">+ {#each COORD_CHOICES as c (c.id)}+ <button+ class="seg-btn"+ class:on={prefs.coordFormat === c.id}+ onclick={() => savePrefs({ coord_format: c.id })}+ >{c.label}</button>+ {/each}+ </div>+ </div>+ <p class="sample mono">{coordSample}</p>+ <p class="note">+ Changes display only; case data stays in decimal degrees.+ </p>+</section>++<section class="group">+ <h3>Measurements</h3>+ <div class="row">+ <div class="row-label">+ <span>Units</span>+ <span class="row-hint">The Satellite ruler, area and readouts.</span>+ </div>+ <div class="seg" role="group" aria-label="Units">+ {#each UNIT_CHOICES as c (c.id)}+ <button+ class="seg-btn"+ class:on={prefs.units === c.id}+ onclick={() => savePrefs({ units: c.id })}+ >{c.label}</button>+ {/each}+ </div>+ </div>+ <p class="sample mono">+ {formatDistance(1234, prefs.units)} · {formatArea(52000, prefs.units)}+ </p>+</section>++<section class="group">+ <h3>Satellite home view</h3>+ <p class="intro">+ Default opening position for Satellite; case navigation still takes priority.+ </p>+ <div class="grid-3">+ <label class="field">+ <span>Latitude</span>+ <input class="input mono" bind:value={home.lat} onchange={saveHome} inputmode="decimal" spellcheck="false" />+ </label>+ <label class="field">+ <span>Longitude</span>+ <input class="input mono" bind:value={home.lon} onchange={saveHome} inputmode="decimal" spellcheck="false" />+ </label>+ <label class="field">+ <span>Zoom</span>+ <input class="input mono" bind:value={home.zoom} onchange={saveHome} type="number" min="1" max="21" />+ </label>+ </div>+</section>++<section class="group">+ <h3>Proofs</h3>+ <p class="intro">+ Saving a proof turns the coordinates it carries into a place on the map, and+ says the proof shows it.+ </p>+ <div class="row">+ <div class="row-label">+ <span>Save the point without asking</span>+ <span class="row-hint">+ Off, the composer asks each time. A point already saved is never asked about.+ </span>+ </div>+ <input+ type="checkbox"+ bind:checked={proofPlaceAuto}+ onchange={() => savePrefs({ proof_place_auto: proofPlaceAuto })}+ aria-label="Save a proof's point without asking"+ />+ </div>+</section>++<style>+ .sample {+ color: var(--text-2);+ font-size: var(--fs-sm);+ padding: 6px 9px;+ border-radius: var(--r-sm);+ background: var(--bg-2);+ border: 1px solid var(--border);+ display: inline-block;+ margin-top: 4px;+ }+++ .grid-3 {+ display: grid;+ grid-template-columns: 1fr 1fr 90px;+ gap: 10px;+ }+</style>diff --git a/frontend/src/tools/settings/ImageryTab.svelte b/frontend/src/tools/settings/ImageryTab.sveltenew file mode 100644index 0000000..18c8972--- /dev/null+++ b/frontend/src/tools/settings/ImageryTab.svelte@@ -0,0 +1,620 @@+<script>+ /**+ * Imagery provider keys, and what each one has cost this month.+ *+ * One card per keyed provider (IMAGERY_PROVIDERS.md): collapsed it shows what+ * the provider gives and what it costs, open it holds the setup steps, the key+ * field, a live test and the two allowances the analyst can correct. Keys are+ * app-wide, stored in settings.json, and never travel into a case or an export.+ *+ * The meter is the point of the card. A basemap that bills per tile is one an+ * investigation can run into silently, so the free-tier share is on screen+ * before it matters, and past `BLOCK_SHARE` the app falls back to free imagery+ * unless the analyst says otherwise.+ */+ import Icon from '../../components/Icon.svelte';+ import {+ monthCount,+ tilesOfFree,+ freeTierShare,+ usageBlocked,+ providerStatus,+ BLOCK_SHARE,+ FREE_TIER,+ } from '../../lib/usage.js';++ let {+ KEYED,+ keys,+ usage,+ month,+ tiers,+ tierEdits,+ enabled,+ overrides,+ testResult,+ testing,+ ecoZooms,+ load,+ saveKey,+ testKey,+ saveProviderPrefs,+ saveEcoZoom,+ saveFreeTier,+ eco = $bindable(),+ ecoMaxZoom = $bindable(),+ } = $props();++ const perProvider = (value) => Object.fromEntries(KEYED.map((k) => [k.id, value(k)]));++ // Card state is this tab's own: which card is open, whose key is legible.+ // Start closed so setup details appear only for the provider being set up.+ let open = $state(perProvider(() => false));+ let shown = $state(perProvider(() => false));+ let termsOpen = $state(false);+</script>++<section class="group">+ <h3>Providers</h3>+ <p class="intro">+ Add provider keys to unlock more Satellite basemaps; usage appears on each card.+ </p>++ <div class="cards">+ {#each KEYED as k (k.id)}+ {@const count = monthCount(usage, k.id, month)}+ {@const share = freeTierShare(count, k.id, tiers)}+ {@const st = providerStatus({+ key: keys[k.id],+ enabled: enabled[k.id],+ status: testResult[k.id],+ count,+ meter: k.id,+ overrides,+ tiers,+ })}+ <div class="card" class:open={open[k.id]}>+ <div class="card-head">+ <button+ class="card-toggle"+ onclick={() => (open[k.id] = !open[k.id])}+ aria-expanded={open[k.id]}+ >+ <Icon name={open[k.id] ? 'chevronDown' : 'chevronRight'} size={13} />+ <span class="card-name">{k.label}</span>+ <span class="card-gives">{k.gives}</span>+ </button>+ <span+ class="chip {st.tone}"+ title={st.tone === 'bad' ? testResult[k.id]?.detail : undefined}+ >{st.label}</span>+ {#if keys[k.id]}+ <input+ class="card-enable"+ type="checkbox"+ bind:checked={enabled[k.id]}+ onchange={saveProviderPrefs}+ title="Show or hide this basemap in the Satellite tab"+ aria-label="Show {k.label} in the Satellite tab"+ />+ {/if}+ </div>++ <!-- one line either way: what it would cost, or what it has cost -->+ {#if keys[k.id] || count}+ <div class="card-meter">+ <div class="meter-track" aria-hidden="true">+ <div+ class="meter-fill"+ class:hot={share >= BLOCK_SHARE}+ style="width:{Math.min(share * 100, 100)}%"+ ></div>+ </div>+ <span class="mono meter-read">{tilesOfFree(count, k.id, tiers)}</span>+ </div>+ {:else if !open[k.id]}+ <!-- open, the body's overage already leads with the cost -->+ <p class="card-cost">{k.cost}</p>+ {/if}++ {#if open[k.id]}+ <div class="card-body">+ {#if k.warning}+ <p class="key-warning"><Icon name="alert" size={12} /> {k.warning}</p>+ {/if}+ {#if k.steps}+ <ol class="key-steps">+ {#each k.steps as step (step)}+ <li>{step}</li>+ {/each}+ </ol>+ {/if}++ <label class="key-label" for="key-{k.id}">+ {k.field}+ <a href={k.help} target="_blank" rel="noreferrer" title="How to get one">+ how to get one <Icon name="external" size={11} />+ </a>+ </label>+ <div class="key-line">+ <input+ id="key-{k.id}"+ class="input"+ type={shown[k.id] ? 'text' : 'password'}+ placeholder={k.placeholder}+ bind:value={keys[k.id]}+ onchange={() => saveKey(k.id)}+ autocomplete="off"+ spellcheck="false"+ />+ <button+ class="btn btn-ghost btn-sm"+ onclick={() => (shown[k.id] = !shown[k.id])}+ title={shown[k.id] ? 'Hide key' : 'Show key'}+ aria-label={shown[k.id] ? 'Hide key' : 'Show key'}+ >+ <Icon name={shown[k.id] ? 'eyeOff' : 'eye'} size={14} />+ </button>+ <button+ class="btn btn-sm"+ onclick={() => testKey(k.id)}+ disabled={testing[k.id] || !keys[k.id].trim()}+ title="Exercise this key against the real service"+ >+ {testing[k.id] ? 'Testing…' : 'Test'}+ </button>+ </div>+ {#if testResult[k.id] && !testResult[k.id].ok}+ <p class="verdict bad">+ <Icon name="alert" size={12} />+ {testResult[k.id].detail}+ </p>+ {/if}++ <p class="overage">{k.cost}. {k.overage}</p>++ {#if keys[k.id] || count}+ {#if usageBlocked(count, k.id, overrides, tiers)}+ <p class="blocked">+ <Icon name="alert" size={12} />+ Paused at {Math.round(BLOCK_SHARE * 100)}% of the free tier. The map and+ captures fall back to free imagery until next month, or:+ </p>+ {/if}+ {#if share >= BLOCK_SHARE || overrides[k.id]}+ <label+ class="toggle override"+ title="Serve past the pause (extra tiles are billed)"+ >+ <input+ type="checkbox"+ bind:checked={overrides[k.id]}+ onchange={saveProviderPrefs}+ />+ keep serving past {Math.round(BLOCK_SHARE * 100)}% (billed)+ </label>+ {/if}++ <div class="card-controls">+ <label+ class="ctrl"+ title={k.tierNote ??+ "This account's monthly free allowance. Check the provider dashboard"}+ >+ <span>Free allowance</span>+ <input+ class="input num mono"+ type="number"+ min="1"+ step="1000"+ placeholder={String(FREE_TIER[k.id] ?? '')}+ bind:value={tierEdits[k.id]}+ onchange={saveFreeTier}+ />+ <span class="ctrl-note">+ {tierEdits[k.id].trim() === ''+ ? 'blank = the documented default'+ : `default is ${(FREE_TIER[k.id] ?? 0).toLocaleString('en-US')}`}+ </span>+ </label>++ {#if k.browserTest}+ <p class="ctrl-note">+ Eco mode is unavailable because reopening this widget starts another billed map load.+ </p>+ {:else}+ <label+ class="ctrl"+ title="Blank uses global; 0 disables eco mode"+ >+ <span>Eco below z ≤</span>+ <input+ class="input num mono"+ type="number"+ min="0"+ max="21"+ placeholder={k.id === 'sentinelhub' ? '11' : String(ecoMaxZoom)}+ bind:value={ecoZooms[k.id]}+ onchange={saveEcoZoom}+ disabled={!eco}+ aria-label="Eco threshold for {k.label}"+ />+ <span class="ctrl-note">+ {k.id === 'sentinelhub'+ ? 'blank = 11 (it caps at z14)'+ : 'blank = the global threshold'}+ </span>+ </label>+ {/if}+ </div>++ <a class="card-link" href={k.usage} target="_blank" rel="noreferrer">+ {k.label} usage & limits <Icon name="external" size={11} />+ </a>+ {/if}+ </div>+ {/if}+ </div>+ {/each}+ </div>++ <div class="cards-foot">+ <span class="row-hint">Counters for {month}. Stored locally.</span>+ <button class="btn btn-ghost btn-sm" onclick={() => load()} title="Refresh counters">+ <Icon name="reset" size={13} /> Refresh+ </button>+ </div>+</section>++<section class="group">+ <h3>Eco mode</h3>+ <label+ class="toggle eco"+ title="Zoomed out this far, billed basemaps swap to free imagery"+ >+ <input type="checkbox" bind:checked={eco} onchange={saveEcoZoom} />+ Use free imagery when zoomed out, up to z ≤+ <input+ class="input num mono"+ type="number"+ min="1"+ max="21"+ bind:value={ecoMaxZoom}+ onchange={saveEcoZoom}+ disabled={!eco}+ aria-label="Eco mode zoom threshold"+ />+ </label>+ <p class="note">+ Applies while zoomed out; provider cards can override it.+ </p>+</section>++<section class="group">+ <div class="card">+ <div class="card-head">+ <button+ class="card-toggle"+ onclick={() => (termsOpen = !termsOpen)}+ aria-expanded={termsOpen}+ >+ <Icon name={termsOpen ? 'chevronDown' : 'chevronRight'} size={13} />+ <span class="card-name">Provider terms</span>+ <span class="card-gives">Applied automatically</span>+ </button>+ </div>+ {#if termsOpen}+ <ul class="rules">+ <li>Google tiles are not cached; captures are screenshots with attribution.</li>+ <li>Mapbox attribution remains attached to captures.</li>+ <li>Provider keys stay outside cases and exports.</li>+ </ul>+ {/if}+ </div>+</section>++<style>+ /* Recipe for a provider whose "key" is a configuration you build yourself */+ .key-steps {+ margin: 4px 0 8px;+ padding-left: 18px;+ color: var(--text-3);+ font-size: var(--fs-xs);+ line-height: 1.5;+ }++ .key-steps li {+ margin: 1px 0;+ }++ .key-warning {+ display: flex;+ align-items: baseline;+ gap: 5px;+ margin: 4px 0 8px;+ color: var(--warn, #d8a03d);+ font-size: var(--fs-xs);+ line-height: 1.45;+ }+++ /* Provider cards show a summary until opened for setup. */+ .cards {+ display: flex;+ flex-direction: column;+ gap: 6px;+ }++ .card {+ border: 1px solid var(--border);+ border-radius: var(--r-md);+ padding: 8px 10px;+ background: var(--bg-2);+ transition: border-color 0.12s var(--ease);+ }++ .card-head {+ display: flex;+ align-items: center;+ gap: 10px;+ }++ .card-toggle {+ flex: 1;+ min-width: 0;+ display: flex;+ align-items: center;+ gap: 8px;+ padding: 0;+ border: 0;+ background: none;+ color: var(--text-3);+ font: inherit;+ text-align: left;+ cursor: pointer;+ }++ .card-name {+ font-size: var(--fs-sm);+ font-weight: 600;+ color: var(--text-1);+ flex-shrink: 0;+ }++ .card-gives {+ font-size: var(--fs-xs);+ color: var(--text-3);+ overflow: hidden;+ text-overflow: ellipsis;+ white-space: nowrap;+ }++ .card-enable {+ accent-color: var(--accent);+ margin: 0;+ flex-shrink: 0;+ cursor: pointer;+ }++ /* One-word verdict; the tooltip carries the detail. */+ .chip {+ flex-shrink: 0;+ padding: 1px 7px;+ border-radius: 999px;+ border: 1px solid var(--border);+ font-size: var(--fs-xs);+ color: var(--text-3);+ white-space: nowrap;+ }++ .chip.ok {+ color: var(--ok);+ border-color: color-mix(in srgb, var(--ok) 40%, transparent);+ }++ .chip.bad {+ color: var(--danger);+ border-color: color-mix(in srgb, var(--danger) 40%, transparent);+ }++ .card-meter {+ display: flex;+ align-items: center;+ gap: 9px;+ margin: 7px 0 1px;+ }++ .card-meter .meter-track {+ flex: 1;+ }++ .meter-read,+ .card-cost {+ font-size: var(--fs-xs);+ color: var(--text-3);+ white-space: nowrap;+ }++ .card-cost {+ margin: 5px 0 1px 21px; /* aligned under the name, past the chevron */+ }++ .card-body {+ margin-top: 12px;+ padding-top: 12px;+ border-top: 1px solid var(--border);+ }++ .card-controls {+ display: flex;+ flex-direction: column;+ gap: 7px;+ margin-top: 9px;+ }++ .ctrl {+ display: flex;+ align-items: center;+ gap: 8px;+ font-size: var(--fs-xs);+ color: var(--text-3);+ }++ /* Align provider control fields in one column. */+ .ctrl > span:first-child {+ min-width: 104px;+ color: var(--text-2);+ }++ .ctrl-note {+ opacity: 0.8;+ }++ .card-link {+ display: inline-flex;+ align-items: center;+ gap: 4px;+ margin-top: 10px;+ color: var(--accent);+ font-size: var(--fs-xs);+ }++ .cards-foot {+ display: flex;+ align-items: center;+ justify-content: space-between;+ gap: 12px;+ margin-top: 12px;+ }++ .key-label {+ display: flex;+ align-items: baseline;+ gap: 10px;+ font-size: var(--fs-xs);+ color: var(--text-2);+ font-weight: 600;+ margin-bottom: 5px;+ }++ .key-label a {+ color: var(--accent);+ font-weight: 400;+ display: inline-flex;+ align-items: center;+ gap: 3px;+ }++ .key-line {+ display: flex;+ gap: 6px;+ align-items: center;+ }++ .verdict {+ display: flex;+ align-items: center;+ gap: 4px;+ margin-top: 5px;+ font-size: var(--fs-xs);+ line-height: 1.4;+ }++ .verdict.bad {+ color: var(--danger);+ }++ .meter-track {+ height: 5px;+ border-radius: var(--r-sm);+ background: var(--bg-2);+ border: 1px solid var(--border);+ overflow: hidden;+ }++ .meter-fill {+ height: 100%;+ background: var(--accent);+ border-radius: inherit;+ transition: width 0.3s var(--ease);+ }++ .meter-fill.hot {+ background: var(--danger);+ }++ .overage {+ margin-top: 9px;+ color: var(--text-3);+ font-size: var(--fs-xs);+ line-height: 1.45;+ }++ .toggle {+ display: inline-flex;+ align-items: center;+ gap: 6px;+ font-size: var(--fs-xs);+ color: var(--text-2);+ cursor: pointer;+ user-select: none;+ }++ .toggle input {+ accent-color: var(--accent);+ margin: 0;+ }++ .toggle.override {+ margin-top: 6px;+ color: var(--danger);+ }++ .toggle.eco {+ display: flex;+ margin: 2px 0;+ }++ /* every small numeric box in this tab: eco thresholds, free allowances */+ .num {+ width: 92px;+ padding: 2px 6px;+ flex-shrink: 0;+ }++ .blocked {+ margin-top: 6px;+ color: var(--danger);+ font-size: var(--fs-xs);+ display: flex;+ align-items: center;+ gap: 5px;+ line-height: 1.4;+ }++ .rules {+ margin: 12px 0 2px;+ padding-left: 18px;+ color: var(--text-2);+ font-size: var(--fs-xs);+ display: flex;+ flex-direction: column;+ gap: 6px;+ line-height: 1.45;+ }++ .card.open {+ border-color: var(--text-3);+ background: none;+ }++ .chip.warn {+ color: var(--warn, #d8a03d);+ border-color: color-mix(in srgb, var(--warn, #d8a03d) 40%, transparent);+ }++ .key-line .input {+ flex: 1;+ font-family: var(--font-mono);+ }+</style>diff --git a/frontend/src/tools/settings/PublishingTab.svelte b/frontend/src/tools/settings/PublishingTab.sveltenew file mode 100644index 0000000..ebd7ebc--- /dev/null+++ b/frontend/src/tools/settings/PublishingTab.svelte@@ -0,0 +1,140 @@+<script>+ /**+ * What a new Geo Report starts from, and the logo signed proofs carry.+ *+ * The logo lives beside settings.json and reaches a case only inside an+ * exported proof PNG; `sigBust` re-fetches the preview past the cache after a+ * replacement.+ */+ import { POST_TARGETS } from '../../lib/post.js';++ let {+ signature,+ sigBust,+ savePrefs,+ removeSignature,+ uploadSignature,+ mention = $bindable(),+ postTarget = $bindable(),+ signatureHandle = $bindable(),+ sigInput = $bindable(),+ } = $props();+</script>++<section class="group">+ <h3>Geo Report</h3>+ <div class="row">+ <div class="row-label">+ <span>Default mention</span>+ <span class="row-hint">Pre-filled on a new draft. Leave empty for none.</span>+ </div>+ <input+ class="input mention"+ bind:value={mention}+ onchange={() => savePrefs({ post_mention: mention })}+ placeholder="@GeoConfirmed"+ spellcheck="false"+ />+ </div>+ <div class="row">+ <div class="row-label">+ <span>Preferred platform</span>+ <span class="row-hint">Used for new Geo Report drafts.</span>+ </div>+ <div class="seg" role="group" aria-label="Preferred platform">+ {#each Object.values(POST_TARGETS) as option (option.id)}+ <button+ class="seg-btn"+ class:on={postTarget === option.id}+ onclick={() => {+ postTarget = option.id;+ savePrefs({ post_target: option.id });+ }}+ >{option.label}</button>+ {/each}+ </div>+ </div>+</section>++<section class="group">+ <h3>Signature</h3>+ <div class="row">+ <div class="row-label">+ <span>Your account handle</span>+ <span class="row-hint">Shown on proofs that enable “Add account handle”.</span>+ </div>+ <input+ class="input mention"+ bind:value={signatureHandle}+ onchange={() => savePrefs({ signature_handle: signatureHandle })}+ placeholder="@my_handle"+ maxlength="64"+ spellcheck="false"+ />+ </div>+ <div class="row">+ <div class="row-label">+ <span>Your logo</span>+ <span class="row-hint">+ Transparent PNG, up to 2 MB, used only on signed proofs.+ </span>+ </div>+ <div class="sig-side">+ {#if signature}+ <img class="sig-preview" src={`/api/settings/signature.png?v=${sigBust}`} alt="Your signature" />+ {/if}+ <div class="sig-buttons">+ <button class="btn btn-sm" onclick={() => sigInput?.click()}>+ {signature ? 'Replace…' : 'Choose PNG…'}+ </button>+ {#if signature}+ <button class="btn btn-danger btn-sm" onclick={removeSignature}>Remove</button>+ {/if}+ </div>+ </div>+ <input+ bind:this={sigInput}+ class="sig-file"+ type="file"+ accept="image/png"+ onchange={uploadSignature}+ />+ </div>+</section>++<style>+ .sig-side {+ display: flex;+ align-items: center;+ gap: 10px;+ }++ .sig-preview {+ /* Checkerboard preview for transparent logos. */+ max-width: 88px;+ max-height: 44px;+ padding: 4px;+ border: 1px solid var(--border);+ border-radius: var(--r-sm);+ background-color: var(--bg-2);+ background-image:+ linear-gradient(45deg, var(--bg-3) 25%, transparent 25% 75%, var(--bg-3) 75%),+ linear-gradient(45deg, var(--bg-3) 25%, transparent 25% 75%, var(--bg-3) 75%);+ background-size: 10px 10px;+ background-position: 0 0, 5px 5px;+ }++ .sig-buttons {+ display: flex;+ gap: 6px;+ }++ .sig-file {+ display: none;+ }++ .mention {+ width: 200px;+ flex-shrink: 0;+ }+</style>diff --git a/frontend/src/tools/settings/StorageTab.svelte b/frontend/src/tools/settings/StorageTab.sveltenew file mode 100644index 0000000..c4592c2--- /dev/null+++ b/frontend/src/tools/settings/StorageTab.svelte@@ -0,0 +1,77 @@+<script>+ /**+ * Where the workspace lives, where each export lands, and how the app's own+ * state moves to another machine.+ */+ import Icon from '../../components/Icon.svelte';+ import WorkspaceFolder from '../../components/WorkspaceFolder.svelte';+ import { CASE_FOLDER_LABEL } from '../../lib/exportDest.js';++ let {+ about,+ exportDirs,+ EXPORT_KINDS,+ importSettings,+ resetExportDestination,+ exportPickerKind = $bindable(),+ settingsFile = $bindable(),+ } = $props();+</script>++<WorkspaceFolder onchange={(status) => (about.workspace_root = status.root)} />++<section class="group">+ <h3>Export folders</h3>+ <p class="note">Choose a folder for each export type.</p>+ {#each EXPORT_KINDS as kind (kind.id)}+ <div class="row">+ <div class="row-label">+ <span>{kind.label}</span>+ <span class="row-hint mono export-path" title={exportDirs[kind.id] || CASE_FOLDER_LABEL}>+ {exportDirs[kind.id] || CASE_FOLDER_LABEL}+ </span>+ </div>+ <div class="scraper-actions">+ <button class="btn btn-sm" onclick={() => (exportPickerKind = kind.id)}>Change…</button>+ <button+ class="btn btn-ghost btn-sm"+ onclick={() => resetExportDestination(kind.id)}+ disabled={!exportDirs[kind.id]}+ >Reset</button>+ </div>+ </div>+ {/each}+</section>++<section class="group">+ <h3>Settings backup</h3>+ <p class="note">+ Carries settings, keys, templates and your signature; export folders and+ download logins stay here, so keep this backup private.+ </p>+ <div class="links">+ <a class="btn btn-sm" href="/api/settings/export" download>+ <Icon name="save" size={13} /> Export backup+ </a>+ <button class="btn btn-sm" onclick={() => settingsFile?.click()}>+ <Icon name="file" size={13} /> Import backup+ </button>+ <input+ type="file"+ accept="application/json,.json"+ bind:this={settingsFile}+ onchange={importSettings}+ hidden+ />+ </div>+</section>++<style>+ .export-path {+ display: block;+ max-width: min(380px, 48vw);+ overflow: hidden;+ text-overflow: ellipsis;+ white-space: nowrap;+ }+</style>diff --git a/frontend/src/tools/settings/SystemTab.svelte b/frontend/src/tools/settings/SystemTab.sveltenew file mode 100644index 0000000..e982f3b--- /dev/null+++ b/frontend/src/tools/settings/SystemTab.svelte@@ -0,0 +1,317 @@+<script>+ /**+ * What this installation is, what it can reach, and how to report a problem.+ *+ * Two update stories share the tab because they answer the same question from+ * the analyst's side — *is anything here behind?* Azimut itself checks GitHub,+ * the downloaders check PyPI, and both read the answer the startup check+ * already put in the store rather than asking again on mount.+ *+ * The issue report is built by the server and shown in full before it is filed:+ * the tracker is public, so nothing leaves without being read first.+ */+ import Icon from '../../components/Icon.svelte';++ let {+ about,+ ffmpeg,+ badges,+ appUpdate,+ checkingApp,+ checkAppUpdate,+ scrapers,+ checking,+ checkScrapers,+ updating,+ updateScraper,+ resetScraper,+ savePrefs,+ report,+ loadReport,+ refreshReport,+ copyReport,+ REPO_URL,+ SITE_URL,+ updateOnStart = $bindable(),+ reportKind = $bindable(),+ reportSummary = $bindable(),+ } = $props();++ // Downloaders can be refreshed from PyPI between Azimut releases.+ const SCRAPER_LABELS = { 'yt-dlp': 'yt-dlp', 'gallery-dl': 'gallery-dl' };+</script>++<section class="group">+ <h3>Azimut</h3>+ <dl class="facts">+ <dt>Version</dt>+ <dd class="mono">{about.version || '—'}</dd>+ <dt>ffmpeg</dt>+ <dd class="mono" title={ffmpeg.path || ''}>+ {#if ffmpeg.available}+ {ffmpeg.version || 'installed'}+ <span class="sub">· {ffmpeg.source === 'bundled' ? 'bundled' : 'system PATH'}</span>+ {:else}+ not found <span class="sub">· install ffmpeg on your PATH</span>+ {/if}+ </dd>+ <dt>License</dt>+ <dd>AGPL-3.0-only</dd>+ </dl>+ <p class="note">+ Case data stays in the workspace; network access is limited to requested features+ and the automatic GitHub update check.+ </p>+ <div class="links">+ <a class="btn btn-sm" href={REPO_URL} target="_blank" rel="noreferrer">+ <Icon name="link" size={13} /> Source & issues <Icon name="external" size={11} />+ </a>+ <a class="btn btn-sm" href={SITE_URL} target="_blank" rel="noreferrer">+ <Icon name="globe" size={13} /> osintmethat.com <Icon name="external" size={11} />+ </a>+ </div>+</section>++<section class="group">+ <h3>Updates</h3>+ <div class="row">+ <div class="row-label">+ <span>Check for a newer release</span>+ <span class="row-hint">+ {#if appUpdate?.update_available}+ <span class="mono">{appUpdate.latest}</span> is out. You have+ <span class="mono">{about.version}</span>+ {:else if appUpdate && !appUpdate.error}+ you're on the latest (<span class="mono">{about.version}</span>)+ {:else}+ {updateOnStart+ ? 'checks GitHub on startup and when requested'+ : 'checks GitHub when requested'}+ {/if}+ </span>+ </div>+ {#if appUpdate?.update_available}+ <a class="btn btn-sm btn-primary dotted" href={appUpdate.url} target="_blank" rel="noreferrer">+ <Icon name="download" size={13} /> Get {appUpdate.latest} <Icon name="external" size={11} />+ {#if badges.app}+ <span class="update-dot" aria-label="an update is waiting"></span>+ {/if}+ </a>+ {:else}+ <button class="btn btn-sm" onclick={checkAppUpdate} disabled={checkingApp}>+ {checkingApp ? 'Checking…' : 'Check for updates'}+ </button>+ {/if}+ </div>+ <div class="row">+ <div class="row-label">+ <span>Tell me on startup</span>+ <span class="row-hint">+ Asks GitHub and PyPI once when the app opens, and marks what is behind.+ </span>+ </div>+ <input+ type="checkbox"+ bind:checked={updateOnStart}+ onchange={() => savePrefs({ update_check_on_start: updateOnStart })}+ aria-label="Check for updates on startup"+ />+ </div>+ <p class="note">+ Update with <span class="mono">pipx upgrade azimut</span>; standalone users replace+ the downloaded binary.+ </p>+</section>++<section class="group">+ <h3>Report an issue</h3>+ <p class="note">+ Opens a new issue on the public GitHub tracker; anyone can read it.+ </p>+ <div class="report-kind">+ <label>+ <input+ type="radio"+ value="bug"+ bind:group={reportKind}+ onchange={loadReport}+ /> Something is broken+ </label>+ <label>+ <input+ type="radio"+ value="idea"+ bind:group={reportKind}+ onchange={loadReport}+ /> Something is missing+ </label>+ </div>+ <textarea+ class="report-summary"+ rows="3"+ maxlength="2000"+ placeholder={reportKind === 'bug'+ ? 'What you did, what you expected, what you got'+ : 'What you would like Azimut to do'}+ bind:value={reportSummary}+ oninput={refreshReport}+ ></textarea>+ {#if report}+ <details class="report-preview">+ <summary>What gets sent</summary>+ <pre class="mono">{report.report}</pre>+ </details>+ {/if}+ <div class="links">+ <a+ class="btn btn-sm btn-primary"+ href={report?.url || `${REPO_URL}/issues/new`}+ target="_blank"+ rel="noreferrer"+ >+ <Icon name="link" size={13} /> Open a GitHub issue <Icon name="external" size={11} />+ </a>+ <button class="btn btn-sm" onclick={copyReport} disabled={!report}>+ <Icon name="copy" size={13} /> Copy report+ </button>+ </div>+ <p class="note">+ Your text, the version, the OS and the last warnings of this run, with your+ paths, account name, case names and any keys removed. Nothing leaves the app+ until you open the issue.+ </p>+</section>++<section class="group">+ <h3>Downloaders</h3>+ <p class="note">+ Update these tools if a media link stops resolving.+ </p>+ {#each scrapers as s (s.dist)}+ <div class="row">+ <div class="row-label">+ <span>{SCRAPER_LABELS[s.dist] ?? s.dist}</span>+ <span class="row-hint">+ <span class="mono">{s.version || 'not installed'}</span>+ {#if s.source === 'runtime'}+ · updated in place{#if s.bundled_version}, shipped with {s.bundled_version}{/if}+ {:else}+ · as shipped+ {/if}+ {#if s.restart_required}+ · <span class="stale">restart to apply</span>+ {:else if s.outdated}+ · <span class="stale">{s.latest} available</span>+ {:else if s.latest}+ · up to date+ {/if}+ </span>+ </div>+ <div class="scraper-actions">+ {#if s.source === 'runtime'}+ <button class="btn btn-sm" onclick={() => resetScraper(s.dist)}>Revert</button>+ {/if}+ <button+ class="btn btn-sm dotted"+ class:btn-primary={s.outdated}+ disabled={updating[s.dist]}+ onclick={() => updateScraper(s.dist)}+ >+ {updating[s.dist] ? 'Updating…' : 'Update'}+ {#if s.outdated && !updating[s.dist]}+ <span class="update-dot" aria-label="an update is waiting"></span>+ {/if}+ </button>+ </div>+ </div>+ {/each}+ <div class="links">+ <button class="btn btn-sm" disabled={checking} onclick={checkScrapers}>+ <Icon name="download" size={13} />+ {checking ? 'Checking…' : 'Check for updates'}+ </button>+ </div>+ <p class="note">+ Updates are hash-verified from PyPI when requested; Revert restores the bundled version.+ </p>+</section>++<style>+ .sub {+ color: var(--text-3);+ font-size: var(--fs-sm);+ }++ /* the one state worth pulling the eye: this downloader will fail on real links */+ .stale {+ color: var(--warn, var(--text-1));+ font-weight: 500;+ }+++ .facts {+ display: grid;+ grid-template-columns: max-content 1fr;+ gap: 6px 18px;+ margin: 0;+ font-size: var(--fs-sm);+ }++ .facts dt {+ color: var(--text-3);+ font-size: var(--fs-xs);+ align-self: center;+ }++ .facts dd {+ margin: 0;+ color: var(--text-1);+ overflow-wrap: anywhere;+ }+++ /* Report an issue: kind, the user's words, then the report itself folded away. */+ .report-kind {+ display: flex;+ gap: 16px;+ margin: 10px 0 8px;+ font-size: var(--fs-xs);+ color: var(--text-2);+ }++ .report-kind label {+ display: flex;+ align-items: center;+ gap: 6px;+ }++ .report-summary {+ width: 100%;+ resize: vertical;+ font: inherit;+ font-size: var(--fs-sm);+ }++ .report-preview {+ margin-top: 10px;+ font-size: var(--fs-xs);+ }++ .report-preview summary {+ color: var(--text-3);+ cursor: pointer;+ }++ .report-preview pre {+ margin: 8px 0 0;+ padding: 8px 10px;+ max-height: 240px;+ overflow: auto;+ white-space: pre-wrap;+ overflow-wrap: anywhere;+ background: var(--bg-2);+ border: 1px solid var(--border);+ border-radius: var(--r-sm);+ color: var(--text-2);+ }+</style>diff --git a/frontend/src/tools/settings/TemplatesTab.svelte b/frontend/src/tools/settings/TemplatesTab.sveltenew file mode 100644index 0000000..d5ae610--- /dev/null+++ b/frontend/src/tools/settings/TemplatesTab.svelte@@ -0,0 +1,106 @@+<script>+ /**+ * Reusable proof styles and report structures, shared across cases.+ *+ * Content-free presets: a template carries house style, never a case's+ * material. Editing one opens the parent's editor modal.+ */+ import Icon from '../../components/Icon.svelte';+ import { templatesState } from '../../lib/state.svelte.js';++ let { newTemplate, editTemplate, deleteTpl = $bindable() } = $props();+</script>++<section class="group">+ <h3>Geo Proof templates</h3>+ <p class="note">+ Reusable proof styles shared across cases.+ </p>+ <div class="tpl-list">+ {#each templatesState.proof as t (t.id)}+ <div class="tpl-row">+ <span class="tpl-name">{t.name}</span>+ <div class="tpl-actions">+ <button class="btn btn-sm" onclick={() => editTemplate('proof', t)}>+ <Icon name="edit" size={13} /> Edit+ </button>+ <button class="btn btn-sm" title="Delete"+ onclick={() => (deleteTpl = { kind: 'proof', id: t.id, name: t.name })}>+ <Icon name="trash" size={13} />+ </button>+ </div>+ </div>+ {/each}+ {#if !templatesState.proof.length}+ <p class="empty">No proof templates yet.</p>+ {/if}+ </div>+ <button class="btn btn-sm" onclick={() => newTemplate('proof')}>+ <Icon name="plus" size={13} /> New proof template+ </button>+</section>++<section class="group">+ <h3>Geo Report templates</h3>+ <p class="note">+ Reusable thread structures for new Geo Reports.+ </p>+ <div class="tpl-list">+ {#each templatesState.post as t (t.id)}+ <div class="tpl-row">+ <span class="tpl-name">{t.name}</span>+ <div class="tpl-actions">+ <button class="btn btn-sm" onclick={() => editTemplate('post', t)}>+ <Icon name="edit" size={13} /> Edit+ </button>+ <button class="btn btn-sm" title="Delete"+ onclick={() => (deleteTpl = { kind: 'post', id: t.id, name: t.name })}>+ <Icon name="trash" size={13} />+ </button>+ </div>+ </div>+ {/each}+ {#if !templatesState.post.length}+ <p class="empty">No post templates yet.</p>+ {/if}+ </div>+ <button class="btn btn-sm" onclick={() => newTemplate('post')}>+ <Icon name="plus" size={13} /> New post template+ </button>+</section>++<style>++ /* --- templates tab ------------------------------------------------------ */+ .tpl-list {+ display: flex;+ flex-direction: column;+ gap: 6px;+ margin-bottom: 12px;+ }++ .tpl-row {+ display: flex;+ align-items: center;+ justify-content: space-between;+ gap: 12px;+ padding: 7px 10px;+ border: 1px solid var(--border);+ border-radius: var(--r-md);+ background: var(--bg-2);+ }++ .tpl-name {+ font-size: var(--fs-sm);+ color: var(--text-1);+ overflow: hidden;+ text-overflow: ellipsis;+ white-space: nowrap;+ }++ .tpl-actions {+ display: flex;+ gap: 6px;+ flex-shrink: 0;+ }+</style>diff --git a/src/azimut/api/cases.py b/src/azimut/api/cases.pydeleted file mode 100644index eb5975e..0000000--- a/src/azimut/api/cases.py+++ /dev/null@@ -1,1879 +0,0 @@-"""REST API for case lifecycle, entities and links.--The note bodies and their PDF export live next door in `api/notes.py`.-"""--from __future__ import annotations--import json-import math-import sqlite3-from io import BytesIO-from pathlib import Path-from typing import Any, Literal, cast--from fastapi import APIRouter, File, Form, HTTPException, Query, UploadFile-from fastapi.responses import FileResponse-from pydantic import BaseModel, Field, StrictInt--from .. import config, workspace-from ..engine import artifacts as artifact_engine-from ..engine import analysis_views as analysis_view_engine-from ..engine import bundles as bundle_engine-from ..engine import doctor as doctor_engine-from ..engine import entities as entity_engine-from ..engine import entity_images as entity_image_engine-from ..engine import graph as graph_engine-from ..engine import links as link_engine-from ..engine import media as media_engine-from ..engine import reveal as reveal_engine-from ..engine import satellite as satellite_engine-from ..engine import tally as tally_engine-from ..engine import trash as trash_engine-from ..engine import timeline as timeline_engine-from ..engine.temporal import TemporalError, window_bound-from ..repository import EntityStatus-from ..workspace import Case, CaseError-from .limits import MAX_IMAGE_BYTES--router = APIRouter(prefix="/api/cases", tags=["cases"])--#: Folders in the workspace that are not cases yet. Deliberately *not* under-#: `/api/cases`: a case's id is its folder name, so a literal segment there is a-#: name someone can give a folder — `/api/cases/folders` is already the case-#: named "Folders" (`tests/test_cases_api.py`). These operate on the workspace-#: anyway, one level above any case.-workspace_router = APIRouter(prefix="/api/workspace", tags=["cases"])---def get_case(case_id: str) -> Case:- try:- return Case.open(case_id)- except CaseError as exc:- raise HTTPException(status_code=404, detail=str(exc)) from exc---def _ensure_name_free(name: str, *, exclude_id: str | None = None) -> None:- """Reject a case name already taken by another (non-scratch) case, matched- case-insensitively on the trimmed name. ``exclude_id`` lets a rename keep- its own name."""- wanted = name.strip().casefold()- for c in Case.list_all():- if c.get("scratch") or c["id"] == exclude_id:- continue- if str(c.get("name", "")).strip().casefold() == wanted:- raise HTTPException(status_code=409, detail=f"a case named '{name}' already exists")---def delete_entities_deep(case: Case, entity_ids: list[str]) -> dict[str, Any]:- """Delete one UI action and everything that cannot outlive its targets.-- The one door every delete goes through — sidebar, Media Library, a tool's- own list — so the rules hold wherever the click came from:-- - artifacts that ``depends-on`` the target die with it (an Inspect session- is only adjustments over a video), transitively;- - artifacts ``derived-from`` it are never touched, and are scarred with a- tombstone first, while the target can still describe itself.-- The whole action lands in the trash as one group, so undoing it brings the- cascade back together or not at all. The graph rows are still hard-deleted:- what is kept is the recipe, not a hidden state every other query would have- to filter out.- """- with case.lock:- going_by_id: dict[str, dict[str, Any]] = {}- tombstoned: set[str] = set()- for entity_id in dict.fromkeys(entity_ids):- plan = link_engine.plan_delete(case, entity_id)- target = case.get_entity(entity_id)- if target is None:- raise CaseError(f"entity '{entity_id}' not found")- for entity in (target, *plan["cascade"]):- going_by_id[entity["id"]] = entity- tombstoned.update(entity["id"] for entity in plan["tombstone"])- going = list(going_by_id.values())-- scars: list[dict[str, str]] = []- losses = link_engine.losses(case, {e["id"] for e in going})- for survivor_id, lost_sources in losses.items():- survivor = case.get_entity(survivor_id)- existing = {- item.get("path")- for item in (survivor or {}).get("attrs", {}).get(link_engine.LOST, [])- }- for lost in lost_sources:- path = link_engine.tombstone_of(lost).get("path")- if path and path not in existing:- scars.append({"entity": survivor_id, "path": path})- existing.add(path)-- group = trash_engine.send(case, going, scars)- try:- for survivor_id, lost_sources in losses.items():- link_engine.add_tombstones(- case,- survivor_id,- [link_engine.tombstone_of(source) for source in lost_sources],- )- for entity in going:- if case.get_entity(entity["id"]) is not None:- case.remove_entity(entity["id"])- trash_engine.commit(case, group["id"])- except Exception:- trash_engine.rollback(case, group["id"])- raise-- return {- "status": "deleted",- "deleted": [e["id"] for e in going],- "tombstoned": sorted(tombstoned - set(going_by_id)),- "trash": group["id"],- }---def delete_entity_deep(case: Case, entity_id: str) -> dict[str, Any]:- return delete_entities_deep(case, [entity_id])---def _summary(entity: dict[str, Any]) -> dict[str, Any]:- return {- "id": entity["id"],- "type": entity.get("type"),- "label": entity.get("label"),- "path": link_engine.artifact_path(entity),- }---def delete_by_path(case: Case, rel_path: str) -> dict[str, Any]:- """Chokepoint entry for a tool that knows its artifact by path, not by id.-- Returns an empty ``deleted`` when no entity claims the path: the artifact was- never filed, so there is no graph to honour and the caller drops the files- itself.- """- entity = (- case.find_entity(attr="path", value=rel_path)- or case.find_entity(attr="spec", value=rel_path)- or case.find_entity(attr="draft", value=rel_path)- )- if entity is None:- return {"status": "deleted", "deleted": [], "tombstoned": []}- return delete_entity_deep(case, entity["id"])---class CreateCase(BaseModel):- name: str = Field(min_length=1, max_length=120)---class PromoteCase(BaseModel):- name: str = Field(min_length=1, max_length=120)---class EntityIn(BaseModel):- type: str = Field(min_length=1, max_length=40)- label: str = Field(min_length=1, max_length=300)- attrs: dict[str, Any] = Field(default_factory=dict)- status: EntityStatus = "confirmed"---class EntityPatch(BaseModel):- type: str | None = None- label: str | None = Field(default=None, min_length=1, max_length=300)- attrs: dict[str, Any] | None = None- status: EntityStatus | None = None---class EntityDeleteIn(BaseModel):- ids: list[str] = Field(min_length=1, max_length=200)---class EntityImagesIn(BaseModel):- media_ids: list[str] = Field(min_length=1, max_length=100)---class LinkIn(BaseModel):- # `from`/`to` are the link's own field names, but `from` is a Python keyword;- # the request spells them out rather than aliasing around it.- from_id: str = Field(min_length=1, max_length=64)- to_id: str = Field(min_length=1, max_length=64)- type: str = Field(min_length=1, max_length=40)---class LinkPatch(BaseModel):- status: EntityStatus | None = None- type: str | None = Field(default=None, min_length=1, max_length=40)- #: One closed ordinal, or `null` to return the edge to "not assessed". Sending it- #: at all is what counts, so the route reads `model_fields_set` rather than the- #: value: `null` clears a rating, where omitting the key leaves it alone.- #:- #: Strict, so JSON `true` is refused rather than coerced to `1`: a lax int would- #: turn a nonsense body into the "possible" level without anyone noticing, and- #: `2.5` into `2`.- confidence: StrictInt | None = None- #: What kind of tie the edge states, in the analyst's own words, or `null` to- #: clear it. Read through `model_fields_set` like the rating above, for the same- #: reason: `null` unsays it, omitting the key leaves it alone. Only a verb- #: declaring a `qualifier` accepts one (`engine/links.set_qualifier`).- nature: str | None = None---class TemporalClaimIn(BaseModel):- statement: str = Field(min_length=1, max_length=300)- when: str | None = None- time_role: Literal["occurred", "observed", "valid"] | None = None- confidence: Literal["certain", "probable", "possible", "refuted"] | None = None- method: str | None = None- verbatim: str | None = None- count: StrictInt | None = None- condition: Literal["intact", "damaged", "destroyed", "abandoned"] | None = None- about: list[str] = Field(default_factory=list, max_length=200)- at: list[str] = Field(default_factory=list, max_length=50)- cites: list[str] = Field(default_factory=list, max_length=200)---class TemporalClaimPatch(BaseModel):- statement: str | None = Field(default=None, min_length=1, max_length=300)- when: str | None = None- time_role: Literal["occurred", "observed", "valid"] | None = None- confidence: Literal["certain", "probable", "possible", "refuted"] | None = None- method: str | None = None- verbatim: str | None = None- count: StrictInt | None = None- condition: Literal["intact", "damaged", "destroyed", "abandoned"] | None = None- about: list[str] | None = Field(default=None, max_length=200)- at: list[str] | None = Field(default=None, max_length=50)- cites: list[str] | None = Field(default=None, max_length=200)- status: EntityStatus | None = None---class FolderIn(BaseModel):- name: str = Field(min_length=1, max_length=120)---class FolderName(BaseModel):- """A directory name in the workspace root, never a path: what it may hold is- `layout.usable_case_name`'s answer, checked where the folder is opened."""-- name: str = Field(min_length=1, max_length=120)---class BundlePassword(BaseModel):- password: str | None = Field(default=None, max_length=1024)---class BundleUpload(BundlePassword):- upload_id: str = Field(min_length=32, max_length=32)---class MediaPath(BaseModel):- """One case-relative file path, bounded the way every other media route bounds- one. Where it may point is `Case.resolve_inside`'s answer, not this model's."""-- path: str = Field(min_length=1, max_length=300)---class GraphPin(BaseModel):- """One node and where it was dropped, in the graph's own canvas units.-- Bounded because a coordinate arrives from a pointer and nothing downstream- clamps it: the layout would happily place a node at 1e300 and the view would- then scale the whole case down to a dot trying to frame it.- """-- id: str = Field(min_length=1, max_length=64)- x: float = Field(ge=-1_000_000, le=1_000_000)- y: float = Field(ge=-1_000_000, le=1_000_000)---class GraphPins(BaseModel):- #: Which reading was being arranged. An arrangement belongs to one, because a- #: lens draws its own nodes and clusters them its own way.- lens: str = Field(min_length=1, max_length=40)- #: One drag, or the batch a debounce collected. Capped at the view's own node- #: ceiling: nothing can be arranged that was never drawn.- pins: list[GraphPin] = Field(min_length=1, max_length=graph_engine.MAX_OPENING)---class DoctorRepair(BaseModel):- action: str = Field(min_length=1, max_length=20)- entity_id: str | None = Field(default=None, max_length=64)- path: str | None = Field(default=None, max_length=300)- replacement: str | None = Field(default=None, max_length=300)---def list_cases(q: str | None = None, limit: int | None = None) -> list[dict[str, Any]]:- return Case.list_all(q=q, limit=limit)---def create_case(body: CreateCase) -> dict[str, Any]:- _ensure_name_free(body.name)- try:- case = Case.create(body.name)- except CaseError as exc:- raise HTTPException(status_code=409, detail=str(exc)) from exc- return {"id": case.id, **case.overview()}---@workspace_router.get("/folders")-def list_workspace_folders() -> list[dict[str, Any]]:- """Folders sitting in the workspace that are not cases yet, and their state."""- return workspace.list_workspace_folders()---@workspace_router.post("/folders/adopt")-def adopt_folder(body: FolderName) -> dict[str, Any]:- """Make a case out of one of those folders, where it already is."""- _ensure_name_free(body.name)- try:- case = Case.adopt(body.name)- except CaseError as exc:- raise HTTPException(status_code=409, detail=str(exc)) from exc- return {"id": case.id, **case.overview()}---@workspace_router.post("/folders/recover")-def recover_folder(body: FolderName) -> dict[str, Any]:- """Write back the manifest of a folder holding a case that lost it.-- The manifest and nothing else: the case is reachable again after this, and- anything still damaged belongs to the Doctor, which the caller opens next.- """- try:- case = workspace.restore_manifest(body.name)- except CaseError as exc:- raise HTTPException(status_code=409, detail=str(exc)) from exc- return {"id": case.id, "name": case.read().get("name", case.id)}--[email protected]("/scratch")-def create_scratch() -> dict[str, Any]:- case = Case.create("Scratch session", scratch=True)- return {"id": case.id, **case.overview()}--[email protected]("/bundles/inspect")-def inspect_bundle(- file: UploadFile = File(),- password: str | None = Form(default=None, max_length=1024),-) -> dict[str, Any]:- upload_id: str | None = None- try:- upload_id, path = bundle_engine.stage_upload(file.file)- preview = bundle_engine.inspect_bundle(path, password=password)- except CaseError as exc:- if upload_id is not None:- bundle_engine.discard_upload(upload_id)- raise HTTPException(status_code=400, detail=str(exc)) from exc- preview.pop("path", None)- return {**preview, "upload_id": upload_id}--[email protected]("/bundles/import")-def import_bundle(body: BundleUpload) -> dict[str, Any]:- try:- source = bundle_engine.uploaded_bundle(body.upload_id)- case, job = bundle_engine.queue_import(- source,- password=body.password,- cleanup_source=True,- )- except CaseError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc- return {- "case_id": case.id,- "name": case.read().get("name", case.id),- "job_id": job["id"],- "state": job["state"],- }--[email protected]("/bundles/uploads/{upload_id}")-def discard_bundle_upload(upload_id: str) -> dict[str, str]:- try:- bundle_engine.discard_upload(upload_id)- except CaseError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc- return {"status": "discarded"}--[email protected]("/relation-types")-def relation_types() -> list[dict[str, Any]]:- """The relation vocabulary (ONTOLOGY §3): how each type reads in words, the- entity types each end accepts, and whether an analyst may state it.-- Every surface reads this instead of keeping its own copy — the picker offers- the ``manual`` ones, the relation rows use ``label`` to name an edge. Declared- above ``/{case_id}`` so the literal path wins.- """- return [- {- "type": entry.type,- "label": entry.label,- "inverse_label": entry.inverse_label or entry.label,- # one clause saying what the verb means, for the surface that shows it- "hint": entry.hint,- # the heading this verb sits under, empty when it sits with the rest- "group": entry.group,- # A mention is filed with its own gesture. It is not another wording- # a relation can turn into after the analyst chose a target.- "action": entry.action,- "from_types": sorted(entry.from_types),- "to_types": sorted(entry.to_types),- "manual": entry.manual,- # A mention is a pointer, not a claim to grade. The surface omits the- # control instead of offering one the model would refuse.- "ratable": entry.ratable,- # How a free note on this edge is labelled, empty when the verb takes- # none — the same shape as `ratable`, and read the same way: a surface- # draws the field because the verb declares it, never because an edge- # happens to carry one.- "qualifier": entry.qualifier,- "from_media_kinds": sorted(entry.from_media_kinds),- "to_media_kinds": sorted(entry.to_media_kinds),- }- for entry in link_engine.RELATION_TYPES- ]--[email protected]("/graph-lenses")-def graph_lenses() -> dict[str, Any]:- """The readings the graph offers, and the orderings it ranks by.-- A lens is a set of verbs *and* a set of node roles, and both live in the- registries, so each one is resolved from them rather than listed again here — a- verb or a type added there joins its lens with no edit. ``orders`` is the same- contract as the radius rungs: served, so the picker and the validator cannot drift.-- ``hides`` is the types the reading leaves out of the drawing. Served because the- surface has to be able to say so *before* asking: a legend row that switches- nothing and a "bring this in" that the reading will refuse are both controls that- can only appear to be broken.-- Declared above ``/{case_id}`` so the literal path wins.- """- return {- "lenses": [- {"id": entry.id, "label": entry.label, "hint": entry.hint,- "types": list(entry.types), "hides": list(entry.hides)}- for entry in graph_engine.lenses()- ],- "orders": [- {"value": value, "label": label, "hint": hint}- for value, label, hint in graph_engine.ORDERS- ],- "max_hops": graph_engine.MAX_HOPS,- }--[email protected]("/confidence-levels")-def confidence_levels() -> list[dict[str, Any]]:- """How sure an edge may say the analyst is (ONTOLOGY §3), coarsest word last.-- Served rather than hardcoded on each surface for the reason the radius rungs are:- one list, so the picker and the validator cannot drift. **Not assessed is absent- from this list on purpose** — it is the lack of a rating, not a sixth level, and a- surface offers it as "clear" rather than as a choice.-- Declared above ``/{case_id}`` so the literal path wins.- """- return [- {"value": value, "label": label, "hint": hint}- for value, label, hint in link_engine.CONFIDENCE_LEVELS- ]--[email protected]("/entity-types")-def entity_types() -> list[dict[str, Any]]:- """The entity vocabulary (ONTOLOGY §2): each type's reading, family, icon and- the fields an analyst may fill on it.-- One registry so a create form is generated rather than written per type, and so- no screen keeps its own copy. ``manual`` marks the types an analyst creates by- hand — a ``media`` is born from an import, so it never belongs in a create menu.- Declared above ``/{case_id}`` so the literal path wins.- """- return [- {- "type": entry.type,- "label": entry.label,- "family": entry.family,- # what the type is, and what its family is, each in one clause. The- # vocabulary is terse by design, and a terse word nobody can look up is- # jargon — so the readings travel with it rather than being written per- # screen.- "hint": entry.hint,- "family_reads": entity_engine.FAMILY_READS.get(entry.family, ""),- "icon": entry.icon,- "manual": entry.manual,- "image_gallery": entry.image_gallery,- # ``entity.label`` is the primary value, but "Name" is not an honest- # reading for an IP address, a phone number or a claim. The generated- # form names that field from the type instead of duplicating it in attrs.- "identity_label": entry.identity_label,- "identity_placeholder": entry.identity_placeholder,- "attrs": [- {- "key": attr.key,- "label": attr.label,- "hint": attr.hint,- "kind": attr.kind,- "editable": attr.editable,- # Heads this field and the ones after it that share it; empty- # means the field stands on its own label. On the field rather- # than on the type because a Claim separates what it states,- # when it applies and why it is believed.- "group": attr.group,- # Served so the form refuses exactly what the API refuses; a- # rung list is the shortcut UI, the bounds are the contract.- "rungs": [{"label": name, "value": v} for name, v in attr.rungs],- "minimum": attr.minimum,- "maximum": attr.maximum,- # A count steps by one. Served so the spinner and the validator- # cannot disagree about what a valid quantity is.- "whole": attr.whole,- # The whole of a closed field, in scale order. A source's- # reliability rides here rather than on a route of its own: it- # belongs to the entity, so it travels with the entity registry.- "options": [- {"value": stored, "label": reading}- for stored, reading in attr.options- ],- }- for attr in entry.attrs- ],- }- for entry in entity_engine.ENTITY_TYPES- ]--[email protected]("/{case_id}/doctor")-def doctor_report(case_id: str) -> dict[str, Any]:- """Inspect a case even when its database is missing."""- try:- return doctor_engine.scan(Case.locate(case_id))- except CaseError as exc:- raise HTTPException(status_code=404, detail=str(exc)) from exc--[email protected]("/{case_id}/doctor/repair")-def doctor_repair(case_id: str, body: DoctorRepair) -> dict[str, Any]:- """Apply one repair that the current Doctor report explicitly offers."""- try:- located = Case.locate(case_id)- if body.action == "rebuild":- result = doctor_engine.rebuild_database(located)- case = located- else:- case = Case.open(case_id)- if body.action == "rebuild-timeline":- doctor_engine.require_stale_temporal_projection(case)- result = {- "status": "rebuilt",- "items": case.rebuild_temporal_projection(),- }- elif body.action == "import" and body.path:- doctor_engine.require_unknown_media(case, body.path)- result = media_engine.register_existing(case, body.path)- elif body.action == "drop" and body.entity_id:- doctor_engine.require_missing_media(case, body.entity_id)- result = delete_entity_deep(case, body.entity_id)- elif body.action == "relink" and body.entity_id and body.replacement:- doctor_engine.require_missing_media(case, body.entity_id)- doctor_engine.require_unknown_media(case, body.replacement)- result = media_engine.relink_existing(- case,- body.entity_id,- body.replacement,- )- else:- raise CaseError("this repair action is not valid")- return {"repair": result, "report": doctor_engine.scan(case)}- except (CaseError, OSError, ValueError, sqlite3.Error) as exc:- raise HTTPException(status_code=409, detail=str(exc)) from exc--[email protected]("/{case_id}")-def read_case(case_id: str) -> dict[str, Any]:- case = get_case(case_id)- return {"id": case.id, "scratch": case.is_scratch, **case.overview()}--[email protected]("/{case_id}/promote")-def promote_case(case_id: str, body: PromoteCase) -> dict[str, Any]:- case = get_case(case_id)- _ensure_name_free(body.name)- try:- promoted = case.promote(body.name)- except CaseError as exc:- raise HTTPException(status_code=409, detail=str(exc)) from exc- return {"id": promoted.id, **promoted.overview()}--[email protected]("/{case_id}")-def rename_case(case_id: str, body: CreateCase) -> dict[str, Any]:- case = get_case(case_id)- _ensure_name_free(body.name, exclude_id=case.id)- case.rename(body.name)- return {"id": case.id, **case.overview()}--[email protected]("/{case_id}")-def delete_case(case_id: str) -> dict[str, str]:- get_case(case_id).delete()- return {"status": "deleted"}--[email protected]("/{case_id}/reveal")-def reveal_case_folder(case_id: str) -> dict[str, str]:- """Open this case's folder in the system file manager.-- The route takes no path: the case id is enough to find the folder, so nothing- the browser sends can point somewhere else.- """- case = get_case(case_id)- try:- reveal_engine.reveal(case.path)- except reveal_engine.RevealError as exc:- raise HTTPException(status_code=409, detail=str(exc)) from exc- return {"path": str(case.path)}--[email protected]("/{case_id}/media/reveal")-def reveal_media_folder(case_id: str, body: MediaPath) -> dict[str, str]:- """Show the folder holding one of this case's files.-- For what the app cannot display: a PDF, a scan bundle, a spreadsheet. Handing- those to the browser downloads a second copy into Downloads, which is how an- analyst ends up working on a file the case no longer knows about. The folder is- the honest answer — the original is opened in whatever program owns it.-- The path is the browser's, so it goes through ``resolve_inside`` like every- other media route; ``reveal`` then re-checks that the folder is inside the- workspace, and it is a folder that is opened, never the file itself.- """- case = get_case(case_id)- try:- target = case.resolve_inside(body.path)- except CaseError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc- if not target.is_file():- raise HTTPException(status_code=404, detail="file not found")- try:- reveal_engine.reveal(target.parent)- except reveal_engine.RevealError as exc:- raise HTTPException(status_code=409, detail=str(exc)) from exc- return {"path": str(target.parent)}--[email protected]("/{case_id}/bundle/export")-def export_bundle(case_id: str, body: BundlePassword) -> dict[str, Any]:- case = get_case(case_id)- try:- job = bundle_engine.queue_export(case, password=body.password)- except CaseError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc- return {- "case_id": case.id,- "job_id": job["id"],- "state": job["state"],- }--[email protected]("/{case_id}/bundle/jobs/{job_id}")-def bundle_job(case_id: str, job_id: str) -> dict[str, Any]:- job = bundle_engine.job_status(case_id, job_id)- if job is None or job.get("kind") not in {- bundle_engine.EXPORT_JOB,- bundle_engine.IMPORT_JOB,- }:- raise HTTPException(status_code=404, detail=f"bundle job '{job_id}' not found")- return {- "id": job["id"],- "kind": job["kind"],- "state": job["state"],- "error": job.get("error"),- }--[email protected]("/{case_id}/bundle/jobs/{job_id}/download")-def download_bundle(case_id: str, job_id: str) -> FileResponse:- job = bundle_engine.job_status(case_id, job_id)- if (- job is None- or job.get("kind") != bundle_engine.EXPORT_JOB- or job.get("state") != "ready"- ):- raise HTTPException(status_code=404, detail="bundle download not ready")- path = Path(job.get("payload", {}).get("output", ""))- try:- allowed = path.resolve().parent == config.bundles_dir().resolve()- except OSError:- allowed = False- if not allowed or not path.is_file():- raise HTTPException(status_code=404, detail="bundle download not found")- return FileResponse(- path,- filename=path.name,- media_type="application/octet-stream",- )---def _explain_catalog_matches(page: dict[str, Any], query: str | None) -> dict[str, Any]:- if not query:- return page- for entity in page.get("items", []):- if matches := entity_engine.search_matches(entity, query):- entity["matches"] = matches- return page---def _temporal_filter_args(- from_: str | None,- to: str | None,- category: str | None,-) -> tuple[str | None, str | None, list[str] | None]:- """Validate the fact-time window kept separate from filing dates."""- if from_ is None and to is None:- return None, None, None- if from_ is None or to is None:- raise HTTPException(status_code=400, detail="a temporal filter needs both boundaries")- since = _timeline_bound(from_, upper=False)- until = _timeline_bound(to, upper=True)- if since is not None and until is not None and since >= until:- raise HTTPException(status_code=400, detail="the temporal filter ends before it starts")- categories = (- list(dict.fromkeys(part.strip() for part in category.split(",") if part.strip()))- if category is not None- else list(timeline_engine.DEFAULT_CATEGORIES)- )- invalid = sorted(set(categories) - set(timeline_engine.ALL_CATEGORIES))- if invalid:- raise HTTPException(status_code=400, detail=f"unknown timeline category '{invalid[0]}'")- if not categories:- raise HTTPException(status_code=400, detail="a temporal filter needs a category")- return since, until, categories--[email protected]("/{case_id}/catalog/entities")-def catalog_entities(- case_id: str,- cursor: str | None = None,- limit: int = 100,- type: str | None = None,- status: str | None = None,- q: str | None = None,- folder: str | None = None,- unfiled: bool = False,- recursive: bool = False,- attr: str | None = None,- value: str | None = None,- linked: str | None = None,- unlinked: bool = False,- since: str | None = None,- until: str | None = None,- by: str | None = None,- temporal_from: str | None = None,- temporal_to: str | None = None,- temporal_category: str | None = None,- order: str = "",- view: str | None = None,-) -> dict[str, Any]:- """A bounded page of the entity catalog (Step 5, "Bounded loading").-- Stable cursor order, server-side filters and a ``next_cursor`` that is null on the- last page. ``limit`` is clamped so no request can ask for the whole graph at once.-- The filters: a comma-separated ``type`` set, ``status``, a label substring ``q``,- folder (``unfiled=true`` or a ``folder`` path, optionally including descendants),- one stored field holding one value (``attr`` with ``value``), having a neighbour of- a type (``linked``) or none at all (``unlinked``), and how the row got here —- ``since``/``until`` over the date it was filed, and a comma-separated ``by`` set of- whatever filed it. Together they are what make the page an answer rather than a- shorter list: *media, kind video, linked to a place* is "which videos have- coordinates", and ``total`` is how many.-- ``order`` sorts the whole filtered set rather than the page — ``created`` and- ``label``, each with a ``-`` prefix for the other direction. Empty is the insertion- order that has always been the default.-- ``attr`` without ``value`` is not a term — it is the analyst having chosen which- field they are about to ask about, and answering it as "holds nothing" would empty- the table between two clicks of one act.- """- case = get_case(case_id)- limit = max(1, min(limit, 500))- if view:- saved = case.get_analysis_view(view)- if saved is None:- raise HTTPException(status_code=404, detail=f"analysis view '{view}' not found")- if saved["mode"] == "snapshot":- try:- return _explain_catalog_matches(- analysis_view_engine.snapshot_page(- saved, limit=limit, cursor=cursor, order=order- ),- q,- )- except CaseError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc- types = [t.strip() for t in type.split(",") if t.strip()] if type else None- filed_by = [name.strip() for name in by.split(",") if name.strip()] if by else None- temporal_since, temporal_until, temporal_categories = _temporal_filter_args(- temporal_from, temporal_to, temporal_category- )- valid_status = (- cast(EntityStatus, status) if status in ("confirmed", "suggested") else None- )- try:- page = case.page_entities(- limit=limit, cursor=cursor, types=types, status=valid_status,- query=q, folder=folder, unfiled=unfiled, recursive=recursive,- attr=attr, attr_value=value, linked=linked, unlinked=unlinked,- since=since, until=until, filed_by=filed_by, order=order,- temporal_since=temporal_since, temporal_until=temporal_until,- temporal_categories=temporal_categories,- )- thumbs = case.entity_image_thumbs([entity["id"] for entity in page["items"]])- for entity in page["items"]:- if thumb := thumbs.get(entity["id"]):- entity["thumb"] = thumb- return _explain_catalog_matches(page, q)- except CaseError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc--[email protected]("/{case_id}/catalog/summary")-def catalog_summary(case_id: str) -> dict[str, Any]:- """Counts per type, status, folder and filer, plus how many the case connects to- nothing, so the catalog shows badges and populates its filter menus without- loading the graph."""- return get_case(case_id).catalog_summary()--[email protected]("/{case_id}/catalog/attributes")-def catalog_attributes(case_id: str, type: str | None = None) -> dict[str, Any]:- """Which stored fields these entities hold, and which values, as a menu.-- What lets a field be filtered on without a query language: the field select and- the value select are both populated from the case, so every term of a search is- chosen rather than typed (SPEC anti-goals). It reaches fields the vocabulary does- not declare, which is the point — `kind` is written by the importer, so a- registry-driven menu would never have offered the one field an analyst most wants.-- Narrowed by the same comma-separated ``type`` set as the page it filters: the- fields a media holds are not the fields a claim holds, and one menu of both is a- menu of neither.- """- types = [t.strip() for t in type.split(",") if t.strip()] if type else None- return {"attrs": get_case(case_id).attr_facets(types=types)}--[email protected]("/{case_id}/catalog/tally")-def catalog_tally(- case_id: str,- type: str | None = None,- status: str | None = None,- q: str | None = None,- folder: str | None = None,- unfiled: bool = False,- recursive: bool = False,- attr: str | None = None,- value: str | None = None,- linked: str | None = None,- unlinked: bool = False,- since: str | None = None,- until: str | None = None,- by: str | None = None,- temporal_from: str | None = None,- temporal_to: str | None = None,- temporal_category: str | None = None,-) -> dict[str, Any]:- """What the statements in this narrowing add up to, per subject.-- The same terms as the catalog page it sits beside, spelled the same way, because- it is the same question: the table lists the statements, this one adds them up- (``engine/tally.py``). Every rule about what may enter a sum is there — a ruled-out- statement never does, an absent count is not one, and nothing is totalled across- subjects.- """- types = [t.strip() for t in type.split(",") if t.strip()] if type else None- filed_by = [name.strip() for name in by.split(",") if name.strip()] if by else None- temporal_since, temporal_until, temporal_categories = _temporal_filter_args(- temporal_from, temporal_to, temporal_category- )- try:- return tally_engine.tally(- get_case(case_id), types=types, status=status, query=q,- folder=folder, unfiled=unfiled, recursive=recursive,- attr=attr, attr_value=value, linked=linked, unlinked=unlinked,- since=since, until=until, filed_by=filed_by,- temporal_since=temporal_since, temporal_until=temporal_until,- temporal_categories=temporal_categories,- )- except CaseError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc---def _ids(value: str | None) -> list[str] | None:- """One of the graph's comma-separated id lists, or nothing at all.-- ``None`` rather than an empty list when nothing was sent, because the engine- tells "no list" from "an empty one" and answers the first by not asking.- """- if not value:- return None- named = [entity_id.strip() for entity_id in value.split(",") if entity_id.strip()]- return named or None--[email protected]("/{case_id}/graph")-def graph_view(- case_id: str,- lens: str = "all",- limit: int | None = None,- order: str = "degree",- type: str | None = None,- status: str | None = None,- q: str | None = None,- folder: str | None = None,- unfiled: bool = False,- recursive: bool = False,- attr: str | None = None,- value: str | None = None,- linked: str | None = None,- unlinked: bool = False,- since: str | None = None,- until: str | None = None,- by: str | None = None,- temporal_from: str | None = None,- temporal_to: str | None = None,- temporal_category: str | None = None,- keep: str | None = None,- expand: str | None = None,- omit: str | None = None,- view: str | None = None,-) -> dict[str, Any]:- """The whole case as one bounded graph — the view the graph opens on.-- A case is a subject before it is a set of statements, so this is the entry- point and expansion is the drill-down, not the other way round. ``order``- decides which nodes a case too large to draw keeps: the hubs, or the latest- work. **The catalog's whole filter vocabulary narrows it** — down to the stored- field, the one-hop test and the date it was filed — so the board and the graph- cannot disagree about what "confirmed people in this folder, added this week"- means, and a question asked in the table can be handed to the drawing as itself- rather than as a list of ids that goes stale on the next save.-- Three comma-separated lists then edit that set, and the drawing is whatever they- say it is. ``keep`` draws these nodes and nothing around them; ``expand`` draws- these and one hop, which is what lets the analyst follow a thread without losing- the case they were reading it in; ``omit`` leaves these out, whichever of the- three put them there. Ids the case does not hold are skipped rather than refused —- a drawing races a delete made in another tab.- """- case = get_case(case_id)- if view:- saved = case.get_analysis_view(view)- if saved is None:- raise HTTPException(status_code=404, detail=f"analysis view '{view}' not found")- if saved["mode"] == "snapshot":- try:- return graph_engine.snapshot_view(- saved["spec"]["snapshot"], lens_id=lens, query=q- )- except CaseError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc- types = [t.strip() for t in type.split(",") if t.strip()] if type else None- filed_by = [name.strip() for name in by.split(",") if name.strip()] if by else None- temporal_since, temporal_until, temporal_categories = _temporal_filter_args(- temporal_from, temporal_to, temporal_category- )- try:- payload = graph_engine.view(- case, lens_id=lens, limit=limit, types=types, status=status,- query=q, folder=folder, unfiled=unfiled, recursive=recursive, order=order,- attr=attr, attr_value=value, linked=linked, unlinked=unlinked,- since=since, until=until, filed_by=filed_by,- temporal_since=temporal_since, temporal_until=temporal_until,- temporal_categories=temporal_categories,- keep=_ids(keep), expand=_ids(expand), omit=_ids(omit),- )- except CaseError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc- _adopt_spec_previews(case, payload)- return payload--[email protected]("/{case_id}/graph/neighborhood")-def graph_neighborhood(- case_id: str,- root: str,- lens: str = "all",- hops: int = 1,- limit: int | None = None,-) -> dict[str, Any]:- """One node and what surrounds it, for a question that does have a root.-- Every node carries its degree in this lens, so the analyst sees what a further- expansion costs before paying it, and ``truncated`` says when the node budget- ended the walk rather than the graph doing so.- """- case = get_case(case_id)- try:- payload = graph_engine.neighborhood(- case, root, lens_id=lens, hops=hops, limit=limit- )- except CaseError as exc:- detail = str(exc)- status_code = 404 if "not found" in detail else 400- raise HTTPException(status_code=status_code, detail=detail) from exc- _adopt_spec_previews(case, payload)- return payload--[email protected]("/{case_id}/graph/paths")-def graph_paths(- case_id: str,- from_id: str = Query(alias="from"),- to_id: str = Query(alias="to"),- lens: str = "all",- hops: int = graph_engine.MAX_PATH_HOPS,-) -> dict[str, Any]:- """Every shortest route between two entities, or the fact that there is none.-- A read, and the one question the graph existed without: the case answers "what- touches this" a hop at a time, where an investigation asks "how does this reach- that". ``found: false`` is an answer rather than an error — learning that two- entities are *not* connected within the budget is a finding about the case.-- ``from`` and ``to`` are query names rather than argument names because ``from``- is a Python keyword, and the URL is the vocabulary the client reads.- """- case = get_case(case_id)- try:- return graph_engine.paths(case, from_id, to_id, lens_id=lens, max_hops=hops)- except CaseError as exc:- detail = str(exc)- status_code = 404 if "not found" in detail else 400- raise HTTPException(status_code=status_code, detail=detail) from exc---def _lens_id(lens: str) -> str:- """The lens an arrangement belongs to, refused if the registry does not know it.-- Checked at the edge like every other lens: an unrecognised one would file pins- under a reading nothing can ever draw, where they would sit in the case forever- with no surface able to show or clear them.- """- try:- return graph_engine.lens(lens).id- except CaseError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc--[email protected]("/{case_id}/graph/pins")-def pin_graph_nodes(case_id: str, body: GraphPins) -> dict[str, Any]:- """Record where nodes were dragged to, so the arrangement survives a reload.-- Filed against the lens they were arranged in: a lens draws its own nodes and- clusters them its own way, so one shared arrangement would anchor every reading- into the shape of whichever one it was built in.-- The whole batch in one transaction: a drag that moved several nodes is one- act, and half of it landing would leave an arrangement nobody chose. Writing a- pin asserts nothing about the case — it is where a hand put a dot — which is- why it never touches the entity or its provenance.- """- case = get_case(case_id)- lens = _lens_id(body.lens)- case.pin_entities(lens, {pin.id: (pin.x, pin.y) for pin in body.pins})- return {"lens": lens, "pinned": len(case.graph_pins(lens))}--[email protected]("/{case_id}/graph/pins/{entity_id}")-def unpin_graph_node(case_id: str, entity_id: str, lens: str = "all") -> dict[str, Any]:- """Hand one node back to the computed layout, in this lens."""- case = get_case(case_id)- reading = _lens_id(lens)- case.unpin_entities(reading, [entity_id])- return {"lens": reading, "pinned": len(case.graph_pins(reading))}--[email protected]("/{case_id}/graph/pins")-def unpin_graph(case_id: str, lens: str = "all") -> dict[str, Any]:- """Drop this lens's arrangement: the reading goes back to the placement it- computes, and the other readings keep theirs.-- The way out of an arrangement that stopped helping. It is offered because the- pins are saved as they are made — an autosave with no way back is a trap.- """- case = get_case(case_id)- reading = _lens_id(lens)- case.clear_graph_pins(reading)- return {"lens": reading, "pinned": 0}---def _adopt_spec_previews(case: Case, payload: dict[str, Any]) -> None:- """Give a node the preview its own spec file has been keeping to itself.-- A proof records its thumbnail in ``proofs/.meta/<name>.json``, and the graph- answers from the database alone — that boundary is what keeps a graph read one- query instead of a walk of the case, so it is not the place to open files. This- copies the path across, **once per proof, ever**: the first view that draws one- reads its spec, records it on the entity, and every later view finds it on the row- like any other preview. A proof saved from now on carries it from the start.- """- for node in payload.get("nodes", []):- if node.get("thumb") or node.get("type") != "proof":- continue- entity = case.get_entity(node["id"])- thumb = artifact_engine.spec_thumb(case, entity) if entity else None- if not thumb:- continue- node["thumb"] = thumb- try:- case.update_entity(node["id"], {"attrs": {"thumb": thumb}})- except (CaseError, sqlite3.Error):- # The copy is an optimisation, not the answer: a background import or- # a mass delete holding the write lock past `busy_timeout` must not- # turn a read of the graph into an error. The node already carries- # what it needs, and the next draw tries the copy again.- pass--[email protected]("/{case_id}/entities/lookup")-def lookup_entity(case_id: str, attr: str, value: str) -> dict[str, Any]:- """One entity by an ``attrs`` value (``path``, ``spec``, ``draft``), or null.-- The bounded replacement for a tool scanning the whole graph to answer "is the- file/spec I am bound to still in the case?" after a delete elsewhere, or to- resolve a file path back to its entity (Step 5).- """- entity = get_case(case_id).find_entity(attr=attr, value=value)- return {"entity": entity}--[email protected]("/{case_id}/entities/twin")-def entity_twin(- case_id: str, type: str, label: str, ignore: str = ""-) -> dict[str, Any]:- """The entity already holding this identifier's value, or null.-- Only the ``identifier`` family answers anything: there the value *is* the- identity, so two records of it are two records of one thing (ONTOLOGY §2).- Everywhere else two entities may share a label and the question is meaningless.-- **It warns, it never refuses.** Merging is not shipped (`same-as`, SPEC §10), and- a create that failed would leave the analyst holding a value with nowhere to put- it — so this reports and the surface offers the row it found. ``ignore`` is the- entity being renamed, which is not its own twin.-- The comparison lives in ``engine/entities.identity_key`` and is served rather- than reimplemented: the create form used to lowercase the raw label in the- browser, which let `@handle` and `handle` sit side by side as two accounts.- """- key = entity_engine.identity_key(type, label)- if not key:- return {"entity": None}- case = get_case(case_id)- for entity_id, existing in case.labels_of_type(type):- if entity_id != ignore and entity_engine.identity_key(type, existing) == key:- return {"entity": case.get_entity(entity_id)}- return {"entity": None}--[email protected]("/{case_id}/entities")-def add_entity(case_id: str, body: EntityIn) -> dict[str, Any]:- case = get_case(case_id)- _check_attrs(body.type, body.attrs)- if body.type == "note":- attrs = body.attrs- return case.create_note(- body.label.strip(),- str(attrs.get("folder", "")).strip(),- str(attrs.get("content", "")),- )- return case.add_entity(body.type, body.label, body.attrs, by="user", status=body.status)---def _check_attrs(- type_: str,- attrs: dict[str, Any],- *,- current: dict[str, Any] | None = None,-) -> None:- """Refuse a malformed declared field with a 400, never a 404.-- Split out because the two write paths reach it from different places and the- update path's own ``except CaseError`` answers 404 — a bad radius is a bad- request, not a missing entity.- """- try:- entity_engine.check_attrs(type_, attrs, current=current)- except CaseError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc---def _timeline_bound(raw: str | None, *, upper: bool) -> str | None:- if raw is None:- return None- try:- return window_bound(raw, upper=upper)- except TemporalError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc--[email protected]("/{case_id}/timeline")-def timeline(- case_id: str,- from_: str | None = Query(default=None, alias="from"),- to: str | None = None,- category: list[str] | None = Query(default=None),- entity: str | None = None,- include_undated: bool = True,- limit: int = Query(default=100, ge=1, le=200),- cursor: str | None = None,- bucket: Literal["year", "month", "day", "hour"] | None = None,- track: str | None = None,- spread: bool = False,-) -> dict[str, Any]:- """One bounded temporal page, independent of the projection's SQL shape.-- ``spread`` is for a caller drawing the page on an axis: it samples the window- rather than serving its front, so a lopsided case fills the axis it spans.- """- since = _timeline_bound(from_, upper=False)- until = _timeline_bound(to, upper=True)- if since is not None and until is not None and since >= until:- raise HTTPException(status_code=400, detail="the timeline window ends before it starts")- if track and len(track.encode("utf-8")) > 64 * 1024:- raise HTTPException(status_code=400, detail="timeline track query is too large")- try:- track_query = json.loads(track) if track else None- if track_query is not None and not isinstance(track_query, dict):- raise CaseError("a timeline track query must be an object")- page = get_case(case_id).timeline_page(- since=since,- until=until,- categories=category,- entity_id=entity,- include_undated=include_undated,- limit=limit,- cursor=cursor,- bucket=bucket,- track=track_query,- spread=spread,- )- except (CaseError, json.JSONDecodeError) as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc- return {**page, "window": {"from": since, "to": until}}---# Every way the case puts something on the map. A Claim says where it happened with-# `at`, and that was the only one this layer knew — so a window full of photographs-# recorded somewhere, captures showing somewhere, or a structure standing somewhere-# answered with an empty map and the words "nothing carries a place". `mentions` is-# not here: a note referring to a place is not a thing that was there.-_MAP_PLACE_LINKS = (- link_engine.AT,- link_engine.LOCATED_AT,- link_engine.DEPICTS,- link_engine.SITED_AT,-)--[email protected]("/{case_id}/timeline/map")-def timeline_map(- case_id: str,- from_: str = Query(alias="from"),- to: str = Query(),- category: list[str] | None = Query(default=None),-) -> dict[str, Any]:- """Whatever the window holds that the case has put somewhere, for the Map layer."""- since = _timeline_bound(from_, upper=False)- until = _timeline_bound(to, upper=True)- if since is None or until is None or since >= until:- raise HTTPException(status_code=400, detail="the timeline window ends before it starts")- categories = (- list(dict.fromkeys(part.strip() for part in ",".join(category).split(",") if part.strip()))- if category- else list(timeline_engine.DEFAULT_CATEGORIES)- )- invalid = sorted(set(categories) - set(timeline_engine.ALL_CATEGORIES))- if invalid:- raise HTTPException(status_code=400, detail=f"unknown timeline category '{invalid[0]}'")- if not categories:- raise HTTPException(status_code=400, detail="a temporal filter needs a category")-- case = get_case(case_id)- rows: list[dict[str, Any]] = []- cursor: str | None = None- read = 0- total = 0- ceiling = 5000- while read < ceiling:- page = case.timeline_page(- since=since,- until=until,- categories=categories,- include_undated=False,- limit=min(200, ceiling - read),- cursor=cursor,- )- if read == 0:- total = int(page["total"])- batch = list(page["items"])- rows.extend(batch)- read += len(batch)- cursor = page["next_cursor"]- if cursor is None or not batch:- break-- # Resolved from the edges themselves rather than from the row's own `at` list,- # which only a Claim ever fills.- owners = {str(item["owner_id"]) for item in rows}- held: dict[str, list[str]] = {}- for edge in case.links_touching(- sorted(owners), types=list(_MAP_PLACE_LINKS), end_types=["place"]- ):- if edge["from"] in owners and edge["to"] != edge["from"]:- held.setdefault(edge["from"], []).append(edge["to"])-- place_ids = list(dict.fromkeys(- place_id for places in held.values() for place_id in places- ))- places = {entity["id"]: entity for entity in case.entities_by_ids(place_ids)}-- # What a mark on the map has to know to hand its row back to the tool that owns- # it, and to show a photograph as a photograph rather than as a line of text.- placed_owners = sorted(held)- owned = {entity["id"]: entity for entity in case.entities_by_ids(placed_owners)}- thumbs = dict(case.media_thumbs(placed_owners))- thumbs.update(case.entity_image_thumbs(placed_owners))- for owner_id, entity in owned.items():- # A capture or a proof records its own preview rather than owning an indexed- # media row, and the graph reads them the same way.- recorded = (entity.get("attrs") or {}).get("thumb")- if recorded and owner_id not in thumbs:- thumbs[owner_id] = recorded-- mapped: list[dict[str, Any]] = []- mark_count = 0- for item in rows:- owner_id = str(item["owner_id"])- owner = owned.get(owner_id)- positioned = []- for place_id in dict.fromkeys(held.get(owner_id, [])):- place = places.get(place_id)- attrs = place.get("attrs") if place else None- if place is None or not isinstance(attrs, dict):- continue- try:- lat = float(attrs["lat"])- lon = float(attrs["lon"])- except (KeyError, TypeError, ValueError):- continue- if not math.isfinite(lat) or not math.isfinite(lon):- continue- positioned.append({- "id": place_id,- "label": place.get("label", "Place"),- "lat": lat,- "lon": lon,- "radius_m": attrs.get("radius_m"),- "footprint": attrs.get("footprint"),- })- if positioned:- mapped.append({- **item,- "place_entities": positioned,- "owner": {- "id": owner_id,- "type": owner.get("type", "") if owner else item.get("owner_type", ""),- "label": owner.get("label", "") if owner else item.get("label", ""),- "attrs": owner.get("attrs") or {} if owner else {},- "thumb": thumbs.get(owner_id),- },- })- mark_count += len(positioned)-- return {- "items": mapped,- "matched": total,- "mapped": len(mapped),- "marks": mark_count,- "truncated": read < total,- "window": {"from": since, "to": until},- }---_TEMPORAL_CLAIM_ATTRS = (- "when", "time_role", "confidence", "method", "verbatim", "count", "condition"-)-_TEMPORAL_CONNECTORS = ("about", "at", "cites")---def _temporal_item(case: Case, claim_id: str) -> dict[str, Any]:- """The row this Claim owns, wherever the entity scope puts it.-- That scope also answers with rows owned by whatever cites the Claim, and they- are ordered by date rather than by ownership — so a Claim many others rest on- can sit past the first page, and reading only that page would fail a write- that has already been committed.- """- cursor: str | None = None- while True:- page = case.timeline_page(- categories=[timeline_engine.STATEMENT],- entity_id=claim_id,- include_undated=True,- limit=200,- cursor=cursor,- )- for item in page["items"]:- if item["owner_id"] == claim_id:- return item- cursor = page["next_cursor"]- if cursor is None:- raise HTTPException(- status_code=500,- detail=f"claim '{claim_id}' was saved without a temporal row",- )---def _check_claim_connectors(- case: Case,- source: dict[str, Any],- connectors: dict[str, list[str]],-) -> None:- for type_, targets in connectors.items():- for target in dict.fromkeys(targets):- target_entity = case.get_entity(target)- if type_ == "about" and target_entity is not None and target_entity["type"] == "claim":- raise HTTPException(- status_code=400,- detail=(- "A Claim has one date or range. Edit its date, or create a"- " separate Claim."- ),- )- try:- link_engine.check_relation_target(case, source, target, type_)- except CaseError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc--[email protected]("/{case_id}/timeline/claims")-def create_temporal_claim(case_id: str, body: TemporalClaimIn) -> dict[str, Any]:- """Create the statement, date and all of its connectors in one transaction."""- case = get_case(case_id)- statement = body.statement.strip()- if not statement:- raise HTTPException(status_code=400, detail="a Claim statement cannot be empty")- attrs = {- key: getattr(body, key)- for key in _TEMPORAL_CLAIM_ATTRS- if getattr(body, key) is not None- }- _check_attrs("claim", attrs)- connectors = {key: getattr(body, key) for key in _TEMPORAL_CONNECTORS}- _check_claim_connectors(case, {"type": "claim"}, connectors)- try:- saved = case.save_temporal_claim(- entity_id=None,- label=statement,- attrs=attrs,- connectors=connectors,- by="user",- )- except CaseError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc- return {**saved, "temporal": _temporal_item(case, saved["entity"]["id"])}--[email protected]("/{case_id}/timeline/claims/{claim_id}")-def update_temporal_claim(- case_id: str, claim_id: str, body: TemporalClaimPatch-) -> dict[str, Any]:- """Replace a Claim's temporal fields and selected connector sets atomically."""- if not body.model_fields_set:- raise HTTPException(status_code=400, detail="nothing to update")- case = get_case(case_id)- current = case.get_entity(claim_id)- if current is None:- raise HTTPException(status_code=404, detail=f"entity '{claim_id}' not found")- if current["type"] != "claim":- raise HTTPException(status_code=400, detail=f"entity '{claim_id}' is not a Claim")- if "statement" in body.model_fields_set and body.statement is None:- raise HTTPException(status_code=400, detail="a Claim statement cannot be empty")- statement = (body.statement or current["label"]).strip()- if not statement:- raise HTTPException(status_code=400, detail="a Claim statement cannot be empty")-- attrs = dict(current.get("attrs") or {})- for key in _TEMPORAL_CLAIM_ATTRS:- if key in body.model_fields_set:- attrs[key] = getattr(body, key)- _check_attrs("claim", attrs, current=current.get("attrs") or {})- connector_keys = set(_TEMPORAL_CONNECTORS) & body.model_fields_set- connectors = (- {key: list(getattr(body, key) or []) for key in connector_keys}- if connector_keys- else None- )- if connectors is not None:- _check_claim_connectors(case, current, connectors)- try:- saved = case.save_temporal_claim(- entity_id=claim_id,- label=statement,- attrs=attrs,- connectors=connectors,- by="user",- status=body.status or current["provenance"]["status"],- )- except CaseError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc- return {**saved, "temporal": _temporal_item(case, claim_id)}--[email protected]("/{case_id}/timeline/claims/{claim_id}")-def remove_temporal_claim(case_id: str, claim_id: str) -> dict[str, Any]:- """Delete one Claim through the normal recoverable Trash workflow."""- case = get_case(case_id)- entity = case.get_entity(claim_id)- if entity is None:- raise HTTPException(status_code=404, detail=f"entity '{claim_id}' not found")- if entity["type"] != "claim":- raise HTTPException(status_code=400, detail=f"entity '{claim_id}' is not a Claim")- try:- return delete_entity_deep(case, claim_id)- except CaseError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc--[email protected]("/{case_id}/entities/{entity_id}")-def update_entity(case_id: str, entity_id: str, body: EntityPatch) -> dict[str, Any]:- case = get_case(case_id)- patch = {k: v for k, v in body.model_dump().items() if v is not None}- if body.attrs is not None:- # Against the type it will have once patched, and the entity has to exist- # before its fields can be judged.- current = case.get_entity(entity_id)- if current is None:- raise HTTPException(status_code=404, detail=f"entity '{entity_id}' not found")- _check_attrs(- body.type or str(current["type"]),- body.attrs,- current=current.get("attrs") or {},- )- try:- entity = case.update_entity(entity_id, patch)- if body.status == "confirmed":- link_engine.confirm_incident_relations(case, entity_id)- return entity- except CaseError as exc:- raise HTTPException(status_code=404, detail=str(exc)) from exc--[email protected]("/{case_id}/links")-def create_link(case_id: str, body: LinkIn) -> dict[str, Any]:- """State one relation by hand. Confirmed, and only from the registry."""- try:- return link_engine.add_relation(- get_case(case_id), body.from_id, body.to_id, body.type, by="user"- )- except CaseError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc--[email protected]("/{case_id}/links/{link_id}")-def update_link(case_id: str, link_id: str, body: LinkPatch) -> dict[str, Any]:- """Confirm a suggestion, correct which relation an edge states, rate it, or say- what kind of tie it is.-- Restating the type goes through the vocabulary, so a 400 means the ontology- has no such reading for those two entities; a missing link is a 404.-- Rating runs last on purpose: confirming a suggestion and rating it can arrive in- one request, and a rating is refused on an unreviewed edge — so the confirm has- to have landed before the rating is judged. The qualifier runs last for the- mirror reason: a reword that drops it must not be undone by a value sent against- the verb the edge no longer states.- """- rating = "confidence" in body.model_fields_set- qualifying = "nature" in body.model_fields_set- if body.status is None and body.type is None and not rating and not qualifying:- raise HTTPException(status_code=400, detail="nothing to update")- case = get_case(case_id)- try:- link = case.get_link(link_id)- if link is None:- raise HTTPException(status_code=404, detail=f"link '{link_id}' not found")- if body.type is not None and body.type != link["type"]:- link = link_engine.set_relation_type(case, link_id, body.type)- if body.status == "confirmed":- link = link_engine.confirm_relation(case, link_id)- elif body.status is not None:- link = case.update_link(link_id, {"status": body.status})- if rating:- link = link_engine.set_confidence(case, link_id, body.confidence)- if qualifying:- link = link_engine.set_qualifier(case, link_id, body.nature)- return link- except CaseError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc--[email protected]("/{case_id}/links/{link_id}")-def remove_link(case_id: str, link_id: str) -> dict[str, str]:- """Take back one relation. Dismissing a proposal and retracting a confirmed- statement are the same gesture; a derivation is neither, and is refused with a- 400 rather than dropped without its tombstone."""- case = get_case(case_id)- if case.get_link(link_id) is None:- raise HTTPException(status_code=404, detail=f"link '{link_id}' not found")- try:- link_engine.remove_relation(case, link_id)- except CaseError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc- return {"status": "deleted"}--[email protected]("/{case_id}/entities/{entity_id}/dependents")-def entity_dependents(case_id: str, entity_id: str) -> dict[str, Any]:- """What deleting this entity would take with it, and what it would scar.-- Feeds the confirm dialog so a delete states its consequences before it is- irreversible (ONTOLOGY §3).- """- case = get_case(case_id)- try:- plan = link_engine.plan_delete(case, entity_id)- except CaseError as exc:- raise HTTPException(status_code=404, detail=str(exc)) from exc- return {- "cascade": [_summary(e) for e in plan["cascade"]],- "tombstone": [_summary(e) for e in plan["tombstone"]],- }--[email protected]("/{case_id}/entities/{entity_id}/chain")-def entity_chain(case_id: str, entity_id: str) -> dict[str, Any]:- """One entity plus its derivation chain and direct relations, read from its- incident links only without shipping the whole graph."""- case = get_case(case_id)- chain = link_engine.chain_of(case, entity_id)- if chain is None:- raise HTTPException(status_code=404, detail=f"entity '{entity_id}' not found")- return chain---def _entity_image_error(exc: CaseError) -> HTTPException:- status = 404 if "not found" in str(exc) else 400- return HTTPException(status_code=status, detail=str(exc))--[email protected]("/{case_id}/entities/{entity_id}/images")-def entity_images(case_id: str, entity_id: str) -> dict[str, Any]:- """Presentation photos attached to one hand-made entity."""- try:- images = entity_image_engine.list_images(get_case(case_id), entity_id)- except CaseError as exc:- raise _entity_image_error(exc) from exc- return {"images": images}--[email protected]("/{case_id}/entities/{entity_id}/images")-def attach_entity_images(- case_id: str, entity_id: str, body: EntityImagesIn-) -> dict[str, Any]:- """Attach existing case images without creating semantic graph links."""- try:- return entity_image_engine.attach(get_case(case_id), entity_id, body.media_ids)- except CaseError as exc:- raise _entity_image_error(exc) from exc--[email protected]("/{case_id}/entities/{entity_id}/images/upload")-async def upload_entity_image(- case_id: str,- entity_id: str,- file: UploadFile = File(...),-) -> dict[str, Any]:- """Store one private presentation photo outside the Media Library.-- Bounded at the edge like the two other surfaces that swallow an image, and- against the same limit: a portrait is a portrait wherever it came from. The- pixel clamp further in answers a decompression bomb, not a file that is simply- enormous, and refusing early is what keeps a mistaken drag from filling the- disk with a temporary nobody asked for.- """- raw = await file.read(MAX_IMAGE_BYTES + 1)- if len(raw) > MAX_IMAGE_BYTES:- raise HTTPException(- status_code=413,- detail=f"photo must be under {MAX_IMAGE_BYTES // 1024 // 1024} MB",- )- try:- return entity_image_engine.import_photo(- get_case(case_id), entity_id, BytesIO(raw), file.filename- )- except CaseError as exc:- raise _entity_image_error(exc) from exc--[email protected]("/{case_id}/entities/{entity_id}/images/{image_id}/primary")-def set_primary_entity_image(- case_id: str, entity_id: str, image_id: str-) -> dict[str, Any]:- try:- images = entity_image_engine.set_primary(get_case(case_id), entity_id, image_id)- except CaseError as exc:- raise _entity_image_error(exc) from exc- return {"images": images}--[email protected]("/{case_id}/entities/{entity_id}/images/{image_id}")-def detach_entity_image(case_id: str, entity_id: str, image_id: str) -> dict[str, Any]:- """Detach a Media reference or delete a private presentation photo."""- try:- images = entity_image_engine.detach(get_case(case_id), entity_id, image_id)- except CaseError as exc:- raise _entity_image_error(exc) from exc- return {"images": images}--[email protected]("/{case_id}/entities/{entity_id}/placement")-def entity_placement(case_id: str, entity_id: str) -> dict[str, Any]:- """Where the derivation chain puts this entity, nearest placement first.-- Its own route rather than a field on the chain payload: the chain is read on- every Details open and every map popup, and this walks further than one hop.- """- case = get_case(case_id)- placement = satellite_engine.placements(case, entity_id)- if placement is None:- raise HTTPException(status_code=404, detail=f"entity '{entity_id}' not found")- return placement--[email protected]("/{case_id}/entities/{entity_id}/tally")-def entity_tally(case_id: str, entity_id: str) -> dict[str, Any]:- """What the statements about this entity come to, or 404 when nothing states one.-- Its own route for the same reason placement is: the panel already lists the claims- pointing here, and adding them up walks their attributes, which the chain read has- no reason to carry on every Details open.-- Over the whole case, never a filter: the panel is not narrowed, so a total obeying- a narrowing set on another screen would be a different number under one wording.- """- row = tally_engine.for_subject(get_case(case_id), entity_id)- if row is None:- raise HTTPException(status_code=404, detail="no statement is about this entity")- return row--[email protected]("/{case_id}/entities/{entity_id}/derivation")-def entity_derivation(case_id: str, entity_id: str) -> dict[str, Any]:- """The transitive ``derived-from`` closure rooted at this entity as- ``{entities, links}`` — the Post composer traces a proof back to its original- downloaded media over this slice, not the whole graph (Step 5)."""- case = get_case(case_id)- subgraph = link_engine.derivation_subgraph(case, entity_id)- if subgraph is None:- raise HTTPException(status_code=404, detail=f"entity '{entity_id}' not found")- return subgraph--[email protected]("/{case_id}/entities/{entity_id}")-def remove_entity(case_id: str, entity_id: str) -> dict[str, Any]:- """Delete an entity and the on-disk artifact it stands for, so removing a- row in the sidebar deletes it everywhere it appears (spec §3.5)."""- case = get_case(case_id)- try:- return delete_entity_deep(case, entity_id)- except CaseError as exc:- raise HTTPException(status_code=404, detail=str(exc)) from exc--[email protected]("/{case_id}/entities/delete")-def remove_entities(case_id: str, body: EntityDeleteIn) -> dict[str, Any]:- """Delete a multi-selection as one recoverable trash group."""- case = get_case(case_id)- try:- return delete_entities_deep(case, body.ids)- except CaseError as exc:- raise HTTPException(status_code=404, detail=str(exc)) from exc--[email protected]("/{case_id}/trash")-def list_trash(case_id: str) -> dict[str, Any]:- """What the case is holding for you, newest first.-- Head columns only — no payload is read here, so the node costs one indexed- query however much is waiting in it.- """- case = get_case(case_id)- summary = case.trash_summary()- return {- "groups": case.list_trash(),- "items": summary["items"],- "size_bytes": summary["size_bytes"],- }--[email protected]("/{case_id}/trash/{group_id}/restore")-def restore_trash(case_id: str, group_id: str) -> dict[str, Any]:- """Take one delete back, all of it or none.-- A 409 means a file is back at a path the group wants: restoring would have to- rename an artifact behind the analyst, so it refuses and names the path- instead.- """- case = get_case(case_id)- try:- return trash_engine.restore(case, group_id)- except CaseError as exc:- message = str(exc)- status = 404 if "not found" in message else 409- raise HTTPException(status_code=status, detail=message) from exc--[email protected]("/{case_id}/trash/{group_id}")-def purge_trash(case_id: str, group_id: str) -> dict[str, str]:- """Drop one group for good. This is where the bytes actually go."""- case = get_case(case_id)- try:- trash_engine.purge(case, group_id)- except CaseError as exc:- raise HTTPException(status_code=404, detail=str(exc)) from exc- return {"status": "purged"}--[email protected]("/{case_id}/trash")-def empty_trash(case_id: str) -> dict[str, int]:- return {"purged": trash_engine.empty(get_case(case_id))}--[email protected]("/{case_id}/folders")-def list_folders(case_id: str) -> list[str]:- return get_case(case_id).list_folders()--[email protected]("/{case_id}/folders")-def add_folder(case_id: str, body: FolderIn) -> list[str]:- case = get_case(case_id)- try:- return case.add_folder(body.name)- except CaseError as exc:- raise HTTPException(status_code=400, detail=str(exc)) from exc--[email protected]("/{case_id}/folders")-def remove_folder(case_id: str, name: str) -> list[str]:- return get_case(case_id).remove_folder(name)diff --git a/src/azimut/api/cases/__init__.py b/src/azimut/api/cases/__init__.pynew file mode 100644index 0000000..17a1b99--- /dev/null+++ b/src/azimut/api/cases/__init__.py@@ -0,0 +1,63 @@+"""REST API for case lifecycle, entities and links.++One router per domain, assembled here. The order below is the order routes are+matched in, and it is load-bearing: a case's id is its folder name, so+`/api/cases/entity-types` and `/api/cases/{case_id}` are the same shape and the+literal one has to be registered first. `registry` therefore goes before+`lifecycle`, and nothing declaring a bare `/{case_id}` may move above it.++The note bodies and their PDF export live next door in `api/notes.py`.+"""++from __future__ import annotations++from fastapi import APIRouter++from .bundles import router as _bundles+from .catalog import router as _catalog+from .common import (+ delete_by_path,+ delete_entities_deep,+ delete_entity_deep,+ get_case,+)+from .doctor import router as _doctor+from .entities import router as _entities+from .entity_images import router as _entity_images+from .folders import router as _folders+from .graph import router as _graph+from .lifecycle import router as _lifecycle+from .lifecycle import workspace_router+from .links import router as _links+from .registry import router as _registry+from .timeline import router as _timeline+from .timeline import timeline+from .trash import router as _trash++router = APIRouter()+# Literal paths first — see the module docstring.+for _sub in (+ _registry,+ _bundles,+ _doctor,+ _lifecycle,+ _catalog,+ _graph,+ _entities,+ _entity_images,+ _links,+ _timeline,+ _trash,+ _folders,+):+ router.include_router(_sub)++__all__ = [+ "delete_by_path",+ "delete_entities_deep",+ "delete_entity_deep",+ "get_case",+ "router",+ "timeline",+ "workspace_router",+]diff --git a/src/azimut/api/cases/bundles.py b/src/azimut/api/cases/bundles.pynew file mode 100644index 0000000..f2bf87b--- /dev/null+++ b/src/azimut/api/cases/bundles.py@@ -0,0 +1,120 @@+"""Case bundles: export one, inspect an upload, import it back.++The work itself runs as a durable job (`engine/bundles.py`); these routes queue it,+report on it and hand back the finished file.+"""++from __future__ import annotations++from pathlib import Path+from typing import Any++from fastapi import APIRouter, File, Form, HTTPException, UploadFile+from fastapi.responses import FileResponse+from pydantic import BaseModel, Field++from ... import config+from ...engine import bundles as bundle_engine+from ...workspace import CaseError+from .common import get_case++router = APIRouter(prefix="/api/cases", tags=["cases"])+++class BundlePassword(BaseModel):+ password: str | None = Field(default=None, max_length=1024)++class BundleUpload(BundlePassword):+ upload_id: str = Field(min_length=32, max_length=32)+[email protected]("/bundles/inspect")+def inspect_bundle(+ file: UploadFile = File(),+ password: str | None = Form(default=None, max_length=1024),+) -> dict[str, Any]:+ upload_id: str | None = None+ try:+ upload_id, path = bundle_engine.stage_upload(file.file)+ preview = bundle_engine.inspect_bundle(path, password=password)+ except CaseError as exc:+ if upload_id is not None:+ bundle_engine.discard_upload(upload_id)+ raise HTTPException(status_code=400, detail=str(exc)) from exc+ preview.pop("path", None)+ return {**preview, "upload_id": upload_id}+[email protected]("/bundles/import")+def import_bundle(body: BundleUpload) -> dict[str, Any]:+ try:+ source = bundle_engine.uploaded_bundle(body.upload_id)+ case, job = bundle_engine.queue_import(+ source,+ password=body.password,+ cleanup_source=True,+ )+ except CaseError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from exc+ return {+ "case_id": case.id,+ "name": case.read().get("name", case.id),+ "job_id": job["id"],+ "state": job["state"],+ }+[email protected]("/bundles/uploads/{upload_id}")+def discard_bundle_upload(upload_id: str) -> dict[str, str]:+ try:+ bundle_engine.discard_upload(upload_id)+ except CaseError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from exc+ return {"status": "discarded"}+[email protected]("/{case_id}/bundle/export")+def export_bundle(case_id: str, body: BundlePassword) -> dict[str, Any]:+ case = get_case(case_id)+ try:+ job = bundle_engine.queue_export(case, password=body.password)+ except CaseError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from exc+ return {+ "case_id": case.id,+ "job_id": job["id"],+ "state": job["state"],+ }+[email protected]("/{case_id}/bundle/jobs/{job_id}")+def bundle_job(case_id: str, job_id: str) -> dict[str, Any]:+ job = bundle_engine.job_status(case_id, job_id)+ if job is None or job.get("kind") not in {+ bundle_engine.EXPORT_JOB,+ bundle_engine.IMPORT_JOB,+ }:+ raise HTTPException(status_code=404, detail=f"bundle job '{job_id}' not found")+ return {+ "id": job["id"],+ "kind": job["kind"],+ "state": job["state"],+ "error": job.get("error"),+ }+[email protected]("/{case_id}/bundle/jobs/{job_id}/download")+def download_bundle(case_id: str, job_id: str) -> FileResponse:+ job = bundle_engine.job_status(case_id, job_id)+ if (+ job is None+ or job.get("kind") != bundle_engine.EXPORT_JOB+ or job.get("state") != "ready"+ ):+ raise HTTPException(status_code=404, detail="bundle download not ready")+ path = Path(job.get("payload", {}).get("output", ""))+ try:+ allowed = path.resolve().parent == config.bundles_dir().resolve()+ except OSError:+ allowed = False+ if not allowed or not path.is_file():+ raise HTTPException(status_code=404, detail="bundle download not found")+ return FileResponse(+ path,+ filename=path.name,+ media_type="application/octet-stream",+ )diff --git a/src/azimut/api/cases/catalog.py b/src/azimut/api/cases/catalog.pynew file mode 100644index 0000000..edb8da1--- /dev/null+++ b/src/azimut/api/cases/catalog.py@@ -0,0 +1,186 @@+"""The bounded catalog: a page of entities, and the counts that describe them.++Every read here is bounded and filtered in SQL (docs/STORAGE_AND_PERFORMANCE.md).+The summary, the attribute facets and the tally are what let the Board offer a+filter built from what the case actually holds rather than from typed syntax.+"""++from __future__ import annotations++from typing import Any, cast++from fastapi import APIRouter, HTTPException++from ...engine import analysis_views as analysis_view_engine+from ...engine import entities as entity_engine+from ...engine import tally as tally_engine+from ...repository import EntityStatus+from ...workspace import CaseError+from .common import _temporal_filter_args, get_case++router = APIRouter(prefix="/api/cases", tags=["cases"])+++def _explain_catalog_matches(page: dict[str, Any], query: str | None) -> dict[str, Any]:+ if not query:+ return page+ for entity in page.get("items", []):+ if matches := entity_engine.search_matches(entity, query):+ entity["matches"] = matches+ return page+[email protected]("/{case_id}/catalog/entities")+def catalog_entities(+ case_id: str,+ cursor: str | None = None,+ limit: int = 100,+ type: str | None = None,+ status: str | None = None,+ q: str | None = None,+ folder: str | None = None,+ unfiled: bool = False,+ recursive: bool = False,+ attr: str | None = None,+ value: str | None = None,+ linked: str | None = None,+ unlinked: bool = False,+ since: str | None = None,+ until: str | None = None,+ by: str | None = None,+ temporal_from: str | None = None,+ temporal_to: str | None = None,+ temporal_category: str | None = None,+ order: str = "",+ view: str | None = None,+) -> dict[str, Any]:+ """A bounded page of the entity catalog (Step 5, "Bounded loading").++ Stable cursor order, server-side filters and a ``next_cursor`` that is null on the+ last page. ``limit`` is clamped so no request can ask for the whole graph at once.++ The filters: a comma-separated ``type`` set, ``status``, a label substring ``q``,+ folder (``unfiled=true`` or a ``folder`` path, optionally including descendants),+ one stored field holding one value (``attr`` with ``value``), having a neighbour of+ a type (``linked``) or none at all (``unlinked``), and how the row got here —+ ``since``/``until`` over the date it was filed, and a comma-separated ``by`` set of+ whatever filed it. Together they are what make the page an answer rather than a+ shorter list: *media, kind video, linked to a place* is "which videos have+ coordinates", and ``total`` is how many.++ ``order`` sorts the whole filtered set rather than the page — ``created`` and+ ``label``, each with a ``-`` prefix for the other direction. Empty is the insertion+ order that has always been the default.++ ``attr`` without ``value`` is not a term — it is the analyst having chosen which+ field they are about to ask about, and answering it as "holds nothing" would empty+ the table between two clicks of one act.+ """+ case = get_case(case_id)+ limit = max(1, min(limit, 500))+ if view:+ saved = case.get_analysis_view(view)+ if saved is None:+ raise HTTPException(status_code=404, detail=f"analysis view '{view}' not found")+ if saved["mode"] == "snapshot":+ try:+ return _explain_catalog_matches(+ analysis_view_engine.snapshot_page(+ saved, limit=limit, cursor=cursor, order=order+ ),+ q,+ )+ except CaseError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from exc+ types = [t.strip() for t in type.split(",") if t.strip()] if type else None+ filed_by = [name.strip() for name in by.split(",") if name.strip()] if by else None+ temporal_since, temporal_until, temporal_categories = _temporal_filter_args(+ temporal_from, temporal_to, temporal_category+ )+ valid_status = (+ cast(EntityStatus, status) if status in ("confirmed", "suggested") else None+ )+ try:+ page = case.page_entities(+ limit=limit, cursor=cursor, types=types, status=valid_status,+ query=q, folder=folder, unfiled=unfiled, recursive=recursive,+ attr=attr, attr_value=value, linked=linked, unlinked=unlinked,+ since=since, until=until, filed_by=filed_by, order=order,+ temporal_since=temporal_since, temporal_until=temporal_until,+ temporal_categories=temporal_categories,+ )+ thumbs = case.entity_image_thumbs([entity["id"] for entity in page["items"]])+ for entity in page["items"]:+ if thumb := thumbs.get(entity["id"]):+ entity["thumb"] = thumb+ return _explain_catalog_matches(page, q)+ except CaseError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from exc+[email protected]("/{case_id}/catalog/summary")+def catalog_summary(case_id: str) -> dict[str, Any]:+ """Counts per type, status, folder and filer, plus how many the case connects to+ nothing, so the catalog shows badges and populates its filter menus without+ loading the graph."""+ return get_case(case_id).catalog_summary()+[email protected]("/{case_id}/catalog/attributes")+def catalog_attributes(case_id: str, type: str | None = None) -> dict[str, Any]:+ """Which stored fields these entities hold, and which values, as a menu.++ What lets a field be filtered on without a query language: the field select and+ the value select are both populated from the case, so every term of a search is+ chosen rather than typed (SPEC anti-goals). It reaches fields the vocabulary does+ not declare, which is the point — `kind` is written by the importer, so a+ registry-driven menu would never have offered the one field an analyst most wants.++ Narrowed by the same comma-separated ``type`` set as the page it filters: the+ fields a media holds are not the fields a claim holds, and one menu of both is a+ menu of neither.+ """+ types = [t.strip() for t in type.split(",") if t.strip()] if type else None+ return {"attrs": get_case(case_id).attr_facets(types=types)}+[email protected]("/{case_id}/catalog/tally")+def catalog_tally(+ case_id: str,+ type: str | None = None,+ status: str | None = None,+ q: str | None = None,+ folder: str | None = None,+ unfiled: bool = False,+ recursive: bool = False,+ attr: str | None = None,+ value: str | None = None,+ linked: str | None = None,+ unlinked: bool = False,+ since: str | None = None,+ until: str | None = None,+ by: str | None = None,+ temporal_from: str | None = None,+ temporal_to: str | None = None,+ temporal_category: str | None = None,+) -> dict[str, Any]:+ """What the statements in this narrowing add up to, per subject.++ The same terms as the catalog page it sits beside, spelled the same way, because+ it is the same question: the table lists the statements, this one adds them up+ (``engine/tally.py``). Every rule about what may enter a sum is there — a ruled-out+ statement never does, an absent count is not one, and nothing is totalled across+ subjects.+ """+ types = [t.strip() for t in type.split(",") if t.strip()] if type else None+ filed_by = [name.strip() for name in by.split(",") if name.strip()] if by else None+ temporal_since, temporal_until, temporal_categories = _temporal_filter_args(+ temporal_from, temporal_to, temporal_category+ )+ try:+ return tally_engine.tally(+ get_case(case_id), types=types, status=status, query=q,+ folder=folder, unfiled=unfiled, recursive=recursive,+ attr=attr, attr_value=value, linked=linked, unlinked=unlinked,+ since=since, until=until, filed_by=filed_by,+ temporal_since=temporal_since, temporal_until=temporal_until,+ temporal_categories=temporal_categories,+ )+ except CaseError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from excdiff --git a/src/azimut/api/cases/common.py b/src/azimut/api/cases/common.pynew file mode 100644index 0000000..31ff2fc--- /dev/null+++ b/src/azimut/api/cases/common.py@@ -0,0 +1,175 @@+"""What every case route needs, and the delete chokepoint they all go through.++`get_case` is the 404 boundary: every route in this package and several outside it+(`api/media.py`, `api/proofs.py`, `api/inspect.py`, …) open a case through it, so a+missing case answers the same way everywhere.++The deep deletes are here for the same reason. Removing an entity is never one row:+what cannot outlive it goes too, its files move to the trash, and the links it stood+in leave tombstones. That recipe is stated once and imported, rather than+re-derived per surface.+"""++from __future__ import annotations++from typing import Any++from fastapi import HTTPException++from ...engine import entities as entity_engine+from ...engine import links as link_engine+from ...engine import timeline as timeline_engine+from ...engine import trash as trash_engine+from ...engine.temporal import TemporalError, window_bound+from ...workspace import Case, CaseError+++def get_case(case_id: str) -> Case:+ try:+ return Case.open(case_id)+ except CaseError as exc:+ raise HTTPException(status_code=404, detail=str(exc)) from exc++def delete_entities_deep(case: Case, entity_ids: list[str]) -> dict[str, Any]:+ """Delete one UI action and everything that cannot outlive its targets.++ The one door every delete goes through — sidebar, Media Library, a tool's+ own list — so the rules hold wherever the click came from:++ - artifacts that ``depends-on`` the target die with it (an Inspect session+ is only adjustments over a video), transitively;+ - artifacts ``derived-from`` it are never touched, and are scarred with a+ tombstone first, while the target can still describe itself.++ The whole action lands in the trash as one group, so undoing it brings the+ cascade back together or not at all. The graph rows are still hard-deleted:+ what is kept is the recipe, not a hidden state every other query would have+ to filter out.+ """+ with case.lock:+ going_by_id: dict[str, dict[str, Any]] = {}+ tombstoned: set[str] = set()+ for entity_id in dict.fromkeys(entity_ids):+ plan = link_engine.plan_delete(case, entity_id)+ target = case.get_entity(entity_id)+ if target is None:+ raise CaseError(f"entity '{entity_id}' not found")+ for entity in (target, *plan["cascade"]):+ going_by_id[entity["id"]] = entity+ tombstoned.update(entity["id"] for entity in plan["tombstone"])+ going = list(going_by_id.values())++ scars: list[dict[str, str]] = []+ losses = link_engine.losses(case, {e["id"] for e in going})+ for survivor_id, lost_sources in losses.items():+ survivor = case.get_entity(survivor_id)+ existing = {+ item.get("path")+ for item in (survivor or {}).get("attrs", {}).get(link_engine.LOST, [])+ }+ for lost in lost_sources:+ path = link_engine.tombstone_of(lost).get("path")+ if path and path not in existing:+ scars.append({"entity": survivor_id, "path": path})+ existing.add(path)++ group = trash_engine.send(case, going, scars)+ try:+ for survivor_id, lost_sources in losses.items():+ link_engine.add_tombstones(+ case,+ survivor_id,+ [link_engine.tombstone_of(source) for source in lost_sources],+ )+ for entity in going:+ if case.get_entity(entity["id"]) is not None:+ case.remove_entity(entity["id"])+ trash_engine.commit(case, group["id"])+ except Exception:+ trash_engine.rollback(case, group["id"])+ raise++ return {+ "status": "deleted",+ "deleted": [e["id"] for e in going],+ "tombstoned": sorted(tombstoned - set(going_by_id)),+ "trash": group["id"],+ }++def delete_entity_deep(case: Case, entity_id: str) -> dict[str, Any]:+ return delete_entities_deep(case, [entity_id])++def _summary(entity: dict[str, Any]) -> dict[str, Any]:+ return {+ "id": entity["id"],+ "type": entity.get("type"),+ "label": entity.get("label"),+ "path": link_engine.artifact_path(entity),+ }++def delete_by_path(case: Case, rel_path: str) -> dict[str, Any]:+ """Chokepoint entry for a tool that knows its artifact by path, not by id.++ Returns an empty ``deleted`` when no entity claims the path: the artifact was+ never filed, so there is no graph to honour and the caller drops the files+ itself.+ """+ entity = (+ case.find_entity(attr="path", value=rel_path)+ or case.find_entity(attr="spec", value=rel_path)+ or case.find_entity(attr="draft", value=rel_path)+ )+ if entity is None:+ return {"status": "deleted", "deleted": [], "tombstoned": []}+ return delete_entity_deep(case, entity["id"])++def _check_attrs(+ type_: str,+ attrs: dict[str, Any],+ *,+ current: dict[str, Any] | None = None,+) -> None:+ """Refuse a malformed declared field with a 400, never a 404.++ Split out because the two write paths reach it from different places and the+ update path's own ``except CaseError`` answers 404 — a bad radius is a bad+ request, not a missing entity.+ """+ try:+ entity_engine.check_attrs(type_, attrs, current=current)+ except CaseError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from exc++def _timeline_bound(raw: str | None, *, upper: bool) -> str | None:+ if raw is None:+ return None+ try:+ return window_bound(raw, upper=upper)+ except TemporalError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from exc++def _temporal_filter_args(+ from_: str | None,+ to: str | None,+ category: str | None,+) -> tuple[str | None, str | None, list[str] | None]:+ """Validate the fact-time window kept separate from filing dates."""+ if from_ is None and to is None:+ return None, None, None+ if from_ is None or to is None:+ raise HTTPException(status_code=400, detail="a temporal filter needs both boundaries")+ since = _timeline_bound(from_, upper=False)+ until = _timeline_bound(to, upper=True)+ if since is not None and until is not None and since >= until:+ raise HTTPException(status_code=400, detail="the temporal filter ends before it starts")+ categories = (+ list(dict.fromkeys(part.strip() for part in category.split(",") if part.strip()))+ if category is not None+ else list(timeline_engine.DEFAULT_CATEGORIES)+ )+ invalid = sorted(set(categories) - set(timeline_engine.ALL_CATEGORIES))+ if invalid:+ raise HTTPException(status_code=400, detail=f"unknown timeline category '{invalid[0]}'")+ if not categories:+ raise HTTPException(status_code=400, detail="a temporal filter needs a category")+ return since, until, categoriesdiff --git a/src/azimut/api/cases/doctor.py b/src/azimut/api/cases/doctor.pynew file mode 100644index 0000000..a618dcd--- /dev/null+++ b/src/azimut/api/cases/doctor.py@@ -0,0 +1,72 @@+"""The case doctor: what is inconsistent on disk, and the repairs offered.++Read the report, then apply one repair by name. Every repair is stated as an+explicit action rather than run on open, because a case that silently rewrites+itself is one an analyst cannot vouch for.+"""++from __future__ import annotations++import sqlite3+from typing import Any++from fastapi import APIRouter, HTTPException+from pydantic import BaseModel, Field++from ...engine import doctor as doctor_engine+from ...engine import media as media_engine+from ...workspace import Case, CaseError+from .common import delete_entity_deep++router = APIRouter(prefix="/api/cases", tags=["cases"])+++class DoctorRepair(BaseModel):+ action: str = Field(min_length=1, max_length=20)+ entity_id: str | None = Field(default=None, max_length=64)+ path: str | None = Field(default=None, max_length=300)+ replacement: str | None = Field(default=None, max_length=300)+[email protected]("/{case_id}/doctor")+def doctor_report(case_id: str) -> dict[str, Any]:+ """Inspect a case even when its database is missing."""+ try:+ return doctor_engine.scan(Case.locate(case_id))+ except CaseError as exc:+ raise HTTPException(status_code=404, detail=str(exc)) from exc+[email protected]("/{case_id}/doctor/repair")+def doctor_repair(case_id: str, body: DoctorRepair) -> dict[str, Any]:+ """Apply one repair that the current Doctor report explicitly offers."""+ try:+ located = Case.locate(case_id)+ if body.action == "rebuild":+ result = doctor_engine.rebuild_database(located)+ case = located+ else:+ case = Case.open(case_id)+ if body.action == "rebuild-timeline":+ doctor_engine.require_stale_temporal_projection(case)+ result = {+ "status": "rebuilt",+ "items": case.rebuild_temporal_projection(),+ }+ elif body.action == "import" and body.path:+ doctor_engine.require_unknown_media(case, body.path)+ result = media_engine.register_existing(case, body.path)+ elif body.action == "drop" and body.entity_id:+ doctor_engine.require_missing_media(case, body.entity_id)+ result = delete_entity_deep(case, body.entity_id)+ elif body.action == "relink" and body.entity_id and body.replacement:+ doctor_engine.require_missing_media(case, body.entity_id)+ doctor_engine.require_unknown_media(case, body.replacement)+ result = media_engine.relink_existing(+ case,+ body.entity_id,+ body.replacement,+ )+ else:+ raise CaseError("this repair action is not valid")+ return {"repair": result, "report": doctor_engine.scan(case)}+ except (CaseError, OSError, ValueError, sqlite3.Error) as exc:+ raise HTTPException(status_code=409, detail=str(exc)) from excdiff --git a/src/azimut/api/cases/entities.py b/src/azimut/api/cases/entities.pynew file mode 100644index 0000000..899e2df--- /dev/null+++ b/src/azimut/api/cases/entities.py@@ -0,0 +1,205 @@+"""Entities: create, amend, look up, delete, and what each one is tied to.++The reads beside them answer questions a single entity raises — what depends on it,+what it was derived from, where it sits, what it counts.+"""++from __future__ import annotations++from typing import Any++from fastapi import APIRouter, HTTPException+from pydantic import BaseModel, Field++from ...engine import entities as entity_engine+from ...engine import links as link_engine+from ...engine import satellite as satellite_engine+from ...engine import tally as tally_engine+from ...repository import EntityStatus+from ...workspace import CaseError+from .common import (+ _check_attrs,+ _summary,+ delete_entities_deep,+ delete_entity_deep,+ get_case,+)++router = APIRouter(prefix="/api/cases", tags=["cases"])+++class EntityIn(BaseModel):+ type: str = Field(min_length=1, max_length=40)+ label: str = Field(min_length=1, max_length=300)+ attrs: dict[str, Any] = Field(default_factory=dict)+ status: EntityStatus = "confirmed"++class EntityPatch(BaseModel):+ type: str | None = None+ label: str | None = Field(default=None, min_length=1, max_length=300)+ attrs: dict[str, Any] | None = None+ status: EntityStatus | None = None++class EntityDeleteIn(BaseModel):+ ids: list[str] = Field(min_length=1, max_length=200)+[email protected]("/{case_id}/entities/lookup")+def lookup_entity(case_id: str, attr: str, value: str) -> dict[str, Any]:+ """One entity by an ``attrs`` value (``path``, ``spec``, ``draft``), or null.++ The bounded replacement for a tool scanning the whole graph to answer "is the+ file/spec I am bound to still in the case?" after a delete elsewhere, or to+ resolve a file path back to its entity (Step 5).+ """+ entity = get_case(case_id).find_entity(attr=attr, value=value)+ return {"entity": entity}+[email protected]("/{case_id}/entities/twin")+def entity_twin(+ case_id: str, type: str, label: str, ignore: str = ""+) -> dict[str, Any]:+ """The entity already holding this identifier's value, or null.++ Only the ``identifier`` family answers anything: there the value *is* the+ identity, so two records of it are two records of one thing (ONTOLOGY §2).+ Everywhere else two entities may share a label and the question is meaningless.++ **It warns, it never refuses.** Merging is not shipped (`same-as`, SPEC §10), and+ a create that failed would leave the analyst holding a value with nowhere to put+ it — so this reports and the surface offers the row it found. ``ignore`` is the+ entity being renamed, which is not its own twin.++ The comparison lives in ``engine/entities.identity_key`` and is served rather+ than reimplemented: the create form used to lowercase the raw label in the+ browser, which let `@handle` and `handle` sit side by side as two accounts.+ """+ key = entity_engine.identity_key(type, label)+ if not key:+ return {"entity": None}+ case = get_case(case_id)+ for entity_id, existing in case.labels_of_type(type):+ if entity_id != ignore and entity_engine.identity_key(type, existing) == key:+ return {"entity": case.get_entity(entity_id)}+ return {"entity": None}+[email protected]("/{case_id}/entities")+def add_entity(case_id: str, body: EntityIn) -> dict[str, Any]:+ case = get_case(case_id)+ _check_attrs(body.type, body.attrs)+ if body.type == "note":+ attrs = body.attrs+ return case.create_note(+ body.label.strip(),+ str(attrs.get("folder", "")).strip(),+ str(attrs.get("content", "")),+ )+ return case.add_entity(body.type, body.label, body.attrs, by="user", status=body.status)+[email protected]("/{case_id}/entities/{entity_id}")+def update_entity(case_id: str, entity_id: str, body: EntityPatch) -> dict[str, Any]:+ case = get_case(case_id)+ patch = {k: v for k, v in body.model_dump().items() if v is not None}+ if body.attrs is not None:+ # Against the type it will have once patched, and the entity has to exist+ # before its fields can be judged.+ current = case.get_entity(entity_id)+ if current is None:+ raise HTTPException(status_code=404, detail=f"entity '{entity_id}' not found")+ _check_attrs(+ body.type or str(current["type"]),+ body.attrs,+ current=current.get("attrs") or {},+ )+ try:+ entity = case.update_entity(entity_id, patch)+ if body.status == "confirmed":+ link_engine.confirm_incident_relations(case, entity_id)+ return entity+ except CaseError as exc:+ raise HTTPException(status_code=404, detail=str(exc)) from exc+[email protected]("/{case_id}/entities/{entity_id}/dependents")+def entity_dependents(case_id: str, entity_id: str) -> dict[str, Any]:+ """What deleting this entity would take with it, and what it would scar.++ Feeds the confirm dialog so a delete states its consequences before it is+ irreversible (ONTOLOGY §3).+ """+ case = get_case(case_id)+ try:+ plan = link_engine.plan_delete(case, entity_id)+ except CaseError as exc:+ raise HTTPException(status_code=404, detail=str(exc)) from exc+ return {+ "cascade": [_summary(e) for e in plan["cascade"]],+ "tombstone": [_summary(e) for e in plan["tombstone"]],+ }+[email protected]("/{case_id}/entities/{entity_id}/chain")+def entity_chain(case_id: str, entity_id: str) -> dict[str, Any]:+ """One entity plus its derivation chain and direct relations, read from its+ incident links only without shipping the whole graph."""+ case = get_case(case_id)+ chain = link_engine.chain_of(case, entity_id)+ if chain is None:+ raise HTTPException(status_code=404, detail=f"entity '{entity_id}' not found")+ return chain+[email protected]("/{case_id}/entities/{entity_id}/placement")+def entity_placement(case_id: str, entity_id: str) -> dict[str, Any]:+ """Where the derivation chain puts this entity, nearest placement first.++ Its own route rather than a field on the chain payload: the chain is read on+ every Details open and every map popup, and this walks further than one hop.+ """+ case = get_case(case_id)+ placement = satellite_engine.placements(case, entity_id)+ if placement is None:+ raise HTTPException(status_code=404, detail=f"entity '{entity_id}' not found")+ return placement+[email protected]("/{case_id}/entities/{entity_id}/tally")+def entity_tally(case_id: str, entity_id: str) -> dict[str, Any]:+ """What the statements about this entity come to, or 404 when nothing states one.++ Its own route for the same reason placement is: the panel already lists the claims+ pointing here, and adding them up walks their attributes, which the chain read has+ no reason to carry on every Details open.++ Over the whole case, never a filter: the panel is not narrowed, so a total obeying+ a narrowing set on another screen would be a different number under one wording.+ """+ row = tally_engine.for_subject(get_case(case_id), entity_id)+ if row is None:+ raise HTTPException(status_code=404, detail="no statement is about this entity")+ return row+[email protected]("/{case_id}/entities/{entity_id}/derivation")+def entity_derivation(case_id: str, entity_id: str) -> dict[str, Any]:+ """The transitive ``derived-from`` closure rooted at this entity as+ ``{entities, links}`` — the Post composer traces a proof back to its original+ downloaded media over this slice, not the whole graph (Step 5)."""+ case = get_case(case_id)+ subgraph = link_engine.derivation_subgraph(case, entity_id)+ if subgraph is None:+ raise HTTPException(status_code=404, detail=f"entity '{entity_id}' not found")+ return subgraph+[email protected]("/{case_id}/entities/{entity_id}")+def remove_entity(case_id: str, entity_id: str) -> dict[str, Any]:+ """Delete an entity and the on-disk artifact it stands for, so removing a+ row in the sidebar deletes it everywhere it appears (spec §3.5)."""+ case = get_case(case_id)+ try:+ return delete_entity_deep(case, entity_id)+ except CaseError as exc:+ raise HTTPException(status_code=404, detail=str(exc)) from exc+[email protected]("/{case_id}/entities/delete")+def remove_entities(case_id: str, body: EntityDeleteIn) -> dict[str, Any]:+ """Delete a multi-selection as one recoverable trash group."""+ case = get_case(case_id)+ try:+ return delete_entities_deep(case, body.ids)+ except CaseError as exc:+ raise HTTPException(status_code=404, detail=str(exc)) from excdiff --git a/src/azimut/api/cases/entity_images.py b/src/azimut/api/cases/entity_images.pynew file mode 100644index 0000000..4c96b5c--- /dev/null+++ b/src/azimut/api/cases/entity_images.py@@ -0,0 +1,94 @@+"""The gallery a hand-made entity carries.++Ordered photos, at most one primary. An image is either a reference to something+already in Media or a private file uploaded here — never both, which is the check+`engine/entity_images.py` enforces and these routes surface.+"""++from __future__ import annotations++from io import BytesIO+from typing import Any++from fastapi import APIRouter, File, HTTPException, UploadFile+from pydantic import BaseModel, Field++from ...engine import entity_images as entity_image_engine+from ...workspace import CaseError+from ..limits import MAX_IMAGE_BYTES+from .common import get_case++router = APIRouter(prefix="/api/cases", tags=["cases"])+++class EntityImagesIn(BaseModel):+ media_ids: list[str] = Field(min_length=1, max_length=100)++def _entity_image_error(exc: CaseError) -> HTTPException:+ status = 404 if "not found" in str(exc) else 400+ return HTTPException(status_code=status, detail=str(exc))+[email protected]("/{case_id}/entities/{entity_id}/images")+def entity_images(case_id: str, entity_id: str) -> dict[str, Any]:+ """Presentation photos attached to one hand-made entity."""+ try:+ images = entity_image_engine.list_images(get_case(case_id), entity_id)+ except CaseError as exc:+ raise _entity_image_error(exc) from exc+ return {"images": images}+[email protected]("/{case_id}/entities/{entity_id}/images")+def attach_entity_images(+ case_id: str, entity_id: str, body: EntityImagesIn+) -> dict[str, Any]:+ """Attach existing case images without creating semantic graph links."""+ try:+ return entity_image_engine.attach(get_case(case_id), entity_id, body.media_ids)+ except CaseError as exc:+ raise _entity_image_error(exc) from exc+[email protected]("/{case_id}/entities/{entity_id}/images/upload")+async def upload_entity_image(+ case_id: str,+ entity_id: str,+ file: UploadFile = File(...),+) -> dict[str, Any]:+ """Store one private presentation photo outside the Media Library.++ Bounded at the edge like the two other surfaces that swallow an image, and+ against the same limit: a portrait is a portrait wherever it came from. The+ pixel clamp further in answers a decompression bomb, not a file that is simply+ enormous, and refusing early is what keeps a mistaken drag from filling the+ disk with a temporary nobody asked for.+ """+ raw = await file.read(MAX_IMAGE_BYTES + 1)+ if len(raw) > MAX_IMAGE_BYTES:+ raise HTTPException(+ status_code=413,+ detail=f"photo must be under {MAX_IMAGE_BYTES // 1024 // 1024} MB",+ )+ try:+ return entity_image_engine.import_photo(+ get_case(case_id), entity_id, BytesIO(raw), file.filename+ )+ except CaseError as exc:+ raise _entity_image_error(exc) from exc+[email protected]("/{case_id}/entities/{entity_id}/images/{image_id}/primary")+def set_primary_entity_image(+ case_id: str, entity_id: str, image_id: str+) -> dict[str, Any]:+ try:+ images = entity_image_engine.set_primary(get_case(case_id), entity_id, image_id)+ except CaseError as exc:+ raise _entity_image_error(exc) from exc+ return {"images": images}+[email protected]("/{case_id}/entities/{entity_id}/images/{image_id}")+def detach_entity_image(case_id: str, entity_id: str, image_id: str) -> dict[str, Any]:+ """Detach a Media reference or delete a private presentation photo."""+ try:+ images = entity_image_engine.detach(get_case(case_id), entity_id, image_id)+ except CaseError as exc:+ raise _entity_image_error(exc) from exc+ return {"images": images}diff --git a/src/azimut/api/cases/folders.py b/src/azimut/api/cases/folders.pynew file mode 100644index 0000000..8298a18--- /dev/null+++ b/src/azimut/api/cases/folders.py@@ -0,0 +1,31 @@+"""The folders a case files its entities into."""++from __future__ import annotations++from fastapi import APIRouter, HTTPException+from pydantic import BaseModel, Field++from ...workspace import CaseError+from .common import get_case++router = APIRouter(prefix="/api/cases", tags=["cases"])+++class FolderIn(BaseModel):+ name: str = Field(min_length=1, max_length=120)+[email protected]("/{case_id}/folders")+def list_folders(case_id: str) -> list[str]:+ return get_case(case_id).list_folders()+[email protected]("/{case_id}/folders")+def add_folder(case_id: str, body: FolderIn) -> list[str]:+ case = get_case(case_id)+ try:+ return case.add_folder(body.name)+ except CaseError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from exc+[email protected]("/{case_id}/folders")+def remove_folder(case_id: str, name: str) -> list[str]:+ return get_case(case_id).remove_folder(name)diff --git a/src/azimut/api/cases/graph.py b/src/azimut/api/cases/graph.pynew file mode 100644index 0000000..3659c7c--- /dev/null+++ b/src/azimut/api/cases/graph.py@@ -0,0 +1,260 @@+"""The case drawn: a bounded view, a neighbourhood, the routes between two nodes.++Placement is the frontend's (`lib/graph.js`); what these serve is which nodes and+edges a reading holds, which is `engine/graph.py`. The pins are the other half —+where the analyst put a node by hand, kept per lens.+"""++from __future__ import annotations++import sqlite3+from typing import Any++from fastapi import APIRouter, HTTPException, Query+from pydantic import BaseModel, Field++from ...engine import artifacts as artifact_engine+from ...engine import graph as graph_engine+from ...workspace import Case, CaseError+from .common import _temporal_filter_args, get_case++router = APIRouter(prefix="/api/cases", tags=["cases"])+++class GraphPin(BaseModel):+ """One node and where it was dropped, in the graph's own canvas units.++ Bounded because a coordinate arrives from a pointer and nothing downstream+ clamps it: the layout would happily place a node at 1e300 and the view would+ then scale the whole case down to a dot trying to frame it.+ """++ id: str = Field(min_length=1, max_length=64)+ x: float = Field(ge=-1_000_000, le=1_000_000)+ y: float = Field(ge=-1_000_000, le=1_000_000)++class GraphPins(BaseModel):+ #: Which reading was being arranged. An arrangement belongs to one, because a+ #: lens draws its own nodes and clusters them its own way.+ lens: str = Field(min_length=1, max_length=40)+ #: One drag, or the batch a debounce collected. Capped at the view's own node+ #: ceiling: nothing can be arranged that was never drawn.+ pins: list[GraphPin] = Field(min_length=1, max_length=graph_engine.MAX_OPENING)++def _ids(value: str | None) -> list[str] | None:+ """One of the graph's comma-separated id lists, or nothing at all.++ ``None`` rather than an empty list when nothing was sent, because the engine+ tells "no list" from "an empty one" and answers the first by not asking.+ """+ if not value:+ return None+ named = [entity_id.strip() for entity_id in value.split(",") if entity_id.strip()]+ return named or None+[email protected]("/{case_id}/graph")+def graph_view(+ case_id: str,+ lens: str = "all",+ limit: int | None = None,+ order: str = "degree",+ type: str | None = None,+ status: str | None = None,+ q: str | None = None,+ folder: str | None = None,+ unfiled: bool = False,+ recursive: bool = False,+ attr: str | None = None,+ value: str | None = None,+ linked: str | None = None,+ unlinked: bool = False,+ since: str | None = None,+ until: str | None = None,+ by: str | None = None,+ temporal_from: str | None = None,+ temporal_to: str | None = None,+ temporal_category: str | None = None,+ keep: str | None = None,+ expand: str | None = None,+ omit: str | None = None,+ view: str | None = None,+) -> dict[str, Any]:+ """The whole case as one bounded graph — the view the graph opens on.++ A case is a subject before it is a set of statements, so this is the entry+ point and expansion is the drill-down, not the other way round. ``order``+ decides which nodes a case too large to draw keeps: the hubs, or the latest+ work. **The catalog's whole filter vocabulary narrows it** — down to the stored+ field, the one-hop test and the date it was filed — so the board and the graph+ cannot disagree about what "confirmed people in this folder, added this week"+ means, and a question asked in the table can be handed to the drawing as itself+ rather than as a list of ids that goes stale on the next save.++ Three comma-separated lists then edit that set, and the drawing is whatever they+ say it is. ``keep`` draws these nodes and nothing around them; ``expand`` draws+ these and one hop, which is what lets the analyst follow a thread without losing+ the case they were reading it in; ``omit`` leaves these out, whichever of the+ three put them there. Ids the case does not hold are skipped rather than refused —+ a drawing races a delete made in another tab.+ """+ case = get_case(case_id)+ if view:+ saved = case.get_analysis_view(view)+ if saved is None:+ raise HTTPException(status_code=404, detail=f"analysis view '{view}' not found")+ if saved["mode"] == "snapshot":+ try:+ return graph_engine.snapshot_view(+ saved["spec"]["snapshot"], lens_id=lens, query=q+ )+ except CaseError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from exc+ types = [t.strip() for t in type.split(",") if t.strip()] if type else None+ filed_by = [name.strip() for name in by.split(",") if name.strip()] if by else None+ temporal_since, temporal_until, temporal_categories = _temporal_filter_args(+ temporal_from, temporal_to, temporal_category+ )+ try:+ payload = graph_engine.view(+ case, lens_id=lens, limit=limit, types=types, status=status,+ query=q, folder=folder, unfiled=unfiled, recursive=recursive, order=order,+ attr=attr, attr_value=value, linked=linked, unlinked=unlinked,+ since=since, until=until, filed_by=filed_by,+ temporal_since=temporal_since, temporal_until=temporal_until,+ temporal_categories=temporal_categories,+ keep=_ids(keep), expand=_ids(expand), omit=_ids(omit),+ )+ except CaseError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from exc+ _adopt_spec_previews(case, payload)+ return payload+[email protected]("/{case_id}/graph/neighborhood")+def graph_neighborhood(+ case_id: str,+ root: str,+ lens: str = "all",+ hops: int = 1,+ limit: int | None = None,+) -> dict[str, Any]:+ """One node and what surrounds it, for a question that does have a root.++ Every node carries its degree in this lens, so the analyst sees what a further+ expansion costs before paying it, and ``truncated`` says when the node budget+ ended the walk rather than the graph doing so.+ """+ case = get_case(case_id)+ try:+ payload = graph_engine.neighborhood(+ case, root, lens_id=lens, hops=hops, limit=limit+ )+ except CaseError as exc:+ detail = str(exc)+ status_code = 404 if "not found" in detail else 400+ raise HTTPException(status_code=status_code, detail=detail) from exc+ _adopt_spec_previews(case, payload)+ return payload+[email protected]("/{case_id}/graph/paths")+def graph_paths(+ case_id: str,+ from_id: str = Query(alias="from"),+ to_id: str = Query(alias="to"),+ lens: str = "all",+ hops: int = graph_engine.MAX_PATH_HOPS,+) -> dict[str, Any]:+ """Every shortest route between two entities, or the fact that there is none.++ A read, and the one question the graph existed without: the case answers "what+ touches this" a hop at a time, where an investigation asks "how does this reach+ that". ``found: false`` is an answer rather than an error — learning that two+ entities are *not* connected within the budget is a finding about the case.++ ``from`` and ``to`` are query names rather than argument names because ``from``+ is a Python keyword, and the URL is the vocabulary the client reads.+ """+ case = get_case(case_id)+ try:+ return graph_engine.paths(case, from_id, to_id, lens_id=lens, max_hops=hops)+ except CaseError as exc:+ detail = str(exc)+ status_code = 404 if "not found" in detail else 400+ raise HTTPException(status_code=status_code, detail=detail) from exc++def _lens_id(lens: str) -> str:+ """The lens an arrangement belongs to, refused if the registry does not know it.++ Checked at the edge like every other lens: an unrecognised one would file pins+ under a reading nothing can ever draw, where they would sit in the case forever+ with no surface able to show or clear them.+ """+ try:+ return graph_engine.lens(lens).id+ except CaseError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from exc+[email protected]("/{case_id}/graph/pins")+def pin_graph_nodes(case_id: str, body: GraphPins) -> dict[str, Any]:+ """Record where nodes were dragged to, so the arrangement survives a reload.++ Filed against the lens they were arranged in: a lens draws its own nodes and+ clusters them its own way, so one shared arrangement would anchor every reading+ into the shape of whichever one it was built in.++ The whole batch in one transaction: a drag that moved several nodes is one+ act, and half of it landing would leave an arrangement nobody chose. Writing a+ pin asserts nothing about the case — it is where a hand put a dot — which is+ why it never touches the entity or its provenance.+ """+ case = get_case(case_id)+ lens = _lens_id(body.lens)+ case.pin_entities(lens, {pin.id: (pin.x, pin.y) for pin in body.pins})+ return {"lens": lens, "pinned": len(case.graph_pins(lens))}+[email protected]("/{case_id}/graph/pins/{entity_id}")+def unpin_graph_node(case_id: str, entity_id: str, lens: str = "all") -> dict[str, Any]:+ """Hand one node back to the computed layout, in this lens."""+ case = get_case(case_id)+ reading = _lens_id(lens)+ case.unpin_entities(reading, [entity_id])+ return {"lens": reading, "pinned": len(case.graph_pins(reading))}+[email protected]("/{case_id}/graph/pins")+def unpin_graph(case_id: str, lens: str = "all") -> dict[str, Any]:+ """Drop this lens's arrangement: the reading goes back to the placement it+ computes, and the other readings keep theirs.++ The way out of an arrangement that stopped helping. It is offered because the+ pins are saved as they are made — an autosave with no way back is a trap.+ """+ case = get_case(case_id)+ reading = _lens_id(lens)+ case.clear_graph_pins(reading)+ return {"lens": reading, "pinned": 0}++def _adopt_spec_previews(case: Case, payload: dict[str, Any]) -> None:+ """Give a node the preview its own spec file has been keeping to itself.++ A proof records its thumbnail in ``proofs/.meta/<name>.json``, and the graph+ answers from the database alone — that boundary is what keeps a graph read one+ query instead of a walk of the case, so it is not the place to open files. This+ copies the path across, **once per proof, ever**: the first view that draws one+ reads its spec, records it on the entity, and every later view finds it on the row+ like any other preview. A proof saved from now on carries it from the start.+ """+ for node in payload.get("nodes", []):+ if node.get("thumb") or node.get("type") != "proof":+ continue+ entity = case.get_entity(node["id"])+ thumb = artifact_engine.spec_thumb(case, entity) if entity else None+ if not thumb:+ continue+ node["thumb"] = thumb+ try:+ case.update_entity(node["id"], {"attrs": {"thumb": thumb}})+ except (CaseError, sqlite3.Error):+ # The copy is an optimisation, not the answer: a background import or+ # a mass delete holding the write lock past `busy_timeout` must not+ # turn a read of the graph into an error. The node already carries+ # what it needs, and the next draw tries the copy again.+ passdiff --git a/src/azimut/api/cases/lifecycle.py b/src/azimut/api/cases/lifecycle.pynew file mode 100644index 0000000..4b036e3--- /dev/null+++ b/src/azimut/api/cases/lifecycle.py@@ -0,0 +1,169 @@+"""Cases as folders: create, open, rename, promote, delete, reveal.++Also the workspace routes beside them — the folders someone made in their file+manager that are not cases yet, and the two ways one becomes a case.+"""++from __future__ import annotations++from typing import Any++from fastapi import APIRouter, HTTPException+from pydantic import BaseModel, Field++from ... import workspace+from ...engine import reveal as reveal_engine+from ...workspace import Case, CaseError+from .common import get_case++router = APIRouter(prefix="/api/cases", tags=["cases"])++#: Folders in the workspace that are not cases yet. Deliberately *not* under+#: `/api/cases`: a case's id is its folder name, so a literal segment there is a+#: name someone can give a folder — `/api/cases/folders` is already the case+#: named "Folders" (`tests/test_cases_api.py`). These operate on the workspace+#: anyway, one level above any case.+workspace_router = APIRouter(prefix="/api/workspace", tags=["cases"])+++def _ensure_name_free(name: str, *, exclude_id: str | None = None) -> None:+ """Reject a case name already taken by another (non-scratch) case, matched+ case-insensitively on the trimmed name. ``exclude_id`` lets a rename keep+ its own name."""+ wanted = name.strip().casefold()+ for c in Case.list_all():+ if c.get("scratch") or c["id"] == exclude_id:+ continue+ if str(c.get("name", "")).strip().casefold() == wanted:+ raise HTTPException(status_code=409, detail=f"a case named '{name}' already exists")++class CreateCase(BaseModel):+ name: str = Field(min_length=1, max_length=120)++class PromoteCase(BaseModel):+ name: str = Field(min_length=1, max_length=120)++class FolderName(BaseModel):+ """A directory name in the workspace root, never a path: what it may hold is+ `layout.usable_case_name`'s answer, checked where the folder is opened."""++ name: str = Field(min_length=1, max_length=120)++class MediaPath(BaseModel):+ """One case-relative file path, bounded the way every other media route bounds+ one. Where it may point is `Case.resolve_inside`'s answer, not this model's."""++ path: str = Field(min_length=1, max_length=300)++def list_cases(q: str | None = None, limit: int | None = None) -> list[dict[str, Any]]:+ return Case.list_all(q=q, limit=limit)++def create_case(body: CreateCase) -> dict[str, Any]:+ _ensure_name_free(body.name)+ try:+ case = Case.create(body.name)+ except CaseError as exc:+ raise HTTPException(status_code=409, detail=str(exc)) from exc+ return {"id": case.id, **case.overview()}++@workspace_router.get("/folders")+def list_workspace_folders() -> list[dict[str, Any]]:+ """Folders sitting in the workspace that are not cases yet, and their state."""+ return workspace.list_workspace_folders()++@workspace_router.post("/folders/adopt")+def adopt_folder(body: FolderName) -> dict[str, Any]:+ """Make a case out of one of those folders, where it already is."""+ _ensure_name_free(body.name)+ try:+ case = Case.adopt(body.name)+ except CaseError as exc:+ raise HTTPException(status_code=409, detail=str(exc)) from exc+ return {"id": case.id, **case.overview()}++@workspace_router.post("/folders/recover")+def recover_folder(body: FolderName) -> dict[str, Any]:+ """Write back the manifest of a folder holding a case that lost it.++ The manifest and nothing else: the case is reachable again after this, and+ anything still damaged belongs to the Doctor, which the caller opens next.+ """+ try:+ case = workspace.restore_manifest(body.name)+ except CaseError as exc:+ raise HTTPException(status_code=409, detail=str(exc)) from exc+ return {"id": case.id, "name": case.read().get("name", case.id)}+[email protected]("/scratch")+def create_scratch() -> dict[str, Any]:+ case = Case.create("Scratch session", scratch=True)+ return {"id": case.id, **case.overview()}+[email protected]("/{case_id}")+def read_case(case_id: str) -> dict[str, Any]:+ case = get_case(case_id)+ return {"id": case.id, "scratch": case.is_scratch, **case.overview()}+[email protected]("/{case_id}/promote")+def promote_case(case_id: str, body: PromoteCase) -> dict[str, Any]:+ case = get_case(case_id)+ _ensure_name_free(body.name)+ try:+ promoted = case.promote(body.name)+ except CaseError as exc:+ raise HTTPException(status_code=409, detail=str(exc)) from exc+ return {"id": promoted.id, **promoted.overview()}+[email protected]("/{case_id}")+def rename_case(case_id: str, body: CreateCase) -> dict[str, Any]:+ case = get_case(case_id)+ _ensure_name_free(body.name, exclude_id=case.id)+ case.rename(body.name)+ return {"id": case.id, **case.overview()}+[email protected]("/{case_id}")+def delete_case(case_id: str) -> dict[str, str]:+ get_case(case_id).delete()+ return {"status": "deleted"}+[email protected]("/{case_id}/reveal")+def reveal_case_folder(case_id: str) -> dict[str, str]:+ """Open this case's folder in the system file manager.++ The route takes no path: the case id is enough to find the folder, so nothing+ the browser sends can point somewhere else.+ """+ case = get_case(case_id)+ try:+ reveal_engine.reveal(case.path)+ except reveal_engine.RevealError as exc:+ raise HTTPException(status_code=409, detail=str(exc)) from exc+ return {"path": str(case.path)}+[email protected]("/{case_id}/media/reveal")+def reveal_media_folder(case_id: str, body: MediaPath) -> dict[str, str]:+ """Show the folder holding one of this case's files.++ For what the app cannot display: a PDF, a scan bundle, a spreadsheet. Handing+ those to the browser downloads a second copy into Downloads, which is how an+ analyst ends up working on a file the case no longer knows about. The folder is+ the honest answer — the original is opened in whatever program owns it.++ The path is the browser's, so it goes through ``resolve_inside`` like every+ other media route; ``reveal`` then re-checks that the folder is inside the+ workspace, and it is a folder that is opened, never the file itself.+ """+ case = get_case(case_id)+ try:+ target = case.resolve_inside(body.path)+ except CaseError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from exc+ if not target.is_file():+ raise HTTPException(status_code=404, detail="file not found")+ try:+ reveal_engine.reveal(target.parent)+ except reveal_engine.RevealError as exc:+ raise HTTPException(status_code=409, detail=str(exc)) from exc+ return {"path": str(target.parent)}diff --git a/src/azimut/api/cases/links.py b/src/azimut/api/cases/links.pynew file mode 100644index 0000000..485b229--- /dev/null+++ b/src/azimut/api/cases/links.py@@ -0,0 +1,105 @@+"""Relations between entities: state one, restate it, drop it.++The vocabulary and every endpoint check live in `engine/links.py`; these routes are+the thin edge that turns a refusal there into a status code.+"""++from __future__ import annotations++from typing import Any++from fastapi import APIRouter, HTTPException+from pydantic import BaseModel, Field, StrictInt++from ...engine import links as link_engine+from ...repository import EntityStatus+from ...workspace import CaseError+from .common import get_case++router = APIRouter(prefix="/api/cases", tags=["cases"])+++class LinkIn(BaseModel):+ # `from`/`to` are the link's own field names, but `from` is a Python keyword;+ # the request spells them out rather than aliasing around it.+ from_id: str = Field(min_length=1, max_length=64)+ to_id: str = Field(min_length=1, max_length=64)+ type: str = Field(min_length=1, max_length=40)++class LinkPatch(BaseModel):+ status: EntityStatus | None = None+ type: str | None = Field(default=None, min_length=1, max_length=40)+ #: One closed ordinal, or `null` to return the edge to "not assessed". Sending it+ #: at all is what counts, so the route reads `model_fields_set` rather than the+ #: value: `null` clears a rating, where omitting the key leaves it alone.+ #:+ #: Strict, so JSON `true` is refused rather than coerced to `1`: a lax int would+ #: turn a nonsense body into the "possible" level without anyone noticing, and+ #: `2.5` into `2`.+ confidence: StrictInt | None = None+ #: What kind of tie the edge states, in the analyst's own words, or `null` to+ #: clear it. Read through `model_fields_set` like the rating above, for the same+ #: reason: `null` unsays it, omitting the key leaves it alone. Only a verb+ #: declaring a `qualifier` accepts one (`engine/links.set_qualifier`).+ nature: str | None = None+[email protected]("/{case_id}/links")+def create_link(case_id: str, body: LinkIn) -> dict[str, Any]:+ """State one relation by hand. Confirmed, and only from the registry."""+ try:+ return link_engine.add_relation(+ get_case(case_id), body.from_id, body.to_id, body.type, by="user"+ )+ except CaseError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from exc+[email protected]("/{case_id}/links/{link_id}")+def update_link(case_id: str, link_id: str, body: LinkPatch) -> dict[str, Any]:+ """Confirm a suggestion, correct which relation an edge states, rate it, or say+ what kind of tie it is.++ Restating the type goes through the vocabulary, so a 400 means the ontology+ has no such reading for those two entities; a missing link is a 404.++ Rating runs last on purpose: confirming a suggestion and rating it can arrive in+ one request, and a rating is refused on an unreviewed edge — so the confirm has+ to have landed before the rating is judged. The qualifier runs last for the+ mirror reason: a reword that drops it must not be undone by a value sent against+ the verb the edge no longer states.+ """+ rating = "confidence" in body.model_fields_set+ qualifying = "nature" in body.model_fields_set+ if body.status is None and body.type is None and not rating and not qualifying:+ raise HTTPException(status_code=400, detail="nothing to update")+ case = get_case(case_id)+ try:+ link = case.get_link(link_id)+ if link is None:+ raise HTTPException(status_code=404, detail=f"link '{link_id}' not found")+ if body.type is not None and body.type != link["type"]:+ link = link_engine.set_relation_type(case, link_id, body.type)+ if body.status == "confirmed":+ link = link_engine.confirm_relation(case, link_id)+ elif body.status is not None:+ link = case.update_link(link_id, {"status": body.status})+ if rating:+ link = link_engine.set_confidence(case, link_id, body.confidence)+ if qualifying:+ link = link_engine.set_qualifier(case, link_id, body.nature)+ return link+ except CaseError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from exc+[email protected]("/{case_id}/links/{link_id}")+def remove_link(case_id: str, link_id: str) -> dict[str, str]:+ """Take back one relation. Dismissing a proposal and retracting a confirmed+ statement are the same gesture; a derivation is neither, and is refused with a+ 400 rather than dropped without its tombstone."""+ case = get_case(case_id)+ if case.get_link(link_id) is None:+ raise HTTPException(status_code=404, detail=f"link '{link_id}' not found")+ try:+ link_engine.remove_relation(case, link_id)+ except CaseError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from exc+ return {"status": "deleted"}diff --git a/src/azimut/api/cases/registry.py b/src/azimut/api/cases/registry.pynew file mode 100644index 0000000..a8d8191--- /dev/null+++ b/src/azimut/api/cases/registry.py@@ -0,0 +1,166 @@+"""The vocabulary, served to the frontend.++Relation verbs, graph lenses, confidence levels and entity types: the declarations+in `engine/links.py` and `engine/entities.py` as JSON, so no surface has to keep its+own copy of what the ontology says. Read-only and case-independent, which is why+these paths carry no case id.+"""++from __future__ import annotations++from typing import Any++from fastapi import APIRouter++from ...engine import entities as entity_engine+from ...engine import graph as graph_engine+from ...engine import links as link_engine++router = APIRouter(prefix="/api/cases", tags=["cases"])++[email protected]("/relation-types")+def relation_types() -> list[dict[str, Any]]:+ """The relation vocabulary (ONTOLOGY §3): how each type reads in words, the+ entity types each end accepts, and whether an analyst may state it.++ Every surface reads this instead of keeping its own copy — the picker offers+ the ``manual`` ones, the relation rows use ``label`` to name an edge. Declared+ above ``/{case_id}`` so the literal path wins.+ """+ return [+ {+ "type": entry.type,+ "label": entry.label,+ "inverse_label": entry.inverse_label or entry.label,+ # one clause saying what the verb means, for the surface that shows it+ "hint": entry.hint,+ # the heading this verb sits under, empty when it sits with the rest+ "group": entry.group,+ # A mention is filed with its own gesture. It is not another wording+ # a relation can turn into after the analyst chose a target.+ "action": entry.action,+ "from_types": sorted(entry.from_types),+ "to_types": sorted(entry.to_types),+ "manual": entry.manual,+ # A mention is a pointer, not a claim to grade. The surface omits the+ # control instead of offering one the model would refuse.+ "ratable": entry.ratable,+ # How a free note on this edge is labelled, empty when the verb takes+ # none — the same shape as `ratable`, and read the same way: a surface+ # draws the field because the verb declares it, never because an edge+ # happens to carry one.+ "qualifier": entry.qualifier,+ "from_media_kinds": sorted(entry.from_media_kinds),+ "to_media_kinds": sorted(entry.to_media_kinds),+ }+ for entry in link_engine.RELATION_TYPES+ ]+[email protected]("/graph-lenses")+def graph_lenses() -> dict[str, Any]:+ """The readings the graph offers, and the orderings it ranks by.++ A lens is a set of verbs *and* a set of node roles, and both live in the+ registries, so each one is resolved from them rather than listed again here — a+ verb or a type added there joins its lens with no edit. ``orders`` is the same+ contract as the radius rungs: served, so the picker and the validator cannot drift.++ ``hides`` is the types the reading leaves out of the drawing. Served because the+ surface has to be able to say so *before* asking: a legend row that switches+ nothing and a "bring this in" that the reading will refuse are both controls that+ can only appear to be broken.++ Declared above ``/{case_id}`` so the literal path wins.+ """+ return {+ "lenses": [+ {"id": entry.id, "label": entry.label, "hint": entry.hint,+ "types": list(entry.types), "hides": list(entry.hides)}+ for entry in graph_engine.lenses()+ ],+ "orders": [+ {"value": value, "label": label, "hint": hint}+ for value, label, hint in graph_engine.ORDERS+ ],+ "max_hops": graph_engine.MAX_HOPS,+ }+[email protected]("/confidence-levels")+def confidence_levels() -> list[dict[str, Any]]:+ """How sure an edge may say the analyst is (ONTOLOGY §3), coarsest word last.++ Served rather than hardcoded on each surface for the reason the radius rungs are:+ one list, so the picker and the validator cannot drift. **Not assessed is absent+ from this list on purpose** — it is the lack of a rating, not a sixth level, and a+ surface offers it as "clear" rather than as a choice.++ Declared above ``/{case_id}`` so the literal path wins.+ """+ return [+ {"value": value, "label": label, "hint": hint}+ for value, label, hint in link_engine.CONFIDENCE_LEVELS+ ]+[email protected]("/entity-types")+def entity_types() -> list[dict[str, Any]]:+ """The entity vocabulary (ONTOLOGY §2): each type's reading, family, icon and+ the fields an analyst may fill on it.++ One registry so a create form is generated rather than written per type, and so+ no screen keeps its own copy. ``manual`` marks the types an analyst creates by+ hand — a ``media`` is born from an import, so it never belongs in a create menu.+ Declared above ``/{case_id}`` so the literal path wins.+ """+ return [+ {+ "type": entry.type,+ "label": entry.label,+ "family": entry.family,+ # what the type is, and what its family is, each in one clause. The+ # vocabulary is terse by design, and a terse word nobody can look up is+ # jargon — so the readings travel with it rather than being written per+ # screen.+ "hint": entry.hint,+ "family_reads": entity_engine.FAMILY_READS.get(entry.family, ""),+ "icon": entry.icon,+ "manual": entry.manual,+ "image_gallery": entry.image_gallery,+ # ``entity.label`` is the primary value, but "Name" is not an honest+ # reading for an IP address, a phone number or a claim. The generated+ # form names that field from the type instead of duplicating it in attrs.+ "identity_label": entry.identity_label,+ "identity_placeholder": entry.identity_placeholder,+ "attrs": [+ {+ "key": attr.key,+ "label": attr.label,+ "hint": attr.hint,+ "kind": attr.kind,+ "editable": attr.editable,+ # Heads this field and the ones after it that share it; empty+ # means the field stands on its own label. On the field rather+ # than on the type because a Claim separates what it states,+ # when it applies and why it is believed.+ "group": attr.group,+ # Served so the form refuses exactly what the API refuses; a+ # rung list is the shortcut UI, the bounds are the contract.+ "rungs": [{"label": name, "value": v} for name, v in attr.rungs],+ "minimum": attr.minimum,+ "maximum": attr.maximum,+ # A count steps by one. Served so the spinner and the validator+ # cannot disagree about what a valid quantity is.+ "whole": attr.whole,+ # The whole of a closed field, in scale order. A source's+ # reliability rides here rather than on a route of its own: it+ # belongs to the entity, so it travels with the entity registry.+ "options": [+ {"value": stored, "label": reading}+ for stored, reading in attr.options+ ],+ }+ for attr in entry.attrs+ ],+ }+ for entry in entity_engine.ENTITY_TYPES+ ]diff --git a/src/azimut/api/cases/timeline.py b/src/azimut/api/cases/timeline.pynew file mode 100644index 0000000..97a2b17--- /dev/null+++ b/src/azimut/api/cases/timeline.py@@ -0,0 +1,371 @@+"""When things happened: the timeline page, its map, and the Claims behind it.++A Claim is the entity that states a time, so creating one is an entity write plus+its connectors. The projection those rows are read from is derived and rebuildable+(`store/temporal.py`); Claims and media sidecars stay authoritative.+"""++from __future__ import annotations++import json+import math+from typing import Any, Literal++from fastapi import APIRouter, HTTPException, Query+from pydantic import BaseModel, Field, StrictInt++from ...engine import links as link_engine+from ...engine import timeline as timeline_engine+from ...repository import EntityStatus+from ...workspace import Case, CaseError+from .common import _check_attrs, _timeline_bound, delete_entity_deep, get_case++router = APIRouter(prefix="/api/cases", tags=["cases"])+++class TemporalClaimIn(BaseModel):+ statement: str = Field(min_length=1, max_length=300)+ when: str | None = None+ time_role: Literal["occurred", "observed", "valid"] | None = None+ confidence: Literal["certain", "probable", "possible", "refuted"] | None = None+ method: str | None = None+ verbatim: str | None = None+ count: StrictInt | None = None+ condition: Literal["intact", "damaged", "destroyed", "abandoned"] | None = None+ about: list[str] = Field(default_factory=list, max_length=200)+ at: list[str] = Field(default_factory=list, max_length=50)+ cites: list[str] = Field(default_factory=list, max_length=200)++class TemporalClaimPatch(BaseModel):+ statement: str | None = Field(default=None, min_length=1, max_length=300)+ when: str | None = None+ time_role: Literal["occurred", "observed", "valid"] | None = None+ confidence: Literal["certain", "probable", "possible", "refuted"] | None = None+ method: str | None = None+ verbatim: str | None = None+ count: StrictInt | None = None+ condition: Literal["intact", "damaged", "destroyed", "abandoned"] | None = None+ about: list[str] | None = Field(default=None, max_length=200)+ at: list[str] | None = Field(default=None, max_length=50)+ cites: list[str] | None = Field(default=None, max_length=200)+ status: EntityStatus | None = None+[email protected]("/{case_id}/timeline")+def timeline(+ case_id: str,+ from_: str | None = Query(default=None, alias="from"),+ to: str | None = None,+ category: list[str] | None = Query(default=None),+ entity: str | None = None,+ include_undated: bool = True,+ limit: int = Query(default=100, ge=1, le=200),+ cursor: str | None = None,+ bucket: Literal["year", "month", "day", "hour"] | None = None,+ track: str | None = None,+ spread: bool = False,+) -> dict[str, Any]:+ """One bounded temporal page, independent of the projection's SQL shape.++ ``spread`` is for a caller drawing the page on an axis: it samples the window+ rather than serving its front, so a lopsided case fills the axis it spans.+ """+ since = _timeline_bound(from_, upper=False)+ until = _timeline_bound(to, upper=True)+ if since is not None and until is not None and since >= until:+ raise HTTPException(status_code=400, detail="the timeline window ends before it starts")+ if track and len(track.encode("utf-8")) > 64 * 1024:+ raise HTTPException(status_code=400, detail="timeline track query is too large")+ try:+ track_query = json.loads(track) if track else None+ if track_query is not None and not isinstance(track_query, dict):+ raise CaseError("a timeline track query must be an object")+ page = get_case(case_id).timeline_page(+ since=since,+ until=until,+ categories=category,+ entity_id=entity,+ include_undated=include_undated,+ limit=limit,+ cursor=cursor,+ bucket=bucket,+ track=track_query,+ spread=spread,+ )+ except (CaseError, json.JSONDecodeError) as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from exc+ return {**page, "window": {"from": since, "to": until}}++# Every way the case puts something on the map. A Claim says where it happened with+# `at`, and that was the only one this layer knew — so a window full of photographs+# recorded somewhere, captures showing somewhere, or a structure standing somewhere+# answered with an empty map and the words "nothing carries a place". `mentions` is+# not here: a note referring to a place is not a thing that was there.+_MAP_PLACE_LINKS = (+ link_engine.AT,+ link_engine.LOCATED_AT,+ link_engine.DEPICTS,+ link_engine.SITED_AT,+)+[email protected]("/{case_id}/timeline/map")+def timeline_map(+ case_id: str,+ from_: str = Query(alias="from"),+ to: str = Query(),+ category: list[str] | None = Query(default=None),+) -> dict[str, Any]:+ """Whatever the window holds that the case has put somewhere, for the Map layer."""+ since = _timeline_bound(from_, upper=False)+ until = _timeline_bound(to, upper=True)+ if since is None or until is None or since >= until:+ raise HTTPException(status_code=400, detail="the timeline window ends before it starts")+ categories = (+ list(dict.fromkeys(part.strip() for part in ",".join(category).split(",") if part.strip()))+ if category+ else list(timeline_engine.DEFAULT_CATEGORIES)+ )+ invalid = sorted(set(categories) - set(timeline_engine.ALL_CATEGORIES))+ if invalid:+ raise HTTPException(status_code=400, detail=f"unknown timeline category '{invalid[0]}'")+ if not categories:+ raise HTTPException(status_code=400, detail="a temporal filter needs a category")++ case = get_case(case_id)+ rows: list[dict[str, Any]] = []+ cursor: str | None = None+ read = 0+ total = 0+ ceiling = 5000+ while read < ceiling:+ page = case.timeline_page(+ since=since,+ until=until,+ categories=categories,+ include_undated=False,+ limit=min(200, ceiling - read),+ cursor=cursor,+ )+ if read == 0:+ total = int(page["total"])+ batch = list(page["items"])+ rows.extend(batch)+ read += len(batch)+ cursor = page["next_cursor"]+ if cursor is None or not batch:+ break++ # Resolved from the edges themselves rather than from the row's own `at` list,+ # which only a Claim ever fills.+ owners = {str(item["owner_id"]) for item in rows}+ held: dict[str, list[str]] = {}+ for edge in case.links_touching(+ sorted(owners), types=list(_MAP_PLACE_LINKS), end_types=["place"]+ ):+ if edge["from"] in owners and edge["to"] != edge["from"]:+ held.setdefault(edge["from"], []).append(edge["to"])++ place_ids = list(dict.fromkeys(+ place_id for places in held.values() for place_id in places+ ))+ places = {entity["id"]: entity for entity in case.entities_by_ids(place_ids)}++ # What a mark on the map has to know to hand its row back to the tool that owns+ # it, and to show a photograph as a photograph rather than as a line of text.+ placed_owners = sorted(held)+ owned = {entity["id"]: entity for entity in case.entities_by_ids(placed_owners)}+ thumbs = dict(case.media_thumbs(placed_owners))+ thumbs.update(case.entity_image_thumbs(placed_owners))+ for owner_id, entity in owned.items():+ # A capture or a proof records its own preview rather than owning an indexed+ # media row, and the graph reads them the same way.+ recorded = (entity.get("attrs") or {}).get("thumb")+ if recorded and owner_id not in thumbs:+ thumbs[owner_id] = recorded++ mapped: list[dict[str, Any]] = []+ mark_count = 0+ for item in rows:+ owner_id = str(item["owner_id"])+ owner = owned.get(owner_id)+ positioned = []+ for place_id in dict.fromkeys(held.get(owner_id, [])):+ place = places.get(place_id)+ attrs = place.get("attrs") if place else None+ if place is None or not isinstance(attrs, dict):+ continue+ try:+ lat = float(attrs["lat"])+ lon = float(attrs["lon"])+ except (KeyError, TypeError, ValueError):+ continue+ if not math.isfinite(lat) or not math.isfinite(lon):+ continue+ positioned.append({+ "id": place_id,+ "label": place.get("label", "Place"),+ "lat": lat,+ "lon": lon,+ "radius_m": attrs.get("radius_m"),+ "footprint": attrs.get("footprint"),+ })+ if positioned:+ mapped.append({+ **item,+ "place_entities": positioned,+ "owner": {+ "id": owner_id,+ "type": owner.get("type", "") if owner else item.get("owner_type", ""),+ "label": owner.get("label", "") if owner else item.get("label", ""),+ "attrs": owner.get("attrs") or {} if owner else {},+ "thumb": thumbs.get(owner_id),+ },+ })+ mark_count += len(positioned)++ return {+ "items": mapped,+ "matched": total,+ "mapped": len(mapped),+ "marks": mark_count,+ "truncated": read < total,+ "window": {"from": since, "to": until},+ }++_TEMPORAL_CLAIM_ATTRS = (+ "when", "time_role", "confidence", "method", "verbatim", "count", "condition"+)+_TEMPORAL_CONNECTORS = ("about", "at", "cites")++def _temporal_item(case: Case, claim_id: str) -> dict[str, Any]:+ """The row this Claim owns, wherever the entity scope puts it.++ That scope also answers with rows owned by whatever cites the Claim, and they+ are ordered by date rather than by ownership — so a Claim many others rest on+ can sit past the first page, and reading only that page would fail a write+ that has already been committed.+ """+ cursor: str | None = None+ while True:+ page = case.timeline_page(+ categories=[timeline_engine.STATEMENT],+ entity_id=claim_id,+ include_undated=True,+ limit=200,+ cursor=cursor,+ )+ for item in page["items"]:+ if item["owner_id"] == claim_id:+ return item+ cursor = page["next_cursor"]+ if cursor is None:+ raise HTTPException(+ status_code=500,+ detail=f"claim '{claim_id}' was saved without a temporal row",+ )++def _check_claim_connectors(+ case: Case,+ source: dict[str, Any],+ connectors: dict[str, list[str]],+) -> None:+ for type_, targets in connectors.items():+ for target in dict.fromkeys(targets):+ target_entity = case.get_entity(target)+ if type_ == "about" and target_entity is not None and target_entity["type"] == "claim":+ raise HTTPException(+ status_code=400,+ detail=(+ "A Claim has one date or range. Edit its date, or create a"+ " separate Claim."+ ),+ )+ try:+ link_engine.check_relation_target(case, source, target, type_)+ except CaseError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from exc+[email protected]("/{case_id}/timeline/claims")+def create_temporal_claim(case_id: str, body: TemporalClaimIn) -> dict[str, Any]:+ """Create the statement, date and all of its connectors in one transaction."""+ case = get_case(case_id)+ statement = body.statement.strip()+ if not statement:+ raise HTTPException(status_code=400, detail="a Claim statement cannot be empty")+ attrs = {+ key: getattr(body, key)+ for key in _TEMPORAL_CLAIM_ATTRS+ if getattr(body, key) is not None+ }+ _check_attrs("claim", attrs)+ connectors = {key: getattr(body, key) for key in _TEMPORAL_CONNECTORS}+ _check_claim_connectors(case, {"type": "claim"}, connectors)+ try:+ saved = case.save_temporal_claim(+ entity_id=None,+ label=statement,+ attrs=attrs,+ connectors=connectors,+ by="user",+ )+ except CaseError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from exc+ return {**saved, "temporal": _temporal_item(case, saved["entity"]["id"])}+[email protected]("/{case_id}/timeline/claims/{claim_id}")+def update_temporal_claim(+ case_id: str, claim_id: str, body: TemporalClaimPatch+) -> dict[str, Any]:+ """Replace a Claim's temporal fields and selected connector sets atomically."""+ if not body.model_fields_set:+ raise HTTPException(status_code=400, detail="nothing to update")+ case = get_case(case_id)+ current = case.get_entity(claim_id)+ if current is None:+ raise HTTPException(status_code=404, detail=f"entity '{claim_id}' not found")+ if current["type"] != "claim":+ raise HTTPException(status_code=400, detail=f"entity '{claim_id}' is not a Claim")+ if "statement" in body.model_fields_set and body.statement is None:+ raise HTTPException(status_code=400, detail="a Claim statement cannot be empty")+ statement = (body.statement or current["label"]).strip()+ if not statement:+ raise HTTPException(status_code=400, detail="a Claim statement cannot be empty")++ attrs = dict(current.get("attrs") or {})+ for key in _TEMPORAL_CLAIM_ATTRS:+ if key in body.model_fields_set:+ attrs[key] = getattr(body, key)+ _check_attrs("claim", attrs, current=current.get("attrs") or {})+ connector_keys = set(_TEMPORAL_CONNECTORS) & body.model_fields_set+ connectors = (+ {key: list(getattr(body, key) or []) for key in connector_keys}+ if connector_keys+ else None+ )+ if connectors is not None:+ _check_claim_connectors(case, current, connectors)+ try:+ saved = case.save_temporal_claim(+ entity_id=claim_id,+ label=statement,+ attrs=attrs,+ connectors=connectors,+ by="user",+ status=body.status or current["provenance"]["status"],+ )+ except CaseError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from exc+ return {**saved, "temporal": _temporal_item(case, claim_id)}+[email protected]("/{case_id}/timeline/claims/{claim_id}")+def remove_temporal_claim(case_id: str, claim_id: str) -> dict[str, Any]:+ """Delete one Claim through the normal recoverable Trash workflow."""+ case = get_case(case_id)+ entity = case.get_entity(claim_id)+ if entity is None:+ raise HTTPException(status_code=404, detail=f"entity '{claim_id}' not found")+ if entity["type"] != "claim":+ raise HTTPException(status_code=400, detail=f"entity '{claim_id}' is not a Claim")+ try:+ return delete_entity_deep(case, claim_id)+ except CaseError as exc:+ raise HTTPException(status_code=400, detail=str(exc)) from excdiff --git a/src/azimut/api/cases/trash.py b/src/azimut/api/cases/trash.pynew file mode 100644index 0000000..b8440d2--- /dev/null+++ b/src/azimut/api/cases/trash.py@@ -0,0 +1,63 @@+"""The trash: what was deleted, put back, or purged for good.++One row per delete action rather than per entity, so a video deleted with its three+Inspect sessions comes back as the one thing the analyst removed.+"""++from __future__ import annotations++from typing import Any++from fastapi import APIRouter, HTTPException++from ...engine import trash as trash_engine+from ...workspace import CaseError+from .common import get_case++router = APIRouter(prefix="/api/cases", tags=["cases"])++[email protected]("/{case_id}/trash")+def list_trash(case_id: str) -> dict[str, Any]:+ """What the case is holding for you, newest first.++ Head columns only — no payload is read here, so the node costs one indexed+ query however much is waiting in it.+ """+ case = get_case(case_id)+ summary = case.trash_summary()+ return {+ "groups": case.list_trash(),+ "items": summary["items"],+ "size_bytes": summary["size_bytes"],+ }+[email protected]("/{case_id}/trash/{group_id}/restore")+def restore_trash(case_id: str, group_id: str) -> dict[str, Any]:+ """Take one delete back, all of it or none.++ A 409 means a file is back at a path the group wants: restoring would have to+ rename an artifact behind the analyst, so it refuses and names the path+ instead.+ """+ case = get_case(case_id)+ try:+ return trash_engine.restore(case, group_id)+ except CaseError as exc:+ message = str(exc)+ status = 404 if "not found" in message else 409+ raise HTTPException(status_code=status, detail=message) from exc+[email protected]("/{case_id}/trash/{group_id}")+def purge_trash(case_id: str, group_id: str) -> dict[str, str]:+ """Drop one group for good. This is where the bytes actually go."""+ case = get_case(case_id)+ try:+ trash_engine.purge(case, group_id)+ except CaseError as exc:+ raise HTTPException(status_code=404, detail=str(exc)) from exc+ return {"status": "purged"}+[email protected]("/{case_id}/trash")+def empty_trash(case_id: str) -> dict[str, int]:+ return {"purged": trash_engine.empty(get_case(case_id))}diff --git a/src/azimut/caselayout.py b/src/azimut/caselayout.pynew file mode 100644index 0000000..9a01edb--- /dev/null+++ b/src/azimut/caselayout.py@@ -0,0 +1,379 @@+"""How a case folder is shaped on disk, and how an older one is brought to it.++Two things live here. The small filesystem primitives every case write goes+through — creating a directory, hiding a dotted one on Windows, leaving the+README — and the pass that reshapes a case folder laid out by an earlier version+into the current shape.++That pass is a folder migration (`workspace.FOLDER_MIGRATIONS`), run once on open+and never again: it wraps a bare folder, flattens the trash, moves the machinery+out of sight, names notes after their titles and aligns visible names. Each step+is separately restartable, because a case half-migrated by a crash has to be able+to finish rather than be refused.++It is kept apart from `workspace.py` because it is about the *shape of a+directory*, not about what a case is: nothing here reads the graph, and `Case`+appears only as the thing being reshaped.+"""++from __future__ import annotations++import shutil+import time+from pathlib import Path+from typing import TYPE_CHECKING, Any, Callable++from . import config, layout++if TYPE_CHECKING:+ from .workspace import Case+++def ensure_dir(path: Path) -> Path:+ """``path.mkdir(parents=True, exist_ok=True)``, tolerant of a transient+ ``PermissionError`` Windows can raise when several threads race to create+ the very same directory for the first time (e.g. several concurrent+ downloads all hitting a case's not-yet-created ``media/.dl`` or+ ``media/.thumbs`` at once): CreateDirectory there occasionally answers+ "access is denied" instead of "already exists" mid-race, which+ ``exist_ok=True`` alone does not catch. Retried briefly — the directory+ reliably exists by the next attempt, whoever won the race.+ """+ for attempt in range(20):+ try:+ path.mkdir(parents=True, exist_ok=True)+ _hide_dotted_chain(path)+ return path+ except PermissionError:+ if path.is_dir():+ return path+ if attempt == 19:+ raise+ time.sleep(0.01)+ return path # pragma: no cover - loop always returns or raises above+++def _hide_dotted_chain(path: Path) -> None:+ """Hide *path* on Windows, and the dot-directories `parents=True` just made.++ `media/.meta/<proof>.assets` creates `.meta` on the way to a leaf that is+ not itself dotted, so hiding the leaf alone would leave the directory that+ matters visible. The walk stops at the first ancestor without a leading dot,+ which is always the visible half of the case (`media/`, `proofs/`, the tool+ root), so it never climbs out of the workspace.+ """+ current = path+ while True:+ config.hide_if_dotted(current)+ parent = current.parent+ if parent == current or not parent.name.startswith("."):+ return+ current = parent+++def _follow_hidden_dirs(root: Path) -> None:+ """Put the hidden attribute back on a case's internal directories.++ `.azimut` gets this at every startup (`config.ensure_workspace`); a case only+ got it the day it was born, so any copy of a workspace — a move onto another+ drive, a folder carried between machines, a backup unpacked — showed the+ analyst directories the layout means to keep out of sight.++ Costs nothing off Windows, where `hide_if_dotted` is what returns early: one+ guard in one place beats a second copy of the platform test here.+ """+ for directory in layout.hidden_dirs(root):+ config.hide_if_dotted(directory)+++def write_readme(root: Path) -> None:+ """Leave the note that says which half of the case folder is whose.++ Only when there is none. The file sits in the analyst's half, so once it is+ there it is theirs: an edited or deleted README is a choice, not damage, and+ rewriting it on every open would undo it.+ """+ readme = layout.readme(root)+ if not readme.exists():+ readme.write_text(layout.README_TEXT, encoding="utf-8")++++def _wrap_case_folder(case: "Case") -> None:+ """Move the tool's files into `azimut/`.++ What this buys is in `layout.py`: the case root becomes the analyst's, and a+ folder they create there can no longer collide with one of ours.++ Nothing inside is rewritten. Paths are stored relative to the tool root+ (`media/x.png`), so they go on meaning the same thing one level down — the+ database, the sidecars and any bundle are untouched.++ **Only the tool's own entries move** (`layout.UNWRAPPED_ENTRIES`). Nothing+ stopped an analyst from keeping their own folder beside a case before this,+ and carrying it into `azimut/` would contradict the very boundary being+ drawn. Anything unrecognised stays at the case root, which is where it now+ belongs anyway.++ **The manifest moves last.** While it is still at the case root the move is+ unfinished, and that is exactly what `layout.needs_wrapper` reads, so a+ power cut mid-move is resumed rather than half-applied. Runs before anything+ reads the manifest, which is why it is keyed on the filesystem rather than+ on a schema number nobody could load yet.+ """+ root = case.path+ if not layout.needs_wrapper(root):+ return+ tool = layout.tool_root(root)+ tool.mkdir(exist_ok=True)+ ours = [root / name for name in layout.UNWRAPPED_ENTRIES]+ ours += sorted(root.glob(layout.UNWRAPPED_BACKUP_GLOB))+ for entry in dict.fromkeys(ours):+ destination = tool / entry.name+ if not entry.exists() or destination.exists():+ continue # absent, or already carried over by an interrupted run+ shutil.move(str(entry), str(destination))+ shutil.move(str(layout.unwrapped_manifest(root)), str(layout.manifest(root)))+ case._forget_store() # the database is at a new path now+++def _flatten_trash(case: "Case") -> None:+ """Make trash groups stop mirroring the case tree.++ A group used to hold ``media/clip.mp4`` under its own directory, stacking+ two case trees and making the trash the longest path Azimut could write —+ on its own enough to pass Windows' 260-character limit. The journal already+ knows where each file came from, so the files move to numbered slots and the+ payload gains the ``slots`` list that pairs with ``files``.++ Idempotent: a file already in its slot is left alone, so an interrupted run+ resumes.+ """+ from .engine.trash import slots_for++ groups = [g["id"] for g in case.list_trash()]+ groups += [g["id"] for g in case.list_incomplete_trash()]+ for group_id in dict.fromkeys(groups):+ group = case.get_trash_group(group_id)+ if group is None:+ continue+ payload = dict(group.get("payload") or {})+ files = [str(rel) for rel in (payload.get("files") or [])]+ slots = slots_for(files)+ root = case.trash_dir / group_id+ for rel, slot in zip(files, slots):+ source = root / rel+ destination = root / slot+ if source.exists() and not destination.exists():+ shutil.move(str(source), str(destination))+ _drop_empty_dirs(root)+ payload["slots"] = slots+ case.update_trash_group(group_id, payload=payload)+++def _drop_empty_dirs(root: Path) -> None:+ """Remove the directories a mirrored group left behind, deepest first."""+ if not root.is_dir():+ return+ for path in sorted(root.rglob("*"), key=lambda p: len(p.parts), reverse=True):+ if path.is_dir() and not any(path.iterdir()):+ path.rmdir()+++def _prune_empty_note_dirs(root: Path, directory: Path) -> None:+ """Drop the folder directories a moved note left empty, up to `notes/`.++ A mirrored tree that keeps every directory a note ever passed through stops+ being a mirror. Stops at `notes/` itself, which is born with the case.++ Both paths are resolved before they are compared. Callers hand in the note+ directory as the case knows it and the note's own parent as+ `resolve_inside` returned it, which are the same directory in two spellings+ the moment a symlink sits anywhere above the workspace: macOS reaches every+ temporary directory through `/var` → `/private/var`, and a workspace under a+ synced or linked folder does the same on any platform. Comparing the two+ spellings makes the containment check say "outside", and the loop that+ should prune then does nothing at all.+ """+ root = root.resolve()+ directory = directory.resolve()+ while directory != root and directory.is_relative_to(root):+ try:+ if any(directory.iterdir()):+ return+ directory.rmdir()+ except OSError:+ return+ directory = directory.parent+++def _move_into(source: Path, destination: Path) -> None:+ """Carry one entry over, skipping what an interrupted run already moved."""+ if not source.exists() or destination.exists():+ return+ ensure_dir(destination.parent)+ shutil.move(str(source), str(destination))+++def _hide_the_machinery(case: "Case") -> None:+ """Move what only Azimut can read out of the way.++ The rule is in `layout.py`: visible means openable in another program.+ Applied here it moves the database into `.data/`, the media sidecars into+ `media/.meta/`, the proof specs and their pasted assets into+ `proofs/.meta/`, and renames `inspect/` and `search/` to dot-directories.++ `exports/` is the one that changes meaning rather than place. It held post+ drafts — its name was wrong — so the drafts become `.drafts/` and a fresh,+ empty `exports/` is left behind for what the word actually promises.++ This is the first folder step that rewrites *stored* paths: a proof's+ ``spec``, a session's ``spec`` and a post's ``draft`` all name a directory+ that just moved.+ """+ root = case.path+ tool = layout.tool_root(root)++ # The database first, and with no connection open: on Windows an open file+ # cannot be moved. Nothing holds one here — every backend connection is+ # scoped to its own `with` — but the cached handle is dropped anyway so the+ # next access re-resolves against the new path.+ _move_into(tool / layout.PRE_HIDDEN_DB, layout.database(root))+ case._forget_store()++ # Sidecars: `media/clip.mp4.azimut.json` -> `media/.meta/clip.mp4.json`.+ media_dir = layout.media(root)+ if media_dir.is_dir():+ suffix = layout.PRE_HIDDEN_SIDECAR_SUFFIX+ for sidecar in sorted(media_dir.glob(f"*{suffix}")):+ name = sidecar.name[: -len(suffix)]+ _move_into(sidecar, case.resolve_inside(layout.sidecar_rel(name)))++ # Proof specs and pasted assets join them; the rendered PNG stays visible.+ proofs_dir = layout.subdir(root, "proofs")+ if proofs_dir.is_dir():+ for spec in sorted(proofs_dir.glob("*.json")):+ _move_into(spec, case.resolve_inside(layout.proof_spec_rel(spec.stem)))+ for assets in sorted(proofs_dir.glob("*.assets")):+ _move_into(assets, case.resolve_inside(layout.proof_assets_rel(assets.stem)))++ # The sidecars just moved, and the one-time browse-index backfill may have+ # already run against their old location. Forget it, so the reopen below+ # rebuilds the index from where they are now.+ store = case._sqlite+ if store is not None:+ store.forget_media_index()+ case._forget_store()++ for old, new in layout.PRE_HIDDEN_DIRS.items():+ _move_into(tool / old, tool / new)+ for directory in layout.content_dirs(root):+ ensure_dir(directory)++ _rewrite_moved_paths(case)+++#: entity type -> (attribute holding a case-relative path, old prefix, rebuild).+_MOVED_ATTRS: dict[str, tuple[str, str, Callable[[str], str]]] = {+ "proof": ("spec", "proofs/", layout.proof_spec_rel),+ "inspect-session": ("spec", "inspect/", layout.session_rel),+ "post": ("draft", "exports/", layout.draft_rel),+}+++def _rewrite_moved_paths(case: "Case") -> None:+ """Point the graph at the directories the migration just renamed.++ Only entities still naming the old location are touched, so a re-run after+ an interruption rewrites nothing twice.+ """+ for entity in case.list_entities():+ rule = _MOVED_ATTRS.get(str(entity.get("type") or ""))+ if rule is None:+ continue+ attribute, prefix, rebuild = rule+ current = (entity.get("attrs") or {}).get(attribute)+ if not isinstance(current, str) or not current.startswith(prefix):+ continue+ stem = Path(current).stem+ case.update_entity(entity["id"], {"attrs": {attribute: rebuild(stem)}})+++def _name_notes_after_their_titles(case: "Case") -> None:+ """Make notes stop being named after their entity id.++ `notes/e_03aeb50d41.md` was visible and illegible — in the way without being+ readable. Every other document already follows "the name is the filename";+ notes were the only holdout, and only because they are generic entities with+ their path hardcoded rather than a tool of their own.++ Titles are not unique, so a collision inside one folder takes a numbered+ suffix, exactly as a new note would.++ An empty patch is the whole migration: `update_entity` already moves a note+ whose title or folder no longer matches its filename. Once moved, the+ current path is reserved for that note, so a resumed pass leaves the path+ and any collision suffix unchanged.+ """+ for entity in case.list_entities():+ if entity.get("type") == "note":+ case.update_entity(entity["id"], {})+++def _leave_a_readme(case: "Case") -> None:+ """Teach a case that predates the free zone which half is whose.++ The wrapper gave the analyst the case root three schemas ago; nothing on+ disk told them. This is the step that does, and it is the only migration+ here that writes into their half of the folder rather than ours.+ """+ write_readme(case.path)+++def _align_visible_names(case: "Case") -> None:+ """Make every analyst-visible filename stem the name Azimut displays.++ Uploads belong to the analyst, so their existing filename wins. Downloads,+ captures and derived media belong to an Azimut save gate, so their stored+ title wins and machine timestamps/remote ids remain provenance. Named+ documents run through their existing rename hooks, which also repairs a+ Details edit that changed only the graph label.+ """+ from .engine import media as media_engine++ media_engine.recover_media_rename(case)+ for item in list(case.list_media_items()):+ path = str(item.get("path") or "")+ if not path:+ continue+ source: dict[str, Any] = item["source"] if isinstance(item.get("source"), dict) else {}+ entity = case.find_entity(attr="path", value=path)+ if source.get("type") == "upload":+ desired = Path(path).stem+ else:+ desired = str(item.get("title") or (entity or {}).get("label") or Path(path).stem)+ # `Case.migrate` already owns the case lock. An older case cannot have+ # live work in this process; waiting here would deadlock a test that+ # deliberately rewinds a just-created case while its worker is draining.+ media_engine.rename_media(case, path, desired, settle_worker=False)++ for entity in list(case.list_entities()):+ if entity.get("type") in {"note", "proof", "inspect-session", "post"}:+ case.update_entity(entity["id"], {"label": entity.get("label") or ""})+++def _normalize_case_layout(case: "Case") -> None:+ """Bring every unreleased folder checkpoint to the final layout.++ Schemas 4 through 7 were useful while building the layout, but no released+ Azimut wrote them. One normalizer accepts schema 3 and those development+ states, applies every operation in dependency order, then the runner stamps+ the current schema once. Each operation is idempotent, so an interrupted+ pass restarts here without guessing which line completed.+ """+ _wrap_case_folder(case)+ _flatten_trash(case)+ _hide_the_machinery(case)+ _name_notes_after_their_titles(case)+ _leave_a_readme(case)+ _align_visible_names(case)diff --git a/src/azimut/casestore.py b/src/azimut/casestore.pynew file mode 100644index 0000000..210229c--- /dev/null+++ b/src/azimut/casestore.py@@ -0,0 +1,505 @@+"""The store contract `Case` presents, forwarded to the backend that holds it.++A case is a folder: a manifest, notes on disk, media files, a trash directory. Its+graph is none of those — it lives in `case.db` and is `sqlite_backend.SqliteCase`.+Both are one object to the rest of the app, because a route asks a case for its+entities without caring which half answers.++That seam is what this class is. Every method here forwards to the store and does+nothing else; anything that also touches the folder (creating a note, renaming an+artifact, promoting a scratch case) stays on `Case`, where the two halves have to be+kept in step. Splitting them apart is what keeps that distinction readable: what is+in this file is, by construction, not case-folder behaviour.++The methods are grouped as `repository.CaseRepository` groups them — catalog and+media reads, the timeline projection, graph pins and analysis views, entity and link+writes, folders, the trash journal, the durable job queue.+"""++from __future__ import annotations++from typing import TYPE_CHECKING, Any++from .repository import EntityStatus++if TYPE_CHECKING:+ from .sqlite_backend import SqliteCase+++class CaseStore:+ """Forwards the store half of the case contract. Mixed into `Case`."""++ def _graph(self) -> "SqliteCase":+ """The store behind this case. `Case` supplies it; see `Case._graph`."""+ raise NotImplementedError++ def list_entities(self) -> list[dict[str, Any]]:+ return self._graph().list_entities()++ def page_entities(+ self,+ *,+ limit: int = 100,+ cursor: str | None = None,+ types: list[str] | None = None,+ status: EntityStatus | None = None,+ query: str | None = None,+ folder: str | None = None,+ unfiled: bool = False,+ recursive: bool = False,+ attr: str | None = None,+ attr_value: str | None = None,+ linked: str | None = None,+ unlinked: bool = False,+ since: str | None = None,+ until: str | None = None,+ filed_by: list[str] | None = None,+ temporal_since: str | None = None,+ temporal_until: str | None = None,+ temporal_categories: list[str] | None = None,+ order: str = "",+ ) -> dict[str, Any]:+ """A bounded, filtered page of the catalog (Step 5), paged with an indexed+ keyset over the ordering asked for."""+ return self._graph().page_entities(+ limit=limit,+ cursor=cursor,+ types=types,+ status=status,+ query=query,+ folder=folder,+ unfiled=unfiled,+ recursive=recursive,+ attr=attr,+ attr_value=attr_value,+ linked=linked,+ unlinked=unlinked,+ since=since,+ until=until,+ filed_by=filed_by,+ temporal_since=temporal_since,+ temporal_until=temporal_until,+ temporal_categories=temporal_categories,+ order=order,+ )++ def catalog_summary(self) -> dict[str, Any]:+ """Total plus per-type, per-status, per-folder and per-filer counts."""+ return self._graph().catalog_summary()++ def attr_facets(+ self, *, types: list[str] | None = None, limit: int = 50+ ) -> list[dict[str, Any]]:+ """Which stored fields these entities hold, and which values, as a menu."""+ return self._graph().attr_facets(types=types, limit=limit)++ def list_links(self) -> list[dict[str, Any]]:+ return self._graph().list_links()++ def entity_images(self, entity_id: str) -> list[dict[str, Any]]:+ return self._graph().entity_images(entity_id)++ def entity_image_thumbs(self, entity_ids: list[str]) -> dict[str, str]:+ return self._graph().entity_image_thumbs(entity_ids)++ def entity_images_touching(self, entity_ids: list[str]) -> list[dict[str, Any]]:+ return self._graph().entity_images_touching(entity_ids)++ def add_entity_images(self, entity_id: str, media_ids: list[str]) -> int:+ return self._graph().add_entity_images(entity_id, media_ids)++ def add_entity_image_file(+ self,+ entity_id: str,+ image_id: str,+ path: str,+ thumbnail: str,+ title: str,+ ) -> None:+ self._graph().add_entity_image_file(+ entity_id, image_id, path, thumbnail, title+ )++ def set_primary_entity_image(self, entity_id: str, image_id: str) -> None:+ self._graph().set_primary_entity_image(entity_id, image_id)++ def remove_entity_image(self, entity_id: str, image_id: str) -> dict[str, Any]:+ return self._graph().remove_entity_image(entity_id, image_id)++ def reinsert_entity_images(self, rows: list[dict[str, Any]]) -> dict[str, int]:+ return self._graph().reinsert_entity_images(rows)++ def upsert_media_item(self, item: dict[str, Any], *, entity_id: str | None = None) -> None:+ self._graph().upsert_media_item(item, entity_id=entity_id)++ def remove_media_item(self, path: str) -> None:+ self._graph().remove_media_item(path)++ def timeline_page(+ self,+ *,+ since: str | None = None,+ until: str | None = None,+ categories: list[str] | None = None,+ entity_id: str | None = None,+ include_undated: bool = True,+ limit: int = 100,+ cursor: str | None = None,+ bucket: str | None = None,+ track: dict[str, Any] | None = None,+ spread: bool = False,+ ) -> dict[str, Any]:+ return self._graph().timeline_page(+ since=since,+ until=until,+ categories=categories,+ entity_id=entity_id,+ include_undated=include_undated,+ limit=limit,+ cursor=cursor,+ bucket=bucket,+ track=track,+ spread=spread,+ )++ def rebuild_temporal_projection(self) -> int:+ return self._graph().rebuild_temporal_projection()++ def temporal_projection_status(self) -> dict[str, int | bool]:+ return self._graph().temporal_projection_status()++ def list_media_items(self) -> list[dict[str, Any]]:+ return self._graph().list_media_items()++ def media_items_by_paths(self, paths: list[str]) -> list[dict[str, Any]]:+ return self._graph().media_items_by_paths(paths)++ def media_thumbs(self, entity_ids: list[str]) -> dict[str, str]:+ return self._graph().media_thumbs(entity_ids)++ def media_kinds(self, entity_ids: list[str]) -> dict[str, str]:+ return self._graph().media_kinds(entity_ids)++ def media_origins(self, entity_ids: list[str]) -> dict[str, dict[str, str]]:+ return self._graph().media_origins(entity_ids)++ def page_media_items(+ self,+ *,+ q: str | None = None,+ kind: str | None = None,+ category: str | None = None,+ folder: str | None = None,+ gps: bool = False,+ collected_only: bool = False,+ sort: str = "newest",+ direction: str | None = None,+ limit: int = 200,+ offset: int = 0,+ ) -> dict[str, Any]:+ return self._graph().page_media_items(+ q=q,+ kind=kind,+ category=category,+ folder=folder,+ gps=gps,+ collected_only=collected_only,+ sort=sort,+ direction=direction,+ limit=limit,+ offset=offset,+ )++ def get_link(self, link_id: str) -> dict[str, Any] | None:+ return self._graph().get_link(link_id)++ def links_of(self, entity_id: str) -> list[dict[str, Any]]:+ return self._graph().links_of(entity_id)++ def count_dependents(self, *, link_type: str, from_type: str) -> dict[str, int]:+ return self._graph().count_dependents(link_type=link_type, from_type=from_type)++ def count_incident_links(self, *, exclude_types: list[str]) -> dict[str, int]:+ return self._graph().count_incident_links(exclude_types=exclude_types)++ def rank_entities(+ self,+ *,+ limit: int = 200,+ types: list[str] | None = None,+ exclude_types: list[str] | None = None,+ status: EntityStatus | None = None,+ query: str | None = None,+ folder: str | None = None,+ unfiled: bool = False,+ recursive: bool = False,+ attr: str | None = None,+ attr_value: str | None = None,+ linked: str | None = None,+ unlinked_only: bool = False,+ since: str | None = None,+ until: str | None = None,+ filed_by: list[str] | None = None,+ temporal_since: str | None = None,+ temporal_until: str | None = None,+ temporal_categories: list[str] | None = None,+ link_types: list[str] | None = None,+ order: str = "degree",+ ) -> dict[str, Any]:+ return self._graph().rank_entities(+ limit=limit, types=types, exclude_types=exclude_types, status=status,+ query=query, folder=folder, unfiled=unfiled, recursive=recursive,+ attr=attr, attr_value=attr_value, linked=linked, unlinked_only=unlinked_only,+ since=since, until=until, filed_by=filed_by,+ temporal_since=temporal_since, temporal_until=temporal_until,+ temporal_categories=temporal_categories,+ link_types=link_types, order=order,+ )++ def entities_by_ids(self, ids: list[str]) -> list[dict[str, Any]]:+ return self._graph().entities_by_ids(ids)++ def labels_of_type(self, type_: str) -> list[tuple[str, str]]:+ return self._graph().labels_of_type(type_)++ def links_among(+ self, ids: list[str], *, types: list[str] | None = None+ ) -> list[dict[str, Any]]:+ return self._graph().links_among(ids, types=types)++ def links_touching(+ self,+ ids: list[str],+ *,+ types: list[str] | None = None,+ exclude_types: list[str] | None = None,+ end_types: list[str] | None = None,+ ) -> list[dict[str, Any]]:+ return self._graph().links_touching(+ ids, types=types, exclude_types=exclude_types, end_types=end_types+ )++ def degrees_of(+ self,+ ids: list[str],+ *,+ types: list[str] | None = None,+ exclude_types: list[str] | None = None,+ ) -> dict[str, int]:+ return self._graph().degrees_of(ids, types=types, exclude_types=exclude_types)+++ def graph_pins(self, lens: str) -> dict[str, tuple[float, float]]:+ return self._graph().graph_pins(lens)++ def pin_entities(self, lens: str, pins: dict[str, tuple[float, float]]) -> int:+ return self._graph().pin_entities(lens, pins)++ def unpin_entities(self, lens: str, ids: list[str]) -> int:+ return self._graph().unpin_entities(lens, ids)++ def clear_graph_pins(self, lens: str) -> int:+ return self._graph().clear_graph_pins(lens)++ def list_analysis_views(self) -> list[dict[str, Any]]:+ return self._graph().list_analysis_views()++ def get_analysis_view(self, view_id: str) -> dict[str, Any] | None:+ return self._graph().get_analysis_view(view_id)++ def save_analysis_view(self, view: dict[str, Any]) -> dict[str, Any]:+ return self._graph().save_analysis_view(view)++ def remove_analysis_view(self, view_id: str) -> dict[str, Any] | None:+ return self._graph().remove_analysis_view(view_id)++ def reinsert_analysis_views(self, views: list[dict[str, Any]]) -> int:+ return self._graph().reinsert_analysis_views(views)++ def get_entity(self, entity_id: str) -> dict[str, Any] | None:+ return self._graph().get_entity(entity_id)++ def note_ids_by_titles(self, titles: set[str]) -> dict[str, list[str]]:+ return self._graph().note_ids_by_titles(titles)++ def entity_count(self) -> int:+ """Entity total for the case switcher — one indexed count."""+ return self._graph().count_entities()++ def save_temporal_claim(+ self,+ *,+ entity_id: str | None,+ label: str,+ attrs: dict[str, Any],+ connectors: dict[str, list[str]] | None,+ by: str,+ status: EntityStatus = "confirmed",+ ) -> dict[str, Any]:+ return self._graph().save_temporal_claim(+ entity_id=entity_id,+ label=label,+ attrs=attrs,+ connectors=connectors,+ by=by,+ status=status,+ )++ def remove_entity(self, entity_id: str) -> None:+ self._graph().remove_entity(entity_id)++ def find_entity(self, *, attr: str, value: Any) -> dict[str, Any] | None:+ return self._graph().find_entity(attr=attr, value=value)++ def add_link(+ self,+ from_id: str,+ to_id: str,+ type_: str,+ *,+ by: str,+ status: EntityStatus = "confirmed",+ unique: bool = False,+ ) -> dict[str, Any]:+ """Add a typed edge. ``unique`` returns the existing identical edge+ instead of stacking a duplicate — what a producer wants when its output+ can dedupe onto an entity that is already in the case."""+ return self._graph().add_link(from_id, to_id, type_, by=by, status=status, unique=unique)++ def sync_links(+ self,+ from_id: str,+ type_: str,+ to_ids: list[str],+ *,+ by: str,+ status: EntityStatus = "confirmed",+ ) -> list[dict[str, Any]]:+ """Make ``from_id``'s outgoing links of ``type_`` exactly ``to_ids``.++ Re-saving an artifact restates its sources rather than piling onto them:+ edges that are still true are left untouched (same id, same timestamp),+ edges that are no longer true are dropped, new ones are appended. Unknown+ targets and a self-reference are ignored.+ """+ return self._graph().sync_links(from_id, type_, to_ids, by=by, status=status)++ def update_link(self, link_id: str, patch: dict[str, Any]) -> dict[str, Any]:+ return self._graph().update_link(link_id, patch)++ def remove_link(self, link_id: str) -> None:+ self._graph().remove_link(link_id)++ def list_folders(self) -> list[str]:+ return self._graph().list_folders()++ def add_folder(self, name: str) -> list[str]:+ return self._graph().add_folder(name)++ def remove_folder(self, name: str) -> list[str]:+ return self._graph().remove_folder(name)++ # -- trash journal (engine/trash.py owns the files) ----------------------++ def add_trash_group(+ self,+ group_id: str,+ *,+ label: str,+ type_: str,+ item_count: int,+ size_bytes: int,+ payload: dict[str, Any],+ state: str = "ready",+ ) -> dict[str, Any]:+ return self._graph().add_trash_group(+ group_id,+ label=label,+ type_=type_,+ item_count=item_count,+ size_bytes=size_bytes,+ payload=payload,+ state=state,+ )++ def update_trash_group(+ self,+ group_id: str,+ *,+ state: str | None = None,+ size_bytes: int | None = None,+ payload: dict[str, Any] | None = None,+ ) -> dict[str, Any]:+ return self._graph().update_trash_group(+ group_id,+ state=state,+ size_bytes=size_bytes,+ payload=payload,+ )++ def list_trash(self) -> list[dict[str, Any]]:+ return self._graph().list_trash()++ def get_trash_group(self, group_id: str) -> dict[str, Any] | None:+ return self._graph().get_trash_group(group_id)++ def list_incomplete_trash(self) -> list[dict[str, Any]]:+ return self._graph().list_incomplete_trash()++ def remove_trash_group(self, group_id: str) -> None:+ self._graph().remove_trash_group(group_id)++ def clear_trash(self) -> list[str]:+ return self._graph().clear_trash()++ def trash_summary(self) -> dict[str, int]:+ return self._graph().trash_summary()++ def reinsert(+ self, entities: list[dict[str, Any]], links: list[dict[str, Any]]+ ) -> dict[str, int]:+ return self._graph().reinsert(entities, links)++ # -- durable jobs (thumbnail and background-job model) -------------------++ def enqueue_job(+ self,+ kind: str,+ *,+ key: str | None = None,+ payload: dict[str, Any] | None = None,+ max_attempts: int = 3,+ ) -> dict[str, Any]:+ return self._graph().enqueue_job(kind, key=key, payload=payload, max_attempts=max_attempts)++ def claim_job(self, *, kinds: list[str] | None = None) -> dict[str, Any] | None:+ return self._graph().claim_job(kinds=kinds)++ def complete_job(self, job_id: str) -> None:+ self._graph().complete_job(job_id)++ def fail_job(self, job_id: str, error: str) -> dict[str, Any]:+ return self._graph().fail_job(job_id, error)++ def cancel_job(self, job_id: str) -> None:+ self._graph().cancel_job(job_id)++ def get_job(self, job_id: str) -> dict[str, Any] | None:+ return self._graph().get_job(job_id)++ def list_jobs(+ self, *, kind: str | None = None, state: str | None = None+ ) -> list[dict[str, Any]]:+ return self._graph().list_jobs(kind=kind, state=state)++ def count_jobs(self, *, kind: str | None = None) -> dict[str, int]:+ return self._graph().count_jobs(kind=kind)++ def recover_jobs(self) -> int:+ return self._graph().recover_jobs()++ def prune_jobs(self, *, kind: str | None = None) -> int:+ return self._graph().prune_jobs(kind=kind)++ def replace_path_references(self, old: str, new: str) -> None:+ self._graph().replace_path_references(old, new)diff --git a/src/azimut/sqlite_backend.py b/src/azimut/sqlite_backend.pyindex 180914f..944b0a4 100644--- a/src/azimut/sqlite_backend.py+++ b/src/azimut/sqlite_backend.py@@ -10,28 +10,61 @@ already bundled by PyInstaller, so this adds no runtime dependency. Anythingbeyond core SQL (FTS5, JSON1, RTree) is per-binary and must be probed at runtimewith a fallback before it enters the contract. Two attribute reads live on thatline: `find_entity` and `attr_facets` scan and match in Python, and the field-filter asks JSON1 through `_has_json1()` with a `LIKE` spelling of the same-question behind it.+filter asks JSON1 through `store.filters._has_json1()` with a `LIKE` spelling of+the same question behind it.++The schema, the connection and `SqliteCase` itself live here. What the class is+built out of — statement shaping, the filter predicates, cursors, the indexed+columns a record carries, the temporal projection and the schema upgrades — lives+in `store/`, one module per concern."""from __future__ import annotationsimport json-import reimport sqlite3-from base64 import urlsafe_b64decode, urlsafe_b64encodefrom contextlib import closing, contextmanagerfrom dataclasses import dataclass, field-from functools import lru_cachefrom pathlib import Pathfrom typing import TYPE_CHECKING, Any, Callable, Iterator, TypeVar-from .engine import entities as entity_enginefrom .engine import links as link_engine-from .engine import mapsitesfrom .engine import timeline as timeline_enginefrom . import layoutfrom .repository import EntityStatus+from .store.cursors import (+ _PAGE_ORDERS,+ _page_cursor,+ _parse_timeline_cursor,+ _parse_timeline_phase,+ _timeline_cursor,+ _timeline_phase_cursor,+)+from .store.filters import (+ MAX_ATTR_VALUES,+ _entity_filters,+ _facet_value,+ _holds_number,+ _link_scope,+ _linked_at_all,+)+from .store.migrations import _SQLITE_MIGRATIONS+from .store.rows import (+ _MADE_HERE_SQL,+ _MEDIA_CATEGORIES,+ _MEDIA_CATEGORY_SQL,+ _entity_search_text,+ _folder_of,+ _normalise_media_item,+ _replace_exact,+)+from .store.sql import _SCOPE, _chunks, _like_contains, _marks, _scope_table+from .store.temporal import (+ _rebuild_temporal_projection_conn,+ _sync_entity_temporal,+ _sync_media_temporal,+ _temporal_projection_status_conn,+)from .workspace import Case, CaseError, _new_id, _now, _parse_cursor, _replace_with_retryif TYPE_CHECKING:@@ -275,1041 +308,6 @@ _JOB_TERMINAL = frozenset({"ready", "failed", "cancelled"})T = TypeVar("T")-def _like_contains(term: str) -> str:- """Wrap a search term for a case-insensitive ``LIKE ? ESCAPE '\\'`` substring- match, escaping the LIKE wildcards so a literal ``%`` or ``_`` matches- itself."""- escaped = term.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")- return f"%{escaped}%"---def _like_prefix(term: str) -> str:- escaped = term.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")- return f"{escaped}%"---#: How many ids one ``IN (…)`` clause carries. SQLite's compiled variable ceiling-#: is 999 on the oldest builds still in the wild, and the widest query here binds-#: an id set twice plus its type filter, so the chunk stays well under a third of-#: it rather than assuming the modern 32 766.-_ID_CHUNK = 250---def _chunks(items: list[str]) -> Iterator[list[str]]:- """Split an id set into runs one SQL statement can bind."""- for start in range(0, len(items), _ID_CHUNK):- yield items[start : start + _ID_CHUNK]---def _marks(values: list[str]) -> str:- return ", ".join("?" * len(values))---#: The temp table an id set is asked through when ``IN (…)`` cannot hold it.-_SCOPE = "scope"---def _scope_table(conn: sqlite3.Connection, ids: list[str]) -> None:- """Put an id set in a temp table, so a query over it binds no ids at all.-- The variable ceiling is what forces `_chunks`, and a chunk is a fine answer for a- question each chunk can settle alone. It is the wrong answer for one that needs- two ids at once: the closed edge set asked every pair of chunks, so a drawing of- 650 nodes cost nine statements and one of 5 000 would cost four hundred — the cost- the node ceiling was hiding rather than removing.-- Handed to SQLite as a table instead, the same question is one statement at any- size, and the join uses the primary key. Temp tables belong to the connection, and- `_connect` opens a fresh one per operation, so this cannot leak into another read;- it is still emptied on the way in, because a helper that is only correct when- nobody calls it twice is a trap for the next caller.- """- conn.execute(- f"CREATE TEMP TABLE IF NOT EXISTS {_SCOPE}(id TEXT PRIMARY KEY) WITHOUT ROWID"- )- conn.execute(f"DELETE FROM {_SCOPE}")- conn.executemany(- f"INSERT OR IGNORE INTO {_SCOPE}(id) VALUES (?)", [(one,) for one in ids]- )---#: How many distinct values a field may hold before a select stops being a way to-#: choose one. Fifty platforms or conditions is a menu; five thousand file paths is a-#: list nobody scrolls, and offering it would be the typed query this app refuses.-MAX_ATTR_VALUES = 50--#: How long a value may be and still be worth offering. A quoted paragraph and a-#: traced footprint are stored values, not choices.-MAX_ATTR_TEXT = 120--#: What an attribute key may be made of. The key reaches SQL inside a JSON path — a-#: string the database parses rather than a bound parameter — so the character set is-#: closed rather than escaped, and anything else is refused rather than quoted.-_ATTR_KEY = re.compile(r"^[A-Za-z0-9_.\-]{1,64}$")---@lru_cache(maxsize=1)-def _has_json1() -> bool:- """Whether this SQLite can read inside a JSON column, probed once.-- The extension set is per-binary and not per-Python (see the module docstring):- `sqlite3` links whatever SQLite the build environment provided, so JSON1 can be- present on a dev machine and missing from a shipped binary. Present, an attribute- filter is an expression the database evaluates against the top-level field;- absent, it is the same question spelled as `LIKE` over the exact text- `json.dumps` wrote — which matches the field at any depth, so a nested object- holding the same key *and* the same value matches too. `tests/test_repository.py`- asserts the probe answers true, so CI proves on all three platforms that the- exact path is the one that ships.- """- conn = sqlite3.connect(":memory:")- try:- conn.execute("SELECT json_extract('{\"a\": 1}', '$.\"a\"')").fetchone()- except sqlite3.Error:- return False- finally:- conn.close()- return True---def _attr_match(key: str, value: str) -> tuple[str, list[Any]]:- """One ``attrs`` field holding one value, as this SQLite can ask it.-- The value is compared **as text**, because text is what a select can offer: the- values come back from the facet read as strings, so `kind` is `video` where- `radius_m` is `100`, and both sides of the control agree on the spelling.- """- if not _ATTR_KEY.match(key):- raise CaseError(f"'{key}' is not a field name")- if _has_json1():- return f"CAST(json_extract(attrs_json, '$.\"{key}\"') AS TEXT) = ?", [value]- # The stored text, as `json.dumps` writes it: `{"kind": "video", "path": "…"}`.- # A value runs up to the next comma or to the closing brace, and the terminator is- # part of the pattern — without it, `"radius_m": 1` also matched 100.- quoted = json.dumps(value, ensure_ascii=False)- patterns = [- _like_contains(f'"{key}": {written}{end}')- for written in (quoted, value)- for end in (",", "}")- ]- joined = " OR ".join("attrs_json LIKE ? ESCAPE '\\'" for _ in patterns)- return f"({joined})", patterns---def _holds_number(key: str) -> str:- """One ``attrs`` field holding a *number*, as this SQLite can ask it.-- Not ``_attr_match``, which compares against a chosen value: here nothing is being- matched, the question is whether a number was written at all. It is what tells a- statement that counts something from one that says *seen, not counted*, and both- spellings have to answer it the same way (module docstring).- """- if not _ATTR_KEY.match(key):- raise CaseError(f"'{key}' is not a field name")- if _has_json1():- return f"json_type(attrs_json, '$.\"{key}\"') IN ('integer', 'real')"- # `json.dumps` writes `{"count": 2}`. GLOB rather than LIKE because a digit has to- # be part of the pattern: `LIKE '%"count": %'` also matches a null and a string.- return f"attrs_json GLOB '*\"{key}\": [0-9]*'"---def _facet_value(value: Any) -> str | None:- """One stored value as a menu can offer it, or None when it cannot.-- The spelling has to match what the filter compares against, since one is the menu- and the other is the question it asks: a number reads as its own digits either- side. Booleans are refused because the two sides would not agree — SQLite casts- `true` to `1` where Python writes `True` — and no field in the vocabulary holds- one.- """- if isinstance(value, bool) or value is None or isinstance(value, (dict, list)):- return None- if isinstance(value, (int, float)):- return str(value)- if not isinstance(value, str) or not value or len(value) > MAX_ATTR_TEXT:- return None- return value---def _linked_to(type_: str, alias: str) -> tuple[str, list[Any]]:- """Whether one hop from this entity reaches an entity of that type.-- *Which videos have coordinates* is this test and nothing else, and until now it- could not be asked anywhere in the app: a case could show every video and every- place, and never the one set that is both. Undirected, because "linked to a place"- is a question about the pair rather than about which end states the verb.- """- return (- " EXISTS (SELECT 1 FROM links l JOIN entities far"- f" ON far.id = (CASE WHEN l.from_id = {alias}.id THEN l.to_id ELSE l.from_id END)"- f" WHERE (l.from_id = {alias}.id OR l.to_id = {alias}.id) AND far.type = ?)",- [type_],- )---def _linked_at_all(alias: str) -> str:- """Whether anything at all links this entity to the rest of the case.-- The complement of ``_linked_to`` with the type dropped, and the one question the- catalog could not ask: *what have I filed and never connected to anything.* The- graph counts that set — it is a case's unexploited material — but counting is not- reaching it, and until this existed the only way to a list was to read the drawing- for dots with no line on them.- """- return (- f" EXISTS (SELECT 1 FROM links l WHERE l.from_id = {alias}.id"- f" OR l.to_id = {alias}.id)"- )---#: The character that sorts after every other, appended to an inclusive upper bound.-#: ``prov_at`` holds a full ISO instant and a date range is asked in days, so-#: ``until='2026-08-10'`` has to reach the whole of that day rather than stopping at-#: its first microsecond. Lexicographic order is what ISO-8601 guarantees, so a-#: sentinel above every timestamp starting with that date is the exact bound.-_AFTER_ALL = ""--#: How a catalog page may be ordered, beyond the insertion order it defaults to.-#:-#: Each entry is ``(sort expression, the column its key is read from, descending)``,-#: and a leading ``-`` spells the descending reading of the same key. Insertion order-#: is deliberately absent: it is the rowid keyset the cursor has always been, and it-#: stays the default because a page that never reorders is what makes a background-#: import safe to scroll past.-#:-#: **Each ordering pages on its own key plus the rowid.** An offset would skip a row-#: whenever one was deleted between two pages, and a key on its own ties — a hundred-#: entities filed in the same second, or two people with one name — so the rowid-#: breaks it. That is what makes "newest first" an answer about the case rather than-#: about the hundred rows a table happened to have loaded.-_PAGE_ORDERS: dict[str, tuple[str, str, bool]] = {- "label": ("label COLLATE NOCASE", "label", False),- "-label": ("label COLLATE NOCASE", "label", True),- "created": ("prov_at", "prov_at", False),- "-created": ("prov_at", "prov_at", True),-}---def _page_cursor(cursor: str) -> tuple[int, str]:- """An ordered page's cursor: the rowid it stopped on, and that row's sort key.-- Spelled ``<rowid>:<key>`` because the rowid is an integer and cannot hold the- separator, so the key takes the whole of the rest verbatim — a label with a colon- in it round-trips unharmed. Insertion order keeps the bare rowid it has always- used: it needs no second key, and every client that already round-trips one of- those is unaffected.- """- seat, separator, key = cursor.partition(":")- if not separator:- raise CaseError(f"invalid cursor '{cursor}'")- return _parse_cursor(seat), key---def _entity_filters(- *,- types: list[str] | None = None,- exclude_types: list[str] | None = None,- status: str | None = None,- query: str | None = None,- folder: str | None = None,- unfiled: bool = False,- recursive: bool = False,- attr: str | None = None,- attr_value: str | None = None,- linked: str | None = None,- unlinked: bool = False,- since: str | None = None,- until: str | None = None,- filed_by: list[str] | None = None,- temporal_since: str | None = None,- temporal_until: str | None = None,- temporal_categories: list[str] | None = None,- alias: str = "entities",-) -> tuple[str, list[Any]]:- """The shared ``WHERE`` over entities: type set, review status, folder, search.-- One predicate for the board's page and the graph's ranking, so a filter can- never mean two things depending on which view asked.-- ``types`` and ``exclude_types`` are two different questions and compose rather- than replace each other: the first is the narrowing a caller asked for, the second- is the set a graph lens does not draw at all (``engine/graph.py``). Stated as an- exclusion because a free-typed entity — one the vocabulary has never heard of —- has no role either, and an allowlist resolved from the registry would drop it.-- ``attr``/``attr_value`` narrow on one stored field, and ``linked`` on having a- neighbour of a type. Together with the type set they are the sentence *media,- kind video, linked to a place* — every term chosen from what the case holds, none- of it typed as syntax (SPEC anti-goals). ``alias`` names the entity table in the- statement being built, because the one-hop test has to correlate to the outer row- and the two callers spell that table differently.-- ``unlinked`` is that sentence's other half — *connected to nothing* — and- ``since``/``until``/``filed_by`` are the three terms about how a row got here- rather than about what it says: when it was filed, and by which tool or by hand.- Every one of them reads a column the entity already carries, so none of them costs- a scan the other terms were not already paying for.- """- where: list[str] = []- params: list[Any] = []- if types:- where.append(f"type IN ({_marks(types)})")- params.extend(types)- if exclude_types:- where.append(f"type NOT IN ({_marks(exclude_types)})")- params.extend(exclude_types)- if status is not None:- where.append("prov_status = ?")- params.append(status)- if unfiled:- where.append("folder IS NULL")- elif folder is not None:- if recursive:- where.append("(folder = ? OR folder LIKE ? ESCAPE '\\')")- params.extend((folder, _like_prefix(folder + "/")))- else:- where.append("folder = ?")- params.append(folder)- for term in (query or "").casefold().split():- where.append("search_text LIKE ? ESCAPE '\\'")- params.append(_like_contains(term))- # A field with no value chosen is not a term: it is the analyst having picked which- # field they are about to ask about, and answering it as "holds nothing" would empty- # the table between two clicks of one act.- if attr and attr_value is not None:- clause, bound = _attr_match(attr, attr_value)- where.append(clause)- params.extend(bound)- if linked:- clause, bound = _linked_to(linked, alias)- where.append(clause)- params.extend(bound)- if unlinked:- where.append(f" NOT{_linked_at_all(alias)}")- if since:- where.append("prov_at >= ?")- params.append(since)- if until:- where.append("prov_at <= ?")- params.append(until + _AFTER_ALL)- if filed_by:- where.append(f"prov_by IN ({_marks(filed_by)})")- params.extend(filed_by)- if temporal_since is not None or temporal_until is not None:- if temporal_since is None or temporal_until is None:- raise CaseError("a temporal filter needs both boundaries")- categories = list(dict.fromkeys(- temporal_categories or list(timeline_engine.DEFAULT_CATEGORIES)- ))- invalid = sorted(set(categories) - set(timeline_engine.ALL_CATEGORIES))- if invalid:- raise CaseError(f"unknown timeline category '{invalid[0]}'")- if not categories:- raise CaseError("a temporal filter needs a category")- where.append(- "EXISTS (SELECT 1 FROM temporal_items temporal_match"- " WHERE temporal_match.earliest IS NOT NULL"- " AND temporal_match.latest > ? AND temporal_match.earliest < ?"- f" AND temporal_match.category IN ({_marks(categories)})"- f" AND (temporal_match.owner_id = {alias}.id OR EXISTS ("- "SELECT 1 FROM links temporal_scope"- " WHERE temporal_scope.from_id = temporal_match.owner_id"- f" AND temporal_scope.to_id = {alias}.id"- " AND temporal_scope.type IN ('about', 'at', 'cites'))))"- )- params.extend((temporal_since, temporal_until, *categories))- return ((" WHERE " + " AND ".join(where)) if where else "", params)---def _link_scope(- types: list[str] | None = None,- *,- ends_out: list[str] | None = None,- ends_in: list[str] | None = None,-) -> tuple[str, list[Any]]:- """One lens's edges: its verbs, and which types may stand at an end.-- Every half comes from the same reading (``engine/graph.py``). ``ends_out`` is what- keeps a **degree** honest now that a lens narrows nodes as well as verbs: counted- over every edge, a media whose only connections are to notes would read as- connected in a reading that draws neither the notes nor the edges to them, and the- control offering to open it could only ever appear to do nothing.-- ``ends_in`` is the opposite question, and the one the collapse asks: *which edges- reach a type this reading leaves out.* One end at least is of those types, so paired- with an id set that holds none of them it names the bridge and the node it bridges- to in one row.-- Any half may be empty, which means no narrowing on that axis.- """- where: list[str] = []- params: list[Any] = []- wanted = list(dict.fromkeys(types or []))- if wanted:- where.append(f"type IN ({_marks(wanted)})")- params.extend(wanted)- hidden = list(dict.fromkeys(ends_out or []))- if hidden:- marks = _marks(hidden)- where.append(- f"from_id NOT IN (SELECT id FROM entities WHERE type IN ({marks}))"- f" AND to_id NOT IN (SELECT id FROM entities WHERE type IN ({marks}))"- )- params.extend(hidden * 2)- reached = list(dict.fromkeys(ends_in or []))- if reached:- marks = _marks(reached)- where.append(- f"(from_id IN (SELECT id FROM entities WHERE type IN ({marks}))"- f" OR to_id IN (SELECT id FROM entities WHERE type IN ({marks})))"- )- params.extend(reached * 2)- return ((" WHERE " + " AND ".join(where)) if where else "", params)---def _folder_of(attrs: dict[str, Any] | None) -> str | None:- """The indexed folder value for an entity: its ``attrs.folder`` path, or None- when unfiled — an absent or empty folder both read as unfiled."""- folder = (attrs or {}).get("folder")- return folder or None---def _entity_search_text(type_: str, label: str, attrs: dict[str, Any] | None) -> str:- """What a case search matches an entity against.-- The label, the type, the folder and the notes, plus the type's own declared text- fields (``entities.search_values``): a vehicle is looked for by its plate and a- claim by the words it quotes, and neither was findable while the index stopped- at the notes. Recomputed on every write, and rebuilt for existing rows by the- schema-10 migration.- """- attrs = attrs or {}- fixed = (label, type_, attrs.get("folder"), attrs.get("notes"))- declared = entity_engine.search_values(type_, attrs)- return "\n".join(str(value) for value in (*fixed, *declared) if value).casefold()---def _replace_exact(value: Any, old: str, new: str) -> Any:- """Recursively replace strings equal to ``old``; never edit prose."""- if isinstance(value, str):- return new if value == old else value- if isinstance(value, list):- return [_replace_exact(item, old, new) for item in value]- if isinstance(value, dict):- return {key: _replace_exact(item, old, new) for key, item in value.items()}- return value---_TEMPORAL_COLUMNS = (- "id", "owner_id", "authority", "category", "kind", "raw", "earliest",- "latest", "precision", "shape", "time_role", "uncertain", "approximate",- "zone", "sortable", "status", "confidence", "parse_error",-)---def _write_temporal_rows(- conn: sqlite3.Connection,- owner_id: str,- authority: str,- rows: list[timeline_engine.ProjectionRow],-) -> None:- """Replace one authority's derived rows for one owner."""- conn.execute(- "DELETE FROM temporal_items WHERE owner_id = ? AND authority = ?",- (owner_id, authority),- )- placeholders = ", ".join("?" for _ in _TEMPORAL_COLUMNS)- for row in rows:- record = row.record()- conn.execute(- f"INSERT INTO temporal_items({', '.join(_TEMPORAL_COLUMNS)})"- f" VALUES({placeholders})",- tuple(record[column] for column in _TEMPORAL_COLUMNS),- )---def _entity_for_projection(row: sqlite3.Row) -> dict[str, Any]:- entity: dict[str, Any] = {- "id": row["id"],- "type": row["type"],- "label": row["label"],- "attrs": json.loads(row["attrs_json"]),- "provenance": {- "by": row["prov_by"],- "at": row["prov_at"],- "status": row["prov_status"],- },- }- if row["prov_source"] is not None:- entity["provenance"]["source"] = row["prov_source"]- return entity---def _sync_entity_temporal(conn: sqlite3.Connection, entity: dict[str, Any]) -> None:- _write_temporal_rows(- conn,- str(entity["id"]),- "entity",- timeline_engine.project_entity(entity),- )---def _sync_media_temporal(- conn: sqlite3.Connection, item: dict[str, Any], entity_id: str | None-) -> None:- if not entity_id:- return- # The media browse contract historically permits a row whose optional- # entity id no longer resolves (imports repair that association later).- # Temporal rows do carry a foreign key, so only project an owner that exists.- if conn.execute("SELECT 1 FROM entities WHERE id = ?", (entity_id,)).fetchone() is None:- return- _write_temporal_rows(- conn,- entity_id,- "media",- timeline_engine.project_media(item, entity_id),- )---def _rebuild_temporal_projection_conn(conn: sqlite3.Connection) -> int:- """Rebuild the projection in the caller's transaction, returning its size."""- conn.execute("DELETE FROM temporal_items")- for row in conn.execute("SELECT * FROM entities ORDER BY rowid").fetchall():- _sync_entity_temporal(conn, _entity_for_projection(row))- for row in conn.execute(- "SELECT item_json, entity_id FROM media_items"- " WHERE entity_id IS NOT NULL ORDER BY rowid"- ).fetchall():- _sync_media_temporal(conn, json.loads(row["item_json"]), row["entity_id"])- return int(conn.execute("SELECT COUNT(*) FROM temporal_items").fetchone()[0])---def _temporal_projection_status_conn(conn: sqlite3.Connection) -> dict[str, int | bool]:- """Compare the derived index with graph and media authorities without writing."""- expected: dict[str, tuple[Any, ...]] = {}-- def remember(rows: list[timeline_engine.ProjectionRow]) -> None:- for row in rows:- record = row.record()- expected[row.id] = tuple(- int(record[column])- if column in {"uncertain", "approximate", "sortable"}- else record[column]- for column in _TEMPORAL_COLUMNS- )-- entity_rows = conn.execute("SELECT * FROM entities ORDER BY rowid").fetchall()- entity_ids = {str(row["id"]) for row in entity_rows}- for row in entity_rows:- remember(timeline_engine.project_entity(_entity_for_projection(row)))- for row in conn.execute(- "SELECT item_json, entity_id FROM media_items"- " WHERE entity_id IS NOT NULL ORDER BY rowid"- ).fetchall():- entity_id = str(row["entity_id"])- if entity_id in entity_ids:- remember(timeline_engine.project_media(json.loads(row["item_json"]), entity_id))-- actual = {- str(row["id"]): tuple(row[column] for column in _TEMPORAL_COLUMNS)- for row in conn.execute(- f"SELECT {', '.join(_TEMPORAL_COLUMNS)} FROM temporal_items"- ).fetchall()- }- missing = expected.keys() - actual.keys()- extra = actual.keys() - expected.keys()- changed = {- item_id for item_id in expected.keys() & actual.keys()- if expected[item_id] != actual[item_id]- }- return {- "consistent": not (missing or extra or changed),- "expected": len(expected),- "actual": len(actual),- "missing": len(missing),- "extra": len(extra),- "changed": len(changed),- }---def _timeline_cursor(group: int, stamp: str, item_id: str) -> str:- body = json.dumps([group, stamp, item_id], separators=(",", ":")).encode()- return urlsafe_b64encode(body).decode().rstrip("=")---def _timeline_phase_cursor(stride: int, phase: int) -> str:- body = json.dumps(["phase", stride, phase], separators=(",", ":")).encode()- return urlsafe_b64encode(body).decode().rstrip("=")---def _decode_cursor(cursor: str) -> Any:- padded = cursor + "=" * (-len(cursor) % 4)- return json.loads(urlsafe_b64decode(padded.encode()).decode())---def _parse_timeline_cursor(cursor: str | None) -> tuple[int, str, str] | None:- if cursor is None:- return None- try:- value = _decode_cursor(cursor)- if (- not isinstance(value, list)- or len(value) != 3- or value[0] not in (0, 1)- or not isinstance(value[1], str)- or not isinstance(value[2], str)- ):- raise ValueError- return int(value[0]), value[1], value[2]- except (ValueError, TypeError, UnicodeDecodeError, json.JSONDecodeError):- raise CaseError(f"invalid timeline cursor '{cursor}'") from None---def _parse_timeline_phase(cursor: str | None) -> tuple[int, int] | None:- """Where a spread read resumes: which of ``stride`` interleaved slices is next."""- if cursor is None:- return None- try:- value = _decode_cursor(cursor)- if (- not isinstance(value, list)- or len(value) != 3- or value[0] != "phase"- or any(not isinstance(part, int) or isinstance(part, bool) for part in value[1:])- or not 1 <= value[1] <= 100_000- or not 0 <= value[2] < value[1]- ):- raise ValueError- return int(value[1]), int(value[2])- except (ValueError, TypeError, UnicodeDecodeError, json.JSONDecodeError):- raise CaseError(f"invalid timeline cursor '{cursor}'") from None---def _migrate_1_to_2(conn: sqlite3.Connection) -> None:- """Add the ``folder`` column, backfill it from each entity's ``attrs.folder``- (in Python, no JSON1 dependency), and index it."""- conn.execute("ALTER TABLE entities ADD COLUMN folder TEXT")- for row in conn.execute("SELECT id, attrs_json FROM entities").fetchall():- folder = _folder_of(json.loads(row["attrs_json"]))- if folder is not None:- conn.execute("UPDATE entities SET folder = ? WHERE id = ?", (folder, row["id"]))- conn.execute("CREATE INDEX idx_entities_folder ON entities(folder)")---def _migrate_2_to_3(conn: sqlite3.Connection) -> None:- """Add the durable ``jobs`` table and its indexes (background-job model)."""- conn.execute(- "CREATE TABLE jobs ("- " id TEXT PRIMARY KEY, kind TEXT NOT NULL, job_key TEXT,"- " state TEXT NOT NULL DEFAULT 'queued', attempts INTEGER NOT NULL DEFAULT 0,"- " max_attempts INTEGER NOT NULL DEFAULT 3, payload_json TEXT NOT NULL DEFAULT '{}',"- " error TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL)"- )- conn.execute("CREATE INDEX idx_jobs_state ON jobs(state)")- conn.execute("CREATE UNIQUE INDEX idx_jobs_key ON jobs(kind, job_key) WHERE job_key IS NOT NULL")---def _migrate_3_to_4(conn: sqlite3.Connection) -> None:- """Add the sidecar-derived media browse index.-- Backfilling needs the case directory as well as the database connection, so- ``SqliteCase.open`` performs it after the schema transaction and records a- durable ``media_index_ready`` marker. A crash between the two simply retries- the backfill on the next open.- """- conn.execute("ALTER TABLE entities ADD COLUMN search_text TEXT NOT NULL DEFAULT ''")- for row in conn.execute("SELECT id, type, label, attrs_json FROM entities"):- attrs = json.loads(row["attrs_json"])- conn.execute(- "UPDATE entities SET search_text = ? WHERE id = ?",- (_entity_search_text(row["type"], row["label"], attrs), row["id"]),- )- conn.execute(- "CREATE TABLE media_items ("- " path TEXT PRIMARY KEY, entity_id TEXT UNIQUE, item_json TEXT NOT NULL,"- " filename TEXT NOT NULL, kind TEXT NOT NULL, folder TEXT,"- " name_sort TEXT NOT NULL, size INTEGER NOT NULL DEFAULT 0,"- " added_at TEXT NOT NULL, search_text TEXT NOT NULL,"- " source_type TEXT, source_op TEXT, imagery_mode TEXT)"- )- conn.execute("CREATE INDEX idx_media_kind ON media_items(kind)")- conn.execute("CREATE INDEX idx_media_folder ON media_items(folder)")- conn.execute("CREATE INDEX idx_media_name ON media_items(name_sort)")- conn.execute("CREATE INDEX idx_media_size ON media_items(size)")- conn.execute("CREATE INDEX idx_media_added ON media_items(added_at)")- conn.execute("CREATE INDEX idx_media_source ON media_items(source_type)")---def _migrate_4_to_5(conn: sqlite3.Connection) -> None:- """Add ``media_items.has_gps`` and backfill it from each indexed item.-- The sidecar JSON is already in the row, so this reads no files: a case- enriched before the column existed gains its GPS filter on open, and one that- was never enriched simply has every flag at zero.- """- conn.execute("ALTER TABLE media_items ADD COLUMN has_gps INTEGER NOT NULL DEFAULT 0")- for row in conn.execute("SELECT path, item_json FROM media_items").fetchall():- if _has_gps(json.loads(row["item_json"])):- conn.execute("UPDATE media_items SET has_gps = 1 WHERE path = ?", (row["path"],))- conn.execute("CREATE INDEX idx_media_gps ON media_items(has_gps)")---def _migrate_5_to_6(conn: sqlite3.Connection) -> None:- """Add the ``trash`` journal.-- One row per delete action, not per entity: deleting a video that carries- three Inspect sessions writes a single group that comes back as a whole. The- payload holds the recipe (entities, their incident links, the files moved- aside, the tombstones the delete wrote); the head columns are what the- sidebar node reads, so listing the trash never touches a payload.- """- conn.execute(- "CREATE TABLE trash ("- " id TEXT PRIMARY KEY, deleted_at TEXT NOT NULL, label TEXT NOT NULL,"- " type TEXT NOT NULL, item_count INTEGER NOT NULL DEFAULT 0,"- " size_bytes INTEGER NOT NULL DEFAULT 0,"- " payload_json TEXT NOT NULL DEFAULT '{}')"- )- conn.execute("CREATE INDEX idx_trash_deleted ON trash(deleted_at)")---def _migrate_6_to_7(conn: sqlite3.Connection) -> None:- """Track interrupted delete and restore operations for crash recovery."""- conn.execute("ALTER TABLE trash ADD COLUMN state TEXT NOT NULL DEFAULT 'ready'")---def _migrate_7_to_8(conn: sqlite3.Connection) -> None:- """Let an edge say how sure the analyst is (ONTOLOGY §3).-- Nullable and unset, so every link already in the case reads as "not assessed",- which is the truth about them rather than a level invented on their behalf.- """- conn.execute("ALTER TABLE links ADD COLUMN confidence INTEGER")---def _migrate_8_to_9(conn: sqlite3.Connection) -> None:- """Rebuild every entity's search text so the declared fields are in it.-- The index is a stored column, so widening what goes into it only reaches rows- written afterwards: a case filed last week would keep answering searches from- its label alone. One pass, no shape change.- """- for row in conn.execute("SELECT id, type, label, attrs_json FROM entities").fetchall():- attrs = json.loads(row["attrs_json"])- conn.execute(- "UPDATE entities SET search_text = ? WHERE id = ?",- (_entity_search_text(row["type"], row["label"], attrs), row["id"]),- )---def _migrate_9_to_10(conn: sqlite3.Connection) -> None:- """Let the analyst's own arrangement of the graph survive a reload.-- One row per node *per lens*: a lens draws its own nodes and edges, so it- clusters differently, and a single arrangement would force every reading into- the shape of whichever one it was built in.-- Nothing to backfill: a case opened before this had no way to move a node, so- every node in it is placed by the layout, which is what an empty table says.- """- conn.execute(- "CREATE TABLE graph_pins ("- " entity_id TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE,"- " lens TEXT NOT NULL,"- " x REAL NOT NULL,"- " y REAL NOT NULL,"- " PRIMARY KEY (entity_id, lens)"- ")"- )- conn.execute("CREATE INDEX idx_graph_pins_lens ON graph_pins(lens)")---def _migrate_10_to_11(conn: sqlite3.Connection) -> None:- """Let an edge say what kind of tie it states, where the verb cannot.-- Nothing to backfill and no index: every existing edge is unqualified, which is- what a null column already says, and nothing filters or sorts on this — it is- read with the edge it sits on.- """- conn.execute("ALTER TABLE links ADD COLUMN nature TEXT")---def _migrate_11_to_12(conn: sqlite3.Connection) -> None:- """Add galleries holding private photos or existing Media references."""- conn.execute(- "CREATE TABLE entity_images ("- " entity_id TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE,"- " image_id TEXT NOT NULL,"- " media_id TEXT REFERENCES entities(id) ON DELETE CASCADE,"- " path TEXT,"- " thumbnail TEXT,"- " title TEXT,"- " position INTEGER NOT NULL,"- " is_primary INTEGER NOT NULL DEFAULT 0 CHECK (is_primary IN (0, 1)),"- " PRIMARY KEY (entity_id, image_id),"- " CHECK ((media_id IS NOT NULL AND path IS NULL AND thumbnail IS NULL)"- " OR (media_id IS NULL AND path IS NOT NULL AND thumbnail IS NOT NULL)))"- )- conn.execute("CREATE INDEX idx_entity_images_media ON entity_images(media_id)")- conn.execute(- "CREATE UNIQUE INDEX idx_entity_images_media_once"- " ON entity_images(entity_id, media_id) WHERE media_id IS NOT NULL"- )- conn.execute(- "CREATE UNIQUE INDEX idx_entity_images_path"- " ON entity_images(path) WHERE path IS NOT NULL"- )- conn.execute(- "CREATE UNIQUE INDEX idx_entity_images_primary"- " ON entity_images(entity_id) WHERE is_primary = 1"- )---def _migrate_12_to_13(conn: sqlite3.Connection) -> None:- """Add named analysis readings, empty until the analyst saves one."""- conn.execute(- "CREATE TABLE analysis_views ("- " id TEXT PRIMARY KEY,"- " name TEXT NOT NULL,"- " mode TEXT NOT NULL CHECK (mode IN ('live', 'snapshot')),"- " surface TEXT NOT NULL CHECK ("- "surface IN ('board', 'graph')"- "),"- " spec_json TEXT NOT NULL,"- " snapshot_count INTEGER NOT NULL DEFAULT 0,"- " created_at TEXT NOT NULL,"- " updated_at TEXT NOT NULL"- ")"- )- conn.execute(- "CREATE INDEX idx_analysis_views_updated ON analysis_views(updated_at DESC)"- )---def _migrate_13_to_14(conn: sqlite3.Connection) -> None:- """Index the two columns the catalog orders the whole case by.-- Sorting by identity or by when a row was filed reads the whole filtered set,- not the page — which is the difference between *the newest in this case* and- *the newest of the hundred rows loaded*. Without an index to seek into, every- page of that read scanned the table and sorted it in a temp B-tree, so the- keyset cursor bounded what came back and not what it cost.-- The label index carries `COLLATE NOCASE` because the ordering does: an index- on the bare column sorts by byte and cannot serve the query.- """- conn.execute("CREATE INDEX idx_entities_label ON entities(label COLLATE NOCASE)")- conn.execute("CREATE INDEX idx_entities_filed ON entities(prov_at)")---def _migrate_14_to_15(conn: sqlite3.Connection) -> None:- """Add and backfill the rebuildable Time and Timeline search projection."""- conn.execute(- "CREATE TABLE temporal_items ("- " id TEXT PRIMARY KEY,"- " owner_id TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE,"- " authority TEXT NOT NULL CHECK (authority IN ('entity', 'media')),"- " category TEXT NOT NULL CHECK ("- "category IN ('statement', 'media', 'case_activity')"- "),"- " kind TEXT NOT NULL, raw TEXT, earliest TEXT, latest TEXT, precision TEXT,"- " shape TEXT, time_role TEXT,"- " uncertain INTEGER NOT NULL DEFAULT 0 CHECK (uncertain IN (0, 1)),"- " approximate INTEGER NOT NULL DEFAULT 0 CHECK (approximate IN (0, 1)),"- " zone TEXT, sortable INTEGER NOT NULL DEFAULT 0 CHECK (sortable IN (0, 1)),"- " status TEXT, confidence TEXT, parse_error TEXT"- ")"- )- conn.execute(- "CREATE INDEX idx_temporal_window"- " ON temporal_items(category, earliest, latest)"- )- conn.execute(- "CREATE INDEX idx_temporal_owner ON temporal_items(owner_id, category)"- )- conn.execute("CREATE INDEX idx_temporal_kind ON temporal_items(kind)")- _rebuild_temporal_projection_conn(conn)---def _migrate_15_to_16(conn: sqlite3.Connection) -> None:- """Extend the case-owned Analysis View contract to Timeline readings."""- conn.execute("ALTER TABLE analysis_views RENAME TO analysis_views_legacy")- conn.execute(- "CREATE TABLE analysis_views ("- " id TEXT PRIMARY KEY, name TEXT NOT NULL,"- " mode TEXT NOT NULL CHECK (mode IN ('live', 'snapshot')),"- " surface TEXT NOT NULL CHECK (surface IN ('board', 'graph', 'timeline')),"- " spec_json TEXT NOT NULL, snapshot_count INTEGER NOT NULL DEFAULT 0,"- " created_at TEXT NOT NULL, updated_at TEXT NOT NULL)"- )- # Named, not `SELECT *`: the legacy table's columns are in whatever order its own- # history left them, and a positional copy would silently rotate the last three.- conn.execute(- "INSERT INTO analysis_views"- " (id, name, mode, surface, spec_json, snapshot_count, created_at, updated_at)"- " SELECT id, name, mode, surface, spec_json, snapshot_count, created_at,"- " updated_at FROM analysis_views_legacy"- )- conn.execute("DROP TABLE analysis_views_legacy")- conn.execute(- "CREATE INDEX idx_analysis_views_updated ON analysis_views(updated_at DESC)"- )---def _migrate_16_to_17(conn: sqlite3.Connection) -> None:- """Rewrite temporal bounds to their fixed-width sortable representation."""- _rebuild_temporal_projection_conn(conn)---# from_version -> function(conn) applying the in-place upgrade to from_version + 1.-# The whole chain runs inside one immediate transaction in `SqliteCase._upgrade`,-# which stamps each new schema_version and records each migration as it goes; a-# failure at any step rolls the lot back and the next open replays from where the-# database still says it is. A step only reshapes the db.-_SQLITE_MIGRATIONS: dict[int, Callable[[sqlite3.Connection], None]] = {- 1: _migrate_1_to_2,- 2: _migrate_2_to_3,- 3: _migrate_3_to_4,- 4: _migrate_4_to_5,- 5: _migrate_5_to_6,- 6: _migrate_6_to_7,- 7: _migrate_7_to_8,- 8: _migrate_8_to_9,- 9: _migrate_9_to_10,- 10: _migrate_10_to_11,- 11: _migrate_11_to_12,- 12: _migrate_12_to_13,- 13: _migrate_13_to_14,- 14: _migrate_14_to_15,- 15: _migrate_15_to_16,- 16: _migrate_16_to_17,-}--_MEDIA_CATEGORIES = (- "image",- "video",- "collage",- "satellite",- "upload",- "download",- "other",-)-_SATELLITE_SQL = (- "(COALESCE(source_type, '') = 'satellite' OR "- "(COALESCE(source_type, '') = 'screenshot' AND imagery_mode = 'satellite'))"-)-_MEDIA_CATEGORY_SQL = {- "image": f"(kind = 'image' AND NOT {_SATELLITE_SQL})",- "video": "kind = 'video'",- "collage": "source_op = 'collage'",- "satellite": _SATELLITE_SQL,- # A paste and a drop are one facet: both are material the analyst brought in- # by hand, which is the question this filter asks. They stay two source types- # because only one of them can state where it came from.- "upload": "source_type IN ('upload', 'clipboard')",- "download": "source_type = 'download'",- "other": "kind NOT IN ('image', 'video')",-}--#: Rows the case **made** rather than collected, as one predicate. The set is the-#: relation layer's (`engine/links.py` MADE_HERE), so the list and the graph cannot-#: come to disagree about what a case collected.-_MADE_HERE_SQL = (- "COALESCE(source_type, '') IN ("- + ", ".join(f"'{route}'" for route in link_engine.MADE_HERE)- + ")"-)---def _has_gps(item: dict[str, Any]) -> bool:- """Whether an indexed media item carries a usable position.-- Enrichment writes ``gps`` as ``{lat, lon}`` when a file's own metadata states- one (engine/enrich.py). Anything else — absent, half-filled, non-numeric —- counts as no position, so the filter can never offer a row it cannot place.- """- gps = item.get("gps")- if not isinstance(gps, dict):- return False- try:- float(gps["lat"]), float(gps["lon"])- except (KeyError, TypeError, ValueError):- return False- return True---#: Sidecar fields the browse index deliberately does not mirror. Enrichment's-#: full metadata dumps (engine/enrich.py) are hundreds of rows per file, and this-#: index is read 200 items at a time by the grid and whole by the pickers — one-#: fat field would multiply every one of those responses by ten. They stay in the-#: sidecar, which is the file-level record, and reach the UI one file at a time-#: through ``GET .../media/item``. Parsed facts (``gps``, ``taken_at``,-#: ``dhash``) are small and stay indexed.-_UNINDEXED_MEDIA_FIELDS = ("exif", "video_metadata")---def _normalise_media_item(item: dict[str, Any]) -> tuple[dict[str, Any], tuple[Any, ...]]:- """Return a JSON-safe browse item plus its indexed column values."""- clean = json.loads(json.dumps(item, ensure_ascii=False))- for field_name in _UNINDEXED_MEDIA_FIELDS:- clean.pop(field_name, None)- source = clean.get("source")- if not isinstance(source, dict):- source = {}- clean["source"] = source- if (- source.get("type") == "screenshot"- and "imagery_mode" not in source- and isinstance(source.get("source_url"), str)- ):- parsed = mapsites.parse_map_url(source["source_url"])- if parsed and parsed.get("imagery_mode"):- source = {**source, "imagery_mode": parsed["imagery_mode"]}- clean["source"] = source-- path = str(clean.get("path") or "")- filename = str(clean.get("filename") or Path(path).name)- kind = str(clean.get("kind") or "file")- folder = str(clean.get("folder") or "") or None- title = str(clean.get("title") or "")- notes = str(clean.get("notes") or "")- name_sort = (title or filename).casefold()- try:- size = max(0, int(clean.get("size") or 0))- except (TypeError, ValueError):- size = 0- added_at = str(clean.get("added_at") or "")- search_text = "\n".join(- str(value)- for value in (- filename,- title,- notes,- folder,- source.get("title"),- source.get("uploader"),- source.get("webpage_url") or source.get("url"),- )- if value- ).casefold()- return clean, (- path,- json.dumps(clean, ensure_ascii=False),- filename,- kind,- folder,- name_sort,- size,- added_at,- search_text,- source.get("type"),- source.get("op"),- source.get("imagery_mode"),- int(_has_gps(clean)),- )--def read_meta(db_path: Path) -> dict[str, str]:"""The `meta` table of a case database, without opening the case.diff --git a/src/azimut/store/__init__.py b/src/azimut/store/__init__.pynew file mode 100644index 0000000..7680fda--- /dev/null+++ b/src/azimut/store/__init__.py@@ -0,0 +1,15 @@+"""The pieces `sqlite_backend.SqliteCase` is built out of.++`sqlite_backend` owns the store: the schema, the connection, and the one class+that implements `repository.CaseRepository`. Everything here is what that class+reaches for and nothing more — statement shaping (`sql`), the predicates a case+is narrowed by (`filters`), keyset cursors (`cursors`), the denormalised columns+a record is indexed on (`rows`), the derived temporal projection (`temporal`),+and the versioned schema upgrades (`migrations`).++Split out because they were read far more often than the queries around them: a+LIKE escape, a cursor spelling and a migration step are each answerable on their+own, and none of them needs the class to be understood. Import from the module+that owns a name rather than from here — this package deliberately re-exports+nothing, so there is one place each helper lives.+"""diff --git a/src/azimut/store/cursors.py b/src/azimut/store/cursors.pynew file mode 100644index 0000000..212842a--- /dev/null+++ b/src/azimut/store/cursors.py@@ -0,0 +1,103 @@+"""Keyset cursors, and the orderings they resume.++Every bounded read in the store pages on a key plus a tiebreaker rather than an+offset, so a row deleted between two pages cannot make the next one skip. These+encode and parse the resume points; the queries that use them live with their+domains.+"""++from __future__ import annotations++import json+from base64 import urlsafe_b64decode, urlsafe_b64encode+from typing import Any++from ..workspace import CaseError, _parse_cursor+++#: How a catalog page may be ordered, beyond the insertion order it defaults to.+#:+#: Each entry is ``(sort expression, the column its key is read from, descending)``,+#: and a leading ``-`` spells the descending reading of the same key. Insertion order+#: is deliberately absent: it is the rowid keyset the cursor has always been, and it+#: stays the default because a page that never reorders is what makes a background+#: import safe to scroll past.+#:+#: **Each ordering pages on its own key plus the rowid.** An offset would skip a row+#: whenever one was deleted between two pages, and a key on its own ties — a hundred+#: entities filed in the same second, or two people with one name — so the rowid+#: breaks it. That is what makes "newest first" an answer about the case rather than+#: about the hundred rows a table happened to have loaded.+_PAGE_ORDERS: dict[str, tuple[str, str, bool]] = {+ "label": ("label COLLATE NOCASE", "label", False),+ "-label": ("label COLLATE NOCASE", "label", True),+ "created": ("prov_at", "prov_at", False),+ "-created": ("prov_at", "prov_at", True),+}+++def _page_cursor(cursor: str) -> tuple[int, str]:+ """An ordered page's cursor: the rowid it stopped on, and that row's sort key.++ Spelled ``<rowid>:<key>`` because the rowid is an integer and cannot hold the+ separator, so the key takes the whole of the rest verbatim — a label with a colon+ in it round-trips unharmed. Insertion order keeps the bare rowid it has always+ used: it needs no second key, and every client that already round-trips one of+ those is unaffected.+ """+ seat, separator, key = cursor.partition(":")+ if not separator:+ raise CaseError(f"invalid cursor '{cursor}'")+ return _parse_cursor(seat), key++def _timeline_cursor(group: int, stamp: str, item_id: str) -> str:+ body = json.dumps([group, stamp, item_id], separators=(",", ":")).encode()+ return urlsafe_b64encode(body).decode().rstrip("=")+++def _timeline_phase_cursor(stride: int, phase: int) -> str:+ body = json.dumps(["phase", stride, phase], separators=(",", ":")).encode()+ return urlsafe_b64encode(body).decode().rstrip("=")+++def _decode_cursor(cursor: str) -> Any:+ padded = cursor + "=" * (-len(cursor) % 4)+ return json.loads(urlsafe_b64decode(padded.encode()).decode())+++def _parse_timeline_cursor(cursor: str | None) -> tuple[int, str, str] | None:+ if cursor is None:+ return None+ try:+ value = _decode_cursor(cursor)+ if (+ not isinstance(value, list)+ or len(value) != 3+ or value[0] not in (0, 1)+ or not isinstance(value[1], str)+ or not isinstance(value[2], str)+ ):+ raise ValueError+ return int(value[0]), value[1], value[2]+ except (ValueError, TypeError, UnicodeDecodeError, json.JSONDecodeError):+ raise CaseError(f"invalid timeline cursor '{cursor}'") from None+++def _parse_timeline_phase(cursor: str | None) -> tuple[int, int] | None:+ """Where a spread read resumes: which of ``stride`` interleaved slices is next."""+ if cursor is None:+ return None+ try:+ value = _decode_cursor(cursor)+ if (+ not isinstance(value, list)+ or len(value) != 3+ or value[0] != "phase"+ or any(not isinstance(part, int) or isinstance(part, bool) for part in value[1:])+ or not 1 <= value[1] <= 100_000+ or not 0 <= value[2] < value[1]+ ):+ raise ValueError+ return int(value[1]), int(value[2])+ except (ValueError, TypeError, UnicodeDecodeError, json.JSONDecodeError):+ raise CaseError(f"invalid timeline cursor '{cursor}'") from Nonediff --git a/src/azimut/store/filters.py b/src/azimut/store/filters.pynew file mode 100644index 0000000..b6ab0a5--- /dev/null+++ b/src/azimut/store/filters.py@@ -0,0 +1,317 @@+"""The predicates a case is narrowed by, as SQL.++One `WHERE` for the board's page and the graph's ranking, so a filter can never+mean two things depending on which view asked (`_entity_filters`), plus the+per-field tests it is built from. `_has_json1` is the runtime probe that decides+which spelling of an attribute question this SQLite can answer — see the+`sqlite_backend` module docstring on why the extension set is per-binary.+"""++from __future__ import annotations++import json+import re+import sqlite3+from functools import lru_cache+from typing import Any++from ..engine import timeline as timeline_engine+from ..workspace import CaseError+from .sql import _like_contains, _like_prefix, _marks+++#: How many distinct values a field may hold before a select stops being a way to+#: choose one. Fifty platforms or conditions is a menu; five thousand file paths is a+#: list nobody scrolls, and offering it would be the typed query this app refuses.+MAX_ATTR_VALUES = 50++#: How long a value may be and still be worth offering. A quoted paragraph and a+#: traced footprint are stored values, not choices.+MAX_ATTR_TEXT = 120++#: What an attribute key may be made of. The key reaches SQL inside a JSON path — a+#: string the database parses rather than a bound parameter — so the character set is+#: closed rather than escaped, and anything else is refused rather than quoted.+_ATTR_KEY = re.compile(r"^[A-Za-z0-9_.\-]{1,64}$")+++@lru_cache(maxsize=1)+def _has_json1() -> bool:+ """Whether this SQLite can read inside a JSON column, probed once.++ The extension set is per-binary and not per-Python (see the module docstring):+ `sqlite3` links whatever SQLite the build environment provided, so JSON1 can be+ present on a dev machine and missing from a shipped binary. Present, an attribute+ filter is an expression the database evaluates against the top-level field;+ absent, it is the same question spelled as `LIKE` over the exact text+ `json.dumps` wrote — which matches the field at any depth, so a nested object+ holding the same key *and* the same value matches too. `tests/test_repository.py`+ asserts the probe answers true, so CI proves on all three platforms that the+ exact path is the one that ships.+ """+ conn = sqlite3.connect(":memory:")+ try:+ conn.execute("SELECT json_extract('{\"a\": 1}', '$.\"a\"')").fetchone()+ except sqlite3.Error:+ return False+ finally:+ conn.close()+ return True+++def _attr_match(key: str, value: str) -> tuple[str, list[Any]]:+ """One ``attrs`` field holding one value, as this SQLite can ask it.++ The value is compared **as text**, because text is what a select can offer: the+ values come back from the facet read as strings, so `kind` is `video` where+ `radius_m` is `100`, and both sides of the control agree on the spelling.+ """+ if not _ATTR_KEY.match(key):+ raise CaseError(f"'{key}' is not a field name")+ if _has_json1():+ return f"CAST(json_extract(attrs_json, '$.\"{key}\"') AS TEXT) = ?", [value]+ # The stored text, as `json.dumps` writes it: `{"kind": "video", "path": "…"}`.+ # A value runs up to the next comma or to the closing brace, and the terminator is+ # part of the pattern — without it, `"radius_m": 1` also matched 100.+ quoted = json.dumps(value, ensure_ascii=False)+ patterns = [+ _like_contains(f'"{key}": {written}{end}')+ for written in (quoted, value)+ for end in (",", "}")+ ]+ joined = " OR ".join("attrs_json LIKE ? ESCAPE '\\'" for _ in patterns)+ return f"({joined})", patterns+++def _holds_number(key: str) -> str:+ """One ``attrs`` field holding a *number*, as this SQLite can ask it.++ Not ``_attr_match``, which compares against a chosen value: here nothing is being+ matched, the question is whether a number was written at all. It is what tells a+ statement that counts something from one that says *seen, not counted*, and both+ spellings have to answer it the same way (module docstring).+ """+ if not _ATTR_KEY.match(key):+ raise CaseError(f"'{key}' is not a field name")+ if _has_json1():+ return f"json_type(attrs_json, '$.\"{key}\"') IN ('integer', 'real')"+ # `json.dumps` writes `{"count": 2}`. GLOB rather than LIKE because a digit has to+ # be part of the pattern: `LIKE '%"count": %'` also matches a null and a string.+ return f"attrs_json GLOB '*\"{key}\": [0-9]*'"+++def _facet_value(value: Any) -> str | None:+ """One stored value as a menu can offer it, or None when it cannot.++ The spelling has to match what the filter compares against, since one is the menu+ and the other is the question it asks: a number reads as its own digits either+ side. Booleans are refused because the two sides would not agree — SQLite casts+ `true` to `1` where Python writes `True` — and no field in the vocabulary holds+ one.+ """+ if isinstance(value, bool) or value is None or isinstance(value, (dict, list)):+ return None+ if isinstance(value, (int, float)):+ return str(value)+ if not isinstance(value, str) or not value or len(value) > MAX_ATTR_TEXT:+ return None+ return value+++def _linked_to(type_: str, alias: str) -> tuple[str, list[Any]]:+ """Whether one hop from this entity reaches an entity of that type.++ *Which videos have coordinates* is this test and nothing else, and until now it+ could not be asked anywhere in the app: a case could show every video and every+ place, and never the one set that is both. Undirected, because "linked to a place"+ is a question about the pair rather than about which end states the verb.+ """+ return (+ " EXISTS (SELECT 1 FROM links l JOIN entities far"+ f" ON far.id = (CASE WHEN l.from_id = {alias}.id THEN l.to_id ELSE l.from_id END)"+ f" WHERE (l.from_id = {alias}.id OR l.to_id = {alias}.id) AND far.type = ?)",+ [type_],+ )+++def _linked_at_all(alias: str) -> str:+ """Whether anything at all links this entity to the rest of the case.++ The complement of ``_linked_to`` with the type dropped, and the one question the+ catalog could not ask: *what have I filed and never connected to anything.* The+ graph counts that set — it is a case's unexploited material — but counting is not+ reaching it, and until this existed the only way to a list was to read the drawing+ for dots with no line on them.+ """+ return (+ f" EXISTS (SELECT 1 FROM links l WHERE l.from_id = {alias}.id"+ f" OR l.to_id = {alias}.id)"+ )++#: The character that sorts after every other, appended to an inclusive upper bound.+#: ``prov_at`` holds a full ISO instant and a date range is asked in days, so+#: ``until='2026-08-10'`` has to reach the whole of that day rather than stopping at+#: its first microsecond. Lexicographic order is what ISO-8601 guarantees, so a+#: sentinel above every timestamp starting with that date is the exact bound.+_AFTER_ALL = ""++def _entity_filters(+ *,+ types: list[str] | None = None,+ exclude_types: list[str] | None = None,+ status: str | None = None,+ query: str | None = None,+ folder: str | None = None,+ unfiled: bool = False,+ recursive: bool = False,+ attr: str | None = None,+ attr_value: str | None = None,+ linked: str | None = None,+ unlinked: bool = False,+ since: str | None = None,+ until: str | None = None,+ filed_by: list[str] | None = None,+ temporal_since: str | None = None,+ temporal_until: str | None = None,+ temporal_categories: list[str] | None = None,+ alias: str = "entities",+) -> tuple[str, list[Any]]:+ """The shared ``WHERE`` over entities: type set, review status, folder, search.++ One predicate for the board's page and the graph's ranking, so a filter can+ never mean two things depending on which view asked.++ ``types`` and ``exclude_types`` are two different questions and compose rather+ than replace each other: the first is the narrowing a caller asked for, the second+ is the set a graph lens does not draw at all (``engine/graph.py``). Stated as an+ exclusion because a free-typed entity — one the vocabulary has never heard of —+ has no role either, and an allowlist resolved from the registry would drop it.++ ``attr``/``attr_value`` narrow on one stored field, and ``linked`` on having a+ neighbour of a type. Together with the type set they are the sentence *media,+ kind video, linked to a place* — every term chosen from what the case holds, none+ of it typed as syntax (SPEC anti-goals). ``alias`` names the entity table in the+ statement being built, because the one-hop test has to correlate to the outer row+ and the two callers spell that table differently.++ ``unlinked`` is that sentence's other half — *connected to nothing* — and+ ``since``/``until``/``filed_by`` are the three terms about how a row got here+ rather than about what it says: when it was filed, and by which tool or by hand.+ Every one of them reads a column the entity already carries, so none of them costs+ a scan the other terms were not already paying for.+ """+ where: list[str] = []+ params: list[Any] = []+ if types:+ where.append(f"type IN ({_marks(types)})")+ params.extend(types)+ if exclude_types:+ where.append(f"type NOT IN ({_marks(exclude_types)})")+ params.extend(exclude_types)+ if status is not None:+ where.append("prov_status = ?")+ params.append(status)+ if unfiled:+ where.append("folder IS NULL")+ elif folder is not None:+ if recursive:+ where.append("(folder = ? OR folder LIKE ? ESCAPE '\\')")+ params.extend((folder, _like_prefix(folder + "/")))+ else:+ where.append("folder = ?")+ params.append(folder)+ for term in (query or "").casefold().split():+ where.append("search_text LIKE ? ESCAPE '\\'")+ params.append(_like_contains(term))+ # A field with no value chosen is not a term: it is the analyst having picked which+ # field they are about to ask about, and answering it as "holds nothing" would empty+ # the table between two clicks of one act.+ if attr and attr_value is not None:+ clause, bound = _attr_match(attr, attr_value)+ where.append(clause)+ params.extend(bound)+ if linked:+ clause, bound = _linked_to(linked, alias)+ where.append(clause)+ params.extend(bound)+ if unlinked:+ where.append(f" NOT{_linked_at_all(alias)}")+ if since:+ where.append("prov_at >= ?")+ params.append(since)+ if until:+ where.append("prov_at <= ?")+ params.append(until + _AFTER_ALL)+ if filed_by:+ where.append(f"prov_by IN ({_marks(filed_by)})")+ params.extend(filed_by)+ if temporal_since is not None or temporal_until is not None:+ if temporal_since is None or temporal_until is None:+ raise CaseError("a temporal filter needs both boundaries")+ categories = list(dict.fromkeys(+ temporal_categories or list(timeline_engine.DEFAULT_CATEGORIES)+ ))+ invalid = sorted(set(categories) - set(timeline_engine.ALL_CATEGORIES))+ if invalid:+ raise CaseError(f"unknown timeline category '{invalid[0]}'")+ if not categories:+ raise CaseError("a temporal filter needs a category")+ where.append(+ "EXISTS (SELECT 1 FROM temporal_items temporal_match"+ " WHERE temporal_match.earliest IS NOT NULL"+ " AND temporal_match.latest > ? AND temporal_match.earliest < ?"+ f" AND temporal_match.category IN ({_marks(categories)})"+ f" AND (temporal_match.owner_id = {alias}.id OR EXISTS ("+ "SELECT 1 FROM links temporal_scope"+ " WHERE temporal_scope.from_id = temporal_match.owner_id"+ f" AND temporal_scope.to_id = {alias}.id"+ " AND temporal_scope.type IN ('about', 'at', 'cites'))))"+ )+ params.extend((temporal_since, temporal_until, *categories))+ return ((" WHERE " + " AND ".join(where)) if where else "", params)+++def _link_scope(+ types: list[str] | None = None,+ *,+ ends_out: list[str] | None = None,+ ends_in: list[str] | None = None,+) -> tuple[str, list[Any]]:+ """One lens's edges: its verbs, and which types may stand at an end.++ Every half comes from the same reading (``engine/graph.py``). ``ends_out`` is what+ keeps a **degree** honest now that a lens narrows nodes as well as verbs: counted+ over every edge, a media whose only connections are to notes would read as+ connected in a reading that draws neither the notes nor the edges to them, and the+ control offering to open it could only ever appear to do nothing.++ ``ends_in`` is the opposite question, and the one the collapse asks: *which edges+ reach a type this reading leaves out.* One end at least is of those types, so paired+ with an id set that holds none of them it names the bridge and the node it bridges+ to in one row.++ Any half may be empty, which means no narrowing on that axis.+ """+ where: list[str] = []+ params: list[Any] = []+ wanted = list(dict.fromkeys(types or []))+ if wanted:+ where.append(f"type IN ({_marks(wanted)})")+ params.extend(wanted)+ hidden = list(dict.fromkeys(ends_out or []))+ if hidden:+ marks = _marks(hidden)+ where.append(+ f"from_id NOT IN (SELECT id FROM entities WHERE type IN ({marks}))"+ f" AND to_id NOT IN (SELECT id FROM entities WHERE type IN ({marks}))"+ )+ params.extend(hidden * 2)+ reached = list(dict.fromkeys(ends_in or []))+ if reached:+ marks = _marks(reached)+ where.append(+ f"(from_id IN (SELECT id FROM entities WHERE type IN ({marks}))"+ f" OR to_id IN (SELECT id FROM entities WHERE type IN ({marks})))"+ )+ params.extend(reached * 2)+ return ((" WHERE " + " AND ".join(where)) if where else "", params)diff --git a/src/azimut/store/migrations.py b/src/azimut/store/migrations.pynew file mode 100644index 0000000..dd1b373--- /dev/null+++ b/src/azimut/store/migrations.py@@ -0,0 +1,318 @@+"""In-place schema upgrades for `case.db`, one step per version.++The whole chain runs inside one immediate transaction in `SqliteCase._upgrade`,+which stamps each new schema version and records each migration as it goes. A+failure at any step rolls the lot back and the next open replays from where the+database still says it is. A step only ever reshapes the db: anything needing the+case directory as well is done by the caller after the transaction.+"""++from __future__ import annotations++import json+import sqlite3+from typing import Callable++from .rows import _entity_search_text, _folder_of, _has_gps+from .temporal import _rebuild_temporal_projection_conn+++def _migrate_1_to_2(conn: sqlite3.Connection) -> None:+ """Add the ``folder`` column, backfill it from each entity's ``attrs.folder``+ (in Python, no JSON1 dependency), and index it."""+ conn.execute("ALTER TABLE entities ADD COLUMN folder TEXT")+ for row in conn.execute("SELECT id, attrs_json FROM entities").fetchall():+ folder = _folder_of(json.loads(row["attrs_json"]))+ if folder is not None:+ conn.execute("UPDATE entities SET folder = ? WHERE id = ?", (folder, row["id"]))+ conn.execute("CREATE INDEX idx_entities_folder ON entities(folder)")+++def _migrate_2_to_3(conn: sqlite3.Connection) -> None:+ """Add the durable ``jobs`` table and its indexes (background-job model)."""+ conn.execute(+ "CREATE TABLE jobs ("+ " id TEXT PRIMARY KEY, kind TEXT NOT NULL, job_key TEXT,"+ " state TEXT NOT NULL DEFAULT 'queued', attempts INTEGER NOT NULL DEFAULT 0,"+ " max_attempts INTEGER NOT NULL DEFAULT 3, payload_json TEXT NOT NULL DEFAULT '{}',"+ " error TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL)"+ )+ conn.execute("CREATE INDEX idx_jobs_state ON jobs(state)")+ conn.execute("CREATE UNIQUE INDEX idx_jobs_key ON jobs(kind, job_key) WHERE job_key IS NOT NULL")+++def _migrate_3_to_4(conn: sqlite3.Connection) -> None:+ """Add the sidecar-derived media browse index.++ Backfilling needs the case directory as well as the database connection, so+ ``SqliteCase.open`` performs it after the schema transaction and records a+ durable ``media_index_ready`` marker. A crash between the two simply retries+ the backfill on the next open.+ """+ conn.execute("ALTER TABLE entities ADD COLUMN search_text TEXT NOT NULL DEFAULT ''")+ for row in conn.execute("SELECT id, type, label, attrs_json FROM entities"):+ attrs = json.loads(row["attrs_json"])+ conn.execute(+ "UPDATE entities SET search_text = ? WHERE id = ?",+ (_entity_search_text(row["type"], row["label"], attrs), row["id"]),+ )+ conn.execute(+ "CREATE TABLE media_items ("+ " path TEXT PRIMARY KEY, entity_id TEXT UNIQUE, item_json TEXT NOT NULL,"+ " filename TEXT NOT NULL, kind TEXT NOT NULL, folder TEXT,"+ " name_sort TEXT NOT NULL, size INTEGER NOT NULL DEFAULT 0,"+ " added_at TEXT NOT NULL, search_text TEXT NOT NULL,"+ " source_type TEXT, source_op TEXT, imagery_mode TEXT)"+ )+ conn.execute("CREATE INDEX idx_media_kind ON media_items(kind)")+ conn.execute("CREATE INDEX idx_media_folder ON media_items(folder)")+ conn.execute("CREATE INDEX idx_media_name ON media_items(name_sort)")+ conn.execute("CREATE INDEX idx_media_size ON media_items(size)")+ conn.execute("CREATE INDEX idx_media_added ON media_items(added_at)")+ conn.execute("CREATE INDEX idx_media_source ON media_items(source_type)")+++def _migrate_4_to_5(conn: sqlite3.Connection) -> None:+ """Add ``media_items.has_gps`` and backfill it from each indexed item.++ The sidecar JSON is already in the row, so this reads no files: a case+ enriched before the column existed gains its GPS filter on open, and one that+ was never enriched simply has every flag at zero.+ """+ conn.execute("ALTER TABLE media_items ADD COLUMN has_gps INTEGER NOT NULL DEFAULT 0")+ for row in conn.execute("SELECT path, item_json FROM media_items").fetchall():+ if _has_gps(json.loads(row["item_json"])):+ conn.execute("UPDATE media_items SET has_gps = 1 WHERE path = ?", (row["path"],))+ conn.execute("CREATE INDEX idx_media_gps ON media_items(has_gps)")+++def _migrate_5_to_6(conn: sqlite3.Connection) -> None:+ """Add the ``trash`` journal.++ One row per delete action, not per entity: deleting a video that carries+ three Inspect sessions writes a single group that comes back as a whole. The+ payload holds the recipe (entities, their incident links, the files moved+ aside, the tombstones the delete wrote); the head columns are what the+ sidebar node reads, so listing the trash never touches a payload.+ """+ conn.execute(+ "CREATE TABLE trash ("+ " id TEXT PRIMARY KEY, deleted_at TEXT NOT NULL, label TEXT NOT NULL,"+ " type TEXT NOT NULL, item_count INTEGER NOT NULL DEFAULT 0,"+ " size_bytes INTEGER NOT NULL DEFAULT 0,"+ " payload_json TEXT NOT NULL DEFAULT '{}')"+ )+ conn.execute("CREATE INDEX idx_trash_deleted ON trash(deleted_at)")+++def _migrate_6_to_7(conn: sqlite3.Connection) -> None:+ """Track interrupted delete and restore operations for crash recovery."""+ conn.execute("ALTER TABLE trash ADD COLUMN state TEXT NOT NULL DEFAULT 'ready'")+++def _migrate_7_to_8(conn: sqlite3.Connection) -> None:+ """Let an edge say how sure the analyst is (ONTOLOGY §3).++ Nullable and unset, so every link already in the case reads as "not assessed",+ which is the truth about them rather than a level invented on their behalf.+ """+ conn.execute("ALTER TABLE links ADD COLUMN confidence INTEGER")+++def _migrate_8_to_9(conn: sqlite3.Connection) -> None:+ """Rebuild every entity's search text so the declared fields are in it.++ The index is a stored column, so widening what goes into it only reaches rows+ written afterwards: a case filed last week would keep answering searches from+ its label alone. One pass, no shape change.+ """+ for row in conn.execute("SELECT id, type, label, attrs_json FROM entities").fetchall():+ attrs = json.loads(row["attrs_json"])+ conn.execute(+ "UPDATE entities SET search_text = ? WHERE id = ?",+ (_entity_search_text(row["type"], row["label"], attrs), row["id"]),+ )+++def _migrate_9_to_10(conn: sqlite3.Connection) -> None:+ """Let the analyst's own arrangement of the graph survive a reload.++ One row per node *per lens*: a lens draws its own nodes and edges, so it+ clusters differently, and a single arrangement would force every reading into+ the shape of whichever one it was built in.++ Nothing to backfill: a case opened before this had no way to move a node, so+ every node in it is placed by the layout, which is what an empty table says.+ """+ conn.execute(+ "CREATE TABLE graph_pins ("+ " entity_id TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE,"+ " lens TEXT NOT NULL,"+ " x REAL NOT NULL,"+ " y REAL NOT NULL,"+ " PRIMARY KEY (entity_id, lens)"+ ")"+ )+ conn.execute("CREATE INDEX idx_graph_pins_lens ON graph_pins(lens)")+++def _migrate_10_to_11(conn: sqlite3.Connection) -> None:+ """Let an edge say what kind of tie it states, where the verb cannot.++ Nothing to backfill and no index: every existing edge is unqualified, which is+ what a null column already says, and nothing filters or sorts on this — it is+ read with the edge it sits on.+ """+ conn.execute("ALTER TABLE links ADD COLUMN nature TEXT")+++def _migrate_11_to_12(conn: sqlite3.Connection) -> None:+ """Add galleries holding private photos or existing Media references."""+ conn.execute(+ "CREATE TABLE entity_images ("+ " entity_id TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE,"+ " image_id TEXT NOT NULL,"+ " media_id TEXT REFERENCES entities(id) ON DELETE CASCADE,"+ " path TEXT,"+ " thumbnail TEXT,"+ " title TEXT,"+ " position INTEGER NOT NULL,"+ " is_primary INTEGER NOT NULL DEFAULT 0 CHECK (is_primary IN (0, 1)),"+ " PRIMARY KEY (entity_id, image_id),"+ " CHECK ((media_id IS NOT NULL AND path IS NULL AND thumbnail IS NULL)"+ " OR (media_id IS NULL AND path IS NOT NULL AND thumbnail IS NOT NULL)))"+ )+ conn.execute("CREATE INDEX idx_entity_images_media ON entity_images(media_id)")+ conn.execute(+ "CREATE UNIQUE INDEX idx_entity_images_media_once"+ " ON entity_images(entity_id, media_id) WHERE media_id IS NOT NULL"+ )+ conn.execute(+ "CREATE UNIQUE INDEX idx_entity_images_path"+ " ON entity_images(path) WHERE path IS NOT NULL"+ )+ conn.execute(+ "CREATE UNIQUE INDEX idx_entity_images_primary"+ " ON entity_images(entity_id) WHERE is_primary = 1"+ )+++def _migrate_12_to_13(conn: sqlite3.Connection) -> None:+ """Add named analysis readings, empty until the analyst saves one."""+ conn.execute(+ "CREATE TABLE analysis_views ("+ " id TEXT PRIMARY KEY,"+ " name TEXT NOT NULL,"+ " mode TEXT NOT NULL CHECK (mode IN ('live', 'snapshot')),"+ " surface TEXT NOT NULL CHECK ("+ "surface IN ('board', 'graph')"+ "),"+ " spec_json TEXT NOT NULL,"+ " snapshot_count INTEGER NOT NULL DEFAULT 0,"+ " created_at TEXT NOT NULL,"+ " updated_at TEXT NOT NULL"+ ")"+ )+ conn.execute(+ "CREATE INDEX idx_analysis_views_updated ON analysis_views(updated_at DESC)"+ )+++def _migrate_13_to_14(conn: sqlite3.Connection) -> None:+ """Index the two columns the catalog orders the whole case by.++ Sorting by identity or by when a row was filed reads the whole filtered set,+ not the page — which is the difference between *the newest in this case* and+ *the newest of the hundred rows loaded*. Without an index to seek into, every+ page of that read scanned the table and sorted it in a temp B-tree, so the+ keyset cursor bounded what came back and not what it cost.++ The label index carries `COLLATE NOCASE` because the ordering does: an index+ on the bare column sorts by byte and cannot serve the query.+ """+ conn.execute("CREATE INDEX idx_entities_label ON entities(label COLLATE NOCASE)")+ conn.execute("CREATE INDEX idx_entities_filed ON entities(prov_at)")+++def _migrate_14_to_15(conn: sqlite3.Connection) -> None:+ """Add and backfill the rebuildable Time and Timeline search projection."""+ conn.execute(+ "CREATE TABLE temporal_items ("+ " id TEXT PRIMARY KEY,"+ " owner_id TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE,"+ " authority TEXT NOT NULL CHECK (authority IN ('entity', 'media')),"+ " category TEXT NOT NULL CHECK ("+ "category IN ('statement', 'media', 'case_activity')"+ "),"+ " kind TEXT NOT NULL, raw TEXT, earliest TEXT, latest TEXT, precision TEXT,"+ " shape TEXT, time_role TEXT,"+ " uncertain INTEGER NOT NULL DEFAULT 0 CHECK (uncertain IN (0, 1)),"+ " approximate INTEGER NOT NULL DEFAULT 0 CHECK (approximate IN (0, 1)),"+ " zone TEXT, sortable INTEGER NOT NULL DEFAULT 0 CHECK (sortable IN (0, 1)),"+ " status TEXT, confidence TEXT, parse_error TEXT"+ ")"+ )+ conn.execute(+ "CREATE INDEX idx_temporal_window"+ " ON temporal_items(category, earliest, latest)"+ )+ conn.execute(+ "CREATE INDEX idx_temporal_owner ON temporal_items(owner_id, category)"+ )+ conn.execute("CREATE INDEX idx_temporal_kind ON temporal_items(kind)")+ _rebuild_temporal_projection_conn(conn)+++def _migrate_15_to_16(conn: sqlite3.Connection) -> None:+ """Extend the case-owned Analysis View contract to Timeline readings."""+ conn.execute("ALTER TABLE analysis_views RENAME TO analysis_views_legacy")+ conn.execute(+ "CREATE TABLE analysis_views ("+ " id TEXT PRIMARY KEY, name TEXT NOT NULL,"+ " mode TEXT NOT NULL CHECK (mode IN ('live', 'snapshot')),"+ " surface TEXT NOT NULL CHECK (surface IN ('board', 'graph', 'timeline')),"+ " spec_json TEXT NOT NULL, snapshot_count INTEGER NOT NULL DEFAULT 0,"+ " created_at TEXT NOT NULL, updated_at TEXT NOT NULL)"+ )+ # Named, not `SELECT *`: the legacy table's columns are in whatever order its own+ # history left them, and a positional copy would silently rotate the last three.+ conn.execute(+ "INSERT INTO analysis_views"+ " (id, name, mode, surface, spec_json, snapshot_count, created_at, updated_at)"+ " SELECT id, name, mode, surface, spec_json, snapshot_count, created_at,"+ " updated_at FROM analysis_views_legacy"+ )+ conn.execute("DROP TABLE analysis_views_legacy")+ conn.execute(+ "CREATE INDEX idx_analysis_views_updated ON analysis_views(updated_at DESC)"+ )+++def _migrate_16_to_17(conn: sqlite3.Connection) -> None:+ """Rewrite temporal bounds to their fixed-width sortable representation."""+ _rebuild_temporal_projection_conn(conn)+++# from_version -> function(conn) applying the in-place upgrade to from_version + 1.+# The whole chain runs inside one immediate transaction in `SqliteCase._upgrade`,+# which stamps each new schema_version and records each migration as it goes; a+# failure at any step rolls the lot back and the next open replays from where the+# database still says it is. A step only reshapes the db.+_SQLITE_MIGRATIONS: dict[int, Callable[[sqlite3.Connection], None]] = {+ 1: _migrate_1_to_2,+ 2: _migrate_2_to_3,+ 3: _migrate_3_to_4,+ 4: _migrate_4_to_5,+ 5: _migrate_5_to_6,+ 6: _migrate_6_to_7,+ 7: _migrate_7_to_8,+ 8: _migrate_8_to_9,+ 9: _migrate_9_to_10,+ 10: _migrate_10_to_11,+ 11: _migrate_11_to_12,+ 12: _migrate_12_to_13,+ 13: _migrate_13_to_14,+ 14: _migrate_14_to_15,+ 15: _migrate_15_to_16,+ 16: _migrate_16_to_17,+}diff --git a/src/azimut/store/rows.py b/src/azimut/store/rows.pynew file mode 100644index 0000000..a13c80a--- /dev/null+++ b/src/azimut/store/rows.py@@ -0,0 +1,173 @@+"""Turning a stored record into its indexed columns, and back.++An entity and a media item each reach SQLite as a JSON blob plus the handful of+denormalised columns the catalog filters and sorts on. These compute those+columns, so the write path and the migrations that backfill them cannot come to+disagree about what a column holds.+"""++from __future__ import annotations++import json+from pathlib import Path+from typing import Any++from ..engine import entities as entity_engine+from ..engine import links as link_engine+from ..engine import mapsites+++def _folder_of(attrs: dict[str, Any] | None) -> str | None:+ """The indexed folder value for an entity: its ``attrs.folder`` path, or None+ when unfiled — an absent or empty folder both read as unfiled."""+ folder = (attrs or {}).get("folder")+ return folder or None+++def _entity_search_text(type_: str, label: str, attrs: dict[str, Any] | None) -> str:+ """What a case search matches an entity against.++ The label, the type, the folder and the notes, plus the type's own declared text+ fields (``entities.search_values``): a vehicle is looked for by its plate and a+ claim by the words it quotes, and neither was findable while the index stopped+ at the notes. Recomputed on every write, and rebuilt for existing rows by the+ schema-10 migration.+ """+ attrs = attrs or {}+ fixed = (label, type_, attrs.get("folder"), attrs.get("notes"))+ declared = entity_engine.search_values(type_, attrs)+ return "\n".join(str(value) for value in (*fixed, *declared) if value).casefold()+++def _replace_exact(value: Any, old: str, new: str) -> Any:+ """Recursively replace strings equal to ``old``; never edit prose."""+ if isinstance(value, str):+ return new if value == old else value+ if isinstance(value, list):+ return [_replace_exact(item, old, new) for item in value]+ if isinstance(value, dict):+ return {key: _replace_exact(item, old, new) for key, item in value.items()}+ return value++_MEDIA_CATEGORIES = (+ "image",+ "video",+ "collage",+ "satellite",+ "upload",+ "download",+ "other",+)+_SATELLITE_SQL = (+ "(COALESCE(source_type, '') = 'satellite' OR "+ "(COALESCE(source_type, '') = 'screenshot' AND imagery_mode = 'satellite'))"+)+_MEDIA_CATEGORY_SQL = {+ "image": f"(kind = 'image' AND NOT {_SATELLITE_SQL})",+ "video": "kind = 'video'",+ "collage": "source_op = 'collage'",+ "satellite": _SATELLITE_SQL,+ # A paste and a drop are one facet: both are material the analyst brought in+ # by hand, which is the question this filter asks. They stay two source types+ # because only one of them can state where it came from.+ "upload": "source_type IN ('upload', 'clipboard')",+ "download": "source_type = 'download'",+ "other": "kind NOT IN ('image', 'video')",+}++#: Rows the case **made** rather than collected, as one predicate. The set is the+#: relation layer's (`engine/links.py` MADE_HERE), so the list and the graph cannot+#: come to disagree about what a case collected.+_MADE_HERE_SQL = (+ "COALESCE(source_type, '') IN ("+ + ", ".join(f"'{route}'" for route in link_engine.MADE_HERE)+ + ")"+)+++def _has_gps(item: dict[str, Any]) -> bool:+ """Whether an indexed media item carries a usable position.++ Enrichment writes ``gps`` as ``{lat, lon}`` when a file's own metadata states+ one (engine/enrich.py). Anything else — absent, half-filled, non-numeric —+ counts as no position, so the filter can never offer a row it cannot place.+ """+ gps = item.get("gps")+ if not isinstance(gps, dict):+ return False+ try:+ float(gps["lat"]), float(gps["lon"])+ except (KeyError, TypeError, ValueError):+ return False+ return True+++#: Sidecar fields the browse index deliberately does not mirror. Enrichment's+#: full metadata dumps (engine/enrich.py) are hundreds of rows per file, and this+#: index is read 200 items at a time by the grid and whole by the pickers — one+#: fat field would multiply every one of those responses by ten. They stay in the+#: sidecar, which is the file-level record, and reach the UI one file at a time+#: through ``GET .../media/item``. Parsed facts (``gps``, ``taken_at``,+#: ``dhash``) are small and stay indexed.+_UNINDEXED_MEDIA_FIELDS = ("exif", "video_metadata")+++def _normalise_media_item(item: dict[str, Any]) -> tuple[dict[str, Any], tuple[Any, ...]]:+ """Return a JSON-safe browse item plus its indexed column values."""+ clean = json.loads(json.dumps(item, ensure_ascii=False))+ for field_name in _UNINDEXED_MEDIA_FIELDS:+ clean.pop(field_name, None)+ source = clean.get("source")+ if not isinstance(source, dict):+ source = {}+ clean["source"] = source+ if (+ source.get("type") == "screenshot"+ and "imagery_mode" not in source+ and isinstance(source.get("source_url"), str)+ ):+ parsed = mapsites.parse_map_url(source["source_url"])+ if parsed and parsed.get("imagery_mode"):+ source = {**source, "imagery_mode": parsed["imagery_mode"]}+ clean["source"] = source++ path = str(clean.get("path") or "")+ filename = str(clean.get("filename") or Path(path).name)+ kind = str(clean.get("kind") or "file")+ folder = str(clean.get("folder") or "") or None+ title = str(clean.get("title") or "")+ notes = str(clean.get("notes") or "")+ name_sort = (title or filename).casefold()+ try:+ size = max(0, int(clean.get("size") or 0))+ except (TypeError, ValueError):+ size = 0+ added_at = str(clean.get("added_at") or "")+ search_text = "\n".join(+ str(value)+ for value in (+ filename,+ title,+ notes,+ folder,+ source.get("title"),+ source.get("uploader"),+ source.get("webpage_url") or source.get("url"),+ )+ if value+ ).casefold()+ return clean, (+ path,+ json.dumps(clean, ensure_ascii=False),+ filename,+ kind,+ folder,+ name_sort,+ size,+ added_at,+ search_text,+ source.get("type"),+ source.get("op"),+ source.get("imagery_mode"),+ int(_has_gps(clean)),+ )diff --git a/src/azimut/store/sql.py b/src/azimut/store/sql.pynew file mode 100644index 0000000..bd4cec7--- /dev/null+++ b/src/azimut/store/sql.py@@ -0,0 +1,69 @@+"""Statement-shaping helpers shared by every query in the store.++Nothing here knows what a case is: these turn a Python value into the SQL text+and bound parameters a statement needs. They live apart from the queries so a+wildcard escape or an id-set ceiling is fixed once, for every caller.+"""++from __future__ import annotations++import sqlite3+from typing import Iterator+++def _like_contains(term: str) -> str:+ """Wrap a search term for a case-insensitive ``LIKE ? ESCAPE '\\'`` substring+ match, escaping the LIKE wildcards so a literal ``%`` or ``_`` matches+ itself."""+ escaped = term.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")+ return f"%{escaped}%"+++def _like_prefix(term: str) -> str:+ escaped = term.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")+ return f"{escaped}%"+++#: How many ids one ``IN (…)`` clause carries. SQLite's compiled variable ceiling+#: is 999 on the oldest builds still in the wild, and the widest query here binds+#: an id set twice plus its type filter, so the chunk stays well under a third of+#: it rather than assuming the modern 32 766.+_ID_CHUNK = 250+++def _chunks(items: list[str]) -> Iterator[list[str]]:+ """Split an id set into runs one SQL statement can bind."""+ for start in range(0, len(items), _ID_CHUNK):+ yield items[start : start + _ID_CHUNK]+++def _marks(values: list[str]) -> str:+ return ", ".join("?" * len(values))+++#: The temp table an id set is asked through when ``IN (…)`` cannot hold it.+_SCOPE = "scope"+++def _scope_table(conn: sqlite3.Connection, ids: list[str]) -> None:+ """Put an id set in a temp table, so a query over it binds no ids at all.++ The variable ceiling is what forces `_chunks`, and a chunk is a fine answer for a+ question each chunk can settle alone. It is the wrong answer for one that needs+ two ids at once: the closed edge set asked every pair of chunks, so a drawing of+ 650 nodes cost nine statements and one of 5 000 would cost four hundred — the cost+ the node ceiling was hiding rather than removing.++ Handed to SQLite as a table instead, the same question is one statement at any+ size, and the join uses the primary key. Temp tables belong to the connection, and+ `_connect` opens a fresh one per operation, so this cannot leak into another read;+ it is still emptied on the way in, because a helper that is only correct when+ nobody calls it twice is a trap for the next caller.+ """+ conn.execute(+ f"CREATE TEMP TABLE IF NOT EXISTS {_SCOPE}(id TEXT PRIMARY KEY) WITHOUT ROWID"+ )+ conn.execute(f"DELETE FROM {_SCOPE}")+ conn.executemany(+ f"INSERT OR IGNORE INTO {_SCOPE}(id) VALUES (?)", [(one,) for one in ids]+ )diff --git a/src/azimut/store/temporal.py b/src/azimut/store/temporal.pynew file mode 100644index 0000000..ebb126e--- /dev/null+++ b/src/azimut/store/temporal.py@@ -0,0 +1,147 @@+"""The derived temporal projection, written and checked.++Claims and media sidecars stay authoritative; `temporal_items` is a rebuildable+index over them that Time and Timeline read. These keep it in step with a write+and answer whether it has drifted, both inside the caller's transaction.+"""++from __future__ import annotations++import json+import sqlite3+from typing import Any++from ..engine import timeline as timeline_engine+++_TEMPORAL_COLUMNS = (+ "id", "owner_id", "authority", "category", "kind", "raw", "earliest",+ "latest", "precision", "shape", "time_role", "uncertain", "approximate",+ "zone", "sortable", "status", "confidence", "parse_error",+)+++def _write_temporal_rows(+ conn: sqlite3.Connection,+ owner_id: str,+ authority: str,+ rows: list[timeline_engine.ProjectionRow],+) -> None:+ """Replace one authority's derived rows for one owner."""+ conn.execute(+ "DELETE FROM temporal_items WHERE owner_id = ? AND authority = ?",+ (owner_id, authority),+ )+ placeholders = ", ".join("?" for _ in _TEMPORAL_COLUMNS)+ for row in rows:+ record = row.record()+ conn.execute(+ f"INSERT INTO temporal_items({', '.join(_TEMPORAL_COLUMNS)})"+ f" VALUES({placeholders})",+ tuple(record[column] for column in _TEMPORAL_COLUMNS),+ )+++def _entity_for_projection(row: sqlite3.Row) -> dict[str, Any]:+ entity: dict[str, Any] = {+ "id": row["id"],+ "type": row["type"],+ "label": row["label"],+ "attrs": json.loads(row["attrs_json"]),+ "provenance": {+ "by": row["prov_by"],+ "at": row["prov_at"],+ "status": row["prov_status"],+ },+ }+ if row["prov_source"] is not None:+ entity["provenance"]["source"] = row["prov_source"]+ return entity+++def _sync_entity_temporal(conn: sqlite3.Connection, entity: dict[str, Any]) -> None:+ _write_temporal_rows(+ conn,+ str(entity["id"]),+ "entity",+ timeline_engine.project_entity(entity),+ )+++def _sync_media_temporal(+ conn: sqlite3.Connection, item: dict[str, Any], entity_id: str | None+) -> None:+ if not entity_id:+ return+ # The media browse contract historically permits a row whose optional+ # entity id no longer resolves (imports repair that association later).+ # Temporal rows do carry a foreign key, so only project an owner that exists.+ if conn.execute("SELECT 1 FROM entities WHERE id = ?", (entity_id,)).fetchone() is None:+ return+ _write_temporal_rows(+ conn,+ entity_id,+ "media",+ timeline_engine.project_media(item, entity_id),+ )+++def _rebuild_temporal_projection_conn(conn: sqlite3.Connection) -> int:+ """Rebuild the projection in the caller's transaction, returning its size."""+ conn.execute("DELETE FROM temporal_items")+ for row in conn.execute("SELECT * FROM entities ORDER BY rowid").fetchall():+ _sync_entity_temporal(conn, _entity_for_projection(row))+ for row in conn.execute(+ "SELECT item_json, entity_id FROM media_items"+ " WHERE entity_id IS NOT NULL ORDER BY rowid"+ ).fetchall():+ _sync_media_temporal(conn, json.loads(row["item_json"]), row["entity_id"])+ return int(conn.execute("SELECT COUNT(*) FROM temporal_items").fetchone()[0])+++def _temporal_projection_status_conn(conn: sqlite3.Connection) -> dict[str, int | bool]:+ """Compare the derived index with graph and media authorities without writing."""+ expected: dict[str, tuple[Any, ...]] = {}++ def remember(rows: list[timeline_engine.ProjectionRow]) -> None:+ for row in rows:+ record = row.record()+ expected[row.id] = tuple(+ int(record[column])+ if column in {"uncertain", "approximate", "sortable"}+ else record[column]+ for column in _TEMPORAL_COLUMNS+ )++ entity_rows = conn.execute("SELECT * FROM entities ORDER BY rowid").fetchall()+ entity_ids = {str(row["id"]) for row in entity_rows}+ for row in entity_rows:+ remember(timeline_engine.project_entity(_entity_for_projection(row)))+ for row in conn.execute(+ "SELECT item_json, entity_id FROM media_items"+ " WHERE entity_id IS NOT NULL ORDER BY rowid"+ ).fetchall():+ entity_id = str(row["entity_id"])+ if entity_id in entity_ids:+ remember(timeline_engine.project_media(json.loads(row["item_json"]), entity_id))++ actual = {+ str(row["id"]): tuple(row[column] for column in _TEMPORAL_COLUMNS)+ for row in conn.execute(+ f"SELECT {', '.join(_TEMPORAL_COLUMNS)} FROM temporal_items"+ ).fetchall()+ }+ missing = expected.keys() - actual.keys()+ extra = actual.keys() - expected.keys()+ changed = {+ item_id for item_id in expected.keys() & actual.keys()+ if expected[item_id] != actual[item_id]+ }+ return {+ "consistent": not (missing or extra or changed),+ "expected": len(expected),+ "actual": len(actual),+ "missing": len(missing),+ "extra": len(extra),+ "changed": len(changed),+ }diff --git a/src/azimut/workspace.py b/src/azimut/workspace.pyindex 6ec4af1..f0e6879 100644--- a/src/azimut/workspace.py+++ b/src/azimut/workspace.py@@ -24,6 +24,15 @@ from pathlib import Pathfrom typing import TYPE_CHECKING, Any, Callablefrom . import config, layout+from .caselayout import (+ _follow_hidden_dirs,+ _normalize_case_layout,+ _prune_empty_note_dirs,+ _wrap_case_folder,+ ensure_dir,+ write_readme,+)+from .casestore import CaseStorefrom .layout import MAX_CASE_SLUGfrom .repository import EntityStatus@@ -123,75 +132,6 @@ def _new_id(prefix: str) -> str:return f"{prefix}_{uuid.uuid4().hex[:10]}"-def ensure_dir(path: Path) -> Path:- """``path.mkdir(parents=True, exist_ok=True)``, tolerant of a transient- ``PermissionError`` Windows can raise when several threads race to create- the very same directory for the first time (e.g. several concurrent- downloads all hitting a case's not-yet-created ``media/.dl`` or- ``media/.thumbs`` at once): CreateDirectory there occasionally answers- "access is denied" instead of "already exists" mid-race, which- ``exist_ok=True`` alone does not catch. Retried briefly — the directory- reliably exists by the next attempt, whoever won the race.- """- for attempt in range(20):- try:- path.mkdir(parents=True, exist_ok=True)- _hide_dotted_chain(path)- return path- except PermissionError:- if path.is_dir():- return path- if attempt == 19:- raise- time.sleep(0.01)- return path # pragma: no cover - loop always returns or raises above---def _hide_dotted_chain(path: Path) -> None:- """Hide *path* on Windows, and the dot-directories `parents=True` just made.-- `media/.meta/<proof>.assets` creates `.meta` on the way to a leaf that is- not itself dotted, so hiding the leaf alone would leave the directory that- matters visible. The walk stops at the first ancestor without a leading dot,- which is always the visible half of the case (`media/`, `proofs/`, the tool- root), so it never climbs out of the workspace.- """- current = path- while True:- config.hide_if_dotted(current)- parent = current.parent- if parent == current or not parent.name.startswith("."):- return- current = parent---def _follow_hidden_dirs(root: Path) -> None:- """Put the hidden attribute back on a case's internal directories.-- `.azimut` gets this at every startup (`config.ensure_workspace`); a case only- got it the day it was born, so any copy of a workspace — a move onto another- drive, a folder carried between machines, a backup unpacked — showed the- analyst directories the layout means to keep out of sight.-- Costs nothing off Windows, where `hide_if_dotted` is what returns early: one- guard in one place beats a second copy of the platform test here.- """- for directory in layout.hidden_dirs(root):- config.hide_if_dotted(directory)---def write_readme(root: Path) -> None:- """Leave the note that says which half of the case folder is whose.-- Only when there is none. The file sits in the analyst's half, so once it is- there it is theirs: an edited or deleted README is a choice, not damage, and- rewriting it on every open would undo it.- """- readme = layout.readme(root)- if not readme.exists():- readme.write_text(layout.README_TEXT, encoding="utf-8")--def _replace_with_retry(src: Path, dst: Path) -> None:"""``src.replace(dst)`` with a brief retry for a transient Windows``PermissionError``. The case lock already keeps our own threads off the@@ -231,7 +171,7 @@ def _parse_cursor(cursor: str | None) -> int:raise CaseError(f"invalid cursor '{cursor}'") from None-class Case:+class Case(CaseStore):"""Handle over one case directory.The filesystem shell (manifest, notes, media, lifecycle, path resolution)@@ -239,6 +179,11 @@ class Case:`CaseRepository` contract, delegated to a `SqliteCase` over `case.db`. Alegacy json case (schema ≤ `JSON_SCHEMA`) is converted to sqlite on open(`migrate`), so every live handle is sqlite-backed.++ That delegation is `CaseStore` (`casestore.py`), inherited rather than written+ out here: it is a seam, not behaviour, and the methods that only forward were+ burying the ones that also have a folder to keep in step. What stays below is+ the half that has both."""def __init__(self, path: Path):@@ -269,6 +214,12 @@ class Case:self._sqlite_cache = self._resolve_sqlite()return self._sqlite_cache+ def _forget_store(self) -> None:+ """Drop the cached backend handle so the next graph access re-resolves it+ from the manifest. Called after the database moves on disk or the manifest+ changes storage format."""+ self._sqlite_cache = _UNSET+def _resolve_sqlite(self) -> "SqliteCase | None":from .sqlite_backend import SqliteCase@@ -484,7 +435,7 @@ class Case:"updated_at": data.get("updated_at") or _now(),})- self._sqlite_cache = _UNSET # re-resolve against the new manifest+ self._forget_store() # re-resolve against the new manifestdef _backup(self, tag: str) -> None:"""Copy case.json aside once, under a ``tag``. Never overwrites an@@ -720,298 +671,6 @@ class Case:"""return {**self.read(), "folders": self._graph().list_folders()}- def list_entities(self) -> list[dict[str, Any]]:- return self._graph().list_entities()-- def page_entities(- self,- *,- limit: int = 100,- cursor: str | None = None,- types: list[str] | None = None,- status: EntityStatus | None = None,- query: str | None = None,- folder: str | None = None,- unfiled: bool = False,- recursive: bool = False,- attr: str | None = None,- attr_value: str | None = None,- linked: str | None = None,- unlinked: bool = False,- since: str | None = None,- until: str | None = None,- filed_by: list[str] | None = None,- temporal_since: str | None = None,- temporal_until: str | None = None,- temporal_categories: list[str] | None = None,- order: str = "",- ) -> dict[str, Any]:- """A bounded, filtered page of the catalog (Step 5), paged with an indexed- keyset over the ordering asked for."""- return self._graph().page_entities(- limit=limit,- cursor=cursor,- types=types,- status=status,- query=query,- folder=folder,- unfiled=unfiled,- recursive=recursive,- attr=attr,- attr_value=attr_value,- linked=linked,- unlinked=unlinked,- since=since,- until=until,- filed_by=filed_by,- temporal_since=temporal_since,- temporal_until=temporal_until,- temporal_categories=temporal_categories,- order=order,- )-- def catalog_summary(self) -> dict[str, Any]:- """Total plus per-type, per-status, per-folder and per-filer counts."""- return self._graph().catalog_summary()-- def attr_facets(- self, *, types: list[str] | None = None, limit: int = 50- ) -> list[dict[str, Any]]:- """Which stored fields these entities hold, and which values, as a menu."""- return self._graph().attr_facets(types=types, limit=limit)-- def list_links(self) -> list[dict[str, Any]]:- return self._graph().list_links()-- def entity_images(self, entity_id: str) -> list[dict[str, Any]]:- return self._graph().entity_images(entity_id)-- def entity_image_thumbs(self, entity_ids: list[str]) -> dict[str, str]:- return self._graph().entity_image_thumbs(entity_ids)-- def entity_images_touching(self, entity_ids: list[str]) -> list[dict[str, Any]]:- return self._graph().entity_images_touching(entity_ids)-- def add_entity_images(self, entity_id: str, media_ids: list[str]) -> int:- return self._graph().add_entity_images(entity_id, media_ids)-- def add_entity_image_file(- self,- entity_id: str,- image_id: str,- path: str,- thumbnail: str,- title: str,- ) -> None:- self._graph().add_entity_image_file(- entity_id, image_id, path, thumbnail, title- )-- def set_primary_entity_image(self, entity_id: str, image_id: str) -> None:- self._graph().set_primary_entity_image(entity_id, image_id)-- def remove_entity_image(self, entity_id: str, image_id: str) -> dict[str, Any]:- return self._graph().remove_entity_image(entity_id, image_id)-- def reinsert_entity_images(self, rows: list[dict[str, Any]]) -> dict[str, int]:- return self._graph().reinsert_entity_images(rows)-- def upsert_media_item(self, item: dict[str, Any], *, entity_id: str | None = None) -> None:- self._graph().upsert_media_item(item, entity_id=entity_id)-- def remove_media_item(self, path: str) -> None:- self._graph().remove_media_item(path)-- def timeline_page(- self,- *,- since: str | None = None,- until: str | None = None,- categories: list[str] | None = None,- entity_id: str | None = None,- include_undated: bool = True,- limit: int = 100,- cursor: str | None = None,- bucket: str | None = None,- track: dict[str, Any] | None = None,- spread: bool = False,- ) -> dict[str, Any]:- return self._graph().timeline_page(- since=since,- until=until,- categories=categories,- entity_id=entity_id,- include_undated=include_undated,- limit=limit,- cursor=cursor,- bucket=bucket,- track=track,- spread=spread,- )-- def rebuild_temporal_projection(self) -> int:- return self._graph().rebuild_temporal_projection()-- def temporal_projection_status(self) -> dict[str, int | bool]:- return self._graph().temporal_projection_status()-- def list_media_items(self) -> list[dict[str, Any]]:- return self._graph().list_media_items()-- def media_items_by_paths(self, paths: list[str]) -> list[dict[str, Any]]:- return self._graph().media_items_by_paths(paths)-- def media_thumbs(self, entity_ids: list[str]) -> dict[str, str]:- return self._graph().media_thumbs(entity_ids)-- def media_kinds(self, entity_ids: list[str]) -> dict[str, str]:- return self._graph().media_kinds(entity_ids)-- def media_origins(self, entity_ids: list[str]) -> dict[str, dict[str, str]]:- return self._graph().media_origins(entity_ids)-- def page_media_items(- self,- *,- q: str | None = None,- kind: str | None = None,- category: str | None = None,- folder: str | None = None,- gps: bool = False,- collected_only: bool = False,- sort: str = "newest",- direction: str | None = None,- limit: int = 200,- offset: int = 0,- ) -> dict[str, Any]:- return self._graph().page_media_items(- q=q,- kind=kind,- category=category,- folder=folder,- gps=gps,- collected_only=collected_only,- sort=sort,- direction=direction,- limit=limit,- offset=offset,- )-- def get_link(self, link_id: str) -> dict[str, Any] | None:- return self._graph().get_link(link_id)-- def links_of(self, entity_id: str) -> list[dict[str, Any]]:- return self._graph().links_of(entity_id)-- def count_dependents(self, *, link_type: str, from_type: str) -> dict[str, int]:- return self._graph().count_dependents(link_type=link_type, from_type=from_type)-- def count_incident_links(self, *, exclude_types: list[str]) -> dict[str, int]:- return self._graph().count_incident_links(exclude_types=exclude_types)-- def rank_entities(- self,- *,- limit: int = 200,- types: list[str] | None = None,- exclude_types: list[str] | None = None,- status: EntityStatus | None = None,- query: str | None = None,- folder: str | None = None,- unfiled: bool = False,- recursive: bool = False,- attr: str | None = None,- attr_value: str | None = None,- linked: str | None = None,- unlinked_only: bool = False,- since: str | None = None,- until: str | None = None,- filed_by: list[str] | None = None,- temporal_since: str | None = None,- temporal_until: str | None = None,- temporal_categories: list[str] | None = None,- link_types: list[str] | None = None,- order: str = "degree",- ) -> dict[str, Any]:- return self._graph().rank_entities(- limit=limit, types=types, exclude_types=exclude_types, status=status,- query=query, folder=folder, unfiled=unfiled, recursive=recursive,- attr=attr, attr_value=attr_value, linked=linked, unlinked_only=unlinked_only,- since=since, until=until, filed_by=filed_by,- temporal_since=temporal_since, temporal_until=temporal_until,- temporal_categories=temporal_categories,- link_types=link_types, order=order,- )-- def entities_by_ids(self, ids: list[str]) -> list[dict[str, Any]]:- return self._graph().entities_by_ids(ids)-- def labels_of_type(self, type_: str) -> list[tuple[str, str]]:- return self._graph().labels_of_type(type_)-- def links_among(- self, ids: list[str], *, types: list[str] | None = None- ) -> list[dict[str, Any]]:- return self._graph().links_among(ids, types=types)-- def links_touching(- self,- ids: list[str],- *,- types: list[str] | None = None,- exclude_types: list[str] | None = None,- end_types: list[str] | None = None,- ) -> list[dict[str, Any]]:- return self._graph().links_touching(- ids, types=types, exclude_types=exclude_types, end_types=end_types- )-- def degrees_of(- self,- ids: list[str],- *,- types: list[str] | None = None,- exclude_types: list[str] | None = None,- ) -> dict[str, int]:- return self._graph().degrees_of(ids, types=types, exclude_types=exclude_types)--- def graph_pins(self, lens: str) -> dict[str, tuple[float, float]]:- return self._graph().graph_pins(lens)-- def pin_entities(self, lens: str, pins: dict[str, tuple[float, float]]) -> int:- return self._graph().pin_entities(lens, pins)-- def unpin_entities(self, lens: str, ids: list[str]) -> int:- return self._graph().unpin_entities(lens, ids)-- def clear_graph_pins(self, lens: str) -> int:- return self._graph().clear_graph_pins(lens)-- def list_analysis_views(self) -> list[dict[str, Any]]:- return self._graph().list_analysis_views()-- def get_analysis_view(self, view_id: str) -> dict[str, Any] | None:- return self._graph().get_analysis_view(view_id)-- def save_analysis_view(self, view: dict[str, Any]) -> dict[str, Any]:- return self._graph().save_analysis_view(view)-- def remove_analysis_view(self, view_id: str) -> dict[str, Any] | None:- return self._graph().remove_analysis_view(view_id)-- def reinsert_analysis_views(self, views: list[dict[str, Any]]) -> int:- return self._graph().reinsert_analysis_views(views)-- def get_entity(self, entity_id: str) -> dict[str, Any] | None:- return self._graph().get_entity(entity_id)-- def note_ids_by_titles(self, titles: set[str]) -> dict[str, list[str]]:- return self._graph().note_ids_by_titles(titles)-- def entity_count(self) -> int:- """Entity total for the case switcher — one indexed count."""- return self._graph().count_entities()# -- notes -------------------------------------------------------------@@ -1212,24 +871,6 @@ class Case:self._follow_named_artifact_rename(entity_id, patch)return self._graph().update_entity(entity_id, patch)- def save_temporal_claim(- self,- *,- entity_id: str | None,- label: str,- attrs: dict[str, Any],- connectors: dict[str, list[str]] | None,- by: str,- status: EntityStatus = "confirmed",- ) -> dict[str, Any]:- return self._graph().save_temporal_claim(- entity_id=entity_id,- label=label,- attrs=attrs,- connectors=connectors,- by=by,- status=status,- )def _follow_named_artifact_rename(self, entity_id: str, patch: dict[str, Any]) -> None:"""Keep named tool files aligned with a label edited from Details.@@ -1365,50 +1006,6 @@ class Case:patch.setdefault("attrs", {})["path"] = targetpatch["label"] = canonical- def remove_entity(self, entity_id: str) -> None:- self._graph().remove_entity(entity_id)-- def find_entity(self, *, attr: str, value: Any) -> dict[str, Any] | None:- return self._graph().find_entity(attr=attr, value=value)-- def add_link(- self,- from_id: str,- to_id: str,- type_: str,- *,- by: str,- status: EntityStatus = "confirmed",- unique: bool = False,- ) -> dict[str, Any]:- """Add a typed edge. ``unique`` returns the existing identical edge- instead of stacking a duplicate — what a producer wants when its output- can dedupe onto an entity that is already in the case."""- return self._graph().add_link(from_id, to_id, type_, by=by, status=status, unique=unique)-- def sync_links(- self,- from_id: str,- type_: str,- to_ids: list[str],- *,- by: str,- status: EntityStatus = "confirmed",- ) -> list[dict[str, Any]]:- """Make ``from_id``'s outgoing links of ``type_`` exactly ``to_ids``.-- Re-saving an artifact restates its sources rather than piling onto them:- edges that are still true are left untouched (same id, same timestamp),- edges that are no longer true are dropped, new ones are appended. Unknown- targets and a self-reference are ignored.- """- return self._graph().sync_links(from_id, type_, to_ids, by=by, status=status)-- def update_link(self, link_id: str, patch: dict[str, Any]) -> dict[str, Any]:- return self._graph().update_link(link_id, patch)-- def remove_link(self, link_id: str) -> None:- self._graph().remove_link(link_id)# -- folders (nested organisational buckets for entities) ----------------#@@ -1432,75 +1029,7 @@ class Case:raise CaseError(f"a folder path is at most {layout.MAX_FOLDER_PATH} characters")return path- def list_folders(self) -> list[str]:- return self._graph().list_folders()-- def add_folder(self, name: str) -> list[str]:- return self._graph().add_folder(name)-- def remove_folder(self, name: str) -> list[str]:- return self._graph().remove_folder(name)-- # -- trash journal (engine/trash.py owns the files) ------------------------ def add_trash_group(- self,- group_id: str,- *,- label: str,- type_: str,- item_count: int,- size_bytes: int,- payload: dict[str, Any],- state: str = "ready",- ) -> dict[str, Any]:- return self._graph().add_trash_group(- group_id,- label=label,- type_=type_,- item_count=item_count,- size_bytes=size_bytes,- payload=payload,- state=state,- )-- def update_trash_group(- self,- group_id: str,- *,- state: str | None = None,- size_bytes: int | None = None,- payload: dict[str, Any] | None = None,- ) -> dict[str, Any]:- return self._graph().update_trash_group(- group_id,- state=state,- size_bytes=size_bytes,- payload=payload,- )-- def list_trash(self) -> list[dict[str, Any]]:- return self._graph().list_trash()-- def get_trash_group(self, group_id: str) -> dict[str, Any] | None:- return self._graph().get_trash_group(group_id)-- def list_incomplete_trash(self) -> list[dict[str, Any]]:- return self._graph().list_incomplete_trash()- def remove_trash_group(self, group_id: str) -> None:- self._graph().remove_trash_group(group_id)-- def clear_trash(self) -> list[str]:- return self._graph().clear_trash()-- def trash_summary(self) -> dict[str, int]:- return self._graph().trash_summary()-- def reinsert(- self, entities: list[dict[str, Any]], links: list[dict[str, Any]]- ) -> dict[str, int]:- return self._graph().reinsert(entities, links)@propertydef trash_dir(self) -> Path:@@ -1509,49 +1038,6 @@ class Case:into it."""return layout.trash(self.path)- # -- durable jobs (thumbnail and background-job model) --------------------- def enqueue_job(- self,- kind: str,- *,- key: str | None = None,- payload: dict[str, Any] | None = None,- max_attempts: int = 3,- ) -> dict[str, Any]:- return self._graph().enqueue_job(kind, key=key, payload=payload, max_attempts=max_attempts)-- def claim_job(self, *, kinds: list[str] | None = None) -> dict[str, Any] | None:- return self._graph().claim_job(kinds=kinds)-- def complete_job(self, job_id: str) -> None:- self._graph().complete_job(job_id)-- def fail_job(self, job_id: str, error: str) -> dict[str, Any]:- return self._graph().fail_job(job_id, error)-- def cancel_job(self, job_id: str) -> None:- self._graph().cancel_job(job_id)-- def get_job(self, job_id: str) -> dict[str, Any] | None:- return self._graph().get_job(job_id)-- def list_jobs(- self, *, kind: str | None = None, state: str | None = None- ) -> list[dict[str, Any]]:- return self._graph().list_jobs(kind=kind, state=state)-- def count_jobs(self, *, kind: str | None = None) -> dict[str, int]:- return self._graph().count_jobs(kind=kind)-- def recover_jobs(self) -> int:- return self._graph().recover_jobs()-- def prune_jobs(self, *, kind: str | None = None) -> int:- return self._graph().prune_jobs(kind=kind)-- def replace_path_references(self, old: str, new: str) -> None:- self._graph().replace_path_references(old, new)# -- helpers -------------------------------------------------------------@@ -1699,285 +1185,6 @@ def restore_manifest(name: str) -> "Case":return case-def _wrap_case_folder(case: "Case") -> None:- """Move the tool's files into `azimut/`.-- What this buys is in `layout.py`: the case root becomes the analyst's, and a- folder they create there can no longer collide with one of ours.-- Nothing inside is rewritten. Paths are stored relative to the tool root- (`media/x.png`), so they go on meaning the same thing one level down — the- database, the sidecars and any bundle are untouched.-- **Only the tool's own entries move** (`layout.UNWRAPPED_ENTRIES`). Nothing- stopped an analyst from keeping their own folder beside a case before this,- and carrying it into `azimut/` would contradict the very boundary being- drawn. Anything unrecognised stays at the case root, which is where it now- belongs anyway.-- **The manifest moves last.** While it is still at the case root the move is- unfinished, and that is exactly what `layout.needs_wrapper` reads, so a- power cut mid-move is resumed rather than half-applied. Runs before anything- reads the manifest, which is why it is keyed on the filesystem rather than- on a schema number nobody could load yet.- """- root = case.path- if not layout.needs_wrapper(root):- return- tool = layout.tool_root(root)- tool.mkdir(exist_ok=True)- ours = [root / name for name in layout.UNWRAPPED_ENTRIES]- ours += sorted(root.glob(layout.UNWRAPPED_BACKUP_GLOB))- for entry in dict.fromkeys(ours):- destination = tool / entry.name- if not entry.exists() or destination.exists():- continue # absent, or already carried over by an interrupted run- shutil.move(str(entry), str(destination))- shutil.move(str(layout.unwrapped_manifest(root)), str(layout.manifest(root)))- case._sqlite_cache = _UNSET # the database is at a new path now---def _flatten_trash(case: "Case") -> None:- """Make trash groups stop mirroring the case tree.-- A group used to hold ``media/clip.mp4`` under its own directory, stacking- two case trees and making the trash the longest path Azimut could write —- on its own enough to pass Windows' 260-character limit. The journal already- knows where each file came from, so the files move to numbered slots and the- payload gains the ``slots`` list that pairs with ``files``.-- Idempotent: a file already in its slot is left alone, so an interrupted run- resumes.- """- from .engine.trash import slots_for-- groups = [g["id"] for g in case.list_trash()]- groups += [g["id"] for g in case.list_incomplete_trash()]- for group_id in dict.fromkeys(groups):- group = case.get_trash_group(group_id)- if group is None:- continue- payload = dict(group.get("payload") or {})- files = [str(rel) for rel in (payload.get("files") or [])]- slots = slots_for(files)- root = case.trash_dir / group_id- for rel, slot in zip(files, slots):- source = root / rel- destination = root / slot- if source.exists() and not destination.exists():- shutil.move(str(source), str(destination))- _drop_empty_dirs(root)- payload["slots"] = slots- case.update_trash_group(group_id, payload=payload)---def _drop_empty_dirs(root: Path) -> None:- """Remove the directories a mirrored group left behind, deepest first."""- if not root.is_dir():- return- for path in sorted(root.rglob("*"), key=lambda p: len(p.parts), reverse=True):- if path.is_dir() and not any(path.iterdir()):- path.rmdir()---def _prune_empty_note_dirs(root: Path, directory: Path) -> None:- """Drop the folder directories a moved note left empty, up to `notes/`.-- A mirrored tree that keeps every directory a note ever passed through stops- being a mirror. Stops at `notes/` itself, which is born with the case.-- Both paths are resolved before they are compared. Callers hand in the note- directory as the case knows it and the note's own parent as- `resolve_inside` returned it, which are the same directory in two spellings- the moment a symlink sits anywhere above the workspace: macOS reaches every- temporary directory through `/var` → `/private/var`, and a workspace under a- synced or linked folder does the same on any platform. Comparing the two- spellings makes the containment check say "outside", and the loop that- should prune then does nothing at all.- """- root = root.resolve()- directory = directory.resolve()- while directory != root and directory.is_relative_to(root):- try:- if any(directory.iterdir()):- return- directory.rmdir()- except OSError:- return- directory = directory.parent---def _move_into(source: Path, destination: Path) -> None:- """Carry one entry over, skipping what an interrupted run already moved."""- if not source.exists() or destination.exists():- return- ensure_dir(destination.parent)- shutil.move(str(source), str(destination))---def _hide_the_machinery(case: "Case") -> None:- """Move what only Azimut can read out of the way.-- The rule is in `layout.py`: visible means openable in another program.- Applied here it moves the database into `.data/`, the media sidecars into- `media/.meta/`, the proof specs and their pasted assets into- `proofs/.meta/`, and renames `inspect/` and `search/` to dot-directories.-- `exports/` is the one that changes meaning rather than place. It held post- drafts — its name was wrong — so the drafts become `.drafts/` and a fresh,- empty `exports/` is left behind for what the word actually promises.-- This is the first folder step that rewrites *stored* paths: a proof's- ``spec``, a session's ``spec`` and a post's ``draft`` all name a directory- that just moved.- """- root = case.path- tool = layout.tool_root(root)-- # The database first, and with no connection open: on Windows an open file- # cannot be moved. Nothing holds one here — every backend connection is- # scoped to its own `with` — but the cached handle is dropped anyway so the- # next access re-resolves against the new path.- _move_into(tool / layout.PRE_HIDDEN_DB, layout.database(root))- case._sqlite_cache = _UNSET-- # Sidecars: `media/clip.mp4.azimut.json` -> `media/.meta/clip.mp4.json`.- media_dir = layout.media(root)- if media_dir.is_dir():- suffix = layout.PRE_HIDDEN_SIDECAR_SUFFIX- for sidecar in sorted(media_dir.glob(f"*{suffix}")):- name = sidecar.name[: -len(suffix)]- _move_into(sidecar, case.resolve_inside(layout.sidecar_rel(name)))-- # Proof specs and pasted assets join them; the rendered PNG stays visible.- proofs_dir = layout.subdir(root, "proofs")- if proofs_dir.is_dir():- for spec in sorted(proofs_dir.glob("*.json")):- _move_into(spec, case.resolve_inside(layout.proof_spec_rel(spec.stem)))- for assets in sorted(proofs_dir.glob("*.assets")):- _move_into(assets, case.resolve_inside(layout.proof_assets_rel(assets.stem)))-- # The sidecars just moved, and the one-time browse-index backfill may have- # already run against their old location. Forget it, so the reopen below- # rebuilds the index from where they are now.- store = case._sqlite- if store is not None:- store.forget_media_index()- case._sqlite_cache = _UNSET-- for old, new in layout.PRE_HIDDEN_DIRS.items():- _move_into(tool / old, tool / new)- for directory in layout.content_dirs(root):- ensure_dir(directory)-- _rewrite_moved_paths(case)---#: entity type -> (attribute holding a case-relative path, old prefix, rebuild).-_MOVED_ATTRS: dict[str, tuple[str, str, Callable[[str], str]]] = {- "proof": ("spec", "proofs/", layout.proof_spec_rel),- "inspect-session": ("spec", "inspect/", layout.session_rel),- "post": ("draft", "exports/", layout.draft_rel),-}---def _rewrite_moved_paths(case: "Case") -> None:- """Point the graph at the directories the migration just renamed.-- Only entities still naming the old location are touched, so a re-run after- an interruption rewrites nothing twice.- """- for entity in case.list_entities():- rule = _MOVED_ATTRS.get(str(entity.get("type") or ""))- if rule is None:- continue- attribute, prefix, rebuild = rule- current = (entity.get("attrs") or {}).get(attribute)- if not isinstance(current, str) or not current.startswith(prefix):- continue- stem = Path(current).stem- case.update_entity(entity["id"], {"attrs": {attribute: rebuild(stem)}})---def _name_notes_after_their_titles(case: "Case") -> None:- """Make notes stop being named after their entity id.-- `notes/e_03aeb50d41.md` was visible and illegible — in the way without being- readable. Every other document already follows "the name is the filename";- notes were the only holdout, and only because they are generic entities with- their path hardcoded rather than a tool of their own.-- Titles are not unique, so a collision inside one folder takes a numbered- suffix, exactly as a new note would.-- An empty patch is the whole migration: `update_entity` already moves a note- whose title or folder no longer matches its filename. Once moved, the- current path is reserved for that note, so a resumed pass leaves the path- and any collision suffix unchanged.- """- for entity in case.list_entities():- if entity.get("type") == "note":- case.update_entity(entity["id"], {})---def _leave_a_readme(case: "Case") -> None:- """Teach a case that predates the free zone which half is whose.-- The wrapper gave the analyst the case root three schemas ago; nothing on- disk told them. This is the step that does, and it is the only migration- here that writes into their half of the folder rather than ours.- """- write_readme(case.path)---def _align_visible_names(case: "Case") -> None:- """Make every analyst-visible filename stem the name Azimut displays.-- Uploads belong to the analyst, so their existing filename wins. Downloads,- captures and derived media belong to an Azimut save gate, so their stored- title wins and machine timestamps/remote ids remain provenance. Named- documents run through their existing rename hooks, which also repairs a- Details edit that changed only the graph label.- """- from .engine import media as media_engine-- media_engine.recover_media_rename(case)- for item in list(case.list_media_items()):- path = str(item.get("path") or "")- if not path:- continue- source: dict[str, Any] = item["source"] if isinstance(item.get("source"), dict) else {}- entity = case.find_entity(attr="path", value=path)- if source.get("type") == "upload":- desired = Path(path).stem- else:- desired = str(item.get("title") or (entity or {}).get("label") or Path(path).stem)- # `Case.migrate` already owns the case lock. An older case cannot have- # live work in this process; waiting here would deadlock a test that- # deliberately rewinds a just-created case while its worker is draining.- media_engine.rename_media(case, path, desired, settle_worker=False)-- for entity in list(case.list_entities()):- if entity.get("type") in {"note", "proof", "inspect-session", "post"}:- case.update_entity(entity["id"], {"label": entity.get("label") or ""})---def _normalize_case_layout(case: "Case") -> None:- """Bring every unreleased folder checkpoint to the final layout.-- Schemas 4 through 7 were useful while building the layout, but no released- Azimut wrote them. One normalizer accepts schema 3 and those development- states, applies every operation in dependency order, then the runner stamps- the current schema once. Each operation is idempotent, so an interrupted- pass restarts here without guessing which line completed.- """- _wrap_case_folder(case)- _flatten_trash(case)- _hide_the_machinery(case)- _name_notes_after_their_titles(case)- _leave_a_readme(case)- _align_visible_names(case)-def open_workspace() -> None:"""Bring the workspace at the current root into a state routes can serve.diff --git a/tests/test_entity_images.py b/tests/test_entity_images.pyindex 696e163..f93cfb1 100644--- a/tests/test_entity_images.py+++ b/tests/test_entity_images.py@@ -248,10 +248,10 @@ def test_a_photo_past_the_limit_is_refused_before_anything_is_written(before anything looked at its size."""from azimut import layout- from azimut.api import cases+ from azimut.api.cases import entity_imagesfrom azimut.workspace import Case- monkeypatch.setattr(cases, "MAX_IMAGE_BYTES", 100)+ monkeypatch.setattr(entity_images, "MAX_IMAGE_BYTES", 100)case_id = _case(client, "Bounded photos")subject = _entity(client, case_id, "person", "Unknown subject")diff --git a/tests/test_migrations.py b/tests/test_migrations.pyindex e96d970..4800fcf 100644--- a/tests/test_migrations.py+++ b/tests/test_migrations.py@@ -13,7 +13,7 @@ import pytestimport fullcasefrom legacy_case import rewind_case, unwrap_case, write_legacy_json_case-from azimut import config, layout, workspace+from azimut import caselayout, config, layout, workspacefrom azimut.sqlite_backend import SQLITE_SCHEMAfrom azimut.engine import trash as trash_enginefrom azimut.workspace import Case, CaseError, ensure_dir@@ -323,13 +323,18 @@ def test_released_schema_three_is_stamped_only_once(tmp_workspace, monkeypatch):)def test_folder_normalizer_resumes_after_each_stage(tmp_workspace, monkeypatch, stage):case, expected = _case_at_folder_checkpoint(workspace.STORAGE_SCHEMA)- real_stage = getattr(workspace, stage)+ # The stages live in `caselayout`; `workspace` calls one of them directly+ # (`_wrap_case_folder`, before the manifest can even be read), so the patch+ # goes on every module that looks the name up.+ homes = [m for m in (caselayout, workspace) if hasattr(m, stage)]+ real_stage = getattr(caselayout, stage)def stop_after_stage(current):real_stage(current)raise RuntimeError(f"stop after {stage}")- monkeypatch.setattr(workspace, stage, stop_after_stage)+ for home in homes:+ monkeypatch.setattr(home, stage, stop_after_stage)with pytest.raises(RuntimeError, match="stop after"):Case.open(case.id)@@ -342,7 +347,8 @@ def test_folder_normalizer_resumes_after_each_stage(tmp_workspace, monkeypatch,workspace.STORAGE_SCHEMA)- monkeypatch.setattr(workspace, stage, real_stage)+ for home in homes:+ monkeypatch.setattr(home, stage, real_stage)opened = Case.open(case.id)assert opened.read()["azimut"]["schema"] == workspace.CASE_SCHEMAdiff --git a/tests/test_release_gate.py b/tests/test_release_gate.pyindex e8f6d23..73e5c8a 100644--- a/tests/test_release_gate.py+++ b/tests/test_release_gate.py@@ -170,7 +170,11 @@ def test_storage_and_jobs_add_no_new_runtime_dependency():# sqlite3/threading/subprocess are stdlib; Pillow (declared) does the imaging.assert "pillow" in declaredsrc = Path(__file__).resolve().parent.parent / "src" / "azimut"- text = (src / "sqlite_backend.py").read_text() + (src / "engine" / "thumbnails.py").read_text()+ # The store is a package plus its entry module, so the scan follows it rather+ # than stopping at the file the class happens to live in.+ files = [src / "sqlite_backend.py", src / "engine" / "thumbnails.py"]+ files += sorted((src / "store").glob("*.py"))+ text = "".join(path.read_text() for path in files)assert "import sqlite3" in (src / "sqlite_backend.py").read_text()for banned in ("import numpy", "import pandas", "import redis", "import celery"):assert banned not in text # no heavyweight queue/DB dependency slipped in@@ -260,6 +264,9 @@ def test_current_settings_docs_name_the_current_sections():root / "frontend" / "src" / "components" / "WorkspaceFolder.svelte",root / "frontend" / "src" / "tools" / "Settings.svelte",]+ # Settings is a tab host now, so the copy this reads lives in the tabs. Scan+ # the directory rather than the host, or a stale label walks back in unseen.+ current += sorted((root / "frontend" / "src" / "tools" / "settings").glob("*.svelte"))text = "\n".join(path.read_text(encoding="utf-8") for path in current)for stale in ("Settings → Preferences", "About tab", "Preferences tab"):assert stale not in textdiff --git a/tests/test_repository.py b/tests/test_repository.pyindex bd3bfe0..9496f24 100644--- a/tests/test_repository.py+++ b/tests/test_repository.py@@ -322,9 +322,9 @@ def test_the_store_that_ships_can_read_inside_a_stored_field():belt and braces, and it matches at any depth where this is top-level exact — so ifthis ever fails on a platform, that difference is what ships there."""- from azimut import sqlite_backend+ from azimut.store import filters- assert sqlite_backend._has_json1() is True+ assert filters._has_json1() is Truedef test_page_entities_filters_on_one_stored_field(repo):@@ -450,9 +450,9 @@ def test_a_value_a_menu_cannot_show_is_not_offered(repo):def test_the_field_filter_answers_the_same_without_json1(repo, monkeypatch):"""The fallback is what a binary whose SQLite lacks JSON1 would run, so it isexercised on every platform rather than only where it might one day be needed."""- from azimut import sqlite_backend+ from azimut.store import filters- monkeypatch.setattr(sqlite_backend, "_has_json1", lambda: False)+ monkeypatch.setattr(filters, "_has_json1", lambda: False)video = repo.add_entity("media", "clip", {"kind": "video"}, by="user")repo.add_entity("media", "still", {"kind": "image"}, by="user")hundred = repo.add_entity("place", "block", {"radius_m": 100}, by="user")@@ -623,7 +623,7 @@ def test_links_among_holds_an_edge_whose_ends_bind_in_two_statements(repo):unconnected dots, and each one went on reporting the lost edges as connectionsstill to open under a control that could never bring one in."""- from azimut.sqlite_backend import _ID_CHUNK+ from azimut.store.sql import _ID_CHUNKhub = repo.add_entity("person", "hub", by="user")["id"]# One chunk over the boundary, so the star's arms are bound in three statements@@ -676,7 +676,7 @@ def test_the_closed_set_costs_one_statement_whatever_the_drawing_holds(repo):top of that would have moved the freeze from the canvas to the database, which iswhy this lands with the limit and not after it."""- from azimut.sqlite_backend import _ID_CHUNK+ from azimut.store.sql import _ID_CHUNKhub = repo.add_entity("person", "hub", by="user")["id"]spokes = [@@ -699,7 +699,7 @@ def test_the_closed_set_costs_one_statement_whatever_the_drawing_holds(repo):def test_one_hop_costs_one_statement_too(repo):"""The open set could always be chunked, and is asked through the same table."""- from azimut.sqlite_backend import _ID_CHUNK+ from azimut.store.sql import _ID_CHUNKhub = repo.add_entity("person", "hub", by="user")["id"]spokes = [@@ -719,7 +719,7 @@ def test_one_hop_costs_one_statement_too(repo):def test_the_scope_table_does_not_survive_the_read_that_filled_it(repo):"""A temp table left standing would answer the next question with the last one'sids. It belongs to the connection, and each read opens its own."""- from azimut.sqlite_backend import _SCOPE+ from azimut.store.sql import _SCOPEhub = repo.add_entity("person", "hub", by="user")["id"]other = repo.add_entity("person", "other", by="user")["id"]@@ -746,7 +746,7 @@ def test_every_case_wide_ordering_is_served_by_an_index(repo):a temp B-tree for every page. This holds the plan to the index, in bothdirections and with a cursor in hand, which is the shape a second page runs."""- from azimut.sqlite_backend import _PAGE_ORDERS+ from azimut.store.cursors import _PAGE_ORDERSrepo.add_entity("person", "Ada", by="user")plans: dict[str, list[str]] = {}