blockpatch 1.0.0 → 1.1.0

package/docs/behavior.md

@@ -0,0 +1,207 @@
+# blockpatch Behavior
+
+`blockpatch` is intentionally strict. It prefers refusing a patch over guessing, regenerating bytes, or applying a fuzzy edit.
+
+For CLI forms, see [Commands](commands.md). For the `.blockpatch` artifact format and JSON contracts, see [Patch spec](spec.md).
+
+## Core Invariant
+
+A move transfers one exact, hash-verified payload between endpoints. In a paired move, the source hunk removes exact bytes and the target hunk adds the same exact bytes, so `blockpatch` moves the original source bytes instead of regenerating them.
+
+The payload hash is checked before any write happens. For paired moves, the source `-` payload and target `+` payload must be byte-identical.
+
+## Planning And Retry Flow
+
+`plan --json -` is the canonical planning handshake. It is a thin alias for `blockpatch move --json - --diff --json-output`: it validates the provided source delimiters and/or target anchors, computes byte ranges, hashes the selected or supplied payload, renders the exact reviewable `.blockpatch`, self-checks that patch through the same in-memory `check` path, lists affected files, and returns the patch in the JSON `patch` field without mutating the working tree.
+
+`move --json --diff` is a planner for the current tree. For relocation, in-file deletion, and whole-file removal, the JSON request selects the payload from the current source file; if that source block or file is already gone, the JSON request often cannot prove the final state because it does not carry the moved bytes. The generated `.blockpatch` is the retry/idempotence artifact because it carries the payload and can report `already_applied` from the final state. Target-only insertion and `create_file` JSON are the exceptions because they include `payload` directly.
+
+A typical flow is: propose a move as JSON, let `blockpatch` validate and render the exact patch, show that patch to the user, then apply the `.blockpatch` in a second explicit step. Retry the `.blockpatch`, not the source-selected JSON plan.
+
+## Path Containment
+
+Patch-declared source and destination paths, and move JSON `src`/`dst` paths, must be relative, non-empty, and resolve inside `--cwd`.
+
+Rejected operation paths include:
+
+- absolute paths
+- `.` or `..` path segments
+- backslashes; operation paths use POSIX-style `/` separators in `.blockpatch` artifacts and move JSON
+- non-printing control characters
+- paths containing symlink components
+- existing regular files whose real path escapes `--cwd`
+
+Patch files and move JSON files may be read from any path; use `--cwd` to choose the directory the operation is allowed to modify.
+
+Relative patch file paths and relative move JSON file paths resolve from the shell working directory, not from `--cwd`. Operation paths declared inside a patch or move JSON request resolve inside `--cwd`.
+
+`/dev/null` is reserved for path absence and is never resolved, opened, or checked against `--cwd`. An empty file is a real endpoint while `/dev/null` is the null endpoint. A missing file is an error unless the patch explicitly says `/dev/null`; missing files never silently resolve as empty files.
+
+## Exact Matching
+
+Source and target anchors are byte-exact. There is no fuzzy matching, regex matching, AST parsing, or formatting.
+
+For source hunks, `blockpatch` locates exactly one source match for:
+
+```text
+source context before + payload + source context after
+```
+
+For target hunks in existing files, `blockpatch` locates exactly one target match for:
+
+```text
+target context before + target context after
+```
+
+For target hunks in existing files, insertion occurs between target-before and target-after context:
+
+```diff
+@@ -40,2 +40,3 @@ blockpatch-target id=move-1
+ context before
++moved payload
+ context after
+```
+
+The moved bytes are extracted from the source file, not regenerated from arguments. `apply` and `check` preserve parsed hunk body bytes exactly, including CRLF and no-trailing-newline cases.
+
+## Move JSON Behavior
+
+Matching and insertion are byte-exact: the moved bytes are cut at the source and inserted directly at the anchor boundary, with no newline handling. Keep delimiters and anchors on line boundaries or the result will splice mid-line. Include the surrounding newlines you want moved in `src_start` and `src_end`.
+
+For source selection, each `src_start` match pairs with the first `src_end` occurrence after it. The resulting source delimiter match must be unique.
+
+For target placement:
+
+- insertion is between the before and after contexts, and their concatenation must match exactly once.
+- if only `target_before` is supplied, insertion is immediately after that context.
+- if only `target_after` is supplied, insertion is immediately before that context.
+- either target side may be empty when both are supplied, but not both may be empty.
+
+When `expected_payload_sha256` is supplied, the moved or materialized payload bytes must hash to that value before any write happens.
+
+Same-file source and target overlap is a hard failure.
+
+`move --json` and generated `move --diff` output render anchors and payloads as UTF-8 text, so they are not a binary-safe round trip for invalid UTF-8.
+
+## Patch Evaluation
+
+For one patch, `blockpatch`:
+
+1. Parses one same-file section with source+target, source-only, or target-only hunks; or parses two cross-file relocation sections tied by `role=source` and `role=target`.
+2. Verifies hunk ids match `blockpatch move id=<id>`.
+3. Extracts source payload from contiguous `-` lines when a source hunk exists.
+4. Extracts target payload from contiguous `+` lines when a target hunk exists.
+5. For paired moves, verifies target payload exactly equals source payload.
+6. Verifies `payload-sha256` matches the exact moved or materialized payload bytes.
+7. For source hunks, locates exactly one source match for `source context before + payload + source context after`.
+8. For target hunks in existing files, locates exactly one target match for `target context before + target context after`.
+9. Fails if a same-file target context range overlaps the source payload bytes.
+10. Applies the hunk transition: remove source payload, insert target payload, or both.
+11. Applies any path-state transition from `/dev/null`: create the missing destination path or remove the source path.
+12. Writes changed files with temp-file-and-rename replacement.
+
+Line-number ranges are review hints only. `blockpatch` validates hunk body line counts, but it locates changes by exact context and payload bytes.
+
+## One-Sided And Null-Endpoint Behavior
+
+Rules for target-only insertion into an existing file:
+
+- the section contains exactly one `blockpatch-target` hunk and no source hunk.
+- the payload comes from the `+` lines and must match `payload-sha256`.
+- the file must exist; missing files are not treated as empty files.
+- `target context before + target context after` must match exactly once; the payload is inserted at the boundary.
+- at least one side of target context is required, so arbitrary zero-byte in-file insertions are not valid.
+- if `target before + payload + target after` is already present exactly once, the result is `already_applied`.
+
+Rules for source-only deletion from an existing file:
+
+- the section contains exactly one `blockpatch-source` hunk and no target hunk.
+- the file must exist; missing files are not treated as empty files.
+- `source context before + payload + source context after` must match exactly once; the payload bytes are removed.
+- if removal leaves zero bytes, the file remains as an empty file.
+- retries are idempotent when both source anchors are adjacent, when the remaining after anchor is at the start of the file, when the remaining before anchor is at the end of the file, or when an anchorless payload is absent.
+
+Rules for `/dev/null -> file` creation:
+
+- the section contains exactly one `blockpatch-target` hunk and no source hunk.
+- the target hunk must be whole-file payload: only contiguous `+` payload lines, with no context lines.
+- zero-byte payload is valid and creates an empty file.
+- a missing destination is created, including parent directories; new files are created with mode 0644.
+- if the destination already exists with exactly the requested bytes, the result is `already_applied`; if it exists with different bytes, the patch fails.
+
+Rules for `file -> /dev/null` removal:
+
+- the section contains exactly one `blockpatch-source` hunk and no target hunk.
+- the source hunk must be whole-file payload: only contiguous `-` payload lines, with no context lines.
+- zero-byte payload is valid and removes an empty file.
+- the existing file bytes must exactly equal the source payload; then the path is removed.
+- if the source path is already missing, the result is `already_applied`.
+
+## Idempotence
+
+If the requested final state is already present, `blockpatch` reports `already_applied`.
+
+For paired moves, that means the source full match is absent and:
+
+```text
+target context before + payload + target context after
+```
+
+is present exactly once.
+
+For one-sided and null-endpoint shapes, the `already_applied` conditions are listed per shape in [One-Sided And Null-Endpoint Behavior](#one-sided-and-null-endpoint-behavior).
+
+This is strict retry idempotence. It does not search fuzzily or infer moved bytes.
+
+## Reverse Application
+
+`-R`/`--reverse` swaps source and target hunk roles: reversing a target-only insertion deletes the inserted payload, reversing a source-only deletion re-inserts the payload, reversing a file creation removes the created file, and reversing a file removal recreates it.
+
+Reverse application is exact and non-fuzzy. A payload-only source hunk has no source-side anchor for reverse insertion, so reverse requires source context before or after unless it is a whole-file path recreation.
+
+## Write Behavior
+
+Same-file moves are atomic at file-replacement granularity. Cross-file moves preflight both files and stage all changed temp files before renaming any original. If staging fails, originals are left untouched.
+
+Before renaming or removing a path, `blockpatch` re-checks that every existing file still matches the bytes and stat captured during planning. For path creation, it re-checks that the destination is still absent or already contains the exact expected bytes. If the live path no longer matches the verified input state, the operation fails with `concurrent_modification`.
+
+Once renames begin, a two-file operation is not transactional. The destination is renamed before the source, so an interruption can duplicate the payload, but should not delete it from both files. Atomic here means per-file replacement, not a crash-durable multi-file transaction.
+
+If a retry sees that a cross-file source payload is still present while the destination already contains the exact final target state, `blockpatch` fails with `partial_applied_duplicate` instead of guessing. The error includes the source range, target range, payload hash, and `suggested_action: "review_then_remove_source"`.
+
+## Failure Rules
+
+`blockpatch` exits non-zero and does not modify files when:
+
+- the patch file is malformed
+- both endpoints are `/dev/null`
+- a patch-declared or move-declared source/destination path is absolute, invalid, or escapes `--cwd`
+- a referenced file is missing, unless the patch explicitly says `/dev/null` where creation or removal would make that legal
+- a referenced path is not a regular file, unreadable, unwritable, or otherwise hits a filesystem error
+- a target-only existing-file insertion has no target context
+- a `/dev/null -> file` creation targets an existing file with different bytes
+- a `file -> /dev/null` removal hunk does not match the whole file
+- source anchors are missing
+- source anchors or full source are ambiguous
+- a cross-file retry finds the source payload still present and the destination already patched
+- the located source payload does not exactly match the source hunk payload
+- target added payload does not exactly match source removed payload
+- `payload-sha256` does not match the moved payload
+- `move --diff` would need to render invalid UTF-8 bytes
+- the target anchor is missing
+- the target anchor is ambiguous
+- the target anchor overlaps the source payload
+- a file changes after `blockpatch` verifies it but before the planned write/remove
+- file I/O fails before a write completes
+
+## Intentionally Out Of Scope
+
+`blockpatch` does not implement:
+
+- multiple independent moves in one patch document
+- arbitrary generated diffs from before/after file snapshots
+- fuzzy matching
+- AST parsing
+- code formatting
+- copy operations
+- regex anchors

package/docs/commands.md

@@ -0,0 +1,84 @@
+# blockpatch Commands
+
+This document lists the supported CLI forms. For `.blockpatch`, move JSON, and JSON output contracts, see [Patch spec](spec.md). For planning, matching, idempotence, and write behavior, see [Behavior](behavior.md).
+
+## Common Commands
+
+```sh
+blockpatch check patch.blockpatch
+blockpatch apply patch.blockpatch --dry-run
+blockpatch apply patch.blockpatch
+blockpatch plan --json -
+blockpatch move --json -
+```
+
+`check` parses a patch and verifies it against the target tree without writing. `apply --dry-run` validates through the apply path without writing. `apply` writes the verified result. `plan` returns a reviewable `.blockpatch` for a move JSON request without writing; `move` applies the request directly.
+
+## Patch Input
+
+```sh
+blockpatch apply - < patch.blockpatch
+blockpatch apply < patch.blockpatch
+blockpatch apply -i patch.blockpatch
+```
+
+`apply` and `check` read the patch from stdin when no patch path is supplied. `-i`/`--input` names the patch file explicitly.
+
+## Paths And Stripping
+
+```sh
+blockpatch apply -d repo-root -p1 patch.blockpatch
+blockpatch check --cwd repo-root --strip 1 < patch.blockpatch
+```
+
+`-d`/`--directory` is an alias for `--cwd`. `-pN`/`--strip N` strips leading path components from patch-declared file paths. Unlike GNU `patch`, the default is `-p1`, matching the git-style `a/`/`b/` prefixes; use `-p0` only if your working tree contains literal `a/` and `b/` directories.
+
+## Reverse
+
+```sh
+blockpatch apply patch.blockpatch --reverse
+blockpatch check patch.blockpatch -R
+```
+
+`-R`/`--reverse` works with both `check` and `apply`.
+
+## Move JSON Input
+
+```sh
+blockpatch plan --json -
+blockpatch move --json -
+blockpatch move --json - --diff --json-output
+blockpatch move --json move.json
+```
+
+`--json -` reads the move request from stdin; `--json move.json` reads the same shape from a file. `plan` is shorthand for `move --json - --diff --json-output`: it validates the request and returns the rendered `.blockpatch` in the JSON `patch` field without writing. On `move`, `--dry-run` validates without writing, and `--diff` never writes: it prints the rendered patch, or returns it in the JSON `patch` field with `--json-output`.
+
+## Plan Envelope
+
+```sh
+blockpatch plan --json - < move.json > plan.json
+jq -r .patch plan.json > patch.blockpatch
+blockpatch apply patch.blockpatch
+```
+
+`plan` writes a single-line JSON envelope to stdout: `ok`, `changed`, `affected`, `status`, per-move byte ranges, and the rendered patch in the `patch` field, per the contract in [Patch spec](spec.md#json-output). Extract the `patch` field to save the reviewable artifact; `apply` accepts only the `.blockpatch`, never the envelope.
+
+## Move Flags
+
+```sh
+blockpatch move --src src/foo.ts --src-start $'\nfunction movedThing() {' --src-end $'\n}\n' --target-before $'class Target {\n'
+blockpatch move --src /dev/null --dst src/foo.ts --payload $'inserted bytes\n' --target-before $'context before\n'
+blockpatch move --src src/foo.ts --src-start $'\nfunction removeMe() {' --src-end $'\n}\n' --dst /dev/null
+```
+
+Each flag sets the move JSON field of the same name and cannot be combined with `--json`. `mode` has no flag form, so whole-file `create_file`/`remove_file` requests are JSON-only. JSON avoids shell quoting problems, so it is usually the more reliable form for agents.
+
+## Output
+
+```sh
+blockpatch apply patch.blockpatch --json-output
+blockpatch apply patch.blockpatch --explain
+blockpatch version --json-output
+```
+
+Without `--json-output`, successful commands print `changed <path>`, `would change <path>`, or `unchanged <path>`. `--json-output` switches success and error reporting to the JSON contract in [Patch spec](spec.md#json-output); `plan` always uses it. `--explain` implies `--json-output` plus, for `apply`, `move`, and `plan`, `--dry-run`, so it always reports without writing. `version` prints the CLI version.

package/docs/spec.md

@@ -0,0 +1,356 @@
+# blockpatch Spec
+
+This document defines the `.blockpatch` artifact format, move JSON request contract, and JSON output contract. The public API is the CLI and its JSON output; there is no library API.
+
+For command forms, see [Commands](commands.md). For planning, matching, idempotence, and write behavior, see [Behavior](behavior.md).
+
+## Format
+
+```diff
+diff --blockpatch a/src/example.ts b/src/example.ts
+blockpatch version 1
+blockpatch move id=move-1 payload-sha256=bc8a95d6eb2b44aa564dbae1040ba8ff2273988ea43f0f3b0c47228f9dba6b3d
+--- a/src/example.ts
++++ b/src/example.ts
+
+@@ -1,8 +1,4 @@ blockpatch-source id=move-1 function movedThing
+ function alpha() {
+ }
+-
+-function movedThing() {
+-  console.log("keep me exact");
+-}
+ function omega() {
+ }
+
+@@ -40,3 +36,7 @@ blockpatch-target id=move-1 constructor
+   constructor() {
+   }
++
++function movedThing() {
++  console.log("keep me exact");
++}
+   methodAfter() {
+```
+
+Same-file moves, insertions, and deletions use one file section. In that shape, the `--- a/<path>` and `+++ b/<path>` headers must name the same file after normal path cleanup.
+
+```text
+diff --blockpatch a/<path> b/<path>
+blockpatch version 1
+blockpatch move id=<id> payload-sha256=<sha256>
+--- a/<path>
++++ b/<path>
+
+@@ -<old-start>,<old-count> +<new-start>,<new-count> @@ blockpatch-source id=<id> optional label
+[ <source context before> ]
+-<moved payload>
+[ <source context after> ]
+
+@@ -<old-start>,<old-count> +<new-start>,<new-count> @@ blockpatch-target id=<id> optional label
+[ <target context before> ]
++<same moved payload>
+[ <target context after> ]
+```
+
+For relocation, include both hunks and the target `+` payload must equal the source `-` payload. For source-only deletion, omit the target hunk. For target-only insertion, omit the source hunk and the payload comes from the target `+` lines.
+
+Cross-file moves use two conventional file sections tied by the same move id and payload hash: one `role=source` section for the source file and one `role=target` section for the target file. Each section's `---` and `+++` headers name the same file. This avoids the misleading patch shape where `--- a/source.ts` and `+++ b/target.ts` look like a transformation from one filename into another.
+
+```text
+diff --blockpatch a/<source-path> b/<source-path>
+blockpatch version 1
+blockpatch move id=<id> role=source payload-sha256=<sha256>
+--- a/<source-path>
++++ b/<source-path>
+
+@@ -<old-start>,<old-count> +<new-start>,<new-count> @@ blockpatch-source id=<id> optional label
+[ <source context before> ]
+-<moved payload>
+[ <source context after> ]
+
+diff --blockpatch a/<target-path> b/<target-path>
+blockpatch version 1
+blockpatch move id=<id> role=target payload-sha256=<sha256>
+--- a/<target-path>
++++ b/<target-path>
+
+@@ -<old-start>,<old-count> +<new-start>,<new-count> @@ blockpatch-target id=<id> optional label
+[ <target context before> ]
++<same moved payload>
+[ <target context after> ]
+```
+
+Format constraints:
+
+- Every file section must declare `blockpatch version 1` on the line after `diff --blockpatch`.
+- The `a/` and `b/` prefixes are required, and each `diff --blockpatch` line must name the same two raw paths as that section's file headers. The prefixes are consumed by the default `-p1` path stripping ([Commands](commands.md#paths-and-stripping)).
+- Patch-declared paths use POSIX-style `/` separators on every platform. Backslashes, `.`/`..` path segments, and non-printing control characters are rejected instead of normalized or escaped.
+- `blockpatch move` metadata keys must be unique. The recognized keys are `id`, `payload-sha256`, and `role`; unknown keys are rejected unless they use the reserved `x-` extension prefix.
+- Source context before and after may each be empty.
+- Target hunks for existing files must include context on at least one side; either side may be empty, but not both.
+- Whole-file creation and removal hunks (a `/dev/null` endpoint) contain only contiguous payload lines, with no context lines.
+- The `-<old-start>,<old-count> +<new-start>,<new-count>` ranges must match the hunk body line counts, but the range values are line-number hints for review.
+
+## One-Sided Hunks And Null Endpoints
+
+One-sided hunks are for in-file insertion and deletion when the file exists both before and after the patch.
+
+Target-only insertion into an existing file:
+
+```diff
+diff --blockpatch a/src/example.ts b/src/example.ts
+blockpatch version 1
+blockpatch move id=move-1 payload-sha256=<sha256 of the added payload>
+--- a/src/example.ts
++++ b/src/example.ts
+
+@@ -1,2 +1,3 @@ blockpatch-target id=move-1
+ context before
++inserted line
+ context after
+```
+
+Source-only deletion from an existing file:
+
+```diff
+diff --blockpatch a/src/example.ts b/src/example.ts
+blockpatch version 1
+blockpatch move id=move-1 payload-sha256=<sha256 of the removed payload>
+--- a/src/example.ts
++++ b/src/example.ts
+
+@@ -1,3 +1,2 @@ blockpatch-source id=move-1
+ context before
+-doomed line
+ context after
+```
+
+`/dev/null` is reserved for path absence. It appears bare, without an `a/` or `b/` prefix, exactly as in git diffs, so it can never collide with a real file named `dev/null` (which would appear as `a/dev/null`).
+
+Use `/dev/null` only when the file path itself is absent before or after the patch. A `/dev/null -> file` section is the whole-file creation shape:
+
+```diff
+diff --blockpatch /dev/null b/src/new.txt
+blockpatch version 1
+blockpatch move id=move-1 payload-sha256=<sha256 of the file payload>
+--- /dev/null
++++ b/src/new.txt
+
+@@ -0,0 +1,2 @@ blockpatch-target id=move-1
++first line
++second line
+```
+
+A `file -> /dev/null` section is the whole-file removal shape:
+
+```diff
+diff --blockpatch a/src/old.txt /dev/null
+blockpatch version 1
+blockpatch move id=move-1 payload-sha256=<sha256 of the file payload>
+--- a/src/old.txt
++++ /dev/null
+
+@@ -1,2 +0,0 @@ blockpatch-source id=move-1
+-first line
+-second line
+```
+
+The section shapes and their meaning:
+
+| Shape | Meaning |
+| --- | --- |
+| `file -> file`, source + target hunks | relocation |
+| `file -> file`, target hunk only | insert payload into an existing file |
+| `file -> file`, source hunk only | delete payload from an existing file |
+| `/dev/null -> file`, target hunk only | create a file |
+| `file -> /dev/null`, source hunk only | remove a file |
+| `/dev/null -> /dev/null` | invalid |
+
+Matching rules, idempotence, reverse application, and write behavior are documented in [Behavior](behavior.md).
+
+## Byte Rules
+
+Hunk body lines use unified-diff prefixes:
+
+- space for context
+- `-` for source payload
+- `+` for target payload
+
+The byte content after the prefix is matched exactly, including line endings. The standard `` marker is supported for a hunk body line without a trailing newline.
+
+Blank lines are separators between the header and hunks. A blank line inside a hunk body is an error; encode an empty context line as a single space.
+
+## Move JSON
+
+Move JSON is the request contract accepted by `blockpatch plan --json` and `blockpatch move --json`.
+
+```ts
+type MoveBlockArgs = {
+  src: string
+  src_start?: string
+  src_end?: string
+  dst?: string
+  payload?: string
+  target_before?: string
+  target_after?: string
+  expected_payload_sha256?: string
+  mode?: "create_file" | "remove_file"
+  dry_run?: boolean
+}
+```
+
+Request shapes:
+
+- For relocation, `src_start` and `src_end` are inclusive source delimiters, and `dst` defaults to `src`.
+- For deletion, set `dst` to `/dev/null`; `src_start` and `src_end` select the removed payload.
+- For insertion, set `src` to `/dev/null`; `dst`, `payload`, and target context are required.
+- For file creation, set `src` to `/dev/null`, set `mode` to `create_file`, and provide `dst` plus `payload`. Empty payload is valid and creates an empty file.
+- For file removal, set `dst` to `/dev/null` and set `mode` to `remove_file`. The whole source file is selected as the payload.
+- `mode` selects the whole-file path shapes; without it, `/dev/null` endpoints denote in-file insertion/deletion. `move --diff` renders the in-file shapes as same-file one-sided sections and the `mode` shapes with `/dev/null` file headers.
+- `target_before`, `target_after`, or both are required for relocation and insertion.
+- `payload` is only valid when `src` is `/dev/null`; it must be non-empty for in-file insertion.
+- `expected_payload_sha256` is optional.
+
+Insertion:
+
+```json
+{
+  "src": "/dev/null",
+  "dst": "src/foo.ts",
+  "payload": "inserted bytes\n",
+  "target_before": "context before\n"
+}
+```
+
+Deletion:
+
+```json
+{
+  "src": "src/foo.ts",
+  "src_start": "function removeMe() {\n",
+  "src_end": "}\n",
+  "dst": "/dev/null"
+}
+```
+
+File creation:
+
+```json
+{
+  "src": "/dev/null",
+  "dst": "src/new.ts",
+  "payload": "export const x = 1;\n",
+  "mode": "create_file"
+}
+```
+
+File removal:
+
+```json
+{
+  "src": "src/old.ts",
+  "dst": "/dev/null",
+  "mode": "remove_file",
+  "expected_payload_sha256": "<sha256>"
+}
+```
+
+Matching behavior for move JSON requests is documented in [Behavior](behavior.md#move-json-behavior).
+
+## JSON Output
+
+With `--json-output`, successful commands print:
+
+```ts
+type ApplyResult = {
+  ok: true
+  changed: string[]
+  affected: string[]
+  written: boolean
+  noop: boolean
+  status: "applied" | "noop" | "already_applied"
+  strip_components?: number
+  patch?: string
+  moves: Array<{
+    id: string
+    src: string
+    dst: string
+    payload_sha256: string
+    payload_bytes: number
+    source_range: { start: number; end: number } | null
+    target_range: { start: number; end: number } | null
+    insert_index: number | null
+  }>
+}
+```
+
+`changed` lists paths whose content changed, or would change during `check`, `--dry-run`, `--diff`, and `--explain`. `written` is true only when files were actually replaced by the command; it is false for `check`, `--dry-run`, `--diff`, `--explain`, `noop`, and `already_applied`. `affected` lists paths examined by the patch. `noop` is true when the patch validated but produced identical bytes.
+
+`status` is `applied` for a normal computed move, `noop` for a computed move whose output bytes are identical, and `already_applied` when the command can prove the requested final state is already present. `strip_components` is present for `check` and `apply` JSON success output and reports the effective `-p` path-stripping count; it defaults to `1`.
+
+`patch` is present when `move --diff --json-output` is used. In `already_applied` relocation results, `source_range` is `null` because the source block is no longer present. For target-only insertions, `source_range` is `null`. For source-only deletions, `target_range` and `insert_index` are `null`. For path creation/removal, `src` or `dst` is the string `/dev/null`.
+
+With `--json-output`, errors print:
+
+```ts
+type BlockPatchJsonError = {
+  ok: false
+  error: {
+    code: BlockPatchErrorCode
+    message: string
+    field?: string
+    path?: string
+    phase?: string
+    anchor?: string
+    matches?: number
+    matches_truncated?: boolean
+    ranges?: Array<{ start: number; end: number }>
+    line_ranges?: Array<{ start: number; end: number }>
+    source_range?: { start: number; end: number }
+    target_range?: { start: number; end: number }
+    payload_sha256?: string
+    suggested_action?: string
+  }
+}
+```
+
+Ambiguous-match errors include up to the first 10 exact byte ranges for the matched anchors or candidate source ranges, plus matching 1-based inclusive `line_ranges` when the relevant file bytes are available. When `matches_truncated` is true, `matches` is a lower bound rather than an exact count. They do not include source snippets, fuzzy suggestions, or repair guidance.
+
+`partial_applied_duplicate` reports an interrupted cross-file apply state where the source payload is still present and the destination already contains the exact final target state. It includes `source_range`, `target_range`, `payload_sha256`, and `suggested_action: "review_then_remove_source"`. `blockpatch` does not auto-repair this state.
+
+Error codes are the agent-facing branch contract: branch on `error.code`, not on human-readable messages. Removing a code or changing its meaning is semver-major.
+
+```ts
+type BlockPatchErrorCode =
+  | "parse_error"
+  | "invalid_path"
+  | "path_outside_cwd"
+  | "symlink_path"
+  | "file_not_found"
+  | "not_regular_file"
+  | "permission_denied"
+  | "io_error"
+  | "source_not_found"
+  | "source_ambiguous"
+  | "target_not_found"
+  | "target_ambiguous"
+  | "destination_exists"
+  | "concurrent_modification"
+  | "partial_applied_duplicate"
+  | "payload_mismatch"
+  | "hash_mismatch"
+  | "invalid_utf8"
+  | "target_overlaps_source"
+  | "invalid_move_args"
+  | "invalid_json"
+  | "missing_move_args"
+  | "unknown_command"
+  | "unknown_option"
+  | "invalid_option"
+  | "missing_option_value"
+  | "too_many_args"
+  | "unexpected_error"
+```
+
+`unexpected_error` is the generic fallback for non-`BlockPatchError` failures; agents should treat it as an internal failure and avoid branching on its message.

package/examples/README.md

@@ -0,0 +1,15 @@
+# Examples
+
+Each successful example contains:
+
+- `patch.blockpatch`: the reviewed patch artifact.
+- `work/`: the before-state tree used by `-d`.
+- `expected/`: the after-state tree after applying the patch.
+
+Check an example without writing:
+
+```sh
+blockpatch check examples/same-file-relocation/patch.blockpatch -d examples/same-file-relocation/work
+```
+
+To apply without changing the checked-in example tree, copy `work/` to a scratch directory and use that as `-d`.

package/examples/create-file/README.md

@@ -0,0 +1,9 @@
+# Create File
+
+Creates `file.txt` from a whole-file `/dev/null -> file` patch.
+
+```sh
+blockpatch check patch.blockpatch -d work
+blockpatch apply patch.blockpatch -d work
+diff -u expected/file.txt work/file.txt
+```

package/examples/create-file/expected/file.txt

@@ -0,0 +1 @@
+created file