Schema: source-inventory

{
  "$id": "https://australis.systems/schemas/htmx-ui-template-scaffold/source-inventory.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "description": "Review-only inventory emitted by htmx_ui_template_scaffold.planner.analyze(). Carries the schema-locked envelope, browser page candidates derived from GET routes, and API operation candidates lifted from the supplied operation catalog. Status is informational and is always REVIEW_ONLY; mutations are forbidden at this stage.",
  "properties": {
    "api_operation_candidates": {
      "description": "API operations sourced from the supplied operation catalog. Each is flagged REQUIRES_MANUAL_REVIEW_BEFORE_SCAFFOLDING because the tool does not authorize handler-side scaffolding for API operations.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "api_path": {
            "description": "Path template parsed from the catalog's rest field.",
            "minLength": 1,
            "type": "string"
          },
          "approval_status": {
            "const": "REQUIRES_MANUAL_REVIEW_BEFORE_SCAFFOLDING",
            "description": "Approval state of the operation candidate. Always REQUIRES_MANUAL_REVIEW_BEFORE_SCAFFOLDING at the inventory stage.",
            "type": "string"
          },
          "domain": {
            "description": "Domain identifier under which the operation is declared in the catalog.",
            "minLength": 1,
            "type": "string"
          },
          "method": {
            "description": "HTTP method parsed from the catalog's rest field.",
            "enum": [
              "GET",
              "POST",
              "PUT",
              "PATCH",
              "DELETE"
            ],
            "type": "string"
          },
          "operation_id": {
            "description": "Stable operation identifier from the catalog entry.",
            "minLength": 1,
            "type": "string"
          },
          "template_url_expression": {
            "description": "MiniJinja expression that builds the URL without resolving request parameters early.",
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "domain",
          "operation_id",
          "method",
          "api_path",
          "template_url_expression",
          "approval_status"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "browser_page_candidates": {
      "description": "GET route candidates discovered in the supplied router source, mapped to their proposed MiniJinja page paths.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "handler_expression": {
            "description": "Direct method-router handler expression when recognized.",
            "minLength": 1,
            "type": "string"
          },
          "method": {
            "description": "HTTP method of the discovered route. Only GET is currently eligible for page scaffolding in analyze().",
            "enum": [
              "GET",
              "POST",
              "PUT",
              "PATCH",
              "DELETE"
            ],
            "type": "string"
          },
          "path": {
            "description": "Original router path literal as discovered in the source.",
            "minLength": 1,
            "type": "string"
          },
          "proposed_path": {
            "description": "Translated MiniJinja page path (e.g. 'pages/index.html' for '/').",
            "minLength": 1,
            "type": "string"
          },
          "route_local_layers_present": {
            "description": "Whether the direct method-router expression includes an explicit route_layer call. Middleware semantics are not interpreted.",
            "type": "boolean"
          },
          "source_line": {
            "description": "One-based source line for a direct route declaration.",
            "minimum": 1,
            "type": "integer"
          }
        },
        "required": [
          "method",
          "path",
          "proposed_path"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "complete_analysis": {
      "additionalProperties": false,
      "description": "Complete mapping-driven UI route/tree report emitted when analyze receives a pages root.",
      "properties": {
        "actual_page_roots": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "actual_ui_routes": {
          "items": {
            "type": "object"
          },
          "type": "array"
        },
        "component_interaction_audit": {
          "type": "object"
        },
        "expected_rest_operations": {
          "items": {
            "type": "object"
          },
          "type": "array"
        },
        "findings": {
          "items": {
            "type": "object"
          },
          "type": "array"
        },
        "inventory_kind": {
          "const": "ui_route_tree_analysis"
        },
        "legacy_flat_page_files": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "proposed_scaffold_plan": {
          "items": {
            "type": "object"
          },
          "type": "array"
        },
        "rest_method_coverage": {
          "items": {
            "type": "object"
          },
          "type": "array"
        },
        "route_owned_partial_files": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "schema_version": {
          "const": "1.0.0"
        },
        "selected_scaffold_files": {
          "description": "Deterministic file-selection manifest derived from the complete analysis policy recommendations.",
          "items": {
            "type": "object"
          },
          "type": "array"
        },
        "sources": {
          "type": "object"
        },
        "summary": {
          "type": "object"
        },
        "web_app_structure_analysis": {
          "type": "object"
        }
      },
      "required": [
        "schema_version",
        "inventory_kind",
        "sources",
        "summary",
        "actual_page_roots",
        "legacy_flat_page_files",
        "route_owned_partial_files",
        "actual_ui_routes",
        "expected_rest_operations",
        "rest_method_coverage",
        "proposed_scaffold_plan",
        "selected_scaffold_files",
        "web_app_structure_analysis",
        "component_interaction_audit",
        "findings"
      ],
      "type": "object"
    },
    "inventory_kind": {
      "description": "Stable discriminator for inventory-kind routing. Currently the only legal value identifies this as an htmx_ui_template_scaffold_plan.",
      "enum": [
        "htmx_ui_template_scaffold_plan"
      ],
      "type": "string"
    },
    "scaffold_rule": {
      "description": "Human-readable scaffold rule summary. Currently the only emitted value is the thin-adapter rule for route-owned templates.",
      "minLength": 1,
      "type": "string"
    },
    "schema_version": {
      "description": "Major-version-locked envelope. Documents with any value other than 1.0.0 MUST fail validation, which enforces the major-version-1 contract.",
      "enum": [
        "1.0.0"
      ],
      "type": "string"
    },
    "status": {
      "const": "REVIEW_ONLY",
      "description": "Review-only status marker. Mutations require a separate plan plus an ACTIVE approval; analyze() never produces anything else.",
      "type": "string"
    },
    "unresolved_evidence": {
      "description": "Unsupported source syntax retained for review; these entries never authorize target mutation.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "expression": {
            "minLength": 1,
            "type": "string"
          },
          "kind": {
            "minLength": 1,
            "type": "string"
          },
          "message": {
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "kind",
          "expression",
          "message"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "schema_version",
    "inventory_kind",
    "status",
    "browser_page_candidates",
    "api_operation_candidates",
    "unresolved_evidence",
    "scaffold_rule"
  ],
  "title": "Source Inventory",
  "type": "object"
}