@ansonlai/docx-redline-js 0.6.1 → 0.7.0

package/docs/AGENT_FAST_START.md

@@ -7,53 +7,51 @@ Use this page for ordinary `.docx` edits. For source changes or unusual Word str
 If your host provides a document-session wrapper:
 
 1. Inspect/search once with enough surrounding context to draft the change.
-2. Apply using the returned revision-bound target handle. Send either the
-   complete desired paragraph or exact replacements supported by that wrapper.
-3. Treat only `ok: true` as complete. A failed handle must be refreshed by
-   inspection; never reuse it against a changed document.
+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.
 
 The repository's `examples/agent-session-wrapper.mjs` demonstrates this pattern.
 It is a development sample, not a package API.
 
 ## CLI fallback
 
-1. Extract only the relevant clause or range:
+1. For a literal mechanical edit with known old and new text, try one-turn apply:
 
    ```bash
-   docx-redline extract contract.docx --search "termination" --around 3
+   docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
    ```
 
-   Search is case-insensitive. Direct hits are capped; follow `selection.nextAfter` with `--after`, and cite `humanReference`, not `P42`.
+   The source must occur in one eligible paragraph. For text after a heading, add `--search "Section 4.1" --context-range 1:3`.
+   `--around 3` is symmetric; use it only when either side is eligible.
+
+2. For semantic drafting such as “make this provision mutual,” extract enough
+   context, then copy `exactText` with `paragraphId` or `fingerprint`:
+
+   ```bash
+   docx-redline extract contract.docx --search "termination" --around 3
+   ```
 
-2. Copy `exactText` with `paragraphId` or `fingerprint`. Use a UTF-8 operations
-   file or serializer-backed stdin, then apply once:
+   Search is case-insensitive; follow `selection.hint` and `selection.nextAfter`, and report `humanReference`. 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
    ```
 
-   `emit-operations.mjs` should use `JSON.stringify`; do not interpolate legal
-   text through shell quoting. `modified` is the complete desired accepted-view
-   paragraph, not only the inserted words.
+   Use `JSON.stringify`, not shell interpolation. `modified` is the complete desired accepted-view paragraph.
 
 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.
 
 ## Batch and result rules
 
-- Strong inspected targets are bound to the batch-start document. Independent
-  edits do not need bottom-up sorting around earlier paragraph splits.
-- Consolidate multiple desired texts for the same source paragraph. Follow an
-  explicit capture dependency for non-unique content created earlier in a batch.
+- 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. The source is not overwritten unless `--in-place` is
-  explicit.
+  per-operation error. For localized edits also require `change.committed: true`
+  and `change.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 correct and replay the complete batch.
-  `base: "output"` means keep committed progressive work and retry only the
-  reported failed or unattempted indexes.
-- Never accept/reject revisions or remove comments without user authorization.
-  `slice-cross-author` is the history-preserving option for a surgical edit
-  inside another reviewer's pending insertion.
+- `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.
 
 Advanced operations and recovery: [Agent Knowledge Base](AGENT_KNOWLEDGE_BASE.md); canonical contract: [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

@@ -482,20 +482,26 @@ Use this for everything by default. `apply` is fast, progressive, and self-valid
 
 The short route for a document-editing request is:
 
-1. Run one focused `extract` for the clauses or range being edited. Search is a
-   case-insensitive substring match; add `--around 3` when surrounding drafting
-   context is needed. Copy `exactText` plus `paragraphId` or `fingerprint`.
-2. Build the final operations from the operation table above. Use one operation
+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 a visible heading with `--search` and a directional range such as
+   `--context-range 1:3`. Repeated anchor matches are unioned; one eligible patch
+   paragraph is still required. `--occurrence` selects only within that 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.
-3. Run `apply` once per stable batch. Strong inspected targets are bound against
+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.
-4. Walk every result and require `completion: true`, `written: true`, and no
-   per-operation error.
-5. Run a focused `extract` on changed clauses only when placement or list/table
+5. Walk every result and require `completion: true`, `written: true`, and no
+   per-operation error. For localized patches also require committed `change`
+   evidence and positive accepted-view verification.
+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
@@ -503,22 +509,28 @@ bundle before this route. If `apply` returns an error, use the recovery matrix
 below and make one cause-specific correction.
 
 ```bash
-# 1. Focused contextual discovery
+# 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
+
+# 2. Mechanical edit strictly within three paragraphs after a visible heading
+docx-redline apply contract.docx --search "Section 4.1" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+
+# 3. Focused contextual discovery for semantic drafting
 docx-redline extract contract.docx --search "termination" --around 3
 
-# 2. Inline one-liner edit (fastest for 1–2 edits; no JSON file needed)
+# 4. Inline complete-paragraph edit
 docx-redline apply contract.docx --target "Original clause" --modified "New clause" --output reviewed.docx
 
-# 3. Direct edit without tracked changes (clean text, no revision clutter)
+# 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
 
-# 4. Cross-author edit inside another reviewer's pending insertion
+# 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
 
-# 5. Batch operations with ops.json
+# 7. Batch operations with ops.json
 docx-redline apply contract.docx --operations operations.json --output reviewed.docx
 
-# 6. Serializer-backed stdin with compact stdout
+# 8. Serializer-backed stdin with compact stdout
 node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
 ```
 
@@ -575,12 +587,17 @@ normalize or reconstruct `exactText`. Operation files follow
 Paragraph indexes are 1-based. Inspection filters are `--index 12`,
 `--range 10:30`, `--indexes 2,5,8`, `--search text`, `--revised`, `--table`,
 `--body`, `--non-empty`, and `--view accepted|rejected|current`. Search is
-case-insensitive. Add `--around N` (`--context N` or `-C N`) to a search;
+case-insensitive. When a search returns 0 matches in the active view but matches
+exist in the alternate view (such as searching for a deleted clause to restore),
+`selection.hint` provides immediate guidance to re-run with `--view rejected`.
+Add `--around N` (`--context N` or `-C N`) to a search;
 context records are labeled separately and do not consume the direct-hit
 `--limit`. Continue a bounded result with `--after <paragraph-index>`. Ordinary
 unscoped CLI inspection defaults to 20 direct records and a 48 KiB soft budget;
 `--all` deliberately opts out. A malformed filter or unknown option is an error
-rather than an unfiltered fallback.
+rather than an unfiltered fallback. CLI help commands (`apply --help`,
+`extract --help`, `--help`) report canonical GitHub repository URLs in their
+`documentation` array.
 
 Mutating commands use `--author`, operation-level authors, then
 `DOCX_REDLINE_AUTHOR`, falling back visibly to `AI Redliner`; review-resolution

package/docs/SKILL_AUTHORING.md

@@ -4,6 +4,31 @@ 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.
 
+> [!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.
+
+For example, an integration authored for the current contract-8 release should
+record a compatibility declaration equivalent to:
+
+```json
+{
+  "testedLibraryRelease": "0.7.0",
+  "requiredCliContractVersion": 8,
+  "requiredCapabilities": [
+    "command-help-v1",
+    "recovery-envelope-v1",
+    "localized-replacements-v1",
+    "speculative-search-apply-v1",
+    "localized-change-summary-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
@@ -13,14 +38,11 @@ the CLI:
 docx-redline version
 ```
 
-Require contract version 7 and only the capabilities the integration uses. A
-typical shell skill should require `command-help-v1`, `inspection-context-v1`,
-`bounded-inspection-v1`, `human-document-references-v1`,
+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 `operations-stdin` or `compact-cli-json-v1` only
-when the host uses those features. Fail closed with an upgrade instruction when
-a required capability is absent. Never inspect `dist/`, minified source, or ZIP
-parts to compensate for a stale runtime.
+`recovery-envelope-v1`. Require other capabilities only when used. Fail closed
+when one is absent; never inspect bundles or ZIP parts as a fallback.
 
 ## Safety invariants
 
@@ -52,14 +74,6 @@ Choose and document these separately from safety invariants:
 | 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. |
 
-Examples of valid profile composition:
-
-```bash
-docx-redline apply input.docx --operations operations.json --profile agent --output reviewed.docx
-docx-redline apply input.docx --operations operations.json --profile agent --atomic --output reviewed.docx
-docx-redline apply input.docx --operations operations.json --profile agent --existing-revisions slice-cross-author --output reviewed.docx
-```
-
 Check `effectiveOptions` rather than assuming the resolved transaction,
 revision, author, or redline policy.
 
@@ -80,16 +94,34 @@ return the full structured result rather than recreating the CLI serializer.
 
 ## Ordinary generated workflow
 
-The first executable document-editing example in a generated skill should be a
-focused contextual extraction:
+For an exact mechanical edit whose existing and replacement literals are known,
+the first executable example should use the one-turn fast path:
+
+```bash
+docx-redline apply input.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+```
+
+If the literal is not globally unique, scope it with a meaningful visible
+anchor. A heading followed by a multi-paragraph provision should use a
+directional window such as `--search "Section 4.1" --context-range 1:3`;
+`--around 3` is symmetric and should be used only when either side is eligible.
+Require the returned localized `change` evidence, including `committed: true`
+and `verification.acceptedViewMatchesCompiledText: true`.
+
+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:
 
 ```bash
-docx-redline extract input.docx --search "force majeure" --around 3
+docx-redline extract input.docx --search "termination" --around 3
 ```
 
-Use `selection.nextAfter` with `--after` when truncated. Apply once per stable
-batch. Run `docx-redline apply --help` for canonical redline, whole-paragraph
-comment, and rejected-view restore shapes; the operation schema remains
+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).
 
 ## Recovery contract
@@ -116,8 +148,15 @@ an exact machine target with a human-facing reference.
 
 ## 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.
-- The first ordinary edit command is focused `extract --search ... --around`.
+- 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.

package/docs/releases/0.7.0.md

@@ -0,0 +1,199 @@
+## @ansonlai/docx-redline-js v0.7.0
+
+Version 0.7.0 targets the remaining latency in AI-driven document editing: tool
+turns and generated paragraph text. It adds exact localized replacements,
+fail-closed one-turn apply, directional provision scoping, and compact verified
+change evidence while retaining the existing OOXML mutation pipeline.
+
+The engine remains OOXML-only and host-independent. This release adds no runtime
+dependency and does not require Microsoft Word, Office automation, COM, or a
+proprietary document API. Existing reconciliation, tracked-change generation,
+package validation, rollback, comment preservation, and Accept/Reject semantics
+remain authoritative.
+
+---
+
+### Breaking Changes & Migration
+
+- **CLI contract version 8:** Wrappers using the new fast path should require
+  `localized-replacements-v1`, `speculative-search-apply-v1`, and
+  `localized-change-summary-v1`. Negotiate only the capabilities actually used.
+- **Pre-1.0 integration pinning:** Skills, MCP servers, and harnesses should pin
+  the exact `0.7.0` package release they tested and declare contract 8 plus their
+  minimum capability set. Treat another release or contract as unverified until
+  compatibility tests pass.
+- **No operation-shape removal:** Existing operations with complete `modified`
+  content continue to work. Localized replacements and `change` results are
+  additive; consumers ignoring unknown result fields remain compatible.
+
+---
+
+### 1. Localized Exact Replacements
+
+A text operation can now provide exact replacement instructions instead of
+reproducing the complete paragraph:
+
+```json
+{
+  "type": "redline",
+  "target": { "paragraphId": "1A2B3C4D" },
+  "replacements": [
+    {
+      "find": "thirty (30) days",
+      "replace": "sixty (60) days"
+    }
+  ]
+}
+```
+
+The compiler resolves the source paragraph against the immutable batch-start
+accepted view, applies non-overlapping patches simultaneously, synthesizes the
+complete desired text, and passes it through the ordinary reconciliation,
+validation, receipt, and rollback pipeline.
+
+V1 is deliberately narrow:
+
+- one accepted-view paragraph;
+- exact, case-sensitive source matching;
+- optional positive, 1-based `occurrence` within that paragraph;
+- an empty `replace` may delete a span;
+- ambiguous, missing, no-op, overlapping, or conflicting patches fail before
+  mutation; and
+- captures, rejected-view mutation, created-content dependencies, and
+  cross-paragraph patches remain outside localized-replacement v1.
+
+### 2. One-Turn Speculative Apply
+
+Globally unique literal edits no longer require preliminary extraction:
+
+```bash
+docx-redline apply contract.docx --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+```
+
+For a heading followed by a multi-paragraph provision, use a visible text anchor
+and directional paragraph scope:
+
+```bash
+docx-redline apply contract.docx --search "Section 4.1" --context-range 1:3 --find "thirty (30) days" --replace "sixty (60) days" --profile agent --output reviewed.docx
+```
+
+`1:3` means strictly the next three physical paragraphs, excluding the heading
+and preceding paragraphs. Other supported forms include `0:0`, `0:3`,
+`-3:-1`, and `-3:3`; offsets are inclusive, bounded to `-20..20`, and clamped at
+document boundaries. `--around 3` is shorthand for `-3:3`.
+
+Every matching search anchor contributes a window. The library unions and
+deduplicates those windows, then requires exactly one eligible paragraph to
+contain the exact `find` literal. Thus a visible section number may appear both
+as a heading and in cross-references without the anchor itself deciding what is
+edited. `--occurrence` may disambiguate only inside the uniquely selected
+paragraph; it never chooses between paragraphs.
+
+### 3. Refusal Without Output Damage
+
+Speculation remains conservative:
+
+- no contextual anchor returns `TARGET_NOT_FOUND`;
+- no exact patch source returns `PATCH_SOURCE_NOT_FOUND`;
+- multiple eligible paragraphs return `AMBIGUOUS_TARGET`;
+- multiple source spans within one paragraph return
+  `AMBIGUOUS_PATCH_SOURCE`; and
+- invalid ranges and mixed targeting forms return a request error.
+
+These failures include machine recovery metadata and bounded candidates. They
+occur before output writing, so an existing destination is not truncated or
+overwritten. The source remains immutable unless `--in-place` is explicit.
+
+### 4. Explicit Post-Mutation Change Evidence
+
+Successful localized operations return a compact evidence object:
+
+```json
+{
+  "change": {
+    "kind": "localized_replacement",
+    "committed": true,
+    "finalDisposition": "applied",
+    "target": {
+      "paragraphId": "1A2B3C4D",
+      "humanReference": "Section 4.1 — Termination"
+    },
+    "context": {
+      "search": "Section 4.1",
+      "range": "1:3",
+      "anchorMatchCount": 2
+    },
+    "replacements": [
+      {
+        "find": "thirty (30) days",
+        "replace": "sixty (60) days",
+        "beforeExcerpt": "...thirty (30) days...",
+        "afterExcerpt": "...sixty (60) days..."
+      }
+    ],
+    "verification": {
+      "acceptedViewMatchesCompiledText": true
+    }
+  }
+}
+```
+
+Evidence is derived from the resolved source and actual post-mutation accepted
+view rather than simply echoing the request. Excerpts are deterministically
+bounded to 120 characters. Agent completion additionally requires committed,
+applied evidence and positive accepted-view verification. Atomic rollback marks
+previously attempted evidence `committed: false` and `rolled_back`.
+
+### 5. Agent Guidance and Development Wrapper
+
+- Agent Fast Start, the repository launch card, Skill Authoring Contract,
+  README, CLI help, and the advanced knowledge base now distinguish exact
+  mechanical edits from semantic drafting.
+- Literal names, dates, numbers, defined terms, and isolated phrase changes can
+  use localized one-turn apply. Semantic requests such as “make this provision
+  mutual” still begin with focused extraction and drafting.
+- The skill-authoring contract warns pre-1.0 integrations to pin the exact
+  package release and required CLI contract/capabilities.
+- `examples/agent-session-wrapper.mjs` remains a development-only illustration,
+  not a package export or alternate mutation engine.
+
+---
+
+### Performance Results
+
+The controlled `npm run benchmark:localized` comparison uses the same runtime
+for both paths, with 3 warmups and 11 measured iterations per case:
+
+- tool turns fell from 2 to 1 (**50% reduction**);
+- generated request bytes fell **65.06%–79.39%**;
+- the deterministic request-token proxy fell **64.77%–78.98%**; and
+- median native engine/I/O time ranged from **0.58% slower to 5.41% faster**,
+  confirming that the intended savings are primarily outside the OOXML engine.
+
+The token proxy is `ceil(UTF-8 request bytes / 4)`, not a provider tokenizer or
+billed-token measurement. Provider reasoning, streaming, network, and full
+Claude/OpenCode wall time were not estimated. See the
+[localized rollout audit](../validation-reports/2026-09-14-localized-patching-rollout.md).
+
+### Verification
+
+- `npm test`: **113 passed, 0 failed**
+- `npm run check:types`: declarations verified for **123 runtime exports**
+- `npm run test:isolation`: dependency and Word-API isolation passed
+- Focused CLI/compiler/test/benchmark lint: passed
+- Package dry run: compiler and published guidance included; development-only
+  benchmark and wrapper excluded
+
+---
+
+### Installation
+
+```bash
+npm install @ansonlai/docx-redline-js@0.7.0
+```
+
+CDN (ESM):
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@ansonlai/docx-redline-js@0.7.0/dist/docx-redline-js.esm.min.js"></script>
+```

package/docs/schemas/document-operations.schema.json

@@ -38,6 +38,16 @@
       },
       "additionalProperties": false
     },
+    "localizedReplacement": {
+      "type": "object",
+      "required": ["find", "replace"],
+      "properties": {
+        "find": { "type": "string", "minLength": 1 },
+        "replace": { "type": "string" },
+        "occurrence": { "type": "integer", "minimum": 1 }
+      },
+      "additionalProperties": false
+    },
     "target": {
       "oneOf": [
         { "type": "string", "minLength": 1 },
@@ -99,6 +109,9 @@
           },
           "additionalProperties": false
         },
+        {
+          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["replacements"], "properties": { "type": { "enum": ["redline", "replace"] }, "replacements": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/localizedReplacement" } } } } ]
+        },
         {
           "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["modified"], "properties": { "type": { "enum": ["redline", "replace", "format", "list-change", "table-reconciliation", "insert"] }, "modified": { "type": "string" }, "structuredContent": { "type": "boolean" }, "targetEnd": { "$ref": "#/$defs/target" }, "targetEndRef": { "type": ["integer", "string", "null"] }, "anchor": { "$ref": "#/$defs/rejectedTextInsertionAnchor" } } } ]
         },

package/docs/validation-reports/2026-09-14-localized-patching-rollout.md

@@ -0,0 +1,90 @@
+# Localized Patching and Turn-Reduction Rollout Audit
+
+**Date:** 2026-09-14
+**Scope:** WP-05 correctness matrix and controlled workflow benchmark for CLI
+contract 8
+
+## Outcome
+
+The contract-8 literal fast path removes one of two tool turns and reduces the
+generated mutation request by roughly two-thirds to four-fifths in the measured
+cases. Native DOCX execution remains essentially the same speed: median changes
+ranged from 0.58% slower to 5.41% faster. This is the intended result—the
+feature attacks agent turn and output-generation latency without replacing the
+OOXML reconciliation or validation pipeline.
+
+All successful candidates produced the expected accepted-view text, positive
+localized change verification, and a byte-identical source document. Refused
+speculation remained non-writing in the automated suite.
+
+## Controlled comparison
+
+Run:
+
+```bash
+npm run benchmark:localized
+```
+
+The benchmark uses `tests/fixtures/sample_doc_test.docx`, 3 warmups, and 11
+measured iterations per workflow. Both paths run on the same current source
+tree to isolate workflow shape from runtime or machine drift:
+
+- **0.6.2-style baseline:** focused `extract`, followed by a canonical
+  full-paragraph operation.
+- **Contract-8 candidate:** targetless localized `apply`, either globally or
+  within a directional heading scope.
+
+| Case | Tool turns | Request bytes | Token proxy | Median local ms | p95 local ms |
+|---|---:|---:|---:|---:|---:|
+| Short punctuation, baseline → candidate | 2 → 1 | 244 → 79 | 61 → 20 | 55.34 → 53.37 | 83.89 → 62.11 |
+| Long provision, baseline → candidate | 2 → 1 | 352 → 123 | 88 → 31 | 58.02 → 54.88 | 70.04 → 59.44 |
+| Directional heading, baseline → candidate | 2 → 1 | 626 → 129 | 157 → 33 | 56.46 → 56.79 | 77.35 → 63.92 |
+
+Observed reductions:
+
+- Tool turns: **50%** in every case.
+- Generated request bytes: **65.06%–79.39%**.
+- Deterministic token proxy: **64.77%–78.98%**.
+- Median local engine/I/O time: **-0.58%–5.41%** (effectively neutral).
+- p95 local engine/I/O time: **15.13%–25.96% lower** in this run; timing is
+  observational and not a correctness gate.
+
+The directional candidate returned 20 more response bytes than its two-turn
+baseline because its one response includes explicit location and before/after
+verification. That small cost is intentional: it removes the verification turn
+while making the applied change auditable.
+
+## Measurement boundary
+
+`generatedTokenProxy` is `ceil(UTF-8 request bytes / 4)`. It is a deterministic
+comparison aid, not a provider tokenizer or billed-token count. Local timing
+uses `performance.now()` and includes DOCX reads, inspection, mutation,
+validation, and output writing.
+
+The benchmark does **not** measure model reasoning, token streaming, tool
+transport, network latency, or end-to-end Claude/OpenCode wall time. Those
+components require external harness transcript instrumentation and must not be
+inferred from native timing. The JSON artifact is written to
+`tmp/benchmarks/localized-turn-reduction-latest.json`.
+
+## Correctness coverage
+
+The expanded suites cover:
+
+- simultaneous localized replacements, ambiguity, deletion, no-op and overlap
+  rejection, unsupported v1 shapes, summary ordering, excerpt bounds, and
+  atomic rollback disposition;
+- global speculative success; `0:0`, `0:3`, `1:3`, `-3:-1`, and `-3:3`
+  directional windows; boundary clamping; repeated-anchor window deduplication;
+  missing anchors and patch sources; multi-paragraph and same-paragraph
+  ambiguity; occurrence scoping; stale IDs; protected outputs; response bounds;
+  and agent-profile exit behavior.
+
+## Verification
+
+- `npm test`: 113 suites passed, 0 failed with the expanded assertions.
+- `npm run check:types`: 123 runtime exports have declarations.
+- `npm run test:isolation`: dependency and Word-API isolation passed.
+- Focused ESLint for the localized compiler, CLI, benchmark, and tests passed.
+- `npm pack --dry-run --json`: 154 entries; the compiler and this report are
+  included, while the fixture-dependent benchmark script is excluded.

package/index.d.ts

@@ -23,6 +23,8 @@ export type {
   DocumentOperationBatchResult,
   HighlightDocumentOperation,
   InsertionAffinity,
+  LocalizedReplacement,
+  LocalizedReplacementChange,
   OperationConflict,
   OperationDependencyPlan,
   OperationPreflightItemResult,