{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/mnemoverse-com/json-schema/mnemoverse-com-ready-response-schema-schema.json",
  "title": "ReadyResponseSchema",
  "description": "Deep readiness check (database + engine + warm-up + embedding).\n\nTwo verdicts, deliberately separate:\n\n* ``ready`` - the hard dependencies (database, engine). ``false`` is served\n  as **HTTP 503**, so a deploy healthcheck refuses to promote a build\n  whose startup failed. For the deploy healthcheck ONLY, a warm-up still\n  inside its gate also makes ``ready`` false (see below).\n* ``degraded`` — ``ready`` but the LIVE embedding probe failed. Served as\n  **HTTP 200**, so an embedding outage never blocks deploying its own fix.\n  External probes must assert ``ready == true && degraded == false``.\n\n``checks.embedding`` is a real embedding call (cached 60 s server-side),\nnot a wiring check.\n\n``checks.warm`` is reported to every caller and is bounded: with the\nwarm-up gate on, it is false while the current process's warm-up is still\ninside the window (at most 200 s). It makes ``ready`` false (HTTP 503) only\nfor the deploy healthcheck, so that traffic promotion waits for the\nwarm-up. Every other caller keeps getting ``ready: true``: after a crash\nrestart the process serves traffic at once, and reporting it as not ready\nwould report an outage that is not happening. Never longer than the cap,\nand never at all with the gate off (the default).",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/mnemoverse-com-memory-v1-api-openapi.yml#/components/schemas/ReadyResponseSchema",
  "properties": {
    "ready": {
      "type": "boolean",
      "title": "Ready",
      "description": "True when the hard dependencies (database, engine) are operational. For the deploy healthcheck only, also false while the bounded warm-up gate is holding - see `checks.warm`. False is served as HTTP 503. Does NOT include the embedding probe — see `degraded`."
    },
    "degraded": {
      "type": "boolean",
      "title": "Degraded",
      "description": "True when `ready` is true but the live embedding probe failed (`checks.embedding == false`). Served as HTTP 200 so a vendor outage cannot block a deploy; probes must alert on it.",
      "default": false
    },
    "checks": {
      "additionalProperties": {
        "type": "boolean"
      },
      "type": "object",
      "title": "Checks",
      "description": "Per-subsystem status. `database`: live SELECT 1; `engine`: initialised; `embedding`: live embed call succeeded within the timeout (cached 60 s); `warm`: true when the warm-up readiness gate is off (the default), the warm-up has finished, or the gate's time cap has elapsed - false only while a gated warm-up is still inside its window (including a just-started instance whose warm run has not begun yet)."
    },
    "embedding_checked_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Embedding Checked At",
      "description": "ISO-8601 UTC timestamp of the live embedding call behind `checks.embedding` (may be up to 60 s old — the probe is cached). None when the engine is not initialised."
    },
    "embedding_error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Embedding Error",
      "description": "Exception CLASS name of the last failed embedding probe (e.g. 'TimeoutError', 'HTTPStatusError'), or a short reason token ('embed_fn_not_wired'). Never the message — messages may carry URLs or credentials. None when the probe succeeded or the engine is not initialised."
    },
    "version": {
      "type": "string",
      "title": "Version",
      "description": "Application version string."
    },
    "git_sha": {
      "type": "string",
      "title": "Git Sha",
      "description": "Git commit SHA of the running build (injected at image build time; 'unknown' for local/dev), so a caller can tell which build answered.",
      "default": "unknown"
    },
    "embedding_identity": {
      "anyOf": [
        {
          "$ref": "#/$defs/EmbeddingIdentitySchema"
        },
        {
          "type": "null"
        }
      ],
      "description": "The embedding model THIS server actually runs (model id and effective output dimension) — the same identity its writes record, not its configuration. Record this one rather than an assumed model. None only when the engine is not initialized."
    }
  },
  "type": "object",
  "required": [
    "ready",
    "checks",
    "version"
  ],
  "$defs": {
    "EmbeddingIdentitySchema": {
      "properties": {
        "model": {
          "type": "string",
          "title": "Model",
          "description": "Model id of the embedding model this server runs."
        },
        "dim": {
          "type": "integer",
          "title": "Dim",
          "description": "Effective output dimension (after any truncation)."
        }
      },
      "type": "object",
      "required": [
        "model",
        "dim"
      ],
      "title": "EmbeddingIdentitySchema",
      "description": "The embedding model this server actually runs, as its writes record it.\n\nExposes ONLY the model id and effective dimension (model names are not\nsecrets); never the vendor URL, key material, or backend internals."
    }
  }
}