Make workspace transactions deeply isolated and truly atomic #7

New issue

Closed

opened 2026-07-30 04:05:13 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-07-30 04:05:13 +00:00

(Migrated from github.com)

Problem

workspace.transaction in PR #3 shallow-copies document and graph values into a candidate workspace. Graph objects and their JSOWN node/edge arrays are therefore shared between the candidate and authoritative workspace.

Graph operations mutate these arrays in place. A failed transaction can leak partial graph changes into authoritative state even when the candidate is discarded.

The existing rollback test only exercises duplicate document creation in a blank candidate. It does not copy an existing graph, mutate it, fail later, and verify the original graph is unchanged.

Several generated inverse operations are also malformed or semantically wrong, including document update inverses using document.create and node/edge inverses nesting objects under payload shapes not consumed by their handlers.

Found during review of PR #3.

Required changes

Implement a real deep clone for all canonical workspace data used by transactions:
- documents
- graphs
- node/edge arrays
- nested JSON objects and arrays
- settings
- revision/journal data as appropriate
Apply all transaction operations exclusively to the isolated candidate.
Do not mutate any object reachable from authoritative state before commit.
Validate the full operation list before replacing authoritative state.
Standardize transaction entries on the documented command/payload format, or explicitly version and document a different format.
Correct inverse operation generation for every CRUD operation.
Preserve the underlying stable error in transaction details while returning transaction.failed at the top level.

Acceptance criteria

A transaction that mutates an existing graph and then fails leaves the authoritative graph byte-for-byte unchanged.
Successful transactions increment the revision once.
Failed transactions do not emit events, save state, or append journal entries.
All inverse operations can be dispatched successfully and restore prior state.
Tests cover document, node, and edge rollback against pre-existing authoritative state.

Related PR: #3

## Problem `workspace.transaction` in PR #3 shallow-copies document and graph values into a candidate workspace. Graph objects and their JSOWN node/edge arrays are therefore shared between the candidate and authoritative workspace. Graph operations mutate these arrays in place. A failed transaction can leak partial graph changes into authoritative state even when the candidate is discarded. The existing rollback test only exercises duplicate document creation in a blank candidate. It does not copy an existing graph, mutate it, fail later, and verify the original graph is unchanged. Several generated inverse operations are also malformed or semantically wrong, including document update inverses using `document.create` and node/edge inverses nesting objects under payload shapes not consumed by their handlers. Found during review of PR #3. ## Required changes - Implement a real deep clone for all canonical workspace data used by transactions: - documents - graphs - node/edge arrays - nested JSON objects and arrays - settings - revision/journal data as appropriate - Apply all transaction operations exclusively to the isolated candidate. - Do not mutate any object reachable from authoritative state before commit. - Validate the full operation list before replacing authoritative state. - Standardize transaction entries on the documented `command`/`payload` format, or explicitly version and document a different format. - Correct inverse operation generation for every CRUD operation. - Preserve the underlying stable error in transaction details while returning `transaction.failed` at the top level. ## Acceptance criteria - A transaction that mutates an existing graph and then fails leaves the authoritative graph byte-for-byte unchanged. - Successful transactions increment the revision once. - Failed transactions do not emit events, save state, or append journal entries. - All inverse operations can be dispatched successfully and restore prior state. - Tests cover document, node, and edge rollback against pre-existing authoritative state. Related PR: #3