spec(categories): define canonical .comapeocat import semantics before re-enabling UI

Decision required

The existing .comapeocat import code persists a category-set record in a separate local Dexie database (comapeo-categories), while the live application primarily consumes project/archive category and preset state from the server-backed project data flow.

useCategorySets() currently summarizes the local imported sets but is not consumed by production UI. Categories Editor uses useApiPresets() against the archive/server. Re-enabling the import UI without first defining the source of truth could make an imported set appear authoritative in one surface while observations, filters, exports, the archive, or mobile clients continue using a different category configuration.

This issue is therefore an architecture/product specification issue first. Do not dispatch it directly as an implementation task until the decisions below are recorded.

Questions to resolve

1. Source of truth

Is an imported .comapeocat set:

• canonical project/server state, synchronized with the archive/project; or
• an explicitly local-only override for this browser/application instance?

Name the authoritative source explicitly.

2. If canonical/server-backed

Define:

• which comapeo-cloud/archive API mutation owns the import
• where the imported set is persisted
• how it is synchronized to other clients
• what category/preset/set IDs and versions are canonical
• whether backend/API work is required before Cloud App implementation

3. If local-only

Identify every surface that must consume the override consistently, including at minimum:

• Categories Editor
• Data/category filters
• category labels and icons
• observation display names
• category metadata hooks
• exports
• any authoring/creation path that uses category/preset IDs

A local-only design must explicitly describe what remote/mobile clients see for data created or viewed with the override.

4. Identity and conflicts

Define conflict identity and precedence for:

• category ID
• preset document ID / logical preset identity
• preset/category version
• set ID

Define exactly what Replace existing replaces. A matching set ID alone is not enough unless that is intentionally the canonical conflict boundary.

5. Sync/resync semantics

Define:

• what happens after archive/project synchronization
• whether server state can overwrite a local import
• whether a local import survives reload/reconnect
• how deleted/updated remote presets interact with imported state
• whether local imports can create or label observations in a way the archive/mobile side cannot interpret

6. Offline semantics

Define:

• what import/view/edit behavior works offline
• what is local-only vs queued for later server mutation
• what happens when connectivity returns and canonical state differs

Acceptance criteria for this spec issue

• Architecture decision recorded in this issue or an ADR
• Canonical source of truth explicitly named
• Canonical/server-backed vs local-only semantics decided
• Category, preset, version, and set identity/conflict semantics defined
• "Replace existing" semantics defined precisely
• Sync, reload, reconnect, and resync behavior defined
• Offline behavior and reconciliation defined
• All category-consuming surfaces identified and assigned consistent behavior
• Cross-client/archive/mobile interpretation risk addressed
• Backend/API dependency documented if canonical import requires server support
• Follow-up implementation issue(s) created only after these decisions make their scopes executable

Existing code to preserve during discovery

• .comapeocat Valibot parsing/validation
• local category-set persistence helpers
• import dialog code and i18n that can be reused if compatible with the chosen architecture

Do not re-enable the UI merely to make imported local records visible in Categories Editor before the source-of-truth decision is complete.

Start by tracing useCategorySets(), useApiPresets(), the local category-set persistence helpers, and the import dialog and i18n mentioned in the issue. Map every category-consuming surface, then record the source-of-truth, identity, conflict, sync, reconnect, and offline decisions in this issue or an ADR. Done means the acceptance checklist is complete and executable follow-up issues exist.