@ansonlai/docx-redline-js 0.7.1 → 0.8.0

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,49 @@ 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. In JavaScript/TypeScript runtimes
+(Node.js, browsers, Cloudflare Workers, Deno, Bun, or sandboxed environments like
+n8n), an in-process wrapper should call `openDocx(uint8Array)` directly from
+`@ansonlai/docx-redline-js` (or `@ansonlai/docx-redline-js/bundle` for zero-dependency
+standalone sandboxes) 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 +128,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/TESTING.md

@@ -31,7 +31,8 @@ fixtures rarely contain.
 | Live-session accuracy and instrumentation | `node tests/performance_phase1_session_tests.mjs` | One full parse/serialization, sequential semantic equivalence, exact accepted/rejected text, valid revisions, list/table/comment/highlight preservation, savepoint no-ops, and zero-serialization rollback | Desktop Word rendering |
 | Target hot-path parity | `node tests/performance_phase3_target_hot_paths_tests.mjs` | Cached and uncached resolution metadata parity, duplicate safety, snapshots, session invalidation, and pointer-based revision-ID seeding | Machine-independent latency thresholds |
 | List and text-walker parity | `node tests/performance_phase4_list_and_text_parity_tests.mjs` | One shared marker vocabulary and canonical/specialized visible-text agreement across structural characters and revision views | That all specialized mappings are interchangeable |
-| Route compatibility | `node tests/performance_phase5_route_consolidation_tests.mjs` | Direct/legacy list accepted-rejected parity, numbering artifacts, route selection, capability records, and stable public exports | Permission to migrate the retained multi-paragraph compatibility route |
+| Universal document facade & ZIP | `node tests/universal_docx_document_tests.mjs`, `node tests/universal_zip_archive_tests.mjs`, `node tests/universal_facade_edge_cases_tests.mjs` | Universal `Uint8Array` binary handling, `fflate` compression/decompression, optimistic concurrency, and complete-DOCX operations without Node built-ins | Desktop Word rendering |
+| Sandbox bundle isolation | `node tests/sandbox_bundle_isolation_tests.mjs` | Zero-dependency standalone ESM/CJS bundles execute in restricted VM sandboxes without `process`, `Buffer`, or `require`, with zero Node built-in imports | Web Worker latency |
 | Cross-author revision slicing | `node tests/cross_author_slicing_fixtures_tests.mjs`, `node tests/cross_author_carrier_splitting_tests.mjs`, `node tests/cross_author_slicing_synthetic_tests.mjs`, `node tests/cross_author_slicing_real_tests.mjs`, `node tests/cross_author_slicing_hyperlink_roundtrip_tests.mjs`, `node tests/cross_author_slicing_insertion_stress_tests.mjs` | Word-native `<w:ins>` splitting, `<w:del>` nesting, multi-author stacking, straddle boundaries, synthetic matrix (SYN-01..12d), strict package differential replay (PKG-01..06), exact hyperlink/NBSP round trips, and 76 insertion stress scenarios | Non-Word consumers beyond OpenXML XSD validation |
 
 The package-facade regression opens a real ZIP buffer, adds a comment beside an

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/document/docx-document.d.ts

@@ -0,0 +1,39 @@
+import type { DocumentOperation, DocumentOperationBatchResult, OperationPreflightResult, StandaloneRunnerOptions } from '../services/standalone-operation-runner.js';
+import type { DocumentInspectionOptions, DocumentInspectionResult, RevisionToken } from '../index.js';
+
+export interface DocxApplyOptions extends StandaloneRunnerOptions {
+  author?: string;
+  validate?: boolean;
+}
+
+export interface DocxApplyResult extends DocumentOperationBatchResult {
+  written: boolean;
+  uint8Array: Uint8Array;
+  buffer: Uint8Array;
+  inspection?: DocumentInspectionResult;
+  artifactsChanged?: string[];
+  validation?: { originalIssues: unknown[]; generatedIssues: unknown[] };
+  issues?: unknown[];
+  toUint8Array(): Uint8Array;
+  toBuffer(): Uint8Array;
+}
+
+export class DocxDocument {
+  constructor(input: Uint8Array | ArrayBuffer | string);
+  readonly originalBytes: Uint8Array;
+  readonly originalBuffer: Uint8Array;
+  readonly entries: Map<string, Uint8Array>;
+  inspect(options?: DocumentInspectionOptions): DocumentInspectionResult;
+  getRevisionToken(): RevisionToken;
+  readonly revisionToken: RevisionToken;
+  preflight(operations: DocumentOperation[], author?: string, options?: StandaloneRunnerOptions): OperationPreflightResult;
+  applyOperations(operations: DocumentOperation[], options?: DocxApplyOptions): Promise<DocxApplyResult>;
+  resolveRevisions(action: 'accept' | 'reject', options?: { author?: string; allAuthors?: boolean; validate?: boolean }): Promise<DocxApplyResult>;
+  deleteComments(options?: { author?: string; allAuthors?: boolean; validate?: boolean }): Promise<DocxApplyResult>;
+  toUint8Array(): Uint8Array;
+  toBuffer(): Uint8Array;
+}
+
+export function computePackageRevisionToken(input: unknown): RevisionToken;
+
+export function openDocx(input: Uint8Array | ArrayBuffer | string): DocxDocument;