Module patch 

weave patch — the WRITE side of the agent contract.

The read side (weave-findings.schema.json) tells an agent what a merge did. This is the symmetric half: how an agent says what it wants, in the same vocabulary, over the same keys.

Why ops rather than a diff

A textual diff is a statement about line numbers, and line numbers are the first thing to rot. extract emits a typed op per entity, drawn from a fixed set: added, edited, renamed, rename_edited, deleted. An op names an entity, so it survives everything that moved around it.

apply is a merge, not a patch

The interesting case is a target that has drifted from the base the ops were extracted against. git apply answers that with fuzz and rejects; weave answers it with the merge it already knows how to do:

  apply(ops, target) = entity_merge(
      base   = the base the ops were extracted from,
      ours   = target,                      // what is actually on disk
      theirs = naive_apply(ops, base),      // what the ops intended
  )

This formulation is what makes drift honest. theirs is the author’s intent reconstructed in the author’s own world; ours is reality; base is the common ancestor they actually share. Anything else — applying ops straight to a drifted target — silently resolves a three-way situation with two-way information, and that is exactly where patch tools lose edits.

When the ops carry no base, or the target is the base, the merge degenerates (ours == base ⟹ result is theirs) and apply short-circuits to the naive application. That degeneracy falls out of 3-way merge itself, not a special case bolted on — and it keeps the naive result byte-for-byte.

The exactness escape hatch

extract verifies itself: it applies the ops it just produced back onto the base and compares with the changed file. When entity granularity cannot express the change (a rewritten module docstring, reordered entities, a changed shebang), it says so — exact: false — and appends a whole-file fallback op. The read side has no counterpart — a line-level fallback merge returns an empty audit trail there, so it reports nothing. The round trip then still holds byte-for-byte, and the document is honest about having lost entity granularity instead of quietly dropping the difference.

Structs

ApplyReport

BaseRef

What the ops were extracted against.

OpsDoc

deny_unknown_fields here and on the two types below is not strictness for its own sake: schema/weave-ops.schema.json says additionalProperties: false at all three levels, and until now this decoder accepted documents its own published schema rejects. A misspelled entitiy used to be discarded in silence.

PatchOp

Enums

ApplyMode

Op

The op alphabet, exactly as schema/weave-ops.schema.json enumerates it.

OpsDocError

Why an ops document could not be read.

PatchError

Why an ops document could not be applied.

Constants

FILE_KEY

The entity key used for a whole-file fallback op. Mirrors the read side’s convention for findings that are about the file rather than an entity.

Functions

apply

Apply doc to target.

extract

Compute the ops that turn base into changed.

parse_ops_doc

Decode an ops document, or say which way it was not one.