{
  "$schema": "../../schemas/types.schema.json",
  "namespace": "storage",
  "version": "1.0.0-draft.1",
  "types": [
    {
      "name": "storage.Folder",
      "kind": "handle",
      "purpose": "Execution-owned folder; not serializable and exposes only these defined operations.",
      "methods": {
        "get": {
          "parameters": [
            {
              "name": "path",
              "type": "core.string",
              "required": true
            }
          ],
          "returns": {
            "nullable": "storage.Entry"
          },
          "purpose": "File/Folder handle or null.",
          "statementOnly": false
        },
        "newFolder": {
          "parameters": [
            {
              "name": "path",
              "type": "core.string",
              "required": true
            }
          ],
          "returns": "storage.Folder",
          "purpose": "Folder, creating it according to the Service contract.",
          "statementOnly": false
        },
        "newFile": {
          "parameters": [
            {
              "name": "path",
              "type": "core.string",
              "required": true
            }
          ],
          "returns": "storage.File",
          "purpose": "New File; exclusive creation fails with Conflict if an entry already exists.",
          "statementOnly": false
        },
        "list": {
          "parameters": [
            {
              "name": "pattern",
              "type": "core.string",
              "required": true
            },
            {
              "name": "visitor",
              "type": "storage.Visitor",
              "required": true
            }
          ],
          "returns": "core.void",
          "purpose": "none; invoke the named one-argument helper for each entry.",
          "statementOnly": true
        },
        "isFile": {
          "parameters": [],
          "returns": "core.boolean",
          "purpose": "Boolean.",
          "statementOnly": false
        },
        "isFolder": {
          "parameters": [],
          "returns": "core.boolean",
          "purpose": "Boolean.",
          "statementOnly": false
        }
      },
      "fields": {
        "name": "core.string",
        "path": "core.string",
        "size": "core.integer",
        "modifiedAt": "core.datetime"
      }
    },
    {
      "name": "storage.File",
      "kind": "handle",
      "purpose": "Execution-owned file; not serializable and exposes only these defined operations.",
      "methods": {
        "isFile": {
          "parameters": [],
          "returns": "core.boolean",
          "purpose": "Boolean.",
          "statementOnly": false
        },
        "isFolder": {
          "parameters": [],
          "returns": "core.boolean",
          "purpose": "Boolean.",
          "statementOnly": false
        },
        "asString": {
          "parameters": [],
          "returns": "core.string",
          "purpose": "Text or bytes under the Service's read contract.",
          "statementOnly": false
        },
        "asBytes": {
          "parameters": [],
          "returns": "core.bytes",
          "purpose": "Text or bytes under the Service's read contract.",
          "statementOnly": false
        },
        "write": {
          "parameters": [
            {
              "name": "value",
              "type": "storage.WriteContent",
              "required": true
            }
          ],
          "returns": "core.void",
          "purpose": "none; write text or stream data.",
          "statementOnly": true
        },
        "openRead": {
          "parameters": [],
          "returns": "storage.ReadStream",
          "purpose": "Owned ReadStream.",
          "statementOnly": false
        },
        "openWrite": {
          "parameters": [
            {
              "name": "append",
              "type": "core.boolean",
              "required": false,
              "default": false
            }
          ],
          "returns": "storage.WriteStream",
          "purpose": "Owned WriteStream.",
          "statementOnly": false
        }
      },
      "fields": {
        "name": "core.string",
        "path": "core.string",
        "size": "core.integer",
        "modifiedAt": "core.datetime"
      }
    },
    {
      "name": "storage.Entry",
      "kind": "handle",
      "purpose": "Execution-owned entry; not serializable and exposes only these defined operations.",
      "methods": {
        "isFile": {
          "parameters": [],
          "returns": "core.boolean",
          "purpose": "Boolean.",
          "statementOnly": false
        },
        "isFolder": {
          "parameters": [],
          "returns": "core.boolean",
          "purpose": "Boolean.",
          "statementOnly": false
        },
        "asString": {
          "parameters": [],
          "returns": "core.string",
          "purpose": "Read the file as text.",
          "statementOnly": false
        },
        "asBytes": {
          "parameters": [],
          "returns": "core.bytes",
          "purpose": "Read the file as bytes.",
          "statementOnly": false
        },
        "write": {
          "parameters": [
            {
              "name": "value",
              "type": "storage.WriteContent",
              "required": true
            }
          ],
          "returns": "core.void",
          "purpose": "Write the permitted text or ReadStream content.",
          "statementOnly": true
        },
        "openRead": {
          "parameters": [],
          "returns": "storage.ReadStream",
          "purpose": "Open an owned read stream.",
          "statementOnly": false
        },
        "openWrite": {
          "parameters": [
            {
              "name": "append",
              "type": "core.boolean",
              "required": false,
              "default": false
            }
          ],
          "returns": "storage.WriteStream",
          "purpose": "Open an owned write stream.",
          "statementOnly": false
        },
        "get": {
          "parameters": [
            {
              "name": "path",
              "type": "core.string",
              "required": true
            }
          ],
          "returns": {
            "nullable": "storage.Entry"
          },
          "purpose": "File/Folder handle or null.",
          "statementOnly": false
        },
        "newFolder": {
          "parameters": [
            {
              "name": "path",
              "type": "core.string",
              "required": true
            }
          ],
          "returns": "storage.Folder",
          "purpose": "Folder, creating it according to the Service contract.",
          "statementOnly": false
        },
        "newFile": {
          "parameters": [
            {
              "name": "path",
              "type": "core.string",
              "required": true
            }
          ],
          "returns": "storage.File",
          "purpose": "New File; exclusive creation fails with Conflict if an entry already exists.",
          "statementOnly": false
        },
        "list": {
          "parameters": [
            {
              "name": "pattern",
              "type": "core.string",
              "required": true
            },
            {
              "name": "visitor",
              "type": "storage.Visitor",
              "required": true
            }
          ],
          "returns": "core.void",
          "purpose": "none; invoke the named one-argument helper for each entry.",
          "statementOnly": true
        }
      },
      "fields": {
        "name": "core.string",
        "path": "core.string",
        "size": "core.integer",
        "modifiedAt": "core.datetime"
      }
    },
    {
      "name": "storage.ReadStream",
      "kind": "handle",
      "purpose": "Execution-owned readStream; not serializable and exposes only these defined operations.",
      "methods": {
        "read": {
          "parameters": [
            {
              "name": "count",
              "type": "core.integer",
              "required": true
            }
          ],
          "returns": {
            "nullable": "core.bytes"
          },
          "purpose": "Up to count bytes, or null at EOF; count must be positive.",
          "statementOnly": false
        },
        "close": {
          "parameters": [],
          "returns": "core.void",
          "purpose": "none; release an owned stream, safely repeatable.",
          "statementOnly": true
        }
      }
    },
    {
      "name": "storage.WriteStream",
      "kind": "handle",
      "purpose": "Execution-owned writeStream; not serializable and exposes only these defined operations.",
      "methods": {
        "write": {
          "parameters": [
            {
              "name": "bytes",
              "type": "core.bytes",
              "required": true
            }
          ],
          "returns": "core.void",
          "purpose": "none; WriteStream only.",
          "statementOnly": true
        },
        "close": {
          "parameters": [],
          "returns": "core.void",
          "purpose": "none; release an owned stream, safely repeatable.",
          "statementOnly": true
        }
      }
    },
    {
      "name": "storage.Visitor",
      "kind": "function",
      "purpose": "Named helper visiting each listed entry.",
      "parameters": [
        {
          "name": "entry",
          "type": "storage.Entry",
          "required": true
        }
      ],
      "returns": "core.void"
    },
    {
      "name": "storage.WriteContent",
      "kind": "union",
      "purpose": "Permitted file-write content.",
      "alternatives": [
        "core.string",
        "storage.ReadStream"
      ]
    }
  ]
}
