cli.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://visual-store.invalid/schema/cli-v2.json",
  "title": "Visual Store CLI v2",
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "schema_version": { "const": 2 },
        "ok": { "const": true },
        "data": {
          "oneOf": [
            { "$ref": "#/$defs/init" },
            { "$ref": "#/$defs/put" },
            { "$ref": "#/$defs/info" },
            { "$ref": "#/$defs/features" },
            { "$ref": "#/$defs/list" },
            { "$ref": "#/$defs/judgment" },
            { "$ref": "#/$defs/judgmentList" },
            { "$ref": "#/$defs/get" },
            { "$ref": "#/$defs/verify" },
            { "$ref": "#/$defs/pack" },
            { "$ref": "#/$defs/prune" },
            { "$ref": "#/$defs/migrate" }
          ]
        }
      },
      "required": ["schema_version", "ok", "data"],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "schema_version": { "const": 2 },
        "ok": { "const": false },
        "error": { "$ref": "#/$defs/error" },
        "data": { "oneOf": [{ "$ref": "#/$defs/verify" }, { "$ref": "#/$defs/pack" }, { "$ref": "#/$defs/prune" }] }
      },
      "required": ["schema_version", "ok", "error"],
      "additionalProperties": false
    }
  ],
  "$defs": {
    "uuid": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "hash": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$"
    },
    "nullableString": {
      "type": ["string", "null"]
    },
    "nullableFrame": {
      "type": ["integer", "null"],
      "minimum": 0
    },
    "init": {
      "type": "object",
      "properties": {
        "store_id": { "$ref": "#/$defs/uuid" },
        "schema_version": { "enum": [1, 2, 3] },
        "already_initialized": { "type": "boolean" }
      },
      "required": ["store_id", "schema_version", "already_initialized"],
      "additionalProperties": false
    },
    "put": {
      "type": "object",
      "properties": {
        "ref": { "type": "string", "pattern": "^visual://[0-9a-f-]{36}/images/[0-9a-f-]{36}$" },
        "image_id": { "$ref": "#/$defs/uuid" },
        "run": { "$ref": "#/$defs/nullableString" },
        "stream": { "$ref": "#/$defs/nullableString" },
        "frame_no": { "$ref": "#/$defs/nullableFrame" },
        "seq": { "type": "integer", "minimum": 1 },
        "width": { "type": "integer", "minimum": 1 },
        "height": { "type": "integer", "minimum": 1 },
        "source_bytes": { "type": "integer", "minimum": 1 },
        "stored_bytes": { "type": "integer", "minimum": 1 },
        "source_retained": { "type": "boolean" },
        "compression_applied": { "type": "boolean" },
        "blob_reused": { "type": "boolean" },
        "record_reused": { "type": "boolean" }
      },
      "required": ["ref", "image_id", "run", "stream", "frame_no", "seq", "width", "height", "source_bytes", "stored_bytes", "source_retained", "compression_applied", "blob_reused", "record_reused"],
      "additionalProperties": false
    },
    "info": {
      "type": "object",
      "properties": {
        "ref": { "type": "string", "pattern": "^visual://[0-9a-f-]{36}/images/[0-9a-f-]{36}$" },
        "image_id": { "$ref": "#/$defs/uuid" },
        "run": { "$ref": "#/$defs/nullableString" },
        "stream": { "$ref": "#/$defs/nullableString" },
        "frame_no": { "$ref": "#/$defs/nullableFrame" },
        "seq": { "type": "integer", "minimum": 1 },
        "created_at": { "type": "string" },
        "captured_at": { "$ref": "#/$defs/nullableString" },
        "label": { "$ref": "#/$defs/nullableString" },
        "note": { "$ref": "#/$defs/nullableString" },
        "tags": { "type": "array", "items": { "type": "string" }, "maxItems": 16, "uniqueItems": true },
        "width": { "type": "integer", "minimum": 1 },
        "height": { "type": "integer", "minimum": 1 },
        "bit_depth": { "const": 8 },
        "color_type": { "enum": [2, 6] },
        "source_sha256": { "$ref": "#/$defs/hash" },
        "source_bytes": { "type": "integer", "minimum": 1 },
        "stored_sha256": { "oneOf": [{ "$ref": "#/$defs/hash" }, { "type": "null" }] },
        "stored_bytes": { "type": ["integer", "null"], "minimum": 1 },
        "source_retained": { "type": "boolean" },
        "scanline_sha256": { "$ref": "#/$defs/hash" },
        "non_idat_sha256": { "$ref": "#/$defs/hash" },
        "pixel_sha256": { "$ref": "#/$defs/hash" },
        "encoding_version": { "type": "string" },
        "compression_level": { "type": ["integer", "null"], "minimum": 0, "maximum": 9 },
        "compression_applied": { "type": ["boolean", "null"] },
        "representation_kind": { "enum": ["png", "vp9_segment"] },
        "representation_version": { "type": "integer", "minimum": 1 },
        "segment_id": { "oneOf": [{ "$ref": "#/$defs/hash" }, { "type": "null" }] },
        "frame_index": { "type": ["integer", "null"], "minimum": 0 },
        "decode_start_index": { "type": ["integer", "null"], "minimum": 0 },
        "shared_representation_bytes": { "type": "integer", "minimum": 1 },
        "shared_image_count": { "type": "integer", "minimum": 1 },
        "capacity_semantics": { "const": "shared_representation_bytes_may_be_shared_by_multiple_images" }
      },
      "required": ["ref", "image_id", "run", "stream", "frame_no", "seq", "created_at", "captured_at", "label", "note", "tags", "width", "height", "bit_depth", "color_type", "source_sha256", "source_bytes", "stored_sha256", "stored_bytes", "source_retained", "scanline_sha256", "non_idat_sha256", "pixel_sha256", "encoding_version", "compression_level", "compression_applied", "representation_kind", "representation_version", "segment_id", "frame_index", "decode_start_index", "shared_representation_bytes", "shared_image_count", "capacity_semantics"],
      "additionalProperties": false
    },
    "listItem": {
      "type": "object",
      "properties": {
        "ref": { "type": "string", "pattern": "^visual://[0-9a-f-]{36}/images/[0-9a-f-]{36}$" },
        "seq": { "type": "integer", "minimum": 1 },
        "run": { "$ref": "#/$defs/nullableString" },
        "stream": { "$ref": "#/$defs/nullableString" },
        "frame_no": { "$ref": "#/$defs/nullableFrame" },
        "label": { "$ref": "#/$defs/nullableString" },
        "width": { "type": "integer", "minimum": 1 },
        "height": { "type": "integer", "minimum": 1 },
        "created_at": { "type": "string" },
        "stored_bytes": { "type": "integer", "minimum": 1 }
      },
      "required": ["ref", "seq", "run", "stream", "frame_no", "label", "width", "height", "created_at", "stored_bytes"],
      "additionalProperties": false
    },
    "list": {
      "type": "object",
      "properties": {
        "items": { "type": "array", "items": { "$ref": "#/$defs/listItem" }, "maxItems": 100 },
        "next_cursor": { "type": "string", "maxLength": 4096 }
      },
      "required": ["items"],
      "additionalProperties": false
    },
    "features": {
      "type": "object",
      "properties": {
        "ref": { "type": "string", "pattern": "^visual://[0-9a-f-]{36}/images/[0-9a-f-]{36}$" },
        "image_id": { "$ref": "#/$defs/uuid" },
        "run": { "$ref": "#/$defs/nullableString" },
        "stream": { "$ref": "#/$defs/nullableString" },
        "frame_no": { "$ref": "#/$defs/nullableFrame" },
        "sha256": {
          "type": "object",
          "properties": {
            "source": { "$ref": "#/$defs/hash" },
            "pixels": { "$ref": "#/$defs/hash" },
            "stored_png": { "oneOf": [{ "$ref": "#/$defs/hash" }, { "type": "null" }] }
          },
          "required": ["source", "pixels", "stored_png"],
          "additionalProperties": false
        },
        "width": { "type": "integer", "minimum": 1 },
        "height": { "type": "integer", "minimum": 1 },
        "source_bytes": { "type": "integer", "minimum": 1 },
        "representation_bytes": { "type": "integer", "minimum": 1 },
        "representation_bytes_semantics": { "const": "shared_and_not_additive_across_images" },
        "previous": {
          "oneOf": [
            { "type": "null" },
            {
              "type": "object",
              "properties": {
                "ref": { "type": "string", "pattern": "^visual://[0-9a-f-]{36}/images/[0-9a-f-]{36}$" },
                "image_id": { "$ref": "#/$defs/uuid" },
                "pixel_sha256": { "$ref": "#/$defs/hash" },
                "same_pixels": { "type": "boolean" }
              },
              "required": ["ref", "image_id", "pixel_sha256", "same_pixels"],
              "additionalProperties": false
            }
          ]
        }
      },
      "required": ["ref", "image_id", "run", "stream", "frame_no", "sha256", "width", "height", "source_bytes", "representation_bytes", "representation_bytes_semantics", "previous"],
      "additionalProperties": false
    },
    "judgment": {
      "type": "object",
      "properties": {
        "seq": { "type": "integer", "minimum": 1 },
        "judgment_id": { "$ref": "#/$defs/uuid" },
        "ref": { "type": "string", "pattern": "^visual://[0-9a-f-]{36}/images/[0-9a-f-]{36}$" },
        "image_id": { "$ref": "#/$defs/uuid" },
        "kind": { "type": "string", "minLength": 1, "maxLength": 128 },
        "producer": { "type": "string", "minLength": 1, "maxLength": 128 },
        "model": { "$ref": "#/$defs/nullableString" },
        "schema_version": { "type": "integer", "minimum": 1 },
        "value": {},
        "probability": { "type": ["number", "null"], "minimum": 0, "maximum": 1 },
        "confidence": { "type": ["number", "null"], "minimum": 0, "maximum": 1 },
        "metadata": { "type": "object" },
        "created_at": { "type": "string" }
      },
      "required": ["judgment_id", "ref", "image_id", "kind", "producer", "model", "schema_version", "value", "probability", "confidence", "metadata", "created_at"],
      "additionalProperties": false
    },
    "judgmentList": {
      "type": "object",
      "properties": {
        "items": { "type": "array", "items": { "$ref": "#/$defs/judgment" }, "maxItems": 100 },
        "next_cursor": { "type": "string", "maxLength": 4096 }
      },
      "required": ["items"],
      "additionalProperties": false
    },
    "get": {
      "type": "object",
      "properties": {
        "ref": { "type": "string", "pattern": "^visual://[0-9a-f-]{36}/images/[0-9a-f-]{36}$" },
        "path": { "type": "string" },
        "media_type": { "const": "image/png" },
        "width": { "type": "integer", "minimum": 1 },
        "height": { "type": "integer", "minimum": 1 },
        "byte_length": { "type": "integer", "minimum": 1 },
        "sha256": { "$ref": "#/$defs/hash" },
        "variant": { "enum": ["stored", "source"] },
        "backend": { "enum": ["png", "source_png", "vp9_segment"] },
        "segment_id": { "oneOf": [{ "$ref": "#/$defs/hash" }, { "type": "null" }] },
        "frame_index": { "type": ["integer", "null"], "minimum": 0 },
        "decoded_from_frame": { "type": ["integer", "null"], "minimum": 0 },
        "decoded_through_frame": { "type": ["integer", "null"], "minimum": 0 },
        "displayed": { "const": false }
      },
      "required": ["ref", "path", "media_type", "width", "height", "byte_length", "sha256", "variant", "backend", "segment_id", "frame_index", "decoded_from_frame", "decoded_through_frame", "displayed"],
      "additionalProperties": false
    },
    "verify": {
      "type": "object",
      "properties": {
        "store_id": { "$ref": "#/$defs/uuid" },
        "images_checked": { "type": "integer", "minimum": 0 },
        "blobs_checked": { "type": "integer", "minimum": 0 },
        "segments_checked": { "type": "integer", "minimum": 0 },
        "error_count": { "type": "integer", "minimum": 0 },
        "unreferenced_candidates": { "type": "integer", "minimum": 0 },
        "issue_count": { "type": "integer", "minimum": 0 },
        "issues": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "code": { "type": "string" },
              "blob_sha256": { "$ref": "#/$defs/hash" }
              ,"segment_id": { "$ref": "#/$defs/hash" }
            },
            "required": ["code"],
            "additionalProperties": false
          },
          "maxItems": 20
        },
        "valid": { "type": "boolean" }
      },
      "required": ["store_id", "images_checked", "blobs_checked", "segments_checked", "error_count", "unreferenced_candidates", "issue_count", "issues", "valid"],
      "additionalProperties": false
    },
    "packResult": {
      "type": "object",
      "properties": {
        "stream": { "type": "string" },
        "first_frame_no": { "type": "integer", "minimum": 0 },
        "last_frame_no": { "type": "integer", "minimum": 0 },
        "image_count": { "type": "integer", "minimum": 1 },
        "status": { "enum": ["packed", "would_pack", "not_beneficial", "skipped", "failed", "no_op"] },
        "reason": { "type": "string" },
        "segment_id": { "$ref": "#/$defs/hash" },
        "png_distinct_bytes": { "type": "integer", "minimum": 0 },
        "candidate_bytes": { "type": "integer", "minimum": 0 },
        "reconstruction_distinct_bytes": { "type": "integer", "minimum": 0 },
        "encode_millis": { "type": "integer", "minimum": 0 }
      },
      "required": ["status", "reason"],
      "additionalProperties": false
    },
    "pack": {
      "type": "object",
      "properties": {
        "run": { "type": "string" },
        "requested_stream": { "$ref": "#/$defs/nullableString" },
        "codec": { "const": "vp9" },
        "segment_frames": { "type": "integer", "minimum": 2, "maximum": 128 },
        "frozen_through_seq": { "type": "integer", "minimum": 0 },
        "dry_run": { "type": "boolean" },
        "candidate_images": { "type": "integer", "minimum": 0 },
        "groups_considered": { "type": "integer", "minimum": 0 },
        "segments_packed": { "type": "integer", "minimum": 0 },
        "images_packed": { "type": "integer", "minimum": 0 },
        "segments_not_beneficial": { "type": "integer", "minimum": 0 },
        "images_not_beneficial": { "type": "integer", "minimum": 0 },
        "images_skipped": { "type": "integer", "minimum": 0 },
        "segments_failed": { "type": "integer", "minimum": 0 },
        "png_distinct_bytes": { "type": "integer", "minimum": 0 },
        "temporal_candidate_bytes": { "type": "integer", "minimum": 0 },
        "published_object_bytes": { "type": "integer", "minimum": 0 },
        "result_count": { "type": "integer", "minimum": 0 },
        "results": { "type": "array", "items": { "$ref": "#/$defs/packResult" }, "maxItems": 20 }
      },
      "required": ["run", "requested_stream", "codec", "segment_frames", "frozen_through_seq", "dry_run", "candidate_images", "groups_considered", "segments_packed", "images_packed", "segments_not_beneficial", "images_not_beneficial", "images_skipped", "segments_failed", "png_distinct_bytes", "temporal_candidate_bytes", "published_object_bytes", "result_count", "results"],
      "additionalProperties": false
    },
    "pruneResult": {
      "type": "object",
      "properties": {
        "blob_sha256": { "$ref": "#/$defs/hash" },
        "byte_length": { "type": "integer", "minimum": 1 },
        "status": { "enum": ["reclaimable", "pruned", "failed"] },
        "reason": { "type": "string" }
      },
      "required": ["blob_sha256", "byte_length", "status", "reason"],
      "additionalProperties": false
    },
    "prune": {
      "type": "object",
      "properties": {
        "dry_run": { "type": "boolean" },
        "active_representation_bytes": { "type": "integer", "minimum": 0 },
        "source_retained_bytes": { "type": "integer", "minimum": 0 },
        "retired_candidate_bytes": { "type": "integer", "minimum": 0 },
        "reclaimable_bytes": { "type": "integer", "minimum": 0 },
        "reclaimed_bytes": { "type": "integer", "minimum": 0 },
        "physical_object_bytes_before": { "type": "integer", "minimum": 0 },
        "physical_object_bytes_after": { "type": "integer", "minimum": 0 },
        "candidate_objects": { "type": "integer", "minimum": 0 },
        "pruned_objects": { "type": "integer", "minimum": 0 },
        "result_count": { "type": "integer", "minimum": 0 },
        "results": { "type": "array", "items": { "$ref": "#/$defs/pruneResult" }, "maxItems": 20 }
      },
      "required": ["dry_run", "active_representation_bytes", "source_retained_bytes", "retired_candidate_bytes", "reclaimable_bytes", "reclaimed_bytes", "physical_object_bytes_before", "physical_object_bytes_after", "candidate_objects", "pruned_objects", "result_count", "results"],
      "additionalProperties": false
    },
    "migrate": {
      "type": "object",
      "properties": {
        "store_id": { "$ref": "#/$defs/uuid" },
        "from_version": { "enum": [1, 2, 3] },
        "to_version": { "enum": [1, 2, 3] },
        "migrated": { "type": "boolean" },
        "resumed": { "type": "boolean" },
        "restored": { "type": "boolean" }
      },
      "required": ["store_id", "from_version", "to_version", "migrated", "resumed", "restored"],
      "additionalProperties": false
    },
    "error": {
      "type": "object",
      "properties": {
        "code": { "type": "string", "pattern": "^E_[A-Z_]+$" },
        "message": { "type": "string" },
        "retryable": { "type": "boolean" }
      },
      "required": ["code", "message", "retryable"],
      "additionalProperties": false
    }
  }
}