[ExSchwi]

Closes #419

What was wrong

`ops_write_file` could only ask for create-only by passing the literal string `"absent"`. The field was required twice over: `expectedRevision` sat in the schema's required list (`src/capabilities/file.ts`) and `WriteArgs.expected_revision` was a bare `String` in the worker, so serde rejected a missing value before publication.

Reproduced on Windows x64, Node v22.19.0, upstream main through the worker call the suite uses:

```
{"status":"error","error":{"code":"INVALID_ARGUMENT","phase":"preflight","retryable":false,"effectState":"none",
"message":"write_file: missing field `expectedRevision`"}}
```

A strict adapter that drops empty optional strings therefore had no way to request create-only without fabricating the sentinel.

The change

• `native/crates/ops-files/src/file_single.rs`: `WriteArgs.expected_revision` keeps its `String` type but gains `#[serde(default = "create_only_revision")]`, which defaults an omitted field to the `"absent"` sentinel the publication layer already understands. `write_single` still refuses an existing target and `check_revision` still compares `absent` against a missing file, so the fallback stays create-only and never becomes an overwrite wildcard (`REVISION_CONFLICT` otherwise). `EditArgs`, `copy`, `move` and `remove` keep their required revision untouched — the worker tolerates absence for `write_file` only.
• `src/capabilities/file.ts`: `write_file.required` becomes `['path','content']`; the field stays declared in `properties`. The `revision` description and `DESCRIPTIONS.write_file` now state that omitting it (or passing `"absent"`) means create-only.
• `test/file-operations.test.mjs`: the strict-contract assertion moves to `edit_file`/`copy`/`move`/`remove`, a `deepEqual` pins `write_file`'s required list, and the behaviour test covers an omitted revision (create, then `REVISION_CONFLICT` against the existing file), explicit blank/empty values (`INVALID_ARGUMENT`, nothing created), `null` (refused, nothing created) and `dryRun`.
• `test/file-args.test.mjs`: one test pins that the host bridge drops a blank or `null` `expectedRevision` for this now-optional field, which the worker reads as create-only, and keeps a real `"absent"` value.
• `native`: unit test `an_omitted_write_revision_defaults_to_the_create_only_sentinel` covers the omitted field, a real observed revision, a blank value that still fails validation, `null` that still fails deserialization, and `EditArgs` still failing without a revision.
• `test/capabilities.test.mjs`: the two pinned contract hashes are re-pinned with the reason recorded inline ([BUG] ops_write_file 的 create-only 只能靠字面量 "absent" 触发：expectedRevision 声明为 required，description 却写 "absent is create-only"，省略与空串两种自然写法都先硬失败 #419), the same way [BUG] ops-search: 非 UTF-8 文件误置 gap 导致 matchedTotal 缺失；且 grep 无 early-exit（实测 limit=5 慢 21×） #384 recorded its change.
• `docs/component-reference.md` + `docs/组件参考.md` updated in pair; `docs/CHANGELOG.md` `## [Unreleased]` entry in both languages.
• Deliberately unchanged: `edit_file`/`copy`/`move`/`remove` still require an observed revision, no schema field is removed, no new dependency, no `package.json` version or `optionalDependencies` change.
• Not done, suggestion 3 of the report (unify the opposite wording of `revision` and `existingRevision` in one pass): that would rewrite the `copy`/`move` descriptions and widen the contract surface past this issue. The new `revision` text names both the literal and the refusal, so the contrast is readable without touching the other field.
• Out of scope, the report's side note that the [Bug] workspace-write 下工作区所有者 ≠ 当前用户时，预准备脚本硬抛错，shell 完全不可用 #106 fix never reached the code: confirmed on main, `bin/prepare-workspace.ps1:14` still throws on an owner mismatch before `$needed` is computed at `:17`, and [Bug] workspace-write 下工作区所有者 ≠ 当前用户时，预准备脚本硬抛错，shell 完全不可用 #106 is already closed as completed with the reporter's own comment attached. This PR does not touch that script.

Scope note for #422

#422 (opened by the maintainer 33 minutes after this report) records the write-side decision boundary: the literal-`"absent"` discoverability problem is tracked in #419, and that issue "does not duplicate it, and does not pre-accept turning an empty string or null into create-only".

This PR therefore relaxes only the omitted field and leaves every explicit value on its previous path: an explicit blank still returns `INVALID_ARGUMENT` from the worker and `null` is still a type error. One consequence is worth stating up front rather than hiding in a test: because the field is no longer required, the generic host rule in `src/file/contract.ts:22-25` — which drops blank and `null` values of optional string fields — now also drops them here, so a call that goes through the bridge with `""` or `null` reaches the worker as an omitted field. That rule predates this PR and applies to every optional string field; `test/file-args.test.mjs` pins the behaviour so a reviewer can see it. Keeping blanks as errors end to end would need either the field back in `required` or a write-specific exception in that normalizer, which is exactly the contract decision #422 reserves. If you prefer that shape, say so and I will follow it.

Validation

Behaviour-level red and green, on the rebased tree (Rust worker rebuilt between runs):

```
$ git checkout origin/main -- native/crates/ops-files/src/file_single.rs && npm run build:ptc && node test/run.mjs file-operations
FAIL an omitted expectedRevision is create-only while an explicit blank or null stays a refusal
AssertionError [ERR_ASSERTION]: {"error":{"code":"INVALID_ARGUMENT","effectState":"none",
"message":"write_file: missing field `expectedRevision`","phase":"preflight","retryable":false},"status":"error"}
dsh-ops file-operations: 1 of 15 check(s) failed

$ cp <the PR's file_single.rs> native/crates/ops-files/src/file_single.rs && npm run build:ptc && node test/run.mjs file-operations
dsh-ops file-operations: all 15 checks passed

$ node test/run.mjs file-args
dsh-ops file-args: all 9 checks passed

$ cd native && cargo test -p ops-files
test result: ok. 14 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

$ node test/run.mjs capabilities
dsh-ops capabilities: all 6 checks passed
```

Full gate, the script CI runs:

```
$ node scripts/verify-gate.mjs --skip-install
=== versions / cargo version: node v22.19.0, cargo 1.98.1
=== build the plugin: 11 browser modules (67749 bytes); PTC declarations for 18 capabilities (113581 bytes); 50 assets
=== native worker unit tests: ok
=== build and stage the native worker: win32-x64 3884544 bytes, sha256 b2fca132952fc76e3a47941c58c9f82c927116ee104d5b0768ba9d14ebdb8489
=== Windows IPC payloads: ok
=== manifest contract: all 83 checks passed
=== full suite verification: 2 of 161 suite(s) failed, 4 skipped in 677s
FAIL 60 levels of nesting and dot segments resolve to the same file
AssertionError: a trailing separator is refused, not silently trimmed
+ undefined - 'INVALID_ARGUMENT' (test/linux-paths.test.mjs:143)
--- bash-ipc.test.mjs exceeded the 120s suite deadline; stopping its owned process tree

$ node test/run.mjs bash-ipc
dsh-ops bash-ipc: all 8 checks passed
dsh-ops test: 3 suite(s) passed in 80s
```

Neither red belongs to this change. `test/linux-paths.test.mjs:143` is the pre-existing Windows difference described under Environment (upstream `CI required` is green on win32-x64). `bash-ipc.test.mjs` hit the 120 s per-suite deadline while quarantining a tampered runtime under load and passes standalone in 80 s, with nothing in this PR touching the Bash lane. The four skips are the host-scoped ones the gate allows (linux-attributes, linux-shell, TUI host, native TUI).

CI required run (pull_request event):

```
$ gh run view 41084069191 --json url,event,conclusion,headSha
{"conclusion":"success","event":"pull_request","headSha":"72d6d0652662a98e47c336eb2fe1ef39a93d3a73",
"url":"https://github.com/T-Auto/dsh-ops/actions/runs/41084069191","workflowName":"Cross-platform validation"}

$ gh pr checks 500
CI required pass 4s
node-floor pass 3m42s
source-size pass 7s
tools-trial pass 30s
validate-macos-intel pass 8m54s
validate-posix (macos-latest, darwin-arm64) pass 2m55s
validate-posix (ubuntu-24.04, linux-x64) pass 3m24s
validate-windows (windows-latest, win32-x64) pass 5m43s
workflow-lint pass 8s
bench-smoke skipping
```

Environment

Windows 11 x64 (win32-x64), Node v22.19.0, npm 10.9.3, Rust 1.98.1 / cargo 1.98.1; base commit 3882e69 (upstream main); dependencies installed with `npm ci --ignore-scripts` from the checked-in lockfile. The one local red that is not part of this change is `test/linux-paths.test.mjs:143` ("a trailing separator is refused"): on Windows the worker accepts a trailing separator because Rust's `Path::components` drops it. Upstream CI was green on win32-x64 at a6e215a (run 40458041379), and this PR does not touch `file_path.rs`, so it is an environment difference rather than a regression.