Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/xxyoudeadpunkxx/canon-boundary-guard-for-gpt-project/llms.txt

Use this file to discover all available pages before exploring further.

SESSION_STATE.schema.json defines the structure of the working session state file stored at /mnt/data/_SESSION_STATE.json. This page documents every field, its type, constraints, and purpose. The file is validated against schemas/SESSION_STATE.schema.json using JSON Schema Draft 2020-12.

​
Full schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Canon Boundary Guard GPT Project Session State",
  "type": "object",
  "required": [
    "protocol",
    "protocol_version",
    "state_seq",
    "updated_at",
    "active_l0_sources",
    "authorized_deltas",
    "open_conflicts",
    "pending_decisions",
    "last_persistent_artifacts"
  ],
  "properties": {
    "protocol": {
      "const": "canon-boundary-guard:gpt-project-adapter"
    },
    "protocol_version": {
      "const": "1.1"
    },
    "state_seq": {
      "type": "integer",
      "minimum": 0
    },
    "updated_at": {
      "type": "string",
      "description": "ISO-8601 timestamp"
    },
    "active_l0_sources": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["source_id", "source_type", "status"],
        "properties": {
          "source_id": { "type": "string" },
          "source_type": {
            "type": "string",
            "enum": [
              "project_file", "project_source", "uploaded_file",
              "local_file", "tool_output", "command_output",
              "verified_external_source", "state_file"
            ]
          },
          "status": {
            "type": "string",
            "enum": ["inspected", "unavailable", "conflicted"]
          },
          "notes": { "type": "string" }
        },
        "additionalProperties": false
      }
    },
    "authorized_deltas": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["delta_id", "authorized_at", "scope", "status"],
        "properties": {
          "delta_id": { "type": "string" },
          "authorized_at": { "type": "string" },
          "scope": { "type": "string" },
          "status": {
            "type": "string",
            "enum": ["pending_persistence", "persisted", "revoked"]
          },
          "target": { "type": "string" }
        },
        "additionalProperties": false
      }
    },
    "open_conflicts": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["conflict_id", "description", "status"],
        "properties": {
          "conflict_id": { "type": "string" },
          "description": { "type": "string" },
          "status": {
            "type": "string",
            "enum": ["open", "resolved", "deferred"]
          }
        },
        "additionalProperties": false
      }
    },
    "pending_decisions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["decision_id", "question"],
        "properties": {
          "decision_id": { "type": "string" },
          "question": { "type": "string" },
          "blocking": { "type": "boolean" }
        },
        "additionalProperties": false
      }
    },
    "last_persistent_artifacts": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["artifact_id", "artifact_type", "created_at"],
        "properties": {
          "artifact_id": { "type": "string" },
          "artifact_type": {
            "type": "string",
            "enum": [
              "project_source", "downloaded_file", "canvas",
              "document", "state_file", "other"
            ]
          },
          "created_at": { "type": "string" },
          "path_or_label": { "type": "string" }
        },
        "additionalProperties": false
      }
    },
    "last_state_hash": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

​
Required fields

​
protocol
string
required
Constant value: "canon-boundary-guard:gpt-project-adapter". Identifies the protocol family. Any other value causes schema validation to fail.
​
protocol_version
string
required
Constant value: "1.1". Identifies the schema revision. Must match exactly.
​
state_seq
integer
required
Non-negative integer (minimum: 0). Starts at 0 after bootstrap and increments by 1 with each Mode B or Mode C state-changing decision. The value must match seq in any associated CANON_STATE_DELTA.
​
updated_at
string
required
ISO-8601 timestamp recording when the state was last written. Example: "2025-07-14T09:15:00+00:00".
​
active_l0_sources
array
required
Array of L0 source objects representing every source surface that has been inspected in this session. Must not be empty after bootstrap — see First-install note. Each item conforms to the active_l0_sources items schema.
​
authorized_deltas
array
required
Array of authorized delta objects tracking every Mode B/C decision that has been approved. May be empty. Each item conforms to the authorized_deltas items schema.
​
open_conflicts
array
required
Array of conflict objects for any provenance conflicts that have been detected. May be empty. Each item conforms to the open_conflicts items schema.
​
pending_decisions
array
required
Array of decision objects for questions awaiting operator resolution. May be empty. Each item conforms to the pending_decisions items schema.
​
last_persistent_artifacts
array
required
Array of artifact objects recording every durable artifact produced since the last state reset. May be empty. Each item conforms to the last_persistent_artifacts items schema.

​
Optional field

​
last_state_hash
string
SHA-256 hash of the previous state, in the format "sha256:<hex>". Used by validate_state.py and artifact_fingerprint.py to verify continuity between state files. Omit if no prior hash is available.

​
active_l0_sources items

Each object in active_l0_sources records one inspected source surface. additionalProperties is false — no extra keys are permitted.
​
source_id
string
required
A path, file ID, or human-readable label that uniquely identifies the source within this session. Examples: "canon-boundary-guard-gpt/references/protocol.md", "uploaded:state_2025-07-14.json".
​
source_type
string
required
Enum describing the nature of the source:
ValueMeaning
project_fileA file present in the ChatGPT Project
project_sourceA source saved as a Project Source
uploaded_fileA file uploaded directly into the conversation
local_fileA file read from the local filesystem via tool
tool_outputOutput produced by a tool invocation
command_outputOutput produced by a shell command
verified_external_sourceAn external URL or resource verified by the operator
state_fileA _SESSION_STATE.json or state-equivalent file
​
status
string
required
Enum describing the current accessibility of the source:
ValueMeaning
inspectedSource was read and verified this session
unavailableSource was expected but could not be accessed
conflictedSource was found but conflicts with another registered source
​
notes
string
Optional free-text annotation. Use to record inspection details, anomalies, or cross-references to open_conflicts entries.

​
authorized_deltas items

Each object in authorized_deltas records one approved Mode B or Mode C decision. additionalProperties is false.
​
delta_id
string
required
Unique identifier for this delta. Typically matches the seq counter or a human-readable label, e.g. "delta-3".
​
authorized_at
string
required
ISO-8601 timestamp when the operator authorized this delta.
​
scope
string
required
Human-readable description of what this delta covers. Example: "Add chapter-2 draft as project source".
​
status
string
required
Enum tracking persistence lifecycle:
ValueMeaning
pending_persistenceDelta authorized but the artifact has not yet been durably saved
persistedArtifact has been saved and confirmed by the operator
revokedAuthorization was withdrawn before or after persistence
​
target
string
Optional path or label identifying the artifact that this delta targets. Example: "/mnt/data/chapter-2-draft.md".

​
open_conflicts items

Each object in open_conflicts records a detected provenance conflict. additionalProperties is false.
​
conflict_id
string
required
Unique identifier for this conflict. Example: "conflict-1".
​
description
string
required
Human-readable explanation of what conflict was detected and which sources are involved.
​
status
string
required
Enum tracking resolution lifecycle:
ValueMeaning
openConflict has been detected and is not yet resolved
resolvedOperator provided a resolution; conflict is closed
deferredResolution explicitly postponed to a future session

​
pending_decisions items

Each object in pending_decisions records a question that must be resolved by the operator before work can continue. additionalProperties is false.
​
decision_id
string
required
Unique identifier for this pending decision. Example: "decision-2".
​
question
string
required
The exact question the operator must answer. Should be precise enough that the answer can unambiguously close the decision.
​
blocking
boolean
When true, this decision blocks all Mode B/C operations until resolved. When false or absent, work may continue under constraints.

​
last_persistent_artifacts items

Each object in last_persistent_artifacts records one durable artifact produced since the last state reset. additionalProperties is false.
​
artifact_id
string
required
Unique identifier for this artifact. Example: "artifact-1".
​
artifact_type
string
required
Enum classifying the artifact:
ValueMeaning
project_sourceSaved as a ChatGPT Project Source
downloaded_fileDownloaded by the operator from the conversation
canvasA Canvas document
documentA generic document artifact
state_fileA SESSION_STATE or CANON_STATE_DELTA file
otherAny artifact not covered by the above types
​
created_at
string
required
ISO-8601 timestamp when the artifact was created or marked as persisted.
​
path_or_label
string
Optional path or human-readable label identifying where the artifact is stored. Example: "/mnt/data/_SESSION_STATE.json" or "chapter-2-draft (Project Source)".

​
First-install note

The schema-minimal shape shown in state-and-recovery.md — with an empty active_l0_sources array — is not a valid first-install template. It is schema-valid (the array is allowed to be empty by the schema), but it does not satisfy the protocol’s bootstrap requirement.After bootstrap, active_l0_sources must contain entries for all inspected bootstrap surfaces, at minimum:
  • canon-boundary-guard-gpt/SKILL.md
  • canon-boundary-guard-gpt/references/protocol.md
  • canon-boundary-guard-gpt/references/gpt-project-adapter.md
  • canon-boundary-guard-gpt/references/state-and-recovery.md
  • canon-boundary-guard-gpt/schemas/SESSION_STATE.schema.json
A state file with an empty active_l0_sources submitted as first-install state will be rejected by a conformant adapter.

CANON_STATE_DELTA schema

Reference for the snapshot delta emitted after every Mode B or Mode C state change, which embeds a full SESSION_STATE object.

Build docs developers (and LLMs) love

Get started for freeTalk to us