provisioning/schemas/generator/contracts.ncl

# Generator Contracts
#
# Type-safe contracts for infrastructure generation, gap analysis,
# change tracking, declarations, and questionnaires.

{
  # ========================================================================
  # Gap Analysis Contracts
  # ========================================================================

  MissingTaskservGap = {
    taskserv_name | String,
    reason | String,
    required | Bool,
    suggested_version | String | optional,
  },

  MissingFieldGap = {
    schema_name | String,
    field_name | String,
    reason | String,
    suggested_value | String | optional,
  },

  VersionMismatchGap = {
    taskserv_name | String,
    current_version | String,
    recommended_version | String,
    reason | String,
  },

  DependencyGap = {
    taskserv_name | String,
    depends_on | String,
    reason | String,
  },

  Gap = {
    kind | String,  # "missing_taskserv" | "missing_field" | "version_mismatch" | "dependency"
    severity | String,  # "error" | "warning" | "info"
    location | String | optional,
    message | String,
    suggestion | String | optional,
    context | {_: String} | optional,
  },

  GapAnalysisReport = {
    declaration_name | String,
    declaration_version | String,
    gaps | Array Gap,
    total_errors | Number,
    total_warnings | Number,
    total_info | Number,
    completeness_score | Number,  # 0.0 to 1.0
  },

  GapFix = {
    gap_id | String,
    action | String,  # "add" | "update" | "remove" | "skip"
    value | String | optional,
    reasoning | String,
  },

  GapFixPlan = {
    declaration_name | String,
    fixes | Array GapFix,
    estimated_changes | Number,
    preservation_strategy | String | optional,
  },

  # ========================================================================
  # Change Tracking Contracts
  # ========================================================================

  AddTaskservChange = {
    taskserv_name | String,
    version | String,
    profile | String,
    reason | String,
  },

  RemoveTaskservChange = {
    taskserv_name | String,
    reason | String,
  },

  UpdateTaskservChange = {
    taskserv_name | String,
    old_version | String | optional,
    new_version | String | optional,
    old_profile | String | optional,
    new_profile | String | optional,
    reason | String,
  },

  UpdateFieldChange = {
    schema_name | String,
    field_name | String,
    old_value | String | optional,
    new_value | String,
    reason | String,
  },

  PreserveCustomizationChange = {
    location | String,
    value | String,
    reason | String,
  },

  Change = {
    kind | String,
    timestamp | String,
    author | String | optional,
    breaking | Bool,
    details | {_: String},
  },

  MergeResult = {
    success | Bool,
    changes | Array Change,
    preserved_customizations | Array String,
    conflicts | Array String,
    version_bumped | String | optional,  # "major" | "minor" | "patch"
    new_version | String | optional,
    warning_messages | Array String,
  },

  ChangelogEntry = {
    version | String,
    date | String,
    changes_summary | Array String,
    breaking_changes | Array String,
    merged_by | String | optional,
  },

  # ========================================================================
  # Declaration Contracts
  # ========================================================================

  Metadata = {
    name | String,
    version | String,
    description | String | optional,
    author | String | optional,
    created_at | String | optional,
    updated_at | String | optional,
  },

  TechnologyDetection = {
    name | String,
    version | String | optional,
    confidence | Number,  # 0.0 to 1.0
    detected_from | Array String | optional,
  },

  TaskservRequirement = {
    name | String,
    version | String | optional,
    profile | String,  # "default" | "minimal" | "HA"
    required | Bool,
    confidence | Number,
    reason | String | optional,
  },

  ServerConfig = {
    name | String,
    provider | String,
    flavor | String | optional,
    region | String | optional,
    taskservs | Array String,
  },

  DeploymentConfig = {
    mode | String,  # "solo" | "multiuser" | "cicd" | "enterprise"
    servers | Array ServerConfig,
    ha_enabled | Bool,
  },

  WorkspaceDeclaration = {
    metadata | Metadata,
    detections | Array TechnologyDetection,
    requirements | Array TaskservRequirement,
    deployment | DeploymentConfig,
    custom_config | {_: String} | optional,
  },

  Changelog = {
    entries | Array ChangelogEntry,
  },

  Workspace = {
    declaration | WorkspaceDeclaration,
    changelog | Changelog,
  },

  # ========================================================================
  # Questionnaire Contracts
  # ========================================================================

  Expression = {
    expr | String,
  },

  ValidationRule = {
    required | Bool,
    pattern | String | optional,
    min_value | Number | optional,
    max_value | Number | optional,
    choices | Array String | optional,
    custom_validator | String | optional,
  },

  Question = {
    id | String,
    kind | String,  # "text" | "select" | "multiselect" | "confirm" | "number"
    message | String,
    help | String | optional,
    default | String | optional,
    when | Expression | optional,
    depends_on | Array String | optional,
    validation | ValidationRule,
    ai_suggest | Bool,
    ai_context | String | optional,
  },

  DecisionNode = {
    question_id | String,
    next_nodes | {_: String} | optional,
    default_next | String | optional,
  },

  DecisionTree = {
    root | String,
    nodes | {_: DecisionNode},
  },

  QuestionnaireMetadata = {
    name | String,
    version | String,
    description | String | optional,
  },

  Questionnaire = {
    metadata | QuestionnaireMetadata,
    questions | Array Question,
    decision_tree | DecisionTree,
  },

  Answer = {
    question_id | String,
    value | Dyn,  # String | Bool | Number
    timestamp | String,
  },

  QuestionnaireResponse = {
    questionnaire_name | String,
    questionnaire_version | String,
    answers | Array Answer,
    completed | Bool,
    completion_time | String | optional,
  },
}