{
  "$schema": "../../schemas/service.schema.json",
  "kind": "service",
  "name": "cache",
  "version": "1.0.0-draft.1",
  "purpose": "Local And Shared Cache capability acquired through a declared System Service.",
  "declarationSchema": "../../../../Service.schema.json",
  "types": "types.json",
  "functions": {
    "get": {
      "parameters": [
        {
          "name": "key",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": {
        "nullable": "core.data"
      },
      "purpose": "Data value or null.",
      "statementOnly": false
    },
    "put": {
      "parameters": [
        {
          "name": "key",
          "type": "core.string",
          "required": true
        },
        {
          "name": "value",
          "type": "core.data",
          "required": true
        },
        {
          "name": "ttlSeconds",
          "type": "core.integer",
          "required": false
        }
      ],
      "returns": "core.void",
      "purpose": "none.",
      "statementOnly": true
    },
    "remove": {
      "parameters": [
        {
          "name": "key",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.void",
      "purpose": "none.",
      "statementOnly": true
    },
    "containsKey": {
      "parameters": [
        {
          "name": "key",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.boolean",
      "purpose": "Boolean.",
      "statementOnly": false
    }
  },
  "rules": [
    "Local cache values are private to one execution engine and Service instance, and disappear on restart or unload. Shared cache values are visible to clients of the same configured store.",
    "Values are copied into and out of both caches. Mutating returned data does not mutate the cached entry. Handles and cyclic data cannot be cached.",
    "Local put may omit ttlSeconds. Zero adds no per-entry expiry; negative TTL fails. Configured capacity and expiry still apply.",
    "Shared put requires ttlSeconds. A zero or negative value requests an ordinary non-expiring write under that contract. Shared keys follow the System namespace convention.",
    "Cache effects do not join database transactions."
  ]
}
