ovstorage-user-write-safely

name	ovstorage-user-write-safely
description	Use when writing a new object without clobbering or updating an existing object with optimistic concurrency.
license	CC-BY-4.0
version	0.1.0
author	NVIDIA Omniverse
tags	["ovstorage","write","safety"]
tools	["Read"]
compatibility	Requires ovstorage MCP tools or equivalent library calls and an already-configured backend route with write permission.

Write Safely (No Clobbering)

Goal: Upload an object's bytes to a path. By default, fail loudly if the destination already exists rather than silently overwriting.

When to use this: You're writing something new and the destination should not exist yet, OR you're updating an existing object and want to verify it hasn't changed since you last looked.

Recipe — new file, refuse to clobber

Pass if_dest: { "kind": "fail" } to refuse to overwrite. The call fails with AlreadyExists if the address is taken.

{
  "tool": "ovstorage_write",
  "arguments": {
    "address": "s3://my-bucket/output/report.json",
    "data_base64": "ewogICJyZXN1bHQiOiAib2sifQo=",
    "if_dest": { "kind": "fail" }
  }
}

Recipe — update with optimistic concurrency

Pass if_dest: { "kind": "match_etag", "etag": "<s>" } with the etag you read earlier. If another writer has changed the object since then, the call fails with ObjectModified and you can decide whether to merge or restart.

{
  "tool": "ovstorage_write",
  "arguments": {
    "address": "s3://my-bucket/state/counter.json",
    "data_base64": "eyJjIjogN30=",
    "if_dest": { "kind": "match_etag", "etag": "\"abc123\"" }
  }
}

Recipe — intentional overwrite

The default behavior when if_dest is omitted is to overwrite. Pass if_dest: { "kind": "overwrite" } explicitly to document intent.

{
  "tool": "ovstorage_write",
  "arguments": {
    "address": "s3://my-bucket/cache/latest.json",
    "data_base64": "...",
    "if_dest": { "kind": "overwrite" }
  }
}

What success looks like

{
  "v": "0.1",
  "ok": true,
  "operation": "ovstorage_write",
  "result": {
    "info": {
      "address": "s3://my-bucket/output/report.json",
      "size": 4231,
      "etag": "\"def456\"",
      "version": null
    }
  }
}

Save info.etag (and info.version if your backend has it) — you need them for any later optimistic-concurrency write or if_match read.

Optional parameters

• user_metadata — map of {key: value} strings attached to the object. Treated as opaque by ovstorage; the backend persists what it can.
• message — an annotation associated with the write (used as a commit message by backends that version objects, e.g. Nucleus checkpoints).

When things go wrong

error.code	Likely cause	What to do
AlreadyExists	if_dest: {"kind": "fail"} and the destination exists	Pick a different address, or drop if_dest (or set {"kind": "overwrite"}) after confirming you really want to clobber
ObjectModified	if_dest: {"kind": "match_etag", ...} didn't match current identity	Re-read with ovstorage_stat, decide whether to merge, retry with the new etag
PermissionDenied	Credentials can't write here	Check ovstorage_doctor connection state
IntegrityFailure	Bytes received didn't match a checksum (rare)	Retry the write
Transient	Backend hiccup	retryable: true — try again
Unsupported	Backend doesn't support etag-conditional writes	Drop if_dest (or use {"kind": "overwrite"}); you lose the concurrency guarantee. Check ovstorage_capabilities to verify in advance

See also

• ovstorage-user-read-bytes — read identity (info.etag) for if_match
• ovstorage-user-delete-safely — symmetric concern for removal
• ovstorage-user-handle-errors — error structure