reuse-surface/registry/capabilities/capability.wiki.overlay.md

id, name, summary, owner, status, domain, tags, maturity, external_evidence, discovery, availability, relations, evidence, consumer_guidance

id	name	summary	owner	status	domain	tags	maturity	external_evidence	discovery	availability	relations	evidence	consumer_guidance
capability.wiki.overlay	Overlay-Before-Mutation Write Path	Non-destructive edits (draft -> patch -> apply-under-drift) that let read-only, rate-limited, or lossy backends be edited safely without silent remote mutation.	shard-wiki	draft	helix_forge	wiki overlay patch write-path conflict shard-wiki	discovery availability current target confidence rationale D5 D6 high Overlay lifecycle and apply-under-drift semantics are specified (ADR-05, blueprint Section 8.6) and implemented as a single principled write path. current target confidence rationale A2 A4 medium OverlayEngine (draft/patch/apply), writable adapter, and InformationSpace.edit exist as a source module; three-way merge is not (refuse-on-drift only).	completeness reliability level name confidence basis satisfied_expectations broken_expectations out_of_scope_expectations C2 Partial medium scope_vs_intent_and_consumer_expectations draft -> patch -> apply with fast-forward / refuse-on-drift / keep-draft outcomes no silent remote mutation; overlay_state surfaced in provenance three-way / auto merge not implemented (refuse-on-conflict only) federation propagation of applied overlays level confidence basis known_reliability_risks R1 low consumer_quality_signals early implementation; conflict handling is detect-and-refuse only	intent includes excludes use_cases 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. overlay drafts recorded as coordination-canonical events patch rendering (unified diff) apply-under-drift (fast-forward / refuse / keep-draft) destructive write without drift check shard-wiki UseCaseCatalog UC-04, UC-26, UC-29 (remix primitives, overlay)	current_level target_level current_artifacts consumption_modes A2 A4 shard-wiki/src/shard_wiki/coordination/overlay.py shard-wiki/src/shard_wiki/coordination/patch.py source module	depends_on capability.wiki.coordination-journal capability.wiki.adapter-contract	documentation tests shard-wiki/spec/FederationRequirements.md (ADR-05) shard-wiki/spec/CoreArchitectureBlueprint.md (Section 8.2, 8.6) shard-wiki/tests/test_apply.py shard-wiki/tests/test_write_path_integration.py	recommended_for not_recommended_for known_limitations safe editing over read-only / rate-limited / lossy backends workflows needing automatic conflict resolution today 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.