{
  "$schema": "../../schemas/utility.schema.json",
  "kind": "utility",
  "name": "Text",
  "version": "1.0.0-draft.1",
  "purpose": "Text value operations. No hidden external Service communication.",
  "types": "types.json",
  "functions": {
    "size": {
      "parameters": [
        {
          "name": "text",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.integer",
      "purpose": "Integer Unicode code-point count.",
      "statementOnly": false
    },
    "trim": {
      "parameters": [
        {
          "name": "text",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.string",
      "purpose": "Remove leading/trailing Unicode whitespace.",
      "statementOnly": false
    },
    "lower": {
      "parameters": [
        {
          "name": "text",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.string",
      "purpose": "Locale-independent case conversion.",
      "statementOnly": false
    },
    "upper": {
      "parameters": [
        {
          "name": "text",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.string",
      "purpose": "Locale-independent case conversion.",
      "statementOnly": false
    },
    "contains": {
      "parameters": [
        {
          "name": "text",
          "type": "core.string",
          "required": true
        },
        {
          "name": "part",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.boolean",
      "purpose": "Boolean literal substring test.",
      "statementOnly": false
    },
    "startsWith": {
      "parameters": [
        {
          "name": "text",
          "type": "core.string",
          "required": true
        },
        {
          "name": "part",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.boolean",
      "purpose": "Boolean.",
      "statementOnly": false
    },
    "endsWith": {
      "parameters": [
        {
          "name": "text",
          "type": "core.string",
          "required": true
        },
        {
          "name": "part",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.boolean",
      "purpose": "Boolean.",
      "statementOnly": false
    },
    "split": {
      "parameters": [
        {
          "name": "text",
          "type": "core.string",
          "required": true
        },
        {
          "name": "separator",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": {
        "arrayOf": "core.string"
      },
      "purpose": "Array of literal-separated parts, including empty parts. Empty separator fails.",
      "statementOnly": false
    },
    "join": {
      "parameters": [
        {
          "name": "strings",
          "type": "Text.Strings",
          "required": true
        },
        {
          "name": "separator",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.string",
      "purpose": "Concatenated string; elements must be strings.",
      "statementOnly": false
    },
    "replace": {
      "parameters": [
        {
          "name": "text",
          "type": "core.string",
          "required": true
        },
        {
          "name": "search",
          "type": "core.string",
          "required": true
        },
        {
          "name": "replacement",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.string",
      "purpose": "Replace all literal occurrences; empty search fails.",
      "statementOnly": false
    },
    "slice": {
      "parameters": [
        {
          "name": "text",
          "type": "core.string",
          "required": true
        },
        {
          "name": "start",
          "type": "core.integer",
          "required": true
        },
        {
          "name": "count",
          "type": "core.integer",
          "required": true
        }
      ],
      "returns": "core.string",
      "purpose": "Checked code-point range.",
      "statementOnly": false
    },
    "escapeHtml": {
      "parameters": [
        {
          "name": "text",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.string",
      "purpose": "Escape text for insertion into HTML text content, not a URL or script context.",
      "statementOnly": false
    },
    "format": {
      "parameters": [
        {
          "name": "template",
          "type": "core.string",
          "required": true
        },
        {
          "name": "values",
          "type": "core.object",
          "required": true
        }
      ],
      "returns": "core.string",
      "purpose": "String with {{path.to.value}} replacements. Missing paths fail; no expressions or code execute.",
      "statementOnly": false
    },
    "matches": {
      "parameters": [
        {
          "name": "text",
          "type": "core.string",
          "required": true
        },
        {
          "name": "pattern",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.boolean",
      "purpose": "Full-string match using the portable pattern subset in this contract.",
      "statementOnly": false
    }
  },
  "rules": [
    "Text operations use Unicode code points. Case conversion is locale-independent. Slicing checks the full range.",
    "Split and replace use literal separators; empty separators/search fail. Format replaces declared data paths and never evaluates code.",
    "Patterns support literals, classes, Unicode categories, dot, anchors, grouping, alternation and quantifiers. Backreferences, lookaround and implementation-specific flags are excluded."
  ]
}
