DocForge2/schemas/client-configuration.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docforge.local/schema/client-configuration-v1.json",
  "title": "DocForge deterministic client configuration plan",
  "$defs": {
    "sha256": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$"
    },
    "adapter_policy": {
      "oneOf": [
        {
          "type": "object",
          "required": [
            "mode",
            "ast_analysis",
            "logic_projection",
            "incremental_extraction",
            "adapter_rewrite"
          ],
          "properties": {
            "mode": { "const": "standard" },
            "ast_analysis": { "const": "allowed" },
            "logic_projection": { "const": "allowed" },
            "incremental_extraction": { "const": "allowed" },
            "adapter_rewrite": { "const": "not_requested" }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "mode",
            "ast_analysis",
            "logic_projection",
            "incremental_extraction",
            "adapter_rewrite",
            "blocked_tools",
            "instruction"
          ],
          "properties": {
            "mode": { "const": "preserve-no-ast" },
            "ast_analysis": { "const": "forbidden" },
            "logic_projection": { "const": "forbidden" },
            "incremental_extraction": { "const": "allowed" },
            "adapter_rewrite": { "const": "forbidden" },
            "blocked_tools": {
              "const": ["docforge_get_logic"]
            },
            "instruction": {
              "const": "Preserve the existing adapter extraction strategy. Do not add Python AST, Tree-sitter, compiler-AST, or function-Logic extraction. Non-AST incremental fingerprinting and caching remain allowed."
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "effective_policy": {
      "type": "object",
      "required": [
        "schema_version",
        "capability_mode",
        "capability_source",
        "adapter_evolution",
        "ast_analysis",
        "logic_indexing",
        "synchronization",
        "integrity",
        "manual_render",
        "graph_render",
        "live_viewer",
        "profiling",
        "blocked_tools",
        "prohibitions",
        "precedence"
      ],
      "properties": {
        "schema_version": { "const": 1 },
        "capability_mode": {
          "enum": ["read", "proposal", "application"]
        },
        "capability_source": { "const": "explicit" },
        "adapter_evolution": { "enum": ["allowed", "preserve"] },
        "ast_analysis": { "enum": ["allowed", "forbidden"] },
        "logic_indexing": { "enum": ["full", "off"] },
        "synchronization": { "const": "automatic" },
        "integrity": { "const": "validated" },
        "manual_render": { "enum": ["auto", "explicit", "disabled"] },
        "graph_render": { "const": "disabled" },
        "live_viewer": { "const": "on-demand" },
        "profiling": { "const": "disabled" },
        "blocked_tools": {
          "type": "array",
          "maxItems": 1,
          "items": { "const": "docforge_get_logic" },
          "uniqueItems": true
        },
        "prohibitions": {
          "type": "array",
          "minItems": 7,
          "maxItems": 11,
          "items": {
            "enum": [
              "arbitrary_file_access",
              "arbitrary_renderer_execution",
              "shell_execution",
              "git_mutation",
              "deployment",
              "publication",
              "project_switching",
              "adapter_ast_upgrade",
              "tree_sitter_upgrade",
              "compiler_ast_upgrade",
              "function_logic_extraction"
            ]
          },
          "uniqueItems": true
        },
        "precedence": {
          "const": [
            "core_safety",
            "explicit_binding",
            "no_ast_shorthand",
            "resource_availability"
          ]
        }
      },
      "additionalProperties": false
    },
    "projection_policy": {
      "type": "object",
      "required": ["schema_version", "manual", "portable_graph", "live_viewer"],
      "properties": {
        "schema_version": { "const": 2 },
        "manual": { "enum": ["auto", "explicit", "disabled"] },
        "portable_graph": { "enum": ["explicit", "disabled"] },
        "live_viewer": { "enum": ["on-demand", "disabled"] }
      },
      "additionalProperties": false
    },
    "diagnostics": {
      "type": "object",
      "required": [
        "schema_version",
        "operation",
        "outcome",
        "elapsed_ns",
        "stages",
        "counters"
      ],
      "properties": {
        "schema_version": { "const": 1 },
        "operation": { "const": "cli.configure" },
        "outcome": { "const": "ok" },
        "elapsed_ns": { "type": "integer", "minimum": 0 },
        "stages": {
          "type": "object",
          "maxProperties": 14,
          "propertyNames": {
            "enum": [
              "source.generation",
              "source.parse",
              "adapter.projection",
              "adapter.extract",
              "index.check",
              "index.synchronize",
              "index.build",
              "index.read",
              "render.status",
              "render.prepare",
              "render.output_hash",
              "visualization.status",
              "viewer.manager",
              "mcp.runtime_validation"
            ]
          },
          "additionalProperties": {
            "type": "object",
            "required": ["calls", "elapsed_ns"],
            "properties": {
              "calls": { "type": "integer", "minimum": 1 },
              "elapsed_ns": { "type": "integer", "minimum": 0 }
            },
            "additionalProperties": false
          }
        },
        "counters": {
          "type": "object",
          "required": [
            "project_loads",
            "source_files_parsed",
            "source_bytes_parsed",
            "adapter_projection_loads",
            "adapter_source_extractions",
            "source_generation_checks",
            "index_checks",
            "index_synchronizations",
            "index_builds",
            "render_prepare_calls",
            "render_output_bytes_built",
            "render_output_bytes_hashed",
            "viewer_manager_requests"
          ],
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          },
          "maxProperties": 13
        }
      },
      "additionalProperties": false
    }
  },
  "type": "object",
  "required": [
    "status",
    "schema_version",
    "docforge_version",
    "operation",
    "action",
    "client",
    "server_name",
    "project",
    "binding",
    "effective_policy",
    "projection_policy",
    "projection_policy_hash",
    "projection_availability",
    "artifact",
    "configuration_hash",
    "warnings"
  ],
  "properties": {
    "status": { "const": "ok" },
    "schema_version": { "const": 1 },
    "docforge_version": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "operation": { "const": "client.configure" },
    "action": { "enum": ["preview", "write"] },
    "client": { "enum": ["codex", "claude", "openclaw"] },
    "server_name": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
    },
    "project": {
      "type": "object",
      "required": [
        "project_id",
        "project_root",
        "project_root_fingerprint",
        "adapter",
        "descriptor_hash"
      ],
      "properties": {
        "project_id": { "type": "string", "minLength": 1 },
        "project_root": { "type": "string", "minLength": 1 },
        "project_root_fingerprint": {
          "type": "string",
          "pattern": "^[0-9a-f]{16}$"
        },
        "adapter": { "type": "string", "minLength": 1 },
        "descriptor_hash": { "$ref": "#/$defs/sha256" }
      },
      "additionalProperties": false
    },
    "binding": {
      "type": "object",
      "required": [
        "transport",
        "capability_mode",
        "adapter_policy",
        "render_policy",
        "command",
        "args",
        "environment",
        "timeouts"
      ],
      "properties": {
        "transport": { "const": "stdio" },
        "capability_mode": {
          "enum": ["read", "proposal", "application"]
        },
        "adapter_policy": { "$ref": "#/$defs/adapter_policy" },
        "render_policy": {
          "type": "object",
          "required": ["manual", "graph", "live_viewer"],
          "properties": {
            "manual": { "enum": ["auto", "explicit", "disabled"] },
            "graph": { "const": "disabled" },
            "live_viewer": { "const": "on-demand" }
          },
          "additionalProperties": false
        },
        "command": { "type": "string", "minLength": 1 },
        "args": {
          "type": "array",
          "minItems": 7,
          "maxItems": 64,
          "prefixItems": [
            { "const": "-I" },
            { "const": "-m" },
            { "const": "docforge.mcp_server" },
            { "const": "--project-root" },
            { "type": "string", "minLength": 1, "maxLength": 4096 },
            { "const": "--capability-mode" },
            { "enum": ["read", "proposal", "application"] }
          ],
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4096
          }
        },
        "environment": {
          "type": "object",
          "maxProperties": 0
        },
        "timeouts": {
          "type": "object",
          "required": ["startup_seconds", "tool_seconds"],
          "properties": {
            "startup_seconds": {
              "type": "integer",
              "minimum": 1,
              "maximum": 3600
            },
            "tool_seconds": {
              "type": "integer",
              "minimum": 1,
              "maximum": 86400
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "effective_policy": { "$ref": "#/$defs/effective_policy" },
    "projection_policy": { "$ref": "#/$defs/projection_policy" },
    "projection_policy_hash": { "$ref": "#/$defs/sha256" },
    "projection_availability": {
      "type": "object",
      "required": [
        "manual_configured",
        "portable_graph_configured",
        "application_enabled",
        "live_viewer_available"
      ],
      "properties": {
        "manual_configured": { "type": "boolean" },
        "portable_graph_configured": { "type": "boolean" },
        "application_enabled": { "type": "boolean" },
        "live_viewer_available": { "const": true }
      },
      "additionalProperties": false
    },
    "artifact": {
      "type": "object",
      "required": [
        "format",
        "content",
        "content_sha256",
        "output_path",
        "write_state",
        "durability"
      ],
      "properties": {
        "format": {
          "enum": [
            "codex-toml-fragment-v1",
            "claude-json-fragment-v1",
            "openclaw-json-fragment-v1"
          ]
        },
        "content": {
          "type": "string",
          "minLength": 1,
          "maxLength": 65536
        },
        "content_sha256": { "$ref": "#/$defs/sha256" },
        "output_path": {
          "type": ["string", "null"],
          "minLength": 1
        },
        "write_state": {
          "enum": ["not_requested", "created", "unchanged"]
        },
        "durability": {
          "enum": ["not_applicable", "confirmed", "unconfirmed"]
        }
      },
      "additionalProperties": false
    },
    "configuration_hash": { "$ref": "#/$defs/sha256" },
    "warnings": {
      "type": "array",
      "maxItems": 8,
      "items": {
        "type": "object",
        "required": ["code"],
        "properties": {
          "code": {
            "enum": [
              "timeout_format_unverified",
              "publication_durability_unconfirmed",
              "publication_location_unconfirmed",
              "publication_binding_unconfirmed"
            ]
          }
        },
        "additionalProperties": false
      }
    },
    "diagnostics": { "$ref": "#/$defs/diagnostics" }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "warnings": {
            "contains": {
              "properties": {
                "code": { "const": "publication_binding_unconfirmed" }
              },
              "required": ["code"]
            }
          }
        },
        "required": ["warnings"]
      },
      "then": {
        "properties": {
          "artifact": {
            "properties": {
              "output_path": { "type": "null" },
              "write_state": { "const": "created" },
              "durability": { "const": "unconfirmed" }
            }
          }
        }
      }
    },
    {
      "if": {
        "properties": { "client": { "const": "codex" } },
        "required": ["client"]
      },
      "then": {
        "properties": {
          "artifact": {
            "properties": {
              "format": { "const": "codex-toml-fragment-v1" }
            }
          },
          "warnings": {
            "not": {
              "contains": {
                "properties": {
                  "code": { "const": "timeout_format_unverified" }
                },
                "required": ["code"]
              }
            }
          }
        }
      }
    },
    {
      "if": {
        "properties": { "client": { "const": "openclaw" } },
        "required": ["client"]
      },
      "then": {
        "properties": {
          "artifact": {
            "properties": {
              "format": { "const": "openclaw-json-fragment-v1" }
            }
          },
          "warnings": {
            "not": {
              "contains": {
                "properties": {
                  "code": { "const": "timeout_format_unverified" }
                },
                "required": ["code"]
              }
            }
          }
        }
      }
    },
    {
      "if": {
        "properties": { "client": { "const": "claude" } },
        "required": ["client"]
      },
      "then": {
        "properties": {
          "artifact": {
            "properties": {
              "format": { "const": "claude-json-fragment-v1" }
            }
          },
          "warnings": {
            "contains": {
              "properties": {
                "code": { "const": "timeout_format_unverified" }
              },
              "required": ["code"]
            }
          }
        }
      }
    },
    {
      "if": {
        "properties": { "action": { "const": "preview" } },
        "required": ["action"]
      },
      "then": {
        "properties": {
          "artifact": {
            "properties": {
              "output_path": { "type": "null" },
              "write_state": { "const": "not_requested" },
              "durability": { "const": "not_applicable" }
            }
          }
        }
      },
      "else": {
        "properties": {
          "artifact": {
            "properties": {
              "output_path": {
                "type": ["string", "null"],
                "minLength": 1
              },
              "write_state": { "enum": ["created", "unchanged"] }
            },
            "allOf": [
              {
                "if": {
                  "properties": { "write_state": { "const": "created" } },
                  "required": ["write_state"]
                },
                "then": {
                  "properties": {
                    "durability": { "enum": ["confirmed", "unconfirmed"] }
                  }
                },
                "else": {
                  "properties": {
                    "durability": { "const": "not_applicable" }
                  }
                }
              }
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "binding": {
            "properties": { "capability_mode": { "const": "read" } },
            "required": ["capability_mode"]
          }
        },
        "required": ["binding"]
      },
      "then": {
        "properties": {
          "binding": {
            "properties": {
              "args": {
                "prefixItems": [{}, {}, {}, {}, {}, {}, { "const": "read" }]
              }
            }
          },
          "effective_policy": {
            "properties": { "capability_mode": { "const": "read" } }
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "binding": {
            "properties": { "capability_mode": { "const": "proposal" } },
            "required": ["capability_mode"]
          }
        },
        "required": ["binding"]
      },
      "then": {
        "properties": {
          "binding": {
            "properties": {
              "args": {
                "prefixItems": [{}, {}, {}, {}, {}, {}, { "const": "proposal" }]
              }
            }
          },
          "effective_policy": {
            "properties": { "capability_mode": { "const": "proposal" } }
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "binding": {
            "properties": { "capability_mode": { "const": "application" } },
            "required": ["capability_mode"]
          }
        },
        "required": ["binding"]
      },
      "then": {
        "properties": {
          "binding": {
            "properties": {
              "args": {
                "prefixItems": [{}, {}, {}, {}, {}, {}, { "const": "application" }]
              }
            }
          },
          "effective_policy": {
            "properties": { "capability_mode": { "const": "application" } }
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "binding": {
            "properties": {
              "adapter_policy": {
                "properties": { "mode": { "const": "preserve-no-ast" } },
                "required": ["mode"]
              }
            },
            "required": ["adapter_policy"]
          }
        },
        "required": ["binding"]
      },
      "then": {
        "properties": {
          "binding": {
            "properties": {
              "args": {
                "contains": { "const": "--no-ast" },
                "minContains": 1,
                "maxContains": 1
              }
            }
          },
          "effective_policy": {
            "properties": {
              "adapter_evolution": { "const": "preserve" },
              "ast_analysis": { "const": "forbidden" },
              "logic_indexing": { "const": "off" },
              "blocked_tools": { "const": ["docforge_get_logic"] },
              "prohibitions": {
                "const": [
                  "arbitrary_file_access",
                  "arbitrary_renderer_execution",
                  "shell_execution",
                  "git_mutation",
                  "deployment",
                  "publication",
                  "project_switching",
                  "adapter_ast_upgrade",
                  "tree_sitter_upgrade",
                  "compiler_ast_upgrade",
                  "function_logic_extraction"
                ]
              }
            }
          }
        }
      },
      "else": {
        "properties": {
          "binding": {
            "properties": {
              "args": {
                "not": {
                  "contains": { "const": "--no-ast" }
                }
              }
            }
          },
          "effective_policy": {
            "properties": {
              "adapter_evolution": { "const": "allowed" },
              "ast_analysis": { "const": "allowed" },
              "logic_indexing": { "const": "full" },
              "blocked_tools": { "const": [] },
              "prohibitions": {
                "const": [
                  "arbitrary_file_access",
                  "arbitrary_renderer_execution",
                  "shell_execution",
                  "git_mutation",
                  "deployment",
                  "publication",
                  "project_switching"
                ]
              }
            }
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "binding": {
            "properties": {
              "render_policy": {
                "properties": { "manual": { "const": "auto" } },
                "required": ["manual"]
              }
            },
            "required": ["render_policy"]
          }
        },
        "required": ["binding"]
      },
      "then": {
        "properties": {
          "effective_policy": {
            "properties": { "manual_render": { "const": "auto" } }
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "binding": {
            "properties": {
              "render_policy": {
                "properties": { "manual": { "const": "explicit" } },
                "required": ["manual"]
              }
            },
            "required": ["render_policy"]
          }
        },
        "required": ["binding"]
      },
      "then": {
        "properties": {
          "effective_policy": {
            "properties": { "manual_render": { "const": "explicit" } }
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "binding": {
            "properties": {
              "render_policy": {
                "properties": { "manual": { "const": "disabled" } },
                "required": ["manual"]
              }
            },
            "required": ["render_policy"]
          }
        },
        "required": ["binding"]
      },
      "then": {
        "properties": {
          "effective_policy": {
            "properties": { "manual_render": { "const": "disabled" } }
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "artifact": {
            "properties": {
              "durability": { "const": "unconfirmed" }
            },
            "required": ["durability"]
          }
        },
        "required": ["artifact"]
      },
      "then": {
        "properties": {
          "artifact": {
            "properties": {
              "write_state": { "const": "created" }
            }
          },
          "warnings": {
            "anyOf": [
              {
                "contains": {
                  "properties": {
                    "code": { "const": "publication_durability_unconfirmed" }
                  },
                  "required": ["code"]
                }
              },
              {
                "contains": {
                  "properties": {
                    "code": { "const": "publication_location_unconfirmed" }
                  },
                  "required": ["code"]
                }
              },
              {
                "contains": {
                  "properties": {
                    "code": { "const": "publication_binding_unconfirmed" }
                  },
                  "required": ["code"]
                }
              }
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "warnings": {
            "contains": {
              "properties": {
                "code": { "const": "publication_location_unconfirmed" }
              },
              "required": ["code"]
            }
          }
        },
        "required": ["warnings"]
      },
      "then": {
        "properties": {
          "artifact": {
            "properties": {
              "output_path": { "type": "null" },
              "write_state": { "const": "created" },
              "durability": { "const": "unconfirmed" }
            }
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "action": { "const": "write" },
          "artifact": {
            "properties": { "output_path": { "type": "null" } },
            "required": ["output_path"]
          }
        },
        "required": ["action", "artifact"]
      },
      "then": {
        "properties": {
          "warnings": {
            "anyOf": [
              {
                "contains": {
                  "properties": {
                    "code": { "const": "publication_location_unconfirmed" }
                  },
                  "required": ["code"]
                }
              },
              {
                "contains": {
                  "properties": {
                    "code": { "const": "publication_binding_unconfirmed" }
                  },
                  "required": ["code"]
                }
              }
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "warnings": {
            "contains": {
              "properties": {
                "code": { "const": "publication_durability_unconfirmed" }
              },
              "required": ["code"]
            }
          }
        },
        "required": ["warnings"]
      },
      "then": {
        "properties": {
          "artifact": {
            "properties": {
              "write_state": { "const": "created" },
              "durability": { "const": "unconfirmed" }
            }
          }
        }
      }
    }
  ],
  "additionalProperties": false
}