amduat-api/registry/amduatd-api-contract.v1.json

{
  "contract": "AMDUATD/API/1",
  "base_path": "/v1",
  "endpoints": [
    {"method": "GET", "path": "/v1/ui"},
    {"method": "GET", "path": "/v1/meta"},
    {"method": "HEAD", "path": "/v1/meta"},
    {"method": "GET", "path": "/v1/contract"},
    {"method": "GET", "path": "/v1/space/doctor"},
    {"method": "GET", "path": "/v1/space/roots"},
    {"method": "GET", "path": "/v1/space/manifest"},
    {"method": "PUT", "path": "/v1/space/manifest"},
    {"method": "GET", "path": "/v1/space/mounts/resolve"},
    {"method": "POST", "path": "/v1/space/mounts/sync/until"},
    {"method": "GET", "path": "/v1/space/sync/status"},
    {"method": "POST", "path": "/v1/capabilities"},
    {"method": "GET", "path": "/v1/cap/resolve"},
    {"method": "GET", "path": "/v1/fed/records"},
    {"method": "GET", "path": "/v1/fed/cursor"},
    {"method": "POST", "path": "/v1/fed/cursor"},
    {"method": "GET", "path": "/v1/fed/pull/plan"},
    {"method": "GET", "path": "/v1/fed/push/plan"},
    {"method": "POST", "path": "/v1/fed/pull"},
    {"method": "GET", "path": "/v1/fed/artifacts/{ref}"},
    {"method": "GET", "path": "/v1/fed/status"},
    {"method": "POST", "path": "/v1/fed/ingest"},
    {"method": "POST", "path": "/v1/fed/pull/until"},
    {"method": "POST", "path": "/v1/fed/push"},
    {"method": "POST", "path": "/v1/fed/push/until"},
    {"method": "POST", "path": "/v1/concepts"},
    {"method": "GET", "path": "/v1/concepts"},
    {"method": "GET", "path": "/v1/concepts/{name}"},
    {"method": "POST", "path": "/v1/concepts/{name}/publish"},
    {"method": "GET", "path": "/v1/resolve/{name}"},
    {"method": "POST", "path": "/v1/artifacts"},
    {"method": "GET", "path": "/v1/relations"},
    {"method": "GET", "path": "/v1/artifacts/{ref}"},
    {"method": "HEAD", "path": "/v1/artifacts/{ref}"},
    {"method": "GET", "path": "/v1/artifacts/{ref}?format=info"},
    {"method": "POST", "path": "/v1/pel/run"},
    {"method": "POST", "path": "/v1/pel/programs"},
    {"method": "POST", "path": "/v1/context_frames"}
  ],
  "schemas": {
    "capability_mint_request": {
      "type": "object",
      "required": ["kind", "target", "expiry_seconds"],
      "properties": {
        "kind": {"type": "string"},
        "target": {"type": "object"},
        "expiry_seconds": {"type": "integer"}
      }
    },
    "capability_mint_response": {
      "type": "object",
      "required": ["token"],
      "properties": {
        "token": {"type": "string"}
      }
    },
    "pel_run_request": {
      "type": "object",
      "required": ["program_ref", "input_refs"],
      "properties": {
        "program_ref": {"type": "string", "description": "hex ref or concept name"},
        "input_refs": {"type": "array", "items": {"type": "string", "description": "hex ref or concept name"}},
        "params_ref": {"type": "string", "description": "hex ref or concept name"},
        "scheme_ref": {"type": "string", "description": "hex ref or 'dag'"},
        "receipt": {
          "type": "object",
          "required": ["input_manifest_ref", "environment_ref", "evaluator_id", "executor_ref", "started_at", "completed_at"],
          "properties": {
            "input_manifest_ref": {"type": "string", "description": "hex ref or concept name"},
            "environment_ref": {"type": "string", "description": "hex ref or concept name"},
            "evaluator_id": {"type": "string", "description": "opaque evaluator bytes (utf-8)"},
            "executor_ref": {"type": "string", "description": "hex ref or concept name"},
            "sbom_ref": {"type": "string", "description": "hex ref or concept name"},
            "parity_digest_hex": {"type": "string", "description": "hex bytes"},
            "executor_fingerprint_ref": {"type": "string", "description": "hex ref or concept name"},
            "run_id_hex": {"type": "string", "description": "hex bytes"},
            "limits": {
              "type": "object",
              "required": ["cpu_ms", "wall_ms", "max_rss_kib", "io_reads", "io_writes"],
              "properties": {
                "cpu_ms": {"type": "integer"},
                "wall_ms": {"type": "integer"},
                "max_rss_kib": {"type": "integer"},
                "io_reads": {"type": "integer"},
                "io_writes": {"type": "integer"}
              }
            },
            "logs": {
              "type": "array",
              "items": {
                "type": "object",
                "required": ["kind", "log_ref", "sha256_hex"],
                "properties": {
                  "kind": {"type": "integer"},
                  "log_ref": {"type": "string", "description": "hex ref or concept name"},
                  "sha256_hex": {"type": "string", "description": "hex bytes"}
                }
              }
            },
            "determinism_level": {"type": "integer", "description": "0-255"},
            "rng_seed_hex": {"type": "string", "description": "hex bytes"},
            "signature_hex": {"type": "string", "description": "hex bytes"},
            "started_at": {"type": "integer"},
            "completed_at": {"type": "integer"}
          }
        }
      }
    },
    "pel_run_response": {
      "type": "object",
      "required": ["result_ref", "output_refs", "status"],
      "properties": {
        "result_ref": {"type": "string", "description": "hex ref"},
        "trace_ref": {"type": "string", "description": "hex ref"},
        "receipt_ref": {"type": "string", "description": "hex ref"},
        "output_refs": {"type": "array", "items": {"type": "string", "description": "hex ref"}},
        "status": {"type": "string"}
      }
    },
    "fed_records_response": {
      "type": "object",
      "required": ["domain_id", "snapshot_id", "log_prefix", "next_logseq", "records"],
      "properties": {
        "domain_id": {"type": "integer"},
        "snapshot_id": {"type": "integer"},
        "log_prefix": {"type": "integer"},
        "next_logseq": {"type": "integer", "description": "Paging cursor; last emitted logseq + 1, or from_logseq if no records emitted."},
        "records": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["domain_id", "type", "ref", "logseq", "snapshot_id", "log_prefix"],
            "properties": {
              "domain_id": {"type": "integer"},
              "type": {"type": "integer"},
              "ref": {"type": "string"},
              "logseq": {"type": "integer"},
              "snapshot_id": {"type": "integer"},
              "log_prefix": {"type": "integer"},
              "visibility": {"type": "integer"},
              "has_source": {"type": "boolean"},
              "source_domain": {"type": "integer"},
              "notes": {"type": "string", "description": "Type mapping: ARTIFACT_PUBLISH -> ARTIFACT, PER when type_tag=FER1_RECEIPT_1, TGK_EDGE when type_tag=TGK1_EDGE_V1; ARTIFACT_UNPUBLISH -> TOMBSTONE."}
            }
          }
        }
      }
    },
    "fed_status_response": {
      "type": "object",
      "required": ["status", "domain_id", "registry_ref", "last_tick_ms"],
      "properties": {
        "status": {"type": "string"},
        "domain_id": {"type": "integer"},
        "registry_ref": {"type": ["string", "null"]},
        "last_tick_ms": {"type": "integer"}
      }
    },
    "context_frame_request": {
      "type": "object",
      "required": ["bindings"],
      "properties": {
        "bindings": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["key"],
            "properties": {
              "key": {"type": "string", "description": "concept name or hex ref"},
              "value": {"type": "string", "description": "hex ref or concept name"},
              "value_ref": {"type": "string", "description": "hex ref or concept name"},
              "value_scalar": {
                "type": "object",
                "properties": {
                  "int": {"type": "integer"},
                  "enum": {"type": "string", "description": "concept name or hex ref"}
                }
              }
            }
          }
        }
      }
    },
    "pel_program_author_request": {
      "type": "object",
      "required": ["nodes", "roots"],
      "properties": {
        "nodes": {"type": "array"},
        "roots": {"type": "array"}
      }
    },
    "concept_create_request": {
      "type": "object",
      "required": ["name"],
      "properties": {
        "name": {"type": "string"},
        "ref": {"type": "string", "description": "hex ref"}
      }
    },
    "artifact_info_response": {
      "type": "object",
      "required": ["len", "has_type_tag", "type_tag"],
      "properties": {
        "len": {"type": "integer"},
        "has_type_tag": {"type": "boolean"},
        "type_tag": {"type": "string"}
      }
    },
    "space_manifest_mount": {
      "type": "object",
      "required": ["name", "peer_key", "space_id", "mode"],
      "properties": {
        "name": {"type": "string"},
        "peer_key": {"type": "string"},
        "space_id": {"type": "string"},
        "mode": {"type": "string"},
        "pinned_root_ref": {"type": "string"}
      }
    },
    "space_manifest": {
      "type": "object",
      "required": ["version", "mounts"],
      "properties": {
        "version": {"type": "integer"},
        "mounts": {"type": "array", "items": {"$ref": "#/schemas/space_manifest_mount"}}
      }
    },
    "space_manifest_response": {
      "type": "object",
      "required": ["effective_space", "manifest_ref", "manifest"],
      "properties": {
        "effective_space": {"type": "object"},
        "manifest_ref": {"type": "string"},
        "manifest": {"$ref": "#/schemas/space_manifest"}
      }
    },
    "space_manifest_put_response": {
      "type": "object",
      "required": ["effective_space", "manifest_ref", "updated", "manifest"],
      "properties": {
        "effective_space": {"type": "object"},
        "manifest_ref": {"type": "string"},
        "updated": {"type": "boolean"},
        "previous_ref": {"type": "string"},
        "manifest": {"$ref": "#/schemas/space_manifest"}
      }
    },
    "space_mounts_pull_cursor": {
      "type": "object",
      "required": ["present"],
      "properties": {
        "present": {"type": "boolean"},
        "last_logseq": {"type": "integer"},
        "ref": {"type": "string"}
      }
    },
    "space_mounts_local_tracking": {
      "type": "object",
      "required": ["cursor_namespace", "cursor_scope", "remote_space_id", "pull_cursor"],
      "properties": {
        "cursor_namespace": {"type": "string"},
        "cursor_scope": {"type": "string"},
        "remote_space_id": {"type": "string"},
        "pull_cursor": {"$ref": "#/schemas/space_mounts_pull_cursor"}
      }
    },
    "space_mounts_resolved_mount": {
      "type": "object",
      "required": ["name", "peer_key", "space_id", "mode", "local_tracking"],
      "properties": {
        "name": {"type": "string"},
        "peer_key": {"type": "string"},
        "space_id": {"type": "string"},
        "mode": {"type": "string"},
        "pinned_root_ref": {"type": "string"},
        "local_tracking": {"$ref": "#/schemas/space_mounts_local_tracking"}
      }
    },
    "space_mounts_resolve_response": {
      "type": "object",
      "required": ["effective_space", "manifest_ref", "mounts"],
      "properties": {
        "effective_space": {"type": "object"},
        "manifest_ref": {"type": "string"},
        "mounts": {"type": "array", "items": {"$ref": "#/schemas/space_mounts_resolved_mount"}}
      }
    },
    "space_mounts_sync_error": {
      "type": "object",
      "required": ["code", "message"],
      "properties": {
        "code": {"type": "string"},
        "message": {"type": "string"}
      }
    },
    "space_mounts_sync_cursor": {
      "type": "object",
      "properties": {
        "last_logseq": {"type": "integer"},
        "ref": {"type": "string"}
      }
    },
    "space_mounts_sync_result": {
      "type": "object",
      "required": ["name", "peer_key", "remote_space_id", "status"],
      "properties": {
        "name": {"type": "string"},
        "peer_key": {"type": "string"},
        "remote_space_id": {"type": "string"},
        "status": {"type": "string"},
        "caught_up": {"type": "boolean"},
        "rounds_executed": {"type": "integer"},
        "applied": {
          "type": "object",
          "required": ["records", "artifacts"],
          "properties": {
            "records": {"type": "integer"},
            "artifacts": {"type": "integer"}
          }
        },
        "cursor": {"$ref": "#/schemas/space_mounts_sync_cursor"},
        "error": {"$ref": "#/schemas/space_mounts_sync_error"}
      }
    },
    "space_mounts_sync_response": {
      "type": "object",
      "required": ["effective_space", "manifest_ref", "limit", "max_rounds", "max_mounts", "mounts_total", "mounts_synced", "ok", "results"],
      "properties": {
        "effective_space": {"type": "object"},
        "manifest_ref": {"type": "string"},
        "limit": {"type": "integer"},
        "max_rounds": {"type": "integer"},
        "max_mounts": {"type": "integer"},
        "mounts_total": {"type": "integer"},
        "mounts_synced": {"type": "integer"},
        "ok": {"type": "boolean"},
        "results": {"type": "array", "items": {"$ref": "#/schemas/space_mounts_sync_result"}}
      }
    },
    "space_sync_status_cursor": {
      "type": "object",
      "required": ["present"],
      "properties": {
        "present": {"type": "boolean"},
        "last_logseq": {"type": "integer"},
        "ref": {"type": "string"}
      }
    },
    "space_sync_status_remote": {
      "type": "object",
      "required": ["remote_space_id", "pull_cursor", "push_cursor"],
      "properties": {
        "remote_space_id": {"type": ["string", "null"]},
        "pull_cursor": {"$ref": "#/schemas/space_sync_status_cursor"},
        "push_cursor": {"$ref": "#/schemas/space_sync_status_cursor"}
      }
    },
    "space_sync_status_peer": {
      "type": "object",
      "required": ["peer_key", "remotes"],
      "properties": {
        "peer_key": {"type": "string"},
        "remotes": {"type": "array", "items": {"$ref": "#/schemas/space_sync_status_remote"}}
      }
    },
    "space_sync_status_response": {
      "type": "object",
      "required": ["effective_space", "store_backend", "federation", "peers"],
      "properties": {
        "effective_space": {"type": "object"},
        "store_backend": {"type": "string"},
        "federation": {
          "type": "object",
          "required": ["enabled", "transport"],
          "properties": {
            "enabled": {"type": "boolean"},
            "transport": {"type": "string"}
          }
        },
        "peers": {"type": "array", "items": {"$ref": "#/schemas/space_sync_status_peer"}}
      }
    }
  }
}