lightcraft/plan/phase-4.md

# Phase 4: Workflow power features and full Immich integration

*Copy of `PLAN_phase_4.md` at the repository root, taken 2026-10-10. The root file is the working copy; refresh this one when it changes.*

Part of [PLAN.md](../PLAN.md). **Estimate:** 60–105 agent-hours (including about 20–35 h of Immich work).
**Depends on:** Phase 1 (catalog v4, `net`, `credentials`, the `immich` crate and links).
**Runs in parallel with:** Phases 2 and 3.

**Goal:**
- the workflow features power users rely on: tethering, publish services, plugins, round trips, actions, people and
  catalog migration;
- **two-way integration with Immich**, so the desktop catalog and a self-hosted Immich server stay one library.

---

## 4.1 Tethered capture (≈ 10–16 h)

1. **Studio capture first** (the design described in Ansel's prose note `doc/studio-capture.md`): watch a folder written by any vendor tool or the camera's own app;
   auto-import with:
   - a develop preset;
   - a metadata preset and keywords;
   - a session name and naming template;
   - a target collection.
   The newest shot shows in the loupe automatically.
2. **Native tethering**, new crate `tether`:
   - PTP over USB with `nusb` (pure Rust), plus PTP/IP over Wi-Fi;
   - vendor extensions for Canon, Nikon, Sony and Fujifilm, in that order;
   - capture, download-on-capture, delete-from-card option.
3. **Tether bar** (as in Classic): camera name, shutter, aperture, ISO and WB readouts and settings; capture button;
   develop settings "same as previous"; **live view** where the camera supports it.
4. Platform notes:
   - Linux needs a udev rule (shipped in packages).
   - macOS: release the camera from `ptpcamerad`.
   - Windows: WinUSB driver notes.
   - Unsupported cameras fall back to studio capture with a clear message.

**Done when:** studio capture works with any camera; native capture is verified on at least one Canon, Nikon and Sony
body; CI uses a simulated PTP device.

---

## 4.2 Publish services framework (≈ 8–12 h)

- **Model:**
  - a *publish service* (type plus account plus export settings) contains **published collections** and sets;
  - each photo has a state: *new to publish*, *modified to re-publish*, *published*, *deleted to remove*;
  - remote ids are stored in `remote_identity` (Phase 1.7);
  - the modified state comes from the develop/metadata change feed (the catalog op log).
- **UI:**
  - Publish Services panel in Library;
  - the Publish button;
  - the grid split into New / Modified / Published sections;
  - "Mark as Up-to-date";
  - remote comments and likes where the service supports them.
  - This closes LRC-LIB-COMMENTS for services that have them.
- **Built-in services:**
  - **Hard Drive** (export to a folder kept in sync);
  - **Immich** (4.6);
  - **SFTP** (reuses Phase 3.6).
- Other services (Flickr, SmugMug, Piwigo, Nextcloud, PhotoPrism, WebDAV) come as **plugins** (4.3).

---

## 4.3 Plugin SDK (≈ 10–16 h)

- **Sandbox:** port PhotoCraft's `plugins` crate (`wasmi`, no host imports by default, fuel and memory limits).
- **Host API, versioned and capability-gated:**
  - catalog query (read);
  - metadata read/write in a plugin-owned namespace, plus standard fields with permission;
  - **export post-process hooks**;
  - **publish service provider interface** (the same trait the built-in services implement);
  - metadata/keyword providers;
  - menu commands that register as engine commands;
  - simple dialogs from a declarative UI description.
- **Permissions:**
  - network per host;
  - filesystem roots;
  - granted on install and revocable in the Plugin Manager.
- **Plugin Manager:** install, enable, disable, update, view logs.
- **SDK:** Rust crate plus template, docs and two example plugins (a WebDAV publisher and a metadata reverse-lookup).
- Lightroom's Lua plugins are not supported, and no promise is made to support them.

---

## 4.4 Edit In and the PhotoCraft round trip (≈ 5–8 h)

- External editor presets (app, file format, colour space, bit depth, resolution, compression, stack with original,
  naming).
- **PhotoCraft integration:**
  - "Edit in PhotoCraft" sends TIFF or **layered PSD** using PhotoCraft's `psd` writer (ported). "Open as Layers"
    builds a layered PSD from the selection.
  - When the file is saved, it is re-imported and stacked with the original; the edit-in round trip keeps metadata.
  - If PhotoCraft runs with `--control`, the two apps can talk directly over the control channel: open, and notify on
    save.
- PSD/PSB **import** uses the PhotoCraft `psd` reader (flattened composite plus layer metadata).

---

## 4.5 Actions, people, migration (≈ 10–18 h)

- **Actions:**
  - record a sequence of engine commands (built on PhotoCraft's `actions_cmds` design and our journal);
  - parameterise it, save it, assign a shortcut, run it on a selection;
  - also exposed through MCP and the CLI (`app-cli run-action`).
- **People:**
  - face clusters with separators and confidence;
  - merge and split;
  - small-face detection on large images (tiled detection beyond 640 px);
  - **write face regions to XMP** (MWG Regions) and read them back;
  - person keywords.
- **`.lrcat` migration v2:**
  - replay develop history and snapshots;
  - a profile mapping table (Adobe profile names → our camera-matching/creative profiles from Phase 2.3);
  - masks (brush, linear, radial, range) and spot/heal;
  - a per-photo **fidelity report** listing what could not be mapped;
  - publish-service collections imported as plain collections.
  - Mapping is derived from the published XMP `crs:` field descriptions and from our own measurements: apply known
    values in Lightroom, export, compare (the local fidelity references of Phase 2.8). darktable's importer is
    **not** read (MIT clean-room).

---

## 4.6 Immich: full two-way integration (≈ 20–35 h)

Builds on Phase 1.8: connection, link by checksum, import, shared originals. Every Immich action is a command
(`immich.*`), so it works from the UI, CLI, control channel and MCP (**IMM-MCP**).

### 4.6.1 IMM-PUBLISH: Immich as a publish service

- An **"Immich" publish service** per connected account. Published collections map 1:1 to **Immich albums** (created
  if missing, renamed if the collection is renamed). Collection sets map to album name prefixes.
- **What is sent**, per service:
  1. **Rendered** JPEG/AVIF/JXL using the export settings, so Immich shows the edited look; or
  2. **Original** (plus XMP sidecar); or
  3. **Both, stacked in Immich**, with the render on top and the original underneath, using Immich's stack feature.
- **Upload:**
  - streaming multipart upload with progress and resume-on-failure (via `net`);
  - a stable device asset id (catalog photo id plus virtual-copy id);
  - **checksum pre-check before upload**, so Immich never stores a duplicate; already-present assets are just linked
    and added to the album.
- **Re-publish:** edits mark photos *modified*; re-publishing replaces the rendered asset in place (keeping its id,
  albums and favourites where the API allows), otherwise uploads a new asset, moves album membership and trashes the
  old one.
- **Removal:** removing from a published collection removes the photo from the album. Deleting the Immich asset is a
  separate, explicit option (default **off**); assets go to the Immich trash, never a hard delete.
- **Shared-originals mode** (IMM-EXTLIB): for originals already in an Immich external library, publish only changes
  album membership and metadata; nothing is uploaded except renders, if chosen.

### 4.6.2 IMM-SYNC: two-way metadata sync

- **Per-field opt-in mapping**, with defaults:

| Catalog | Immich | Default |
|---|---|---|
| Star rating 0–5 | asset rating | two-way |
| Pick flag | favourite | two-way (configurable: favourite ↔ pick, or favourite ↔ 5★, or off) |
| Reject flag | archived | off (configurable) |
| Title / Caption | description | two-way (caption ↔ description; title optional) |
| Keywords (hierarchical) | tags (hierarchical, `A/B/C`) | two-way; export-excluded keywords never sent |
| Collections | albums | two-way for linked collections only |
| GPS, capture date/time | asset location and date | two-way, with a conflict prompt |
| People names / face regions | people / faces | see IMM-PEOPLE |
| Deleted photo | trashed asset | **never automatic**; a queue for the user to confirm |

- **Change detection:**
  - local changes come from the catalog op log since `last_synced_at`;
  - remote changes come from incremental queries (`updatedAfter` or the server's sync stream, depending on the pinned
    Immich API version in `plan/immich.md`).
- **Conflicts** (both sides changed since the last sync):
  - a per-field policy: catalog wins, Immich wins, or newest wins (the default);
  - a Sync Conflicts view that shows both values for anything unresolved.
- **Scheduling:** manual, on publish, or a background interval. It runs offline-safe: queued and retried with
  backoff, and it never blocks the UI.
- Activity log entries for every sync run; a dry-run mode shows what would change.

### 4.6.3 IMM-PEOPLE

- Import Immich **people** (names, birthdates, hidden flag) and **face regions** (bounding boxes) for linked assets
  into the People view. They are marked "from Immich" and can be confirmed or corrected.
- Push names assigned in the app back to Immich people (opt-in); merges map to Immich person merges.
- This gives good face recognition **before Phase 5**, by reusing Immich's own machine learning.

### 4.6.4 IMM-SEARCH

- The Library filter bar and the Text filter get an **"Immich smart search"** mode: a natural-language query (Immich's
  CLIP search) returns asset ids, which are mapped to linked catalog photos. The results show as a temporary
  collection that can be saved as a collection.
- Also: metadata search (OCR text, objects, places) when the server supports it.
- This stands in for local AI search (FILT-SEARCH-AI) until Phase 5, and can coexist with it later.

### 4.6.5 Hardening and tests

- **Version policy:** support the pinned minimum Immich release and the latest release. A nightly CI job runs
  integration tests against both through `cargo xtask immich up --version …`.
- **Scale:** sync of 100k assets completes, resumes after interruption and stays under 5% CPU when idle.
- **Failure:**
  - server down, key revoked, permission missing, TLS change: each gives a clear error, nothing is lost, and work is
    queued;
  - never crash, as the never-crash standard requires; fuzz the JSON decoding of server responses.
- **Privacy:** a "private" saved location (Phase 3.3) strips GPS from renders sent to Immich too. Uploads respect the
  export metadata policy.

---

## Exit gate

- [ ] Studio capture and native tethering (Canon/Nikon/Sony verified) ✅.
- [ ] Publish framework with Hard Drive, SFTP and Immich services; plugin SDK with two example plugins.
- [ ] Edit-in round trip with PhotoCraft (layered PSD) ✅; actions record and replay ✅.
- [ ] People clusters and XMP face regions ✅; `.lrcat` v2 migration with fidelity report.
- [ ] IMM-PUBLISH, IMM-SYNC, IMM-PEOPLE, IMM-SEARCH and IMM-MCP ✅ against the minimum and latest Immich releases.
- [ ] Scripted end-to-end session through MCP, headless in CI:
  1. simulated tethered shoot;
  2. import preset;
  3. cull;
  4. develop;
  5. publish to Hard Drive, SFTP and Immich (album plus stacked original);
  6. edit the rating in Immich and see it sync back;
  7. print a contact sheet to PDF.