Builtin Library
README.md
Observed scene operations
SceneJournal stores field edits with their original observed and proposed values. Each entry belongs to a world, branch, scene GUID and unique editing session. Session sequence numbers order operations under scene_dirty/operations/<session>/<sequence>.json.
session() creates a session token. create(snapshot, session, sequence, previous, current, resolvers, attribution?) normalizes the two scene documents and records their field differences. append(sceneFolder, entry) writes an immutable entry; it returns the path and whether an accepted receipt already settles the entry. Reusing a pending sequence with different bytes is refused. The latest retired sequence can be retried with identical bytes; older retired sequences are refused.
createChanges(observed, session, sequence, entities, settingsEdits, attribution?) records incremental normalized changes. observed carries the scene GUID, world, branch and accepted revision. The live scene writer uses this form for changed entities and settings.
visible(sceneFolder, resolvers, session?, previous?) composes pending entries over the locally accepted artifact. An optional session restricts which pending values are shown. Conflicts identify their journal operation. Structural conflicts retain the supplied previous complete document, or the accepted artifact. The read leaves all source files unchanged.
resolveFields(snapshot, path, resolutions, resolvers) chooses values for exact changed fields. Each selection has an entity id (omit it for scene settings), a field path and a recorded or accepted choice. Other proposed changes remain. Every remaining conflict must be resolved before the transaction is ready, and duplicate or absent field selections are refused.
review(snapshot, resolvers) returns captured operation rows, their recorded changes, current conflicts, and whether an earlier entry in the same session must settle first. resolve(snapshot, path, choice, resolvers) prepares a resolution of one whole reviewed operation. Choose recorded to retain its proposed fields against the reviewed accepted values, or accepted to keep those accepted values. Structural validation still applies. The resulting transaction checks the reviewed source revisions and retires only that operation with its receipt; a stale resolution leaves it intact.
prepare(latestSnapshot, path, resolvers) recovers the captured entry, verifies its identities and predecessor, and prepares a scene transaction. Commit it with SceneCoordinator.commit, then use awaitApplied before reading the accepted revision locally. Successful commit updates the artifact and authored intents, removes the consumed journal entry, and records its sequence and checksum atomically. A stale operation, validation failure or field conflict retains the entry for inspection and resolution. The accepted scene state retains one receipt per editing session.