---
id: capability.wiki.overlay
name: Overlay-Before-Mutation Write Path
summary: Non-destructive edits (draft -> patch -> apply-under-drift) that let read-only, rate-limited, or lossy backends be edited safely without silent remote mutation.
owner: shard-wiki
status: draft
domain: helix_forge
tags: [wiki, overlay, patch, write-path, conflict, shard-wiki]

maturity:
  discovery:
    current: D5
    target: D6
    confidence: high
    rationale: >
      Overlay lifecycle and apply-under-drift semantics are specified (ADR-05, blueprint
      Section 8.6) and implemented as a single principled write path.
  availability:
    current: A2
    target: A4
    confidence: medium
    rationale: >
      OverlayEngine (draft/patch/apply), writable adapter, and InformationSpace.edit
      exist as a source module; three-way merge is not (refuse-on-drift only).

external_evidence:
  completeness:
    level: C2
    name: Partial
    confidence: medium
    basis: scope_vs_intent_and_consumer_expectations
    satisfied_expectations:
      - draft -> patch -> apply with fast-forward / refuse-on-drift / keep-draft outcomes
      - no silent remote mutation; overlay_state surfaced in provenance
    broken_expectations:
      - three-way / auto merge not implemented (refuse-on-conflict only)
    out_of_scope_expectations:
      - federation propagation of applied overlays
  reliability:
    level: R1
    confidence: low
    basis: consumer_quality_signals
    known_reliability_risks:
      - early implementation; conflict handling is detect-and-refuse only

discovery:
  intent: >
    Make any sub-write-through backend editable safely: an edit is an overlay first, applied
    only on explicit intent and only when the source has not drifted.
  includes:
    - overlay drafts recorded as coordination-canonical events
    - patch rendering (unified diff)
    - apply-under-drift (fast-forward / refuse / keep-draft)
  excludes:
    - destructive write without drift check
  use_cases:
    - "shard-wiki UseCaseCatalog UC-04, UC-26, UC-29 (remix primitives, overlay)"

availability:
  current_level: A2
  target_level: A4
  current_artifacts:
    - "shard-wiki/src/shard_wiki/coordination/overlay.py"
    - "shard-wiki/src/shard_wiki/coordination/patch.py"
  consumption_modes:
    - source module

relations:
  depends_on:
    - capability.wiki.coordination-journal
    - capability.wiki.adapter-contract

evidence:
  documentation:
    - "shard-wiki/spec/FederationRequirements.md (ADR-05)"
    - "shard-wiki/spec/CoreArchitectureBlueprint.md (Section 8.2, 8.6)"
  tests:
    - "shard-wiki/tests/test_apply.py"
    - "shard-wiki/tests/test_write_path_integration.py"

consumer_guidance:
  recommended_for:
    - safe editing over read-only / rate-limited / lossy backends
  not_recommended_for:
    - workflows needing automatic conflict resolution today
  known_limitations:
    - merge is detect-and-refuse; three-way merge is future work
---

# Overlay-Before-Mutation Write Path

One principled write path: every edit drafts an overlay (a coordination-canonical event),
renders as a patch, and applies under drift checks — fast-forwarding a writable target,
keeping a local draft on a read-only target, and refusing (never clobbering) on external drift.

## Assessment notes

### Discovery
Specified in FederationRequirements ADR-05 and CoreArchitectureBlueprint Section 8.2/8.6.

### Availability
`overlay.py` + `patch.py` + `InformationSpace.edit` ship the path; built in SHARD-WP-0008.