0065. A photo gallery sync owns only its own Source’s photos
Status: Accepted (2026-09-23)Context
Landlord API Slice 3 lets a sync job keep a property’s photo gallery in step with an external listing site through a declarativePUT .../photos (design:
docs/superpowers/specs/2026-09-23-landlord-api-media-sync-design.md). A gallery can
also hold photos a landlord uploaded by hand, and photos from a second feed.
The obvious reading of a declarative PUT is “this list is the gallery”. Under that
reading a landlord’s hand-uploaded photos vanish on the next nightly sync, and two feeds
delete each other’s photos.
Decision
A gallery PUT governs only the photos owned by the Source it declares.- Ownership is
source = X. It is never inferred fromorigin_channel: acliorapirow is owned by whichever Source declared it, or by none. - A photo with no Source (panel upload, or a single multipart API upload) is unowned. No sync can change or remove it.
- A Source orders only its own block, placed after every photo it does not own. The unowned block never moves, so the landlord’s cover photo survives every sync.
- An owned photo is read-only in the panel: a human cannot move or delete it. The cover is therefore always an unowned photo when one exists. A human change to an owned photo would be undone by the next sync, so the panel does not offer one.
Considered options
- PUT replaces the whole gallery. Simplest contract; silently destroys hand uploads.
- Opt-in “API manages all photos” flag per property. A flag, a UI toggle and two behaviours to test, for a case nobody asked for.
- Absolute positions, last writer wins. Two Sources reshuffle each other nightly.
- Ownership by
origin_channel = 'api' AND source = X. A Slice 5 CLI writing asclicould never remove its own photos. - Panel may hide, move or delete owned photos. Sync would have to remember human overrides (tombstones or pinned positions): new schema and new sync rules. Additive later if landlords ask for it.
Consequences
- The rule is published in the v1 contract. Integrators build against “my PUT touches only my photos”; changing it later breaks them.
sourceis required on the gallery PUT. A declaration that names no owner cannot say which photos it governs.- A photo uploaded by multipart has no Source, so no key can ever remove it. The panel
has no photo delete today, so such a photo is permanent until one is built.
Exception (2026-10-03): on the Partner API a single upload is owned by the partner’s
slug (
docs/superpowers/specs/2026-10-03-partner-api-p1-design.mdD11, §8). v1 and panel uploads are unchanged. - To remove an owned photo, the landlord changes the feed, not the panel.
- Partner grant revocation does not release or clear its photos’ Source. The landlord retains the properties, listings, proofs, External Refs and photos; partner-owned photos keep the immutable partner slug and remain read-only in the panel. A later consent reactivates the same grant row, so that Source may write again. Revocation changes only grant authorization, not gallery ownership.