{
  "$schema": "../../schemas/utility.schema.json",
  "kind": "utility",
  "name": "Dates",
  "version": "1.0.0-draft.1",
  "purpose": "Dates value operations. No hidden external Service communication.",
  "types": "types.json",
  "functions": {
    "now": {
      "parameters": [],
      "returns": "core.datetime",
      "purpose": "Current datetime.",
      "statementOnly": false
    },
    "today": {
      "parameters": [
        {
          "name": "timezone",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.date",
      "purpose": "Current calendar date in the named timezone.",
      "statementOnly": false
    },
    "date": {
      "parameters": [
        {
          "name": "text",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.date",
      "purpose": "Parse yyyy-MM-dd strictly.",
      "statementOnly": false
    },
    "datetime": {
      "parameters": [
        {
          "name": "text",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.datetime",
      "purpose": "Parse an ISO datetime containing an explicit offset or Z.",
      "statementOnly": false
    },
    "parse": {
      "parameters": [
        {
          "name": "text",
          "type": "core.string",
          "required": true
        },
        {
          "name": "kind",
          "type": "core.string",
          "required": true
        },
        {
          "name": "pattern",
          "type": "core.string",
          "required": true
        },
        {
          "name": "timezone",
          "type": {
            "nullable": "core.string"
          },
          "required": false,
          "default": null
        },
        {
          "name": "policy",
          "type": {
            "nullable": "Dates.ParsePolicy"
          },
          "required": false,
          "default": null
        }
      ],
      "returns": {
        "oneOf": [
          "core.date",
          "core.datetime"
        ]
      },
      "purpose": "Parse date/datetime using an explicit pattern and policies.",
      "statementOnly": false
    },
    "add": {
      "parameters": [
        {
          "name": "value",
          "type": {
            "oneOf": [
              "core.date",
              "core.datetime"
            ]
          },
          "required": true
        },
        {
          "name": "amount",
          "type": "core.integer",
          "required": true
        },
        {
          "name": "unit",
          "type": "core.string",
          "required": true
        },
        {
          "name": "options",
          "type": {
            "nullable": "Dates.AddOptions"
          },
          "required": false,
          "default": null
        }
      ],
      "returns": {
        "oneOf": [
          "core.date",
          "core.datetime"
        ]
      },
      "purpose": "Add an integer amount with the rules in this contract.",
      "statementOnly": false
    },
    "startOfDay": {
      "parameters": [
        {
          "name": "date",
          "type": "core.date",
          "required": true
        },
        {
          "name": "timezone",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.datetime",
      "purpose": "Earliest valid instant on that local date; a wholly skipped date fails.",
      "statementOnly": false
    },
    "before": {
      "parameters": [
        {
          "name": "left",
          "type": {
            "oneOf": [
              "core.date",
              "core.datetime"
            ]
          },
          "required": true
        },
        {
          "name": "right",
          "type": {
            "oneOf": [
              "core.date",
              "core.datetime"
            ]
          },
          "required": true
        }
      ],
      "returns": "core.boolean",
      "purpose": "Same-type comparison.",
      "statementOnly": false
    },
    "after": {
      "parameters": [
        {
          "name": "left",
          "type": {
            "oneOf": [
              "core.date",
              "core.datetime"
            ]
          },
          "required": true
        },
        {
          "name": "right",
          "type": {
            "oneOf": [
              "core.date",
              "core.datetime"
            ]
          },
          "required": true
        }
      ],
      "returns": "core.boolean",
      "purpose": "Same-type comparison.",
      "statementOnly": false
    },
    "between": {
      "parameters": [
        {
          "name": "start",
          "type": "core.datetime",
          "required": true
        },
        {
          "name": "end",
          "type": "core.datetime",
          "required": true
        },
        {
          "name": "unit",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.decimal",
      "purpose": "Decimal elapsed datetime difference in milliseconds/seconds/minutes/hours.",
      "statementOnly": false
    },
    "format": {
      "parameters": [
        {
          "name": "value",
          "type": {
            "oneOf": [
              "core.date",
              "core.datetime"
            ]
          },
          "required": true
        },
        {
          "name": "pattern",
          "type": "core.string",
          "required": true
        },
        {
          "name": "timezone",
          "type": {
            "nullable": "core.string"
          },
          "required": false,
          "default": null
        }
      ],
      "returns": "core.string",
      "purpose": "String; datetime formatting requires explicit timezone, date formatting does not.",
      "statementOnly": false
    }
  },
  "rules": [
    "Dates are calendar values; datetimes are instants. Parsing is strict and never chooses an implicit machine timezone.",
    "Calendar date addition accepts days, weeks, months and years. Datetime elapsed addition accepts milliseconds, seconds, minutes and hours. Datetime calendar addition requires options.timezone and preserves local clock time.",
    "Month/year addition defaults to the last valid destination day; monthEnd reject requests failure. Daylight-saving gaps/overlaps fail unless gap forward or overlap earlier/later explicitly resolves them.",
    "Pattern fields are yyyy, MM, dd, HH, mm, ss, SSS and XXX with quoted literal text. kind is date or datetime. Invalid type/unit combinations, zones and dates fail.",
    "startOfDay is the earliest valid instant of the local date; wholly skipped dates fail. Datetime format requires an explicit timezone. Adding a calendar day is not adding 24 elapsed hours."
  ]
}
