@ansonlai/docx-redline-js 0.7.1 → 0.7.2

package/AGENTS.md

@@ -21,53 +21,39 @@ specific advanced operation, API, or recovery topic you need.
 
 ## Ordinary document edits
 
-For a literal mechanical edit with known old and new text, try one fail-closed
-apply call. When global matching is too broad, use a longer, fairly unique
-nearby phrase plus a directional range:
-
-```bash
-docx-redline apply contract.docx --search "distinctive nearby heading or phrase" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
-```
-
-Generic or repeated anchors widen the unioned scope and may return
-`AMBIGUOUS_TARGET`, costing a recovery turn. On success, treat
-`results[i].change.context.anchorMatchCount > 1` as a signal to confirm the
-returned location and excerpts.
-
-For semantic drafting, inspect once and apply once. With a structured wrapper,
-use revision-bound handles. For shell-only work, use serializer-backed stdin:
+Use one focused extraction and one apply call. With a structured wrapper, use
+its revision-bound target handles. For shell-only work, use serializer-backed
+stdin and the explicit agent profile:
 
 ```bash
 docx-redline extract contract.docx --search "termination" --around 3
 node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
 ```
 
-A single deleted paragraph found in rejected view can be restored verbatim with
-`apply --restore --target-id ID`; add one `--find`/`--replace` pair for a small
-exact correction. This shortcut does not infer ranges or companion paragraphs.
-
-For every ordinary text operation, `modified` is the complete desired
-accepted-view content. Copy inspected `exactText` verbatim and include
-`paragraphId` or `fingerprint`. Independent strong targets are bound against the
-batch-start document, so do not manually sort around structural edits.
-Consolidate incompatible writes to the same source; use captures for intentional
-created-content dependencies.
-
-Require `completion: true`, `written: true`, a non-null output path, and no
-per-operation errors. Localized edits also require
-`results[i].change.committed: true`, `finalDisposition: "applied"`, and
-`verification.acceptedViewMatchesCompiledText: true`. Follow
+Retain inspected `exactText` for drafting and target with its compact
+`paragraphId` plus `fingerprint`. Use complete `modified` text for a broad
+semantic revision; for a small literal change, use `replacements` so the apply
+payload need not repeat the whole paragraph. Independent strong targets bind to the batch start, so do
+not manually sort around structural edits. Consolidate incompatible writes to
+one source; use captures only for intentional created-content dependencies.
+
+If the user requests restoration, search `--view rejected` directly. Otherwise
+follow `selection.hint` if extraction identifies an alternate revision view.
+Restore only the inspected strong target; do not infer adjacent content.
+
+Require `completion: true` and a non-null output path. Follow
 `error.recovery.action` and `retryPlan`; never retry unchanged failed arguments.
-Follow `selection.hint` for restorable text. Do not accept/reject another
-reviewer's work or remove comments without explicit user authorization. The
-source is never overwritten unless `--in-place` is explicit.
+Do not accept/reject another reviewer's work or remove comments without explicit
+user authorization. The source is never overwritten unless `--in-place` is
+explicit.
 
 The agent profile preserves progressive execution and the ordinary revision
 policy. Add `--atomic` or `--existing-revisions slice-cross-author` only when
 that policy is intended, and confirm the resolved `effectiveOptions`.
 
-Advanced restore, rejected-view insertion, list, table, formatting, comments,
-revision policies, and failure examples live in the
+Speculative apply, directional search ranges, advanced restore, rejected-view
+insertion, list, table, formatting, comments, revision policies, and failure
+examples live in the
 [knowledge base](docs/AGENT_KNOWLEDGE_BASE.md#agent-document-workflow-cli) and
 [operation schema](docs/schemas/document-operations.schema.json).
 
@@ -82,10 +68,8 @@ targeting, revision allocation, comments, numbering, validation, or rollback.
 The stateful wrapper in `examples/agent-session-wrapper.mjs` is a testable
 development demonstration only. It is excluded from package files and exports.
 Production harnesses own their transport and negotiate the minimum CLI
-`contractVersion`/capabilities they use. The 0.7.0 localized fast path requires
-contract 8 and its localized replacement, speculative apply, and change-summary
-capabilities; the narrow restore shortcut additionally requires
-`restore-shortcuts-v1`.
+`contractVersion` and capabilities they actually use. Optional capabilities do
+not belong in an ordinary editing prompt merely because the CLI supports them.
 
 ## Code map
 

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+- Localized replacement matching now tries exact case-sensitive text first,
+  then a narrow ASCII-space/non-breaking-space equivalent match. Ambiguous
+  equivalent matches still fail closed, and unchanged boundary NBSPs are
+  retained to avoid incidental whitespace redlines.
+
 - Added a narrow single-paragraph restore shortcut. A restore with a strong
   rejected-view target may omit `modified` for verbatim restoration or provide
   exact `replacements`; the CLI exposes the same path through `apply --restore

package/README.md

@@ -16,18 +16,16 @@ Converts AI-generated or programmatic text/markdown edits into valid Office Open
 - Highlights: apply highlight colors to runs
 - Markdown and OOXML conversion in both directions
 - Status/error result fields for parse, targeting, and existing-revision failures
-- Localized exact replacements and fail-closed one-turn CLI edits with verified before/after evidence
+- Localized exact replacements against inspected targets, plus optional fail-closed speculative CLI edits
 - Package plumbing helpers for numbering.xml, comments.xml, content types, and relationships
 - Zero host dependencies: works in Node.js, browsers, Deno, and similar JS runtimes with DOM parsing support
 
 ## What's New in 0.7.0
 
-Version 0.7.0 adds a contract-8 fast path for exact mechanical edits. Agents can
-send a small `find`/`replace` request instead of reproducing a complete legal
-paragraph, and may omit a strong target when the source literal resolves to one
-accepted-view paragraph. A longer, fairly unique nearby phrase can narrow the
-attempt with a signed directional window. Generic or repeated anchors widen the
-unioned scope and may cause a safe ambiguity failure and another tool turn.
+Version 0.7.0 adds contract-8 localized edits. Agents can send a small
+`find`/`replace` request against an inspected target instead of reproducing a
+complete paragraph. An optional speculative form may omit the strong target
+when the source literal resolves uniquely; advanced scoping is described below.
 
 Speculative edits fail without writing when the anchor, paragraph, or source
 span is missing or ambiguous. Successful localized results include a committed
@@ -249,18 +247,10 @@ latency. Checked comparative results are in the
 ### Agent CLI
 
 ```bash
-# One-turn exact mechanical edit; fails closed unless one paragraph matches
-docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
-
-# Directional context using a longer phrase with a higher chance of uniqueness
-docx-redline apply contract.docx --search "distinctive nearby heading or phrase" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
-
-# Semantic drafting still starts with focused context
+# Default agent workflow: inspect once, then apply once
 docx-redline extract contract.docx --search "termination" --around 3
-docx-redline preflight contract.docx --operations operations.json --author "Editor"
-docx-redline apply contract.docx --operations operations.json --author "Editor" --output reviewed.docx
-docx-redline validate reviewed.docx
-```
+node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
+```
 
 ```bash
 # Inline one-liner edit (no operations file needed)
@@ -275,9 +265,9 @@ docx-redline apply contract.docx --target "Another author's clause" --modified "
 # High-assurance atomic batch with nonzero exit on any incomplete result
 docx-redline apply contract.docx --operations operations.json --atomic --require-complete --output reviewed.docx
 
-# Agent shell path: JSON is emitted by a serializer, not interpolated by the shell
-node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
-```
+# Optional read-only audit before a deliberately staged batch
+docx-redline preflight contract.docx --operations operations.json --author "Editor"
+```
 
 All commands emit JSON on stdout. `apply` defaults:
 - **Author**: Defaults to `'AI Redliner'` (or `DOCX_REDLINE_AUTHOR` environment variable).
@@ -290,7 +280,8 @@ All commands emit JSON on stdout. `apply` defaults:
 - **Compact stdout**: `--compact` emits one-line mutation JSON. It changes serialization only, not operation semantics.
 - **Tracked changes**: Defaults to `generateRedlines: true`. Pass `--no-redlines` when clean direct text edits are desired.
 - **Inline edits**: Use `--target <text>` with `--modified <text>` or `--comment <text>` for quick one-liners without creating a JSON file.
-- **Localized edits**: Use `--find`/`--replace` with a known strong target, or omit the target for fail-closed global resolution. Add a longer, fairly unique `--search` phrase with `--context-range 1:3` for directional scope; `--around 3` is symmetric. Generic or repeated anchors can widen the unioned scope until multiple paragraphs contain `find`, producing a safe `AMBIGUOUS_TARGET` failure and an extra recovery turn. On success, `results[i].change.context.anchorMatchCount > 1` signals a non-unique anchor; confirm the returned location and bounded before/after evidence.
+- **Localized edits**: After extraction, use `replacements` with the inspected `paragraphId` plus `fingerprint` to avoid restating a long paragraph. Retain `exactText` locally for drafting. Targetless `--find`/`--replace` is an optional speculative path described below.
+- **Invisible spaces**: Localized matching is case-sensitive and tries exact text first. If no exact span exists, ordinary spaces may match DOCX non-breaking spaces; ambiguous equivalent matches still fail closed, and `change.replacements[i].matchMode` reports `space_equivalent` when used.
 - **Compact mutation results**: `apply`, `accept`, `reject`, and `delete-comments` omit full OOXML/package payloads and inspection text from stdout. CLI operation results omit duplicate nested receipt bodies; the ordered top-level `receipts` array is authoritative. Successful exact target-match diagnostics are omitted and equivalent-whitespace matches retain only mode/count. Node and standalone-runner results remain unchanged. Use `validate` when full issue arrays are needed.
 
 Inspection commands default to 20 direct matches and a 48 KiB soft response
@@ -312,10 +303,31 @@ user-facing Word locations; use `humanReference`, `provision`, or
 `agent-safety-profile-v2`, `deduplicated-cli-receipts`, and
 `compact-cli-json-v1`, `localized-replacements-v1`,
 `speculative-search-apply-v1`, `localized-change-summary-v1`, and
-`restore-shortcuts-v1` capabilities.
+`restore-shortcuts-v1`, plus `localized-space-equivalence-v1` capabilities.
 Wrappers should negotiate only the
 capabilities they use. Run `docx-redline <command> --help` for that command's
 machine-readable options, behavior, exit codes, canonical GitHub documentation links, and compact examples.
+
+#### Optional speculative CLI path
+
+Harnesses with a measured confidence policy may attempt a targetless localized
+edit. This is not the default agent workflow:
+
+```bash
+# Globally unique literal
+docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+
+# Optional directional scope using a longer, fairly unique nearby phrase
+docx-redline apply contract.docx --search "distinctive nearby heading or phrase" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+```
+
+Generic or repeated anchors can widen the unioned scope until multiple
+paragraphs contain `find`, causing a safe `AMBIGUOUS_TARGET` failure and a
+recovery turn. `--around 3` is symmetric. On success,
+`change.context.anchorMatchCount > 1` signals a repeated anchor; confirm the
+returned location and bounded evidence. Matching remains case-sensitive and
+exact-first, with a narrow ordinary-space/NBSP fallback that still refuses
+ambiguity.
 
 See the [compact agent fast start](./docs/AGENT_FAST_START.md), the
 [skill/harness authoring contract](./docs/SKILL_AUTHORING.md), and the

package/dist/docx-redline-js.esm.js

@@ -1,4 +1,4 @@
-// @ansonlai/docx-redline-js v0.7.1 — https://github.com/AnsonLai/docx-redline-js
+// @ansonlai/docx-redline-js v0.7.2 — https://github.com/AnsonLai/docx-redline-js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;

package/docs/AGENT_FAST_START.md

@@ -1,58 +1,55 @@
 # Agent Fast Start
 
-Use this page for ordinary `.docx` edits. For source changes or unusual Word structures, follow the links at the end.
+Use this page for ordinary `.docx` edits. For unusual Word structures or optional shortcuts, follow the links at the end.
 
 ## Structured agent tool
 
-If your host provides a document-session wrapper:
+If the host provides a document-session wrapper:
 
-1. Inspect/search once with enough surrounding context to draft the change.
-2. Apply with the revision-bound handle and complete desired text or exact replacements.
-3. Treat only `ok: true` as complete; refresh failed handles before reuse.
+1. Inspect once with enough surrounding context to draft the change.
+2. Apply once with the returned revision-bound handle.
+3. Accept only the wrapper's complete-success result; refresh failed handles.
 
-The repository's `examples/agent-session-wrapper.mjs` demonstrates this pattern.
-It is a development sample, not a package API.
+The repository's `examples/agent-session-wrapper.mjs` is a development sample, not a package API.
 
-## CLI fallback
+## CLI workflow
 
-1. For a literal mechanical edit with known old and new text, try one-turn apply:
-
-   ```bash
-   docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
-   ```
-
-   The source must occur in one eligible paragraph. To narrow it, use a longer, fairly unique phrase: `--search "distinctive nearby heading or phrase" --context-range 1:3`.
-   Generic/repeated anchors can cause `AMBIGUOUS_TARGET` and waste a recovery turn. If `anchorMatchCount > 1`, confirm the returned location and excerpts. `--around 3` is symmetric.
-
-2. For semantic drafting such as “make this provision mutual,” extract enough
-   context, then copy `exactText` with `paragraphId` or `fingerprint`:
+1. Extract the relevant clause or range:
 
    ```bash
    docx-redline extract contract.docx --search "termination" --around 3
    ```
 
-   Search is case-insensitive; follow `selection.hint` and `selection.nextAfter`, and report `humanReference`. With `--revised`, use `hasRevisions`, `revisionAuthors`, and `deleted` or `inserted` to interpret paragraphs whose active-view `exactText` is empty. Restore one rejected-view paragraph verbatim with `apply --restore --target-id ID`; add one `--find`/`--replace` pair for an exact correction. The shortcut never expands to adjacent paragraphs. Otherwise, apply once with a UTF-8 operations file or serializer-backed stdin:
+   Search is case-insensitive. Follow `selection.nextAfter` when truncated. Preserve `selection`, `humanReference`, target descriptors, and revision cues when reshaping output. Report `humanReference`, not a machine paragraph number.
+
+2. Retain inspected `exactText` for drafting and target with its `paragraphId` plus `fingerprint`, then apply once with a UTF-8 operations file or serializer-backed stdin:
 
    ```bash
    node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
    ```
 
-   Use `JSON.stringify`, not shell interpolation. `modified` is the complete desired accepted-view paragraph.
+   Use complete `modified` text for a broad semantic revision. For a small literal change in that inspected target, use
+   `replacements: [{ "find": "old text", "replace": "new text" }]` instead.
+   Use `JSON.stringify`; never interpolate document text through shell quoting. Preserve intentionally relative wording unless the user asks for a concrete value.
+
+## Restore branch
 
-The `agent` profile preserves progressive execution and the ordinary revision policy while making incomplete work exit nonzero. Add `--atomic` deliberately; check `effectiveOptions`. Run `docx-redline apply --help` for redline, comment, and rejected-view restore shapes.
+If the user requests deleted text, search with `--view rejected` first. Otherwise follow `selection.hint` only when it identifies an alternate revision view. Restore the inspected strong target; do not infer adjacent content. Run `docx-redline apply --help` for canonical restore shapes.
 
-## Batch and result rules
+## Completion and recovery
 
-- Strong inspected targets bind to the batch start; independent edits need no bottom-up sorting.
-- Consolidate writes to one source; use captures for created-content dependencies.
-- Require `completion: true`, `written: true`, a non-null `outputPath`, and no
-  per-operation error. For localized edits also require
-  `results[i].change.committed: true`, `finalDisposition: "applied"`, and
-  `verification.acceptedViewMatchesCompiledText: true`. The source is
-  not overwritten unless `--in-place` is explicit.
-- On failure, follow `error.recovery.action`. Never retry unchanged arguments.
-- `retryPlan.base: "original"` means replay the batch; `"output"` means retain committed work and retry reported indexes.
-- Never accept/reject revisions or remove comments without user authorization. `slice-cross-author` preserves history for edits inside foreign insertions.
+- Require `completion: true` and a non-null `outputPath`; the CLI computes this from write, operation, commit, and localized-verification results.
+- On failure, follow `error.recovery.action`; never retry unchanged arguments.
+- Use `retryPlan.base: "original"` to replay a batch and `"output"` to retain
+  committed progressive work and retry the reported indexes.
+- The source is not overwritten unless `--in-place` is explicit.
+- Never accept/reject revisions or remove comments without authorization.
+- Add `--atomic` or a non-default revision policy only when deliberately needed;
+  confirm `effectiveOptions`.
+- Strong inspected targets bind to batch start. Consolidate writes to one source
+  and use captures only for intentional created-content dependencies.
 
-Advanced operations and recovery: [Agent Knowledge Base](AGENT_KNOWLEDGE_BASE.md); canonical contract: [document-operations.schema.json](schemas/document-operations.schema.json)  
+Advanced speculative apply, directional scoping, operation constraints, and
+recovery: [Agent Knowledge Base](AGENT_KNOWLEDGE_BASE.md). Canonical schema:
+[document-operations.schema.json](schemas/document-operations.schema.json).
 Wrapper design: [README](../README.md#example-agent-session-wrapper-development-only)

package/docs/AGENT_KNOWLEDGE_BASE.md

@@ -476,66 +476,41 @@ The canonical machine-readable contract is
 `docs/schemas/document-operations.schema.json`. Read that schema or the examples
 here instead of grepping bundled implementation code.
 
-#### Standard Workflow (Fast & Direct)
-
-Use this for everything by default. `apply` is fast, progressive, and self-validating by default—it validates the resulting package and revision markup internally before writing. **Do not insert a `preflight` or baseline `validate` step on top of it "to be safe"**; `apply` already covers that internally. It supports inline one-liners as well as batch operations files:
-
-The short route for a document-editing request is:
-
-1. For an exact mechanical change with known old and new literals, use localized
-   `--find`/`--replace`. Omit the target for global fail-closed resolution, or
-   scope it with a longer, fairly unique nearby `--search` phrase and a
-   directional range such as `--context-range 1:3`. Generic or repeated anchors
-   widen the unioned scope and may fail with `AMBIGUOUS_TARGET`, costing another
-   turn. `--occurrence` selects only within one uniquely resolved paragraph.
-2. For semantic drafting, run one focused `extract`. Add `--around 3` when
-   surrounding context on either side is needed, then copy `exactText` plus
-   `paragraphId` or `fingerprint`.
-3. Build the final operations from the operation table above. Use one operation
-   per target paragraph, and consolidate multiple changes to that paragraph.
-4. Run `apply` once per stable batch. Strong inspected targets are bound against
-   the batch-start document, so independent operations do not need manual
-   bottom-up sorting around structural edits. Consolidate multiple complete
-   desired states for the same source. A unique exact reference to paragraph
-   text created elsewhere in the batch is scheduled automatically; use explicit
-   captures/selectors for non-unique or advanced created-content dependencies.
-5. Walk every result and require `completion: true`, `written: true`, and no
-   per-operation error. For localized patches also require
-   `results[i].change.committed: true`, `finalDisposition: "applied"`, and
-   positive accepted-view verification. If `anchorMatchCount > 1`, confirm the
-   returned location and excerpts because the anchor was repeated.
-6. Run a focused `extract` on changed clauses only when placement or list/table
-   structure needs confirmation.
-
-Do not probe operation behavior with disposable apply commands or read a vendor
-bundle before this route. If `apply` returns an error, use the recovery matrix
-below and make one cause-specific correction.
-
-```bash
-# 1. Globally unique mechanical edit in one call
-docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+#### Standard Workflow (Extract Then Apply)
+
+Use this for ordinary edits. `apply` validates the resulting package and
+revision markup internally before writing, so do not add `preflight` or baseline
+`validate` merely for reassurance.
+
+1. Run one focused `extract`. Add `--around 3` when surrounding context is
+   needed. Retain `exactText` for drafting and target with `paragraphId` plus
+   `fingerprint`.
+2. Build one final operation per target. Use complete `modified` text for broad
+   semantic revisions or localized `replacements` for small literal changes in
+   an inspected target. Consolidate multiple changes to one paragraph.
+3. Run `apply` once per stable batch. Independent strong targets bind against
+   the batch-start document and do not need bottom-up sorting. Use captures only
+   for intentional created-content dependencies.
+4. Require `completion: true` and a non-null `outputPath`. The CLI derives
+   completion from write status, operation outcomes, commit disposition, and
+   localized accepted-view verification.
+5. Run a focused post-apply extraction only when placement or structural output
+   needs confirmation.
+
+If `apply` returns an error, follow the recovery envelope below and make one
+cause-specific correction. Do not probe behavior with disposable mutations or
+read a vendor bundle.
 
-# 2. Directional edit using a longer phrase with a higher chance of uniqueness
-docx-redline apply contract.docx --search "distinctive nearby heading or phrase" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
-
-# 3. Focused contextual discovery for semantic drafting
+```bash
+# 1. Focused contextual discovery
 docx-redline extract contract.docx --search "termination" --around 3
 
-# 4. Inline complete-paragraph edit
-docx-redline apply contract.docx --target "Original clause" --modified "New clause" --output reviewed.docx
-
-# 5. Direct edit without tracked changes (clean text, no revision clutter)
-docx-redline apply contract.docx --target "Typo fix" --modified "Fixed typo" --no-redlines --output clean.docx
-
-# 6. Cross-author edit inside another reviewer's pending insertion
-docx-redline apply contract.docx --target "Pending clause text" --modified "Updated clause text" --existing-revisions slice-cross-author --output reviewed.docx
-
-# 7. Batch operations with ops.json
-docx-redline apply contract.docx --operations operations.json --output reviewed.docx
-
-# 8. Serializer-backed stdin with compact stdout
+# 2. Serializer-backed apply against the inspected target
 node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
-```
+
+# Optional clean edit without tracked changes
+docx-redline apply contract.docx --target "Typo fix" --modified "Fixed typo" --no-redlines --output clean.docx
+```
 
 Key CLI defaults and behaviors:
 - **Author**: Automatically defaults to `'AI Redliner'` (overridable via `--author` or `DOCX_REDLINE_AUTHOR` environment variable).
@@ -547,9 +522,36 @@ Key CLI defaults and behaviors:
 - **Agent profile**: `--profile agent` enables complete-success exit behavior but preserves progressive execution and the ordinary revision policy. Compose it with `--atomic` or an explicit `--existing-revisions` choice when intended; resolved values appear in `effectiveOptions`.
 - **Operation transport**: A UTF-8 operations file and serializer-backed `--operations -` are peers. Use whichever the host can construct without interpolating legal text in the shell.
 - **Compact mutation JSON**: `apply`, `accept`, `reject`, and `delete-comments` omit document/package XML, full validation arrays, and duplicate nested receipts. Top-level `receipts` is authoritative. Pass `--compact` for one-line JSON; run `validate` for full issue records.
-- Check `completion: true`, `written: true`, and a non-null `outputPath` on stdout. `completion` is derived from the write result, top-level status, and every operation status, so failed, partial, and unwritten work cannot appear complete. If an error occurs, inspect `error.code` or `results[i].error.code` (e.g. `TARGET_NOT_FOUND`, `ANCHOR_NOT_FOUND`) before correcting the cause and re-applying.
+- Check `completion: true` and a non-null `outputPath` on stdout. Failed,
+  partial, rolled-back, unverified, and unwritten work cannot appear complete.
+  If an error occurs, follow `error.recovery.action` before correcting the cause.
 
-For multi-clause or multi-page reviews, apply edits **section-by-section** or clause-by-clause (e.g., using `--in-place` on a working copy) rather than bundling dozens of edits into one massive batch. This keeps context compact, simplifies error diagnosis, and prevents cascading anchor drift.
+For multi-clause or multi-page reviews, use focused batches rather than one
+massive batch. This keeps context compact and simplifies error diagnosis.
+
+#### Optional Speculative Localized Apply
+
+Targetless localized apply remains available to expert users and harnesses with
+a measured confidence policy. It is not the ordinary agent workflow:
+
+```bash
+# Globally unique literal
+docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+
+# Optional directional scope using a longer, fairly unique phrase
+docx-redline apply contract.docx --search "distinctive nearby heading or phrase" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+```
+
+Omitting a target asks the CLI to resolve one eligible paragraph. Generic or
+repeated anchors union their windows and may produce `AMBIGUOUS_TARGET`, costing
+a recovery turn. `--around 3` is symmetric; `--occurrence` disambiguates only
+inside an already selected paragraph. `anchorMatchCount > 1` signals a repeated
+anchor even after a successful edit. Matching is exact and case-sensitive first,
+then permits only ASCII-space/NBSP equivalence; ambiguity still fails closed.
+
+Localized `change` evidence retains bounded before/after excerpts, commit
+disposition, and accepted-view verification for audit consumers. Ordinary
+agents rely on the computed top-level `completion` signal.
 
 #### High-Assurance / Staged Verification Workflow (Optional)
 

package/docs/SKILL_AUTHORING.md

@@ -1,86 +1,76 @@
 # Skill and Harness Authoring Contract
 
-Use this page when creating or updating an agent skill, MCP server, or custom
-harness for `@ansonlai/docx-redline-js`. Ordinary document-editing agents should
-load [Agent Fast Start](AGENT_FAST_START.md), not this design contract.
+Use this page to create or update an agent skill, MCP server, or custom harness
+for `@ansonlai/docx-redline-js`. Ordinary editing agents should load
+[Agent Fast Start](AGENT_FAST_START.md), not this design contract.
 
 > [!WARNING]
-> Before 1.0, every skill or harness must identify and pin its exact tested
-> library release and required CLI contract/capabilities. Treat any different
-> release or contract as unverified until compatibility tests pass.
+> Before 1.0, every integration must identify and pin its exact tested library
+> release and required CLI contract/capabilities. Treat any different release or
+> contract as unverified until compatibility tests pass.
 
-For example, an integration authored for the current contract-8 release should
-record a compatibility declaration equivalent to:
+Example declaration for a contract-8 shell integration that uses localized
+operations over stdin:
 
 ```json
 {
-  "testedLibraryRelease": "0.7.0",
+  "testedLibraryRelease": "0.7.1",
   "requiredCliContractVersion": 8,
   "requiredCapabilities": [
-    "command-help-v1",
+    "operations-stdin",
+    "agent-safety-profile-v2",
     "recovery-envelope-v1",
-    "localized-replacements-v1",
-    "speculative-search-apply-v1",
-    "localized-change-summary-v1"
+    "localized-replacements-v1"
   ]
 }
 ```
 
-The package pin anchors the release; runtime negotiation proves the executable
-exposes the required contract. A new release cannot inherit an old claim.
-
 ## Runtime negotiation
 
-Run this before the first document operation when the skill vendors or invokes
-the CLI:
-
-```bash
-docx-redline version
-```
+Run `docx-redline version` before the first document operation. Require CLI
+contract version 8 and only the capabilities the integration actually uses. Check once per stable
+runtime, fail closed when a requirement is absent, and never inspect bundles or
+ZIP parts as a fallback.
 
-Require contract version 8 (the currently declared contract) and only the
-capabilities the integration uses. A typical shell skill should require
-`agent-safety-profile-v2`, `deduplicated-cli-receipts`, and
-`recovery-envelope-v1`. Require other capabilities only when used. Fail closed
-when one is absent; never inspect bundles or ZIP parts as a fallback.
+Do not expose negotiated but unused capabilities as choices in the editing
+prompt. `command-help-v1`, restore shortcuts, speculative apply, and localized
+change summaries are optional requirements only for integrations that use them.
 
 ## Safety invariants
 
-Every generated integration must preserve these rules:
+Every generated integration must:
 
-- Inspect narrowly and copy `exactText` plus `paragraphId` or `fingerprint`.
-- Treat `modified` as the complete desired accepted-view target content.
-- Use strict targeting, package validation, and a derived output path; never
-  overwrite the source unless the caller explicitly requests `--in-place`.
-- Require `completion: true`, `written: true`, a non-null `outputPath`, and no
-  per-operation error before reporting completion.
-- Never accept or reject another reviewer's work or delete comments without
-  explicit user authorization.
-- Never retry unchanged failed arguments.
+- inspect narrowly, retain `exactText`, and target with `paragraphId` plus
+  `fingerprint`;
+- use strict targeting, package validation, and a derived output path;
+- never overwrite the source unless `--in-place` is explicitly requested;
+- require `completion: true` and a non-null `outputPath` before reporting
+  success;
+- follow `error.recovery.action` and never retry unchanged failed arguments; and
+- require explicit authorization before accepting/rejecting another reviewer's
+  work or deleting comments.
 
-The `agent` profile enables complete-success exit behavior and retains the
-ordinary progressive default. It does not select atomic execution or a special
-existing-revision policy. A skill must state those choices explicitly when its
-workflow needs them.
+The CLI computes `completion` from write status, operation outcomes, commit
+disposition, and localized accepted-view verification. Preserve the detailed
+results for audit and recovery, but do not make the editing agent re-evaluate
+those fields during ordinary success handling.
 
 ## Workflow policy choices
 
-Choose and document these separately from safety invariants:
+Keep these exceptions separate from the default workflow:
 
-| Choice | Options | Guidance |
+| Choice | Default | Override only when |
 |---|---|---|
-| Transaction | progressive default or `--atomic` | Use progressive for independent edits; use atomic when partial output is unacceptable. |
-| Existing revisions | `merge-same-author` default or explicit policy | Use `slice-cross-author` only when editing inside another reviewer's pending insertion is intended. |
-| Reviewer identity | flag, operation author, environment, or fallback | `AI Redliner` is a valid visible fallback. `DOCX_REDLINE_AUTHOR` is an optional harness preference, not a guard. |
-| Output naming | derived sibling or explicit destination | Keep source immutability unless in-place mutation is deliberately authorized. |
+| Transaction | progressive | Partial output is unacceptable (`--atomic`). |
+| Existing revisions | `merge-same-author` | Editing inside another reviewer's pending insertion is intended (`slice-cross-author`). |
+| Reviewer identity | `AI Redliner` is a valid visible fallback | The host supplies a preferred flag, operation author, or environment value. |
+| Output | derived sibling | The caller deliberately selects another destination. |
 
-Check `effectiveOptions` rather than assuming the resolved transaction,
-revision, author, or redline policy.
+Check `effectiveOptions` when an integration deliberately sets a policy.
 
 ## Transport choices
 
-A UTF-8 operations file and serializer-backed stdin are peer transports. Choose
-the form the host can construct safely:
+A UTF-8 operations file and serializer-backed stdin are peer transports:
 
 ```bash
 docx-redline apply input.docx --operations operations.json --profile agent --output reviewed.docx
@@ -88,46 +78,46 @@ node emit-operations.mjs | docx-redline apply input.docx --operations - --profil
 ```
 
 Use `JSON.stringify` or a structured tool API. Never demonstrate `echo`, a
-heredoc, or shell-interpolated legal text. `--compact` changes stdout formatting,
-not result semantics. A Node byte-oriented wrapper should call `openDocx` and
-return the full structured result rather than recreating the CLI serializer.
+heredoc, or shell-interpolated document text. A Node byte-oriented wrapper should
+call `openDocx` and return the structured result instead of recreating CLI
+serialization, ZIP handling, targeting, validation, or rollback.
 
 ## Ordinary generated workflow
 
-For an exact mechanical edit whose existing and replacement literals are known,
-the first executable example should use the one-turn fast path:
+The first executable editing example in a generated skill must be focused
+extraction:
 
 ```bash
-docx-redline apply input.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+docx-redline extract input.docx --search "renewal notice" --around 3
 ```
 
-If the literal is not globally unique, use a longer, fairly unique nearby phrase
-as `--search` context. Generic or repeated anchors widen the unioned scope and
-may cause `AMBIGUOUS_TARGET`, wasting a recovery turn. Use a directional window
-such as `1:3`; use symmetric `--around 3` only when either side is eligible. On
-success, `anchorMatchCount > 1` signals a repeated anchor: confirm the returned
-location and excerpts. Require `results[i].change` with `committed: true`,
-`finalDisposition: "applied"`, and positive accepted-view verification.
+Then apply once using the inspected strong target. Use complete `modified` text
+for a broad semantic revision or `replacements` for a small literal change in
+that target. Keep requested relative wording relative unless the user asks for
+a concrete value.
 
-Semantic requests such as “make this provision mutual” still begin with focused
-contextual extraction because the agent must identify and draft the complete
-legal change:
+Follow `selection.nextAfter` when extraction is truncated. Output projections must retain
+`selection`, target descriptors, `humanReference`, and revision
+cues.
 
-```bash
-docx-redline extract input.docx --search "termination" --around 3
-```
+### Observed restore branch
+
+If the user requests restoration, search `--view rejected` first. Otherwise
+follow an alternate-view `selection.hint` when returned. Restore only the
+inspected strong target. Require `restore-shortcuts-v1` only if the integration
+uses inline `--restore`; canonical operations remain available.
+
+### Optional speculative execution
 
-Use `selection.nextAfter` with `--after` when truncated. When a search for
-deleted or restorable content yields 0 matches in accepted view, follow
-`selection.hint` and re-run with `--view rejected`. Apply once per stable batch.
-Run `docx-redline apply --help` for canonical redline, whole-paragraph comment,
-and rejected-view restore shapes; CLI help documentation fields return canonical
-GitHub URLs. The operation schema remains
-[document-operations.schema.json](schemas/document-operations.schema.json).
+Do not make speculative apply part of an ordinary generated workflow. A harness
+may opt into `speculative-search-apply-v1` only when it owns a measured confidence
+policy and accepts the recovery cost of a miss. Keep anchor selection,
+directional windows, occurrence handling, and exact matching semantics out of
+the ordinary editing prompt; link to the knowledge base or CLI help instead.
 
 ## Recovery contract
 
-Lead error handling with exactly these runtime fields:
+Lead failure handling with these runtime fields:
 
 1. `error.recovery.action`
 2. `error.recovery.requiresReinspection`
@@ -135,32 +125,23 @@ Lead error handling with exactly these runtime fields:
 4. `error.recovery.sameArgumentsSafe`
 
 Use `retryPlan.base` and its operation indexes to select the original or partial
-output package. Do not generate a second prose decision tree for every error
-code; error messages and bounded diagnostics explain the cause, while the four
-fields above determine the next action.
+output package. Do not reproduce an error-code decision tree in the skill.
 
 ## Presentation rules
 
-Use `humanReference`, `provision`, or `nearestHeading` in user-facing completion
-reports. `P55`, `index: 55`, and phrases such as “the 55th paragraph” are machine
-targeting and pagination coordinates, not locations a Word user can follow.
-When no formal heading exists, use the returned short text lead. Never replace
-an exact machine target with a human-facing reference.
+Use `humanReference`, `provision`, or `nearestHeading` in completion reports.
+Paragraph indexes and `P55`-style references are machine coordinates, not
+locations a document user can follow. Keep the exact machine target internally.
 
 ## Generation checklist
 
-- The exact tested library release is recorded and pinned; floating installs
-  are rejected while the library remains before 1.0.
-- The required CLI contract version and minimum capability set are declared,
-  checked at runtime, and updated only after compatibility tests pass.
-- Runtime version and required capabilities are checked once.
-- Literal edits use localized replacements and one-turn speculative apply;
-  semantic drafting starts with focused extraction.
-- Successful localized edits require committed, post-mutation `change`
-  verification before completion is reported.
-- Safety invariants are not mixed with transaction or revision-policy choices.
-- Operations-file and stdin examples use structured serialization.
-- The four-field recovery contract precedes any diagnostic commentary.
-- Completion prose uses legal references rather than machine ordinals.
-- The wrapper delegates mutation, validation, rollback, comments, numbering,
-  receipts, and OOXML packaging to the library.
+- Exact tested release, contract 8, and the minimum capability set are pinned.
+- Runtime compatibility is checked once.
+- The first ordinary command is focused extraction.
+- Apply uses the inspected target with `modified` or localized `replacements`.
+- Restore appears only as a user-requested or observed-view branch.
+- Speculative execution is absent unless the harness owns a measured policy.
+- Ordinary success requires `completion: true` and a non-null `outputPath`.
+- Recovery, authorization, source immutability, and structured serialization
+  invariants are preserved.
+- Wrappers delegate mutation and OOXML packaging to the library.

package/docs/validation-reports/2026-09-14-agent-surface-simplification.md

@@ -0,0 +1,75 @@
+# Agent Surface Simplification Replay
+
+**Date:** 2026-09-14  
+**Runtime:** Node.js 24.11.1 on Windows x64  
+**Engine:** Current post-0.7.1 source for every policy  
+**Command:** `npm run benchmark:agent-surface`  
+**Configuration:** 7 measured iterations and 1 warmup per scenario/policy
+
+## Scope
+
+This repository-controlled replay compares three workflow policies without
+changing the underlying engine:
+
+1. `v0.6.2-extract-full`: extraction followed by complete modified text.
+2. `v0.7.1-speculation-led`: speculative literal edits with extraction/apply
+   recovery, and extraction for semantic or batch work.
+3. `simplified-extract-localized`: extraction followed by a compact localized
+   operation against `paragraphId` plus `fingerprint`.
+
+The six wholly synthetic scenarios cover a long literal edit, semantic drafting,
+repeated visible text, rejected-view restoration, an NBSP-bearing target, and an
+independent two-target batch. Every output is re-extracted and compared with its
+predetermined accepted-view text. Benchmark-only verification calls are not
+counted as workflow calls.
+
+## Aggregate Results
+
+| Policy | Correct runs | Total calls | Calls/run | Failed calls | Edit request bytes | Median local ms |
+|---|---:|---:|---:|---:|---:|---:|
+| v0.6.2 extract/full | 42/42 | 84 | 2.00 | 0 | 27,034 | 3.86 |
+| v0.7.1 speculation-led | 42/42 | 77 | 1.83 | 7 | 8,988 | 3.86 |
+| simplified extract/localized | 42/42 | 84 | 2.00 | 0 | 10,661 | 3.77 |
+
+The simplified policy reduced generated edit-request bytes by 60.6% relative to
+the complete-paragraph baseline while preserving a fixed two-call workflow and
+zero failed calls. On the long-paragraph case, its median edit request was 193
+bytes rather than 2,104 bytes, a 90.8% reduction.
+
+The speculation-led policy saved seven total calls because two unique literal
+scenarios completed in one call. The repeated-text scenario cost three calls and
+one failure on every iteration. This demonstrates both the legitimate one-turn
+benefit and the recovery cost that the simplified default is intended to avoid.
+
+The localized form is not always smaller for a short paragraph. In the NBSP
+scenario it used 344 bytes versus 343 bytes for complete modified text. The
+benefit is strongest when the inspected source is long relative to the changed
+span.
+
+## Interpretation
+
+The repository evidence supports the surface decision:
+
+- keep speculative apply as an available expert/harness capability;
+- do not make ordinary agents classify whether to use it;
+- lead with deterministic extraction and one apply;
+- retain localized replacements after inspection to avoid long output payloads;
+- use compact `paragraphId` plus `fingerprint` targets for localized requests,
+  while retaining extracted text locally for drafting; and
+- keep restoration as a request/hint-driven branch.
+
+Local execution time is effectively neutral at this scale and remains far below
+agent deliberation or provider latency. No performance claim should be based on
+the small local timing differences in this report.
+
+## Limitations
+
+This is a deterministic workflow replay, not a model evaluation. It cannot
+measure reasoning tokens, provider tokenization, transport latency, stochastic
+instruction following, or subjective drafting quality. Repeated external agent
+runs using the same model, prompt, document, and engine are still required before
+claiming end-to-end latency improvement.
+
+The machine-readable output is written to
+`tmp/benchmarks/agent-surface-simplification-latest.json` and is intentionally
+not committed.

package/node/cli-help.js

@@ -134,7 +134,7 @@ export const CLI_COMMAND_HELP = Object.freeze({
             option('targetId', '--target-id <paragraphId>', 'Strong inline target using a paragraphId from fresh inspection.'),
             option('restore', '--restore', 'Restore one rejected-view paragraph identified by --target-id; omit --modified for verbatim restoration.'),
             option('modified', '--modified <text>', 'Complete desired accepted-view target content.'),
-            option('find', '--find <exact text>', 'Exact case-sensitive source span for one localized replacement.'),
+            option('find', '--find <exact text>', 'Case-sensitive source span; exact match first, then ASCII-space/NBSP equivalence.'),
             option('replace', '--replace <text>', 'Replacement text for --find; an empty string deletes the span.'),
             option('occurrence', '--occurrence <N>', 'Positive 1-based --find occurrence within the uniquely resolved target paragraph.'),
             option('search', '--search <text>', 'Case-insensitive context anchor for speculative find/replace; prefer a longer, fairly unique phrase because all matches contribute scope.'),

package/node/cli.js

@@ -7,6 +7,7 @@ import { validateRedlineOoxml } from '../core/redline-validation.js';
 import { configureLogger } from '../adapters/logger.js';
 import { isExistingRevisionsPolicy } from '../services/document-operation-contract.js';
 import { normalizeErrorWithRecovery } from '../services/error-recovery.js';
+import { localizedReplacementOffsets } from '../services/localized-replacement-compiler.js';
 import { buildCliHelp, CLI_COMMANDS, commandOptionKeys } from './cli-help.js';
 
 const suffixes = { apply: 'redlined', accept: 'accepted', reject: 'rejected', 'delete-comments': 'comments-removed' };
@@ -31,6 +32,7 @@ const CLI_CAPABILITIES = [
     'localized-replacements-v1',
     'speculative-search-apply-v1',
     'localized-change-summary-v1',
+    'localized-space-equivalence-v1',
     'restore-shortcuts-v1',
     'deduplicated-cli-receipts',
     'compact-cli-json-v1'
@@ -242,21 +244,27 @@ function resolveSpeculativePatchTarget(document, flags) {
     }
 
     const find = String(flags.find);
-    const matches = eligible.filter(paragraph => paragraph.exactText.includes(find));
+    const patchCandidates = eligible.map(paragraph => ({
+        paragraph,
+        match: localizedReplacementOffsets(paragraph.exactText, find)
+    })).filter(candidate => candidate.match.offsets.length > 0);
+    const exactCandidates = patchCandidates.filter(candidate => candidate.match.matchMode === 'exact');
+    const matches = (exactCandidates.length > 0 ? exactCandidates : patchCandidates)
+        .map(candidate => candidate.paragraph);
     const context = {
         ...(search ? { search, range: range.text, anchorMatchCount: anchors.length } : {})
     };
     if (matches.length === 0) {
         throw speculativeError('PATCH_SOURCE_NOT_FOUND', search
-            ? `No paragraph in the contextual range contains the exact patch source: "${find}".`
-            : `No paragraph contains the exact patch source: "${find}".`, {
+            ? `No paragraph in the contextual range contains the patch source: "${find}".`
+            : `No paragraph contains the patch source: "${find}".`, {
             context,
             ...(anchors.length ? { candidates: anchors.map(speculativeCandidate) } : {}),
             recovery: { action: 'reinspect', requiresReinspection: true, sameArgumentsSafe: false }
         });
     }
     if (matches.length > 1) {
-        throw speculativeError('AMBIGUOUS_TARGET', `The exact patch source matched ${matches.length} eligible paragraphs.`, {
+        throw speculativeError('AMBIGUOUS_TARGET', `The patch source matched ${matches.length} eligible paragraphs.`, {
             context,
             candidates: matches.map(speculativeCandidate),
             recovery: { action: 'choose_candidate', requiresReinspection: false, sameArgumentsSafe: false }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ansonlai/docx-redline-js",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Host-independent OOXML reconciliation engine for .docx manipulation with track changes",
   "license": "MIT",
   "type": "module",
@@ -47,6 +47,7 @@
     "!scripts/benchmark-agent-workflow.mjs",
     "!scripts/benchmark-agent-cli-discovery.mjs",
     "!scripts/benchmark-localized-turn-reduction.mjs",
+    "!scripts/benchmark-agent-surface-simplification.mjs",
     "!scripts/lib/agent-performance-cases.mjs",
     "docs/AGENT_FAST_START.md",
     "docs/AGENT_KNOWLEDGE_BASE.md",
@@ -58,6 +59,7 @@
     "docs/validation-reports/2026-09-12-agent-cli-discovery-baseline.md",
     "docs/validation-reports/2026-09-13-agent-cli-efficiency-rollout.md",
     "docs/validation-reports/2026-09-14-localized-patching-rollout.md",
+    "docs/validation-reports/2026-09-14-agent-surface-simplification.md",
     "index.js",
     "index.d.ts",
     "dist/",
@@ -97,6 +99,7 @@
     "benchmark:agent": "node scripts/benchmark-agent-workflow.mjs",
     "benchmark:agent-cli": "node scripts/benchmark-agent-cli-discovery.mjs",
     "benchmark:localized": "node scripts/benchmark-localized-turn-reduction.mjs",
+    "benchmark:agent-surface": "node scripts/benchmark-agent-surface-simplification.mjs",
     "benchmark:targeting": "node scripts/benchmark-targeting-hot-paths.mjs",
     "benchmark:tests": "node scripts/benchmark-test-runner.mjs",
     "profile:routes": "node scripts/profile-route-selection.mjs",

package/services/localized-replacement-compiler.js

@@ -41,6 +41,65 @@ function occurrenceOffsets(sourceText, find) {
     return offsets;
 }
 
+function equivalentSpace(left, right) {
+    return (left === ' ' || left === '\u00a0')
+        && (right === ' ' || right === '\u00a0');
+}
+
+function spaceEquivalentOffsets(sourceText, find) {
+    const offsets = [];
+    for (let start = 0; start <= sourceText.length - find.length; start += 1) {
+        let matches = true;
+        for (let offset = 0; offset < find.length; offset += 1) {
+            const sourceCharacter = sourceText[start + offset];
+            const findCharacter = find[offset];
+            if (sourceCharacter !== findCharacter && !equivalentSpace(sourceCharacter, findCharacter)) {
+                matches = false;
+                break;
+            }
+        }
+        if (matches) offsets.push(start);
+    }
+    return offsets;
+}
+
+/** Resolve exact offsets first, then the narrow ASCII-space/NBSP equivalent fallback. */
+export function localizedReplacementOffsets(sourceText, find) {
+    const exact = occurrenceOffsets(sourceText, find);
+    if (exact.length > 0) return { offsets: exact, matchMode: 'exact' };
+    return { offsets: spaceEquivalentOffsets(sourceText, find), matchMode: 'space_equivalent' };
+}
+
+function preserveEquivalentBoundarySpaces(sourceSlice, find, replace) {
+    const effective = replace.split('');
+    let prefix = 0;
+    while (
+        prefix < find.length
+        && prefix < replace.length
+        && (find[prefix] === replace[prefix] || equivalentSpace(find[prefix], replace[prefix]))
+    ) {
+        if (equivalentSpace(sourceSlice[prefix], replace[prefix])) effective[prefix] = sourceSlice[prefix];
+        prefix += 1;
+    }
+    let sourceOffset = find.length - 1;
+    let replacementOffset = replace.length - 1;
+    while (
+        sourceOffset >= prefix
+        && replacementOffset >= prefix
+        && (
+            find[sourceOffset] === replace[replacementOffset]
+            || equivalentSpace(find[sourceOffset], replace[replacementOffset])
+        )
+    ) {
+        if (equivalentSpace(sourceSlice[sourceOffset], replace[replacementOffset])) {
+            effective[replacementOffset] = sourceSlice[sourceOffset];
+        }
+        sourceOffset -= 1;
+        replacementOffset -= 1;
+    }
+    return effective.join('');
+}
+
 function offsetCandidate(sourceText, start, length) {
     const excerptStart = Math.max(0, start - 40);
     const excerptEnd = Math.min(sourceText.length, start + length + 40);
@@ -168,15 +227,15 @@ export function compileExactReplacements(
         const replacement = validation.replacements[index];
         const itemField = `${field}[${index}]`;
         const occurrence = replacement.occurrence ?? null;
-        const offsets = occurrenceOffsets(sourceText, replacement.find);
+        const { offsets, matchMode } = localizedReplacementOffsets(sourceText, replacement.find);
         if (offsets.length === 0 || (occurrence != null && occurrence > offsets.length)) {
             return {
                 ok: false,
                 error: patchError(
                     'PATCH_SOURCE_NOT_FOUND',
                     occurrence == null
-                        ? `Exact patch source was not found: "${replacement.find}".`
-                        : `Occurrence ${occurrence} of exact patch source was not found: "${replacement.find}".`,
+                        ? `Patch source was not found: "${replacement.find}".`
+                        : `Occurrence ${occurrence} of patch source was not found: "${replacement.find}".`,
                     itemField,
                     'change_patch',
                     { matchCount: offsets.length }
@@ -188,7 +247,7 @@ export function compileExactReplacements(
                 ok: false,
                 error: patchError(
                     'AMBIGUOUS_PATCH_SOURCE',
-                    `Exact patch source matched ${offsets.length} locations; provide occurrence.`,
+                    `Patch source matched ${offsets.length} locations; provide occurrence.`,
                     itemField,
                     'choose_occurrence',
                     { candidates: offsets.map(start => offsetCandidate(sourceText, start, replacement.find.length)) }
@@ -197,12 +256,17 @@ export function compileExactReplacements(
         }
 
         const start = offsets[(occurrence || 1) - 1];
+        const sourceSlice = sourceText.slice(start, start + replacement.find.length);
         resolved.push({
             requestIndex: index,
             start,
             end: start + replacement.find.length,
             find: replacement.find,
             replace: replacement.replace,
+            effectiveReplace: matchMode === 'space_equivalent'
+                ? preserveEquivalentBoundarySpaces(sourceSlice, replacement.find, replacement.replace)
+                : replacement.replace,
+            matchMode,
             occurrence: occurrence || 1
         });
     }
@@ -212,7 +276,7 @@ export function compileExactReplacements(
     for (const replacement of resolved) {
         const previous = unique.at(-1);
         if (previous && replacement.start === previous.start && replacement.end === previous.end) {
-            if (replacement.replace !== previous.replace) {
+            if (replacement.effectiveReplace !== previous.effectiveReplace) {
                 return {
                     ok: false,
                     error: patchError(
@@ -245,7 +309,7 @@ export function compileExactReplacements(
     let desiredText = '';
     for (const replacement of unique) {
         desiredText += sourceText.slice(cursor, replacement.start);
-        desiredText += replacement.replace;
+        desiredText += replacement.effectiveReplace;
         cursor = replacement.end;
     }
     desiredText += sourceText.slice(cursor);
@@ -259,9 +323,10 @@ export function compileExactReplacements(
             end: replacement.end,
             find: replacement.find,
             replace: replacement.replace,
+            matchMode: replacement.matchMode,
             occurrence: replacement.occurrence,
             removedLength: replacement.end - replacement.start,
-            insertedLength: replacement.replace.length
+            insertedLength: replacement.effectiveReplace.length
         }))
     };
 }
@@ -280,6 +345,7 @@ export function buildLocalizedReplacementChange(compilation, outputText, target
         return {
             find: replacement.find,
             replace: replacement.replace,
+            ...(replacement.matchMode === 'space_equivalent' ? { matchMode: replacement.matchMode } : {}),
             occurrence: replacement.occurrence,
             beforeExcerpt: boundedExcerpt(sourceText, replacement.start, replacement.end),
             afterExcerpt: boundedExcerpt(desiredText, afterStart, afterEnd)

package/services/standalone-operation-runner.d.ts

@@ -252,6 +252,7 @@ export interface LocalizedReplacementChange {
     find: string;
     replace: string;
     occurrence?: number;
+    matchMode?: 'space_equivalent';
     beforeExcerpt: string;
     afterExcerpt: string;
   }>;