tasknotes-spec 0.2.0

package/08-compatibility-and-migrations.md

@@ -0,0 +1,188 @@
+# 8. Compatibility and Migrations
+
+## 8.1 Purpose
+
+This section defines how implementations transition from historical behavior to canonical specification behavior without silent data breakage.
+
+## 8.2 Compatibility modes
+
+Implementations MAY support compatibility modes for legacy behavior.
+
+If supported, compatibility modes MUST:
+
+- be explicitly enabled or disabled,
+- be discoverable through configuration or capability metadata,
+- not be silently enabled by default in new collections.
+
+## 8.3 Migration expectations
+
+When canonical behavior differs from historical behavior, implementations SHOULD provide:
+
+1. deterministic migration rules,
+2. dry-run preview support,
+3. rollback-safe workflow guidance.
+
+## 8.4 Alias normalization migration
+
+For legacy key aliases, a migration SHOULD:
+
+- read both canonical and alias keys,
+- choose canonical value deterministically (recommended: canonical key precedence),
+- rewrite persisted file using canonical keys,
+- preserve unrelated unknown fields.
+
+### 8.4.1 Example
+
+Before:
+
+```yaml
+recurrenceAnchor: scheduled
+recurrence_anchor: completion
+```
+
+After normalization:
+
+```yaml
+recurrenceAnchor: scheduled
+```
+
+With warning:
+
+- `alias_conflict_ignored`: alias value ignored because canonical key present.
+
+## 8.5 Temporal normalization migration
+
+If historical writes include mixed datetime styles, migration SHOULD normalize to canonical UTC ISO `Z` for datetime roles while preserving date-only roles as dates.
+
+Example:
+
+Before:
+
+```yaml
+dateCreated: 2026-02-20 10:00:00+00:00
+```
+
+After:
+
+```yaml
+dateCreated: 2026-02-20T10:00:00Z
+```
+
+## 8.6 Recurrence state migration
+
+If historical data allows overlapping complete/skip dates, migration MUST resolve overlap deterministically.
+
+Recommended resolution policy:
+
+- if overlap exists, prefer most recent user action where recoverable,
+- otherwise prefer `complete_instances` and remove overlapping skip entries,
+- emit migration report for affected dates.
+
+Policy choice MUST be documented.
+
+## 8.7 Materialized occurrence migration
+
+When introducing materialized occurrence notes into an existing collection, implementations SHOULD avoid automatic bulk creation.
+Recommended migration behavior:
+
+- do not materialize historical or future occurrence notes unless explicitly requested;
+- preserve existing parent `complete_instances` and `skipped_instances`;
+- when importing existing per-occurrence task files, require deterministic parent/date matching before adding `recurrence_parent` and `occurrence_date`;
+- when materialized occurrence state conflicts with parent instance lists, prefer the occurrence note for that date and report `occurrence_state_conflict`;
+- provide a dry-run report before converting existing task files into materialized occurrence notes.
+
+Migration tooling MUST NOT silently delete occurrence notes or parent recurring tasks.
+
+## 8.8 Dependency migration
+
+When migrating legacy dependency data, implementations SHOULD:
+
+- normalize dependency key names to mapped canonical key,
+- ensure each entry has `uid` and canonical `reltype`,
+- normalize legacy string/path references into configured canonical reference style,
+- remove duplicate dependency entries by policy.
+
+If historical data omits `reltype`, migration MAY apply `dependencies.default_reltype` and SHOULD report count of inferred values.
+
+## 8.9 Reminder migration
+
+When migrating legacy reminder data, implementations SHOULD:
+
+- normalize reminder key names,
+- normalize `type` values to canonical enum (`absolute` or `relative`),
+- normalize `relatedTo` values to canonical enum (`due` or `scheduled`),
+- normalize `absoluteTime` to canonical UTC ISO `Z`,
+- validate and normalize offsets to ISO 8601 duration syntax.
+
+If reminder `id` values are missing, migration MAY generate IDs and MUST report generated count.
+
+## 8.10 Link migration
+
+When migrating legacy link values, implementations SHOULD:
+
+- normalize supported link syntaxes according to §11 parsing rules,
+- preserve alias and anchor components where possible,
+- normalize resolved targets into canonical write format by policy,
+- detect and report ambiguous links instead of silently choosing non-deterministically.
+
+## 8.11 Divergence register
+
+Implementations SHOULD maintain a divergence register with columns:
+
+- section
+- current behavior
+- target canonical behavior
+- migration strategy
+- deprecation timeline
+
+## 8.12 Deprecation policy
+
+For any behavior deprecated by the specification:
+
+1. announce deprecation in release notes,
+2. provide warning period,
+3. provide migration tooling where feasible,
+4. remove deprecated behavior only in a version aligned with compatibility commitments.
+
+## 8.13 Data safety requirements
+
+Migrations MUST NOT:
+
+- silently drop unknown fields,
+- silently convert valid date-only fields to datetime,
+- silently rewrite recurrence semantics without explicit policy,
+- silently materialize occurrence notes outside explicit user/configured materialization policy,
+- silently delete materialized occurrence notes during recurrence edits,
+- silently drop unresolved dependency entries,
+- silently rewrite link targets to different destinations without explicit policy,
+- silently delete reminders unless explicitly requested.
+
+## 8.14 Suggested migration report format
+
+```yaml
+spec_version_from: 0.1.0-draft
+spec_version_to: 0.2.0-draft
+files_scanned: 214
+files_changed: 67
+warnings:
+  alias_conflict_ignored: 3
+  instance_state_overlap_resolved: 2
+  occurrence_state_conflict: 1
+  unresolved_dependency_target: 4
+changes:
+  normalized_datetime_fields: 41
+  alias_keys_removed: 29
+  instance_overlaps_fixed: 2
+  occurrence_state_conflicts: 1
+  inferred_dependency_reltype: 5
+  generated_reminder_ids: 8
+  normalized_link_targets: 14
+```
+
+## 8.15 Compatibility statement example
+
+```text
+Compatibility mode: legacy-aliases=true, legacy-timeentry-duration=true
+Planned removal: v2.0.0
+Migration command: tasknotes migrate --normalize-frontmatter
+```