whetstone_RSA/semantic/rsa_semantic_bootstrap_v0.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "whetstone-rsa/semantic-bootstrap-v0",
  "title": "RSA Semantic Bootstrap V0",
  "version": "0.1.0-bootstrap",
  "status": "bootstrap_source_of_truth",
  "notes": [
    "This file is the first machine-readable semantic bootstrap artifact for whetstone_RSA.",
    "It is intentionally smaller than the full target semantic model.",
    "It defines the first three semantic entities called out in Sprint 002: DecisionContract, DecisionSurface, and ProbeDefinition.",
    "Until AST-native authoring is fully in place, this artifact should be treated as the semantic source of truth ahead of handwritten C++ contract growth."
  ],
  "enums": {
    "risk_tier": [
      "low",
      "medium",
      "high"
    ],
    "input_structure": [
      "structured",
      "unstructured",
      "hybrid"
    ],
    "input_modality": [
      "textual",
      "numeric",
      "symbolic",
      "multimodal"
    ],
    "output_topology": [
      "discrete",
      "continuous",
      "hybrid"
    ],
    "output_constraint": [
      "deterministic",
      "bounded",
      "open"
    ],
    "policy_stability": [
      "stable",
      "mixed",
      "non_stationary"
    ],
    "gate_shape": [
      "binary",
      "multiclass",
      "factorized",
      "hierarchical"
    ],
    "backend_family": [
      "linear_model",
      "gradient_boosting",
      "random_forest",
      "bayesian",
      "transformer",
      "hybrid",
      "rl_policy"
    ],
    "failure_class": [
      "unknown",
      "capacity_limited_gate",
      "factorizable_gate",
      "non_stationary_gate",
      "missing_context_gate",
      "deterministic_disguised_as_ml_gate",
      "label_space_mismatch",
      "guardrail_limited_gate"
    ],
    "intervention": [
      "collect_more_evidence",
      "keep_current_gate",
      "deploy_with_guardrails",
      "raise_confidence_threshold",
      "add_retry_with_context",
      "add_deterministic_prepass",
      "replace_with_deterministic_logic",
      "factor_into_subgates",
      "switch_to_hierarchical_gate",
      "revise_label_schema",
      "enrich_input_context",
      "evaluate_larger_model_tier"
    ]
  },
  "entities": {
    "DecisionContract": {
      "purpose": "Semantic identity of an RSA decision gate, independent of runtime backend choice.",
      "fields": [
        {
          "name": "gate_id",
          "type": "string",
          "required": true
        },
        {
          "name": "task_family",
          "type": "string",
          "required": true
        },
        {
          "name": "input_structure",
          "type": "enum:input_structure",
          "required": true
        },
        {
          "name": "input_modality",
          "type": "enum:input_modality",
          "required": true
        },
        {
          "name": "output_topology",
          "type": "enum:output_topology",
          "required": true
        },
        {
          "name": "output_constraint",
          "type": "enum:output_constraint",
          "required": true
        },
        {
          "name": "risk_tier",
          "type": "enum:risk_tier",
          "required": true
        },
        {
          "name": "policy_stability",
          "type": "enum:policy_stability",
          "required": true
        },
        {
          "name": "deterministic_baseline_available",
          "type": "boolean",
          "required": true
        },
        {
          "name": "supports_abstain",
          "type": "boolean",
          "required": true
        },
        {
          "name": "metadata",
          "type": "map<string,string>",
          "required": false
        }
      ]
    },
    "DecisionSurface": {
      "purpose": "Semantic description of output shape, factorization, and bounded slot structure for a gate.",
      "fields": [
        {
          "name": "gate_id",
          "type": "string",
          "required": true
        },
        {
          "name": "primary_mode",
          "type": "enum",
          "allowed_values": [
            "enum",
            "structured",
            "hybrid"
          ],
          "required": true
        },
        {
          "name": "output_labels",
          "type": "array<string>",
          "required": false
        },
        {
          "name": "slot_schema",
          "type": "array<object>",
          "required": false
        },
        {
          "name": "candidate_gate_shapes",
          "type": "array<enum:gate_shape>",
          "required": true
        },
        {
          "name": "candidate_factorizations",
          "type": "array<array<string>>",
          "required": false
        },
        {
          "name": "invalid_combinations",
          "type": "array<object>",
          "required": false
        },
        {
          "name": "deterministic_prepass_options",
          "type": "array<string>",
          "required": false
        },
        {
          "name": "downstream_executor_kind",
          "type": "string",
          "required": false
        }
      ]
    },
    "ProbeDefinition": {
      "purpose": "Semantic declaration of a diagnosis probe before any runtime C++ implementation.",
      "fields": [
        {
          "name": "probe_id",
          "type": "string",
          "required": true
        },
        {
          "name": "applies_to_gate_shapes",
          "type": "array<enum:gate_shape>",
          "required": true
        },
        {
          "name": "required_contract_fields",
          "type": "array<string>",
          "required": false
        },
        {
          "name": "required_evidence_fields",
          "type": "array<string>",
          "required": false
        },
        {
          "name": "produced_signals",
          "type": "array<string>",
          "required": false
        },
        {
          "name": "failure_hints",
          "type": "array<enum:failure_class>",
          "required": false
        },
        {
          "name": "intervention_hints",
          "type": "array<enum:intervention>",
          "required": false
        }
      ]
    }
  },
  "projection_targets": {
    "cpp_runtime": {
      "notes": [
        "The current C++ scaffold is a projection target, not the authoring home of the model.",
        "Future changes should update this semantic artifact first, then realign projected C++ types."
      ],
      "field_map": {
        "DecisionContract": {
          "target_type": "whetstone::rsa::GateDefinition",
          "target_fields": [
            "gate_id",
            "task_family",
            "input_structure",
            "input_modality",
            "output_topology",
            "output_constraint",
            "risk_tier",
            "label_stability",
            "deterministic_baseline_available",
            "supports_abstain",
            "metadata"
          ]
        },
        "DecisionSurface": {
          "target_type": "whetstone::rsa::GateDefinition",
          "target_fields": [
            "labels",
            "candidate_factorizations"
          ],
          "notes": [
            "slot_schema and invalid_combinations are semantic-first fields not yet fully represented in the current C++ scaffold.",
            "candidate_gate_shapes and downstream_executor_kind also need future projected support."
          ]
        },
        "ProbeDefinition": {
          "target_type": "whetstone::rsa::Probe plus ProbeRequest/ProbeResult contract",
          "target_fields": [
            "probe_id",
            "failure_hints",
            "intervention_hints"
          ],
          "notes": [
            "The current runtime does not yet expose semantic-first probe declarations separate from implementations."
          ]
        }
      }
    }
  },
  "bootstrap_instances": {
    "DecisionContract": [
      {
        "gate_id": "verification_type",
        "task_family": "taskitem_verification_routing",
        "input_structure": "unstructured",
        "input_modality": "textual",
        "output_topology": "discrete",
        "output_constraint": "bounded",
        "risk_tier": "medium",
        "policy_stability": "stable",
        "deterministic_baseline_available": true,
        "supports_abstain": true,
        "metadata": {
          "case_study": "whetstone_dsl",
          "source_surface": "editor/src/mcp/RegisterArchitectIntakeTools.h",
          "inventory_disposition": "rsa_immediate",
          "downstream_executor_kind": "verification_contract"
        }
      },
      {
        "gate_id": "worker_type",
        "task_family": "taskitem_worker_routing",
        "input_structure": "unstructured",
        "input_modality": "textual",
        "output_topology": "discrete",
        "output_constraint": "bounded",
        "risk_tier": "medium",
        "policy_stability": "mixed",
        "deterministic_baseline_available": true,
        "supports_abstain": true,
        "metadata": {
          "case_study": "whetstone_dsl",
          "source_surface": "editor/src/TaskitemGeneratorV2.h",
          "inventory_disposition": "rsa_immediate",
          "downstream_executor_kind": "workflow_routing"
        }
      },
      {
        "gate_id": "prereq_op_selector",
        "task_family": "taskitem_execution_readiness",
        "input_structure": "hybrid",
        "input_modality": "symbolic",
        "output_topology": "hybrid",
        "output_constraint": "bounded",
        "risk_tier": "medium",
        "policy_stability": "stable",
        "deterministic_baseline_available": true,
        "supports_abstain": true,
        "metadata": {
          "case_study": "whetstone_dsl",
          "source_surface": "editor/src/TaskitemGeneratorV2.h",
          "inventory_disposition": "rsa_immediate",
          "downstream_executor_kind": "execution_contract",
          "structured_output_reason": "multi_op_selection"
        }
      },
      {
        "gate_id": "cpp_raising_profile",
        "task_family": "cpp_projection_profile_selection",
        "input_structure": "structured",
        "input_modality": "symbolic",
        "output_topology": "discrete",
        "output_constraint": "bounded",
        "risk_tier": "high",
        "policy_stability": "stable",
        "deterministic_baseline_available": true,
        "supports_abstain": true,
        "metadata": {
          "case_study": "whetstone_dsl",
          "source_surface": "editor/src/mcp/RegisterCppRaisingTools.h",
          "inventory_disposition": "rsa_immediate",
          "downstream_executor_kind": "cpp_ir_raising"
        }
      }
    ],
    "DecisionSurface": [
      {
        "gate_id": "verification_type",
        "primary_mode": "enum",
        "output_labels": [
          "unit",
          "schema",
          "smoke",
          "docs"
        ],
        "candidate_gate_shapes": [
          "multiclass"
        ],
        "candidate_factorizations": [],
        "deterministic_prepass_options": [
          "target_file_suffix_rules",
          "title_keyword_prepass"
        ],
        "downstream_executor_kind": "verification_policy"
      },
      {
        "gate_id": "worker_type",
        "primary_mode": "enum",
        "output_labels": [
          "implementer",
          "reviewer",
          "architect",
          "qa"
        ],
        "candidate_gate_shapes": [
          "multiclass"
        ],
        "candidate_factorizations": [],
        "deterministic_prepass_options": [
          "title_keyword_rules"
        ],
        "downstream_executor_kind": "workflow_routing"
      },
      {
        "gate_id": "prereq_op_selector",
        "primary_mode": "structured",
        "slot_schema": [
          {
            "name": "validate_intake",
            "type": "boolean"
          },
          {
            "name": "architect_review",
            "type": "boolean"
          },
          {
            "name": "resolve_dependencies",
            "type": "boolean"
          }
        ],
        "candidate_gate_shapes": [
          "factorized",
          "hierarchical"
        ],
        "candidate_factorizations": [
          [
            "validate_intake",
            "architect_review",
            "resolve_dependencies"
          ]
        ],
        "invalid_combinations": [],
        "deterministic_prepass_options": [
          "always_require_validate_intake"
        ],
        "downstream_executor_kind": "execution_contract"
      },
      {
        "gate_id": "cpp_raising_profile",
        "primary_mode": "enum",
        "output_labels": [
          "safe-first",
          "perf-first",
          "interop-first"
        ],
        "candidate_gate_shapes": [
          "multiclass"
        ],
        "candidate_factorizations": [],
        "deterministic_prepass_options": [
          "environment_policy_override",
          "ffi_presence_prepass"
        ],
        "downstream_executor_kind": "cpp_ir_raising"
      }
    ],
    "ProbeDefinition": [
      {
        "probe_id": "confidence_threshold_probe",
        "applies_to_gate_shapes": [
          "binary",
          "multiclass",
          "factorized",
          "hierarchical"
        ],
        "required_contract_fields": [
          "supports_abstain"
        ],
        "required_evidence_fields": [
          "accept_rate",
          "accuracy_on_accepted"
        ],
        "produced_signals": [
          "accept_rate",
          "accuracy_on_accepted",
          "silent_error_rate"
        ],
        "failure_hints": [
          "guardrail_limited_gate",
          "capacity_limited_gate"
        ],
        "intervention_hints": [
          "deploy_with_guardrails",
          "raise_confidence_threshold",
          "evaluate_larger_model_tier"
        ]
      }
    ]
  }
}