RevertResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/superdocs-app/json-schema/superdocs-app-revert-response-schema.json",
  "title": "RevertResponse",
  "description": "Result of a session revert: restored document state and compose-box prefill.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/superdocs-app-openapi.json#/components/schemas/RevertResponse",
  "properties": {
    "session_id": {
      "type": "string",
      "title": "Session Id",
      "description": "Session identifier."
    },
    "reverted_to_turn": {
      "type": "integer",
      "title": "Reverted To Turn",
      "description": "Turn index that the active conversation now ends at (the AI reply preceding the reverted user message). -1 when the session is reset to its initial empty state (revert from the very first user message)."
    },
    "compose_text": {
      "type": "string",
      "title": "Compose Text",
      "description": "The text of the user message that was reverted. Clients should pre-fill the compose box with this so the user can edit and resend."
    },
    "document_state": {
      "anyOf": [
        {
          "$ref": "#/$defs/DocumentState"
        },
        {
          "type": "null"
        }
      ],
      "description": "Restored document state. Null when the session is reset to empty."
    },
    "editor_action": {
      "type": "string",
      "title": "Editor Action",
      "description": "Client instruction: 'update' to load the restored document, or 'clear' to reset the editor to empty.",
      "default": "update"
    },
    "archived_turn_count": {
      "type": "integer",
      "title": "Archived Turn Count",
      "description": "Number of chat rows soft-archived by this revert (turns hidden from the UI but retained for audit)."
    },
    "revert_changes": {
      "anyOf": [
        {
          "additionalProperties": {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "type": "array"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Revert Changes",
      "description": "Per-document (slug -> change-set) revert diff. Applying these merges the revert onto any concurrent live edits — a conflicting section is surfaced for you to resolve rather than replacing the whole document. On dry_run this is the preview; on a real revert it is what was committed."
    },
    "revert_conflicts": {
      "anyOf": [
        {
          "additionalProperties": {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "type": "array"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Revert Conflicts",
      "description": "Per-document (slug -> entries) sections whose restore did NOT fully land. TWO classes, told apart by the 'displaced' flag. (1) NOT LANDED ('displaced' absent/false): content another writer committed was preserved instead (reason 'concurrent_edit_preserved' / 'lineage_unknown'), or a removal could not be resolved against the live document; the matching revert_changes entry is annotated 'conflict': true and carries the preserved bytes as new_html (the honest committed state) plus the un-landed restore as restore_html. (2) LANDED IN THE WRONG PLACE ('displaced': true): the content WAS restored but not at its original position — reason 'restored_elsewhere' (it was added at the end of the document because the section it anchors to is gone) or 'position_not_restored' (a concurrent writer's placement won). These carry an empty their_html (nothing of another writer's was preserved, so there is nothing to adopt) plus the raw 'resolution' token, and the matching revert_changes entry is annotated 'displaced': true — never 'conflict', because new_html is still the restored content. (3) NOT SAVED AT ALL ('write_failed': true, operation 'write', chunk_id null): the document's recovery write did not commit — reason 'document_deleted' (archived mid-revert), 'storage_paused' (durable saving paused for this account) or 'write_failed'. Document-level, so there is no matching revert_changes entry; storage still holds the pre-revert content while document_state shows the reverted document, so a client MUST re-read the document before saving again. Null/absent when the revert landed cleanly everywhere."
    },
    "dry_run": {
      "type": "boolean",
      "title": "Dry Run",
      "description": "Echoes the request's dry_run: when true nothing was committed/archived — this is a preview only.",
      "default": false
    },
    "redo_checkpoint_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Redo Checkpoint Id",
      "description": "The identifier of the pre-revert state. Revert is non-destructive — passing this back to POST /sessions/{id}/redo (with the same turn_index) restores it and un-archives the rolled-back turns, undoing the revert. Null on a dry-run, and null when the pre-revert state could not be captured — in that case redo_unavailable_reason says which, so absence by design and absence by failure are never the same value."
    },
    "redo_unavailable_reason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Redo Unavailable Reason",
      "description": "Present ONLY when redo_checkpoint_id is null because the pre-revert state could not be captured (never on a dry-run, where null is by design). The revert itself succeeded and is durable; what is unavailable is the one-step undo of it. Treat a non-null value as: do not attempt redo_revert for this revert — it has no argument to pass."
    }
  },
  "type": "object",
  "required": [
    "session_id",
    "reverted_to_turn",
    "compose_text",
    "archived_turn_count"
  ],
  "$defs": {
    "DocumentState": {
      "properties": {
        "html_content": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Html Content",
          "description": "Full document HTML content with data-chunk-id attributes."
        },
        "document_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Document Id",
          "description": "Session-local id (slug) of the focused document. Identifies the document on restore so a restored tab stays in sync with edits made to it in other sessions."
        },
        "version_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Version Id",
          "description": "Document version identifier (UUID string)."
        },
        "chunk_count": {
          "type": "integer",
          "title": "Chunk Count",
          "description": "Number of content sections in the document.",
          "default": 0
        },
        "last_modified": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Last Modified",
          "description": "ISO 8601 timestamp of the last modification."
        },
        "attachments": {
          "anyOf": [
            {
              "items": {
                "additionalProperties": true,
                "type": "object"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Attachments",
          "description": "Session attachments. Each item has: id (string), filename (string), file_extension (string), processing_status ('ready', 'processing', or 'failed')."
        },
        "page_setup": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "title": "Page Setup",
          "description": "Source page geometry of the focused document (width_in, height_in, margin_in{top,right,bottom,left}, orientation) when known, else null. The editor renders the page at this geometry on restore; null ⇒ US-Letter + 1in default."
        }
      },
      "type": "object",
      "title": "DocumentState",
      "description": "Current document state for session restoration."
    }
  }
}