Apply Local JSON Patch Proposals Through an Atomic Store Boundary

Direct answer

A JSON Patch document is an ordered array of operations against a target JSON document. RFC 6902 defines add, remove, replace, move, copy, and test; operations run in array order, with each result becoming the input to the next operation. Every operation uses a JSON Pointer path, and some operations also use from. A model-generated patch is therefore a proposed state transition, not a partial object to merge by field name. Parse it as untrusted input, validate the operation vocabulary, path policy, values, and base revision, and keep the user source unchanged until the application accepts the complete result. JSON Pointer has its own escaping contract: slash inside a reference token is encoded as ~1 and tilde as ~0. During evaluation, decode ~1 before ~0 so a token such as ~01 does not accidentally become a slash. A pointer is interpreted against the current target structure, so array edits shift later indexes. The special dash token denotes the append position when an operation uses an array as its add destination; copy and move also add at their destination, so test those destination rules separately. It is not a general existing array index. Path strings must never be converted to Java/Kotlin property access by reflection; select an allowlisted set of pointers and check every segment against the record schema. The test operation compares the value currently at its target path with the supplied JSON value using RFC 6902 equality: JSON types must match, numbers compare numerically, strings by code points, and compound values by their JSON contents. It can act as a stale-content precondition for a small patch, but it is not an authorization check, a durable revision number, or a user confirmation. If another edit occurs after the test and before save, the patch can still overwrite newer state unless the record owner checks a revision at commit time. Carry a base revision or digest for the full source record and compare it again in the same transaction that persists the accepted result. Do not assume a JSON Patch library mutates atomically. RFC 6902 says evaluation should stop at a failed operation and the patch document must not be deemed successful; it also notes HTTP PATCH is atomic under RFC 5789. That HTTP rule does not automatically apply to a local mutable object, an Android data class, or multiple database writes. Apply to an isolated deep copy or immutable document, validate the complete resulting schema and domain rules, produce a diff for review, then atomically replace the owned record only if its revision still equals the base revision. If any test, path, operation, or commit check fails, discard the candidate without partial persistence. Constrain the operation set to the feature. A note editor may need replace/add and test but not move, copy, or root replacement. A settings proposal can allow only specific leaf values and enumerations; an attempt to alter identity, permissions, account IDs, storage paths, or unknown fields should be rejected before evaluation. Add and remove on arrays change subsequent indexes, and move from a path into one of its children is invalid. Do not claim that arbitrary RFC-compliant patches are acceptable product changes; schema and application policy are narrower than the patch format. Operation count, source size, path length, value size, array index, nesting, and evaluation time should be bounded separately. Keep candidate state, approved state, and user-authored source distinct. The UI should show a readable before/after diff, including removed text and sensitive fields, and ask before committing consequential edits. Model confidence, a passing test operation, or syntactic validity does not supply user consent. Record a privacy-safe proposal ID, base revision, accepted operation classes, validation result, user decision, and committed revision without logging raw private values by default. Each operation requires op and path. Add, replace, and test also require value; move and copy require from. Keep format-required members separate from a product policy that allows only a subset, and enforce operation-specific member rules. Build fixtures around the exact adapter and storage transaction: pointer keys containing slash and tilde, a ~01 token, array insert/remove shifts, dash append for add/copy/move destinations, failed from path, move into a descendant, test value type differences, numeric equality, null, unknown op, duplicate object members, and operation failure midway. Simulate the source changing after preview but before commit and require a revision conflict rather than silent rebasing. Verify both resulting values and the unchanged original after failure. The patch format does not promise that a model proposal is correct or that every storage layer offers the same transaction semantics. This is a local structured-edit method, not a Cove feature claim. It does not establish Cove stores JSON records or supports patch editing. Apply through the actual record owner, such as a Room transaction, rather than mutating serialized state outside the data owner. Keep source history, generated suggestions, approved changes, and migration state separate.

A local model proposes changing one field in a saved profile

An offline assistant reads a user-approved JSON profile and suggests modifying a display name while preserving other fields. The record may have changed after model input was read, and the model could include another operation that targets a private identifier.

Decision

Validate a narrow operation set and pointer allowlist, apply to a copy of the exact source revision, show a before/after diff, and commit only with an atomic owner revision check after user approval.

Expected outcome

The profile is either updated as one reviewed revision or left unchanged with a visible conflict; no partial patch or model authority is inferred.

Evidence to collect

The claim becomes reviewable only when the following evidence is attached to the same artifact and test run:

• Original/candidate document and patch identity
• Pointer escaping and ordered-operation fixtures
• Failure rollback and single-commit observations

Task quality needs a versioned corpus and acceptance rules. Fluent sample output is not an accuracy result.

Implementation workflow

1. Define the editable document and operation set. Choose a typed document schema, approved pointer paths, allowed operations, value limits, and fields that must never be edited. The empty pointer targets the whole document; exclude root replacement, move/copy, or remove unless the product specifically requires and tests them.
2. Parse and validate patch syntax. Require op and path for every operation, value for add/replace/test, and from for move/copy; enforce operation-specific members and validate RFC 6901 escapes. Bound operation count, path length, value size, nesting, array index, and evaluation work before mutation.
3. Apply to an isolated source revision. Load the current source plus a stable revision, apply operations sequentially to a deep copy, evaluate test operations against current values, and validate the complete candidate against schema and domain rules.
4. Preview and obtain user approval. Show a before/after diff for the exact source record and summarize changed fields. Treat test as a content precondition only; it does not authorize saving or replace user confirmation.
5. Commit with conflict detection. Inside the record owner transaction, compare the current revision with the proposal base revision and persist the whole candidate atomically. On mismatch or any failed operation, discard the copy and leave the source unchanged.

Keep each transition observable. A failure should identify the stage, artifact, runtime, and recovery action without logging private user content.

Acceptance criteria

• The application uses a pinned RFC 6902/6901 implementation or a tested subset, with explicit allowed operations and path segments.
• Patch evaluation occurs on an isolated copy; failed operations never partially change the owned source record.
• Commit compares the base revision in the same atomic owner transaction; concurrent edits cause a conflict rather than silent rebase.
• A diff and user decision precede persistence; test operations and valid syntax are not treated as authorization.

Decision table

Failure patterns to prevent

• Applying operations directly to live user state
• Assuming HTTP PATCH semantics make Room transactions atomic
• Treating a model patch as user authorization

Also prevent silent fallback, unpinned artifacts, missing cancellation, and conclusions that combine unlike configurations. Store unsuccessful runs alongside successful ones.

Minimum reproducibility record

Release checklist

• ☐ The primary query is answered without an unsupported number.
• ☐ Every artifact and runtime is pinned.
• ☐ The representative task and failure policy are explicit.
• ☐ Lifecycle, cancellation, cleanup, and fallback are tested.
• ☐ User-content and network boundaries are documented.
• ☐ Result wording applies only to the recorded configuration.
• ☐ The page links to raw method or evidence when results are added.

Sources and related evidence

• Android privacy and security
• IETF — RFC 6902 JSON Patch operations and error handling
• IETF — RFC 6901 JSON Pointer escaping and evaluation
• AndroidX Room — Transaction API
• IETF — RFC 5789 HTTP PATCH atomicity

Chinese deployment and troubleshooting content is organized in the .奇连 AI 端侧专题.

Frequently asked questions