{
  "$schema": "../../schemas/utility.schema.json",
  "kind": "utility",
  "name": "Bytes",
  "version": "1.0.0-draft.1",
  "purpose": "Bytes value operations. No hidden external Service communication.",
  "types": "types.json",
  "functions": {
    "encode": {
      "parameters": [
        {
          "name": "value",
          "type": "core.data",
          "required": true
        },
        {
          "name": "charset",
          "type": "core.string",
          "required": false,
          "default": "UTF-8"
        }
      ],
      "returns": "core.bytes",
      "purpose": "Any AIScript data value as bytes: strings encode directly, bytes pass unchanged, all other data values serialize as JSON and encode. The charset applies to the resulting text; unencodable text fails. Handles and cycles fail.",
      "statementOnly": false
    },
    "decode": {
      "parameters": [
        {
          "name": "value",
          "type": "core.bytes",
          "required": true
        },
        {
          "name": "charset",
          "type": "core.string",
          "required": false,
          "default": "UTF-8"
        }
      ],
      "returns": "core.string",
      "purpose": "String; reject malformed sequences.",
      "statementOnly": false
    },
    "size": {
      "parameters": [
        {
          "name": "value",
          "type": "core.bytes",
          "required": true
        }
      ],
      "returns": "core.integer",
      "purpose": "Integer byte count.",
      "statementOnly": false
    },
    "slice": {
      "parameters": [
        {
          "name": "value",
          "type": "core.bytes",
          "required": true
        },
        {
          "name": "start",
          "type": "core.integer",
          "required": true
        },
        {
          "name": "count",
          "type": "core.integer",
          "required": true
        }
      ],
      "returns": "core.bytes",
      "purpose": "New checked byte range.",
      "statementOnly": false
    },
    "concat": {
      "parameters": [
        {
          "name": "parts",
          "type": "Bytes.Parts",
          "required": true
        }
      ],
      "returns": "core.bytes",
      "purpose": "New bytes from an array of byte sequences.",
      "statementOnly": false
    },
    "base64": {
      "parameters": [
        {
          "name": "value",
          "type": "core.bytes",
          "required": true
        }
      ],
      "returns": "core.string",
      "purpose": "Standard padded Base64 encode/strict decode.",
      "statementOnly": false
    },
    "fromBase64": {
      "parameters": [
        {
          "name": "text",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.bytes",
      "purpose": "Standard padded Base64 encode/strict decode.",
      "statementOnly": false
    },
    "hex": {
      "parameters": [
        {
          "name": "value",
          "type": "core.bytes",
          "required": true
        }
      ],
      "returns": "core.string",
      "purpose": "Lowercase hexadecimal encode; strict even-length decode.",
      "statementOnly": false
    },
    "fromHex": {
      "parameters": [
        {
          "name": "text",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.bytes",
      "purpose": "Lowercase hexadecimal encode; strict even-length decode.",
      "statementOnly": false
    }
  },
  "rules": [
    "Bytes are immutable. Standard charsets are UTF-8, US-ASCII and ISO-8859-1. Decode is strict; malformed or unencodable data fails.",
    "encode passes bytes unchanged, encodes strings directly, and serializes all other data through Object.asString before encoding. Explicit null encodes the text null. Handles and cycles fail.",
    "Base64 is standard padded encoding with strict decoding. Hex encoding is lowercase; decoding requires an even-length valid value. Other encodings require an explicit extension contract."
  ]
}
