Inspect, validate, and review a proposal

External tools can inspect the saved authoring world and propose the same structured transactions used by the atelier. Validation compiles the complete candidate and describes its changes without committing it. Saving remains a separate action with revision/conflict checks.

#In the atelier

1. Save or discard your current unsaved edit, then choose Review proposal… in the left sidebar.
2. Load a proposal JSON file or paste a transaction. Choose Check proposal.
3. Inspect the added, updated and removed counts, affected names, places and properties. A no-op is reported explicitly and cannot be previewed. Validation errors keep the saved world unchanged.
4. Choose Preview in atelier. Use the Place selector to inspect changes in different places. Discard draft cancels; Save changes accepts the commands and records durable undo. Undo/redo survives reload.

Closing the panel or changing its input invalidates an earlier validation response. The editor independently compiles the normalized commands and checks the candidate hash before offering a preview. The original proposal's merge policy survives Save: omitted merge is strict, while merge: "disjoint" explicitly permits safe merging across retained independent edits. Overlapping changes still conflict. A newer server head requires reloading the editor and checking again; the proposal text is retained for that retry.

Validation does not reserve a revision, publish a world, apply a live revision, or guarantee that later saves will fit every history/storage budget. Saved undo retains its existing 8 MiB limit. Preview and Save are separate decisions.

#HTTP API

Both endpoints use POST, JSON content type, the existing editor bearer credential and origin checks. Editing must be enabled. Requests and replies are uncached. An authenticated request initializes a new workspace through the same lazy initialization as the existing draft API; once initialized, observations and validation do not write world, history, room, release or receipt files.

POST /api/authoring/observe accepts at most 4 KiB:

{"format":1,"kind":"summary"}

Observation kinds:

Every response contains head. Entity/log pages contain total, offset, nextOffset and rows. Default page size is 50, maximum 100. Supply the original response's head.sha256 as baseHash for subsequent pages; an offset without that hash fails. A changed head returns 409 rather than mixing revisions. Unknown places, fields and observation kinds fail. Revision logs contain revision/hash transitions and edit keys, with at most 64 keys per row plus omittedKeys. These are bounded accepted authoring revisions, not live simulation entities, runtime console output or a permanent audit archive. The existing 64-revision/4 MiB lineage retention applies.

POST /api/authoring/validate accepts an ordinary transaction, up to 16 MiB:

{
  "format": 1,
  "baseRevision": "12",
  "baseHash": "<checksum returned by observation>",
  "commands": [
    {"kind":"set","entity":"<observed persistent identity>","property":"rotation","value":[0,0.5,0]}
  ]
}

The response contains format, base, candidate, changed, normalized transaction, intervening edit keys, and summary. Base/candidate carry revision and checksum. The summary includes exact added/removed/updated source-row totals, up to 100 detailed changes and an omitted count. Rows cover world metadata, places (including source order), objects, groups, models and prefab links/assets. They are source-change counts, not draw calls or gameplay entity counts. No new snapshot, receipt, revision or undo entry is persisted by validation. The same serialized queue as commits gives each result a coherent saved base.

Strict stale proposals return 409. Explicit disjoint merging uses the same complete retained lineage and overlap rules as commits. Invalid commands, geometry, models and cross-references fail complete-candidate compilation. A later commit must still recheck the base; validation is not a commit token.

The structural schema describes envelope and command fields. It deliberately leaves nested world/model/prefab semantics to readWorldTransaction and the world compiler. Treat validate-only review as the authoritative check; JSON Schema alone cannot prove scene, hierarchy, route, model or identity compatibility.

#Files and CLI

npm run author -- schema
npm run author -- observe world.json observation.json
npm run author -- validate world.json proposal.json

All three commands print JSON to stdout and create no output file. File observations support summary, schema and entities; accepted revision logs require a saved workspace API. File validation requires the exact document base because a standalone document has no merge lineage. Apply a checked proposal separately with the existing author apply command, or review it in the atelier. The packaged production author CLI supports the same operations.

These tools establish inspection and proposal review before full assistant integration. They do not execute scripts or provide autonomous editor approval, role-based credentials, live runtime inspection or a behavior console.