{
  "$schema": "../../schemas/service.schema.json",
  "kind": "service",
  "name": "database",
  "version": "1.0.0-draft.1",
  "purpose": "Database capability acquired through a declared System Service.",
  "declarationSchema": "../../../../Service.schema.json",
  "types": "types.json",
  "functions": {
    "create": {
      "parameters": [
        {
          "name": "collection",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "database.Record",
      "purpose": "Unsaved Record for the named Collection.",
      "statementOnly": false
    },
    "first": {
      "parameters": [
        {
          "name": "query",
          "type": "database.Query",
          "required": true
        }
      ],
      "returns": {
        "nullable": "database.Record"
      },
      "purpose": "Record or null.",
      "statementOnly": false
    },
    "query": {
      "parameters": [
        {
          "name": "query",
          "type": "database.Query",
          "required": true
        }
      ],
      "returns": "database.RecordCursor",
      "purpose": "Forward Cursor of Records.",
      "statementOnly": false
    },
    "count": {
      "parameters": [
        {
          "name": "query",
          "type": "database.Query",
          "required": true
        }
      ],
      "returns": "core.integer",
      "purpose": "Integer count.",
      "statementOnly": false
    },
    "update": {
      "parameters": [
        {
          "name": "query",
          "type": "database.BulkUpdate",
          "required": true
        }
      ],
      "returns": "core.integer",
      "purpose": "Bulk update of matching records; returns integer affected row count.",
      "statementOnly": false
    }
  },
  "rules": [
    "Records are execution-owned handles. Field reads use only the loaded projection. Assignment and load change pending values; remove clears one field. save persists pending state without committing the transaction.",
    "A reference value contains the target identity according to the Collection. Arrays of values do not automatically become arrays of linked Records.",
    "For a single-record business decision use first, check the record, change or remove fields and save. update applies one bulk change to matching base records.",
    "Queries follow Query or BulkUpdate schemas and query-semantics.json. Field names, reference paths, projections and aggregate results are checked against declared Collections.",
    "Read filters explicitly express the intended soft-deletion policy. The Service exposes no physical record deletion. A zero affected-row count is not automatically NotFound.",
    "A RecordCursor is iterated using for each. It visits only the requested page and is released by its execution scope. No undocumented cursor methods are exposed."
  ],
  "references": [
    "query-semantics.json",
    "query.schema.json",
    "bulk-update.schema.json"
  ]
}
