Skip to content

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.md
index 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 matches
on**, beside the label, the type, the folder and the notes — a vehicle is looked for
by 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.md
index 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 engine
changes 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-goals
diff --git a/docs/STORAGE_AND_PERFORMANCE.md b/docs/STORAGE_AND_PERFORMANCE.md
index 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 the
implementation reaches into a raw `case.json` shape. `workspace.Case` is the
filesystem shell (manifest, notes, media, lifecycle, path resolution) and
delegates 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 checks
and test assertions.
diff --git a/frontend/src/app.css b/frontend/src/app.css
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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.svelte
index 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.js
index 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.svelte
index 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 reflow
p.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 size
group.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.svelte
index 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 px
function 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.js
index 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.js
new file mode 100644
index 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.svelte
index 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}
<ExportFolderPicker
kind={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.js
index 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.svelte
new file mode 100644
index 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.svelte
new file mode 100644
index 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.svelte
new file mode 100644
index 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.svelte
new file mode 100644
index 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.svelte
new file mode 100644
index 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.svelte
new file mode 100644
index 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.svelte
new file mode 100644
index 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.py
deleted file mode 100644
index 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 exc
diff --git a/src/azimut/api/cases/common.py b/src/azimut/api/cases/common.py
new file mode 100644
index 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, categories
diff --git a/src/azimut/api/cases/doctor.py b/src/azimut/api/cases/doctor.py
new file mode 100644
index 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 exc
diff --git a/src/azimut/api/cases/entities.py b/src/azimut/api/cases/entities.py
new file mode 100644
index 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 exc
diff --git a/src/azimut/api/cases/entity_images.py b/src/azimut/api/cases/entity_images.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.
+ pass
diff --git a/src/azimut/api/cases/lifecycle.py b/src/azimut/api/cases/lifecycle.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 exc
diff --git a/src/azimut/api/cases/trash.py b/src/azimut/api/cases/trash.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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. Anything
beyond core SQL (FTS5, JSON1, RTree) is per-binary and must be probed at runtime
with a fallback before it enters the contract. Two attribute reads live on that
line: `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 annotations
import json
-import re
import sqlite3
-from base64 import urlsafe_b64decode, urlsafe_b64encode
from contextlib import closing, contextmanager
from dataclasses import dataclass, field
-from functools import lru_cache
from pathlib import Path
from typing import TYPE_CHECKING, Any, Callable, Iterator, TypeVar
-from .engine import entities as entity_engine
from .engine import links as link_engine
-from .engine import mapsites
from .engine import timeline as timeline_engine
from . import layout
from .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_retry
if 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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 None
diff --git a/src/azimut/store/filters.py b/src/azimut/store/filters.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 6ec4af1..f0e6879 100644
--- a/src/azimut/workspace.py
+++ b/src/azimut/workspace.py
@@ -24,6 +24,15 @@ from pathlib import Path
from typing import TYPE_CHECKING, Any, Callable
from . 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 CaseStore
from .layout import MAX_CASE_SLUG
from .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`. A
legacy 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 manifest
def _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"] = target
patch["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)
@property
def 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.py
index 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_images
from 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.py
index e96d970..4800fcf 100644
--- a/tests/test_migrations.py
+++ b/tests/test_migrations.py
@@ -13,7 +13,7 @@ import pytest
import fullcase
from legacy_case import rewind_case, unwrap_case, write_legacy_json_case
-from azimut import config, layout, workspace
+from azimut import caselayout, config, layout, workspace
from azimut.sqlite_backend import SQLITE_SCHEMA
from azimut.engine import trash as trash_engine
from 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_SCHEMA
diff --git a/tests/test_release_gate.py b/tests/test_release_gate.py
index 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 declared
src = 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 text
diff --git a/tests/test_repository.py b/tests/test_repository.py
index 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 if
this 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 True
def 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 is
exercised 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 connections
still to open under a control that could never bring one in.
"""
- from azimut.sqlite_backend import _ID_CHUNK
+ from azimut.store.sql import _ID_CHUNK
hub = 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 is
why this lands with the limit and not after it.
"""
- from azimut.sqlite_backend import _ID_CHUNK
+ from azimut.store.sql import _ID_CHUNK
hub = 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_CHUNK
hub = 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's
ids. It belongs to the connection, and each read opens its own."""
- from azimut.sqlite_backend import _SCOPE
+ from azimut.store.sql import _SCOPE
hub = 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 both
directions 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_ORDERS
repo.add_entity("person", "Ada", by="user")
plans: dict[str, list[str]] = {}