@citeark/agent 0.3.20

package/schemas/execution-contract.schema.json

@@ -0,0 +1,1024 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://citeark.com/schemas/agent/execution-contract-1.0.json",
+  "title": "CiteArk blind execution contract",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "kind",
+    "name",
+    "research",
+    "paper",
+    "repository",
+    "claim",
+    "measurements",
+    "protocol",
+    "reproductionLevel",
+    "contractDigest"
+  ],
+  "properties": {
+    "reproductionScope": {
+      "enum": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "description": "Requested verification work scope; not scientific support, fidelity or budget."
+    },
+    "researchGraph": {
+      "type": "object",
+      "required": [
+        "objects",
+        "steps",
+        "inputIds"
+      ],
+      "description": "Fixed scientific object/step context; prospective specifications are not execution evidence.",
+      "properties": {
+        "objects": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "role",
+              "title"
+            ]
+          }
+        },
+        "steps": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "title",
+              "kind",
+              "inputIds",
+              "outputIds"
+            ]
+          }
+        },
+        "inputIds": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "schemaVersion": {
+      "const": "1.0"
+    },
+    "kind": {
+      "const": "citeark.execution-contract"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "research": {
+      "type": "object",
+      "required": [
+        "workId",
+        "claimId",
+        "claimVersionId",
+        "experimentId",
+        "experimentVersionId",
+        "measurementIds"
+      ],
+      "properties": {
+        "workId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "claimId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "claimVersionId": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "experimentId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "experimentVersionId": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "measurementIds": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "claimMeasurementIds": {
+          "description": "All paper-side measurement ids belonging to the claim, including measurements not covered by this execution.",
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "claimCoverage": {
+          "description": "Whether this execution covers every paper-side measurement in the claim or only a disclosed subset.",
+          "enum": [
+            "complete",
+            "partial"
+          ]
+        },
+        "uncoveredMeasurementIds": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "paper": {
+      "type": "object",
+      "required": [
+        "title",
+        "url"
+      ],
+      "properties": {
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "repository": {
+      "type": "object",
+      "required": [
+        "url",
+        "commit"
+      ],
+      "properties": {
+        "implementationOrigin": {
+          "enum": [
+            "official",
+            "citeark_reconstruction"
+          ]
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1
+        },
+        "commit": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "claim": {
+      "type": "object",
+      "required": [
+        "text",
+        "source"
+      ],
+      "properties": {
+        "text": {
+          "type": "string",
+          "minLength": 1
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "workspacePlan": {
+      "description": "Enables a revisable research workspace. Original claim goals and resource limits remain attached to this contract; execution records identify the actual plan revision.",
+      "type": "object",
+      "required": [
+        "version",
+        "measurements"
+      ],
+      "properties": {
+        "version": {
+          "enum": [
+            1,
+            2
+          ]
+        },
+        "sourceInventory": {
+          "description": "Source context for interpretation, including qualitative findings and ambiguities. It is not observed evidence and does not extend assigned execution scope.",
+          "type": "object",
+          "required": [
+            "digest",
+            "view",
+            "sources",
+            "claims"
+          ],
+          "properties": {
+            "digest": {
+              "type": "string",
+              "pattern": "^sha256:[0-9a-f]{64}$"
+            },
+            "view": {
+              "const": "source-context"
+            },
+            "sources": {
+              "type": "array"
+            },
+            "claims": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": [
+                  "id",
+                  "reportedMeasurements"
+                ],
+                "properties": {
+                  "reportedMeasurements": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "not": {
+                        "anyOf": [
+                          {
+                            "required": [
+                              "value"
+                            ]
+                          },
+                          {
+                            "required": [
+                              "reportedValue"
+                            ]
+                          },
+                          {
+                            "required": [
+                              "verificationTolerance"
+                            ]
+                          }
+                        ]
+                      }
+                    }
+                  },
+                  "id": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                }
+              }
+            }
+          }
+        },
+        "measurements": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": [
+              "measurementId",
+              "metric",
+              "unit"
+            ],
+            "not": {
+              "anyOf": [
+                {
+                  "required": [
+                    "reportedValue"
+                  ]
+                },
+                {
+                  "required": [
+                    "value"
+                  ]
+                }
+              ]
+            },
+            "properties": {
+              "measurementId": {
+                "type": "string",
+                "minLength": 1
+              },
+              "metric": {
+                "type": "string",
+                "minLength": 1
+              },
+              "unit": {
+                "type": "string",
+                "minLength": 1
+              },
+              "dimensions": {
+                "type": "object"
+              },
+              "aggregation": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "measurements": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "measurementId",
+          "metric",
+          "unit",
+          "parser"
+        ],
+        "not": {
+          "required": [
+            "reportedValue"
+          ]
+        },
+        "properties": {
+          "measurementId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "metric": {
+            "type": "string",
+            "minLength": 1
+          },
+          "unit": {
+            "type": "string",
+            "minLength": 1
+          },
+          "dimensions": {
+            "description": "Blind scientific scope that the execution must preserve, such as dataset, split, model variant, seed schedule, hardware, or repetition count.",
+            "type": "object"
+          },
+          "aggregation": {
+            "description": "Blind aggregation rule required for the measurement, such as a mean over repeated seeds or tasks.",
+            "type": "string",
+            "minLength": 1
+          },
+          "parser": {
+            "type": "object",
+            "required": [
+              "id",
+              "version",
+              "evidencePath"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "version": {
+                "type": "string"
+              },
+              "evidencePath": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^(?!/)(?!\\.\\.(?:/|$))(?!.*\\/\\.\\.(?:/|$))[^\\\\]+$"
+              },
+              "config": {
+                "type": "object"
+              }
+            }
+          }
+        }
+      }
+    },
+    "protocol": {
+      "type": "object",
+      "required": [
+        "entrypoint",
+        "requiredCommandFragments"
+      ],
+      "properties": {
+        "workload": {
+          "description": "Complete scientific execution units, grouped by materially different cost or method; probes must execute full units on the allocated device.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "unit",
+            "groups"
+          ],
+          "properties": {
+            "unit": {
+              "type": "string",
+              "minLength": 1
+            },
+            "groups": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "id",
+                  "units",
+                  "description"
+                ],
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "units": {
+                    "type": "integer",
+                    "minimum": 1
+                  },
+                  "description": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                }
+              }
+            }
+          }
+        },
+        "executionMode": {
+          "enum": [
+            "agent_planned",
+            "fixed_entrypoint"
+          ]
+        },
+        "objective": {
+          "type": "string",
+          "minLength": 1
+        },
+        "entrypoint": {
+          "type": "string",
+          "minLength": 1
+        },
+        "requiredCommandFragments": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "allowedChangePaths": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "instructions": {
+          "type": "string"
+        },
+        "preflight": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "schemaVersion",
+            "source",
+            "maxMinutes",
+            "evidencePath",
+            "checks",
+            "assets"
+          ],
+          "properties": {
+            "schemaVersion": {
+              "enum": [
+                "0.1",
+                "0.2",
+                "0.3"
+              ]
+            },
+            "source": {
+              "enum": [
+                "declared",
+                "defaulted"
+              ]
+            },
+            "maxMinutes": {
+              "type": "number",
+              "minimum": 1,
+              "maximum": 240
+            },
+            "evidencePath": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^(?!/)(?!\\.\\.(?:/|$))(?!.*\\/\\.\\.(?:/|$))[^\\\\]+$"
+            },
+            "checks": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "id",
+                  "kind",
+                  "successCriterion"
+                ],
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "kind": {
+                    "enum": [
+                      "runtime",
+                      "dependencies",
+                      "dataset_loader",
+                      "assets",
+                      "entrypoint",
+                      "parser",
+                      "smoke_test",
+                      "duration"
+                    ]
+                  },
+                  "command": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "successCriterion": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                }
+              }
+            },
+            "assets": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "id",
+                  "kind",
+                  "identity",
+                  "availability",
+                  "required",
+                  "verification"
+                ],
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "kind": {
+                    "enum": [
+                      "dataset",
+                      "checkpoint",
+                      "model",
+                      "repository",
+                      "other"
+                    ]
+                  },
+                  "identity": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "availability": {
+                    "enum": [
+                      "bundled",
+                      "public_verified",
+                      "public_unverified",
+                      "private",
+                      "unknown"
+                    ]
+                  },
+                  "required": {
+                    "type": "boolean"
+                  },
+                  "verification": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "scientificRole": {
+                    "enum": [
+                      "execution_required",
+                      "identity_only",
+                      "provenance_only",
+                      "optional"
+                    ]
+                  },
+                  "acquisition": {
+                    "$ref": "#/$defs/assetAcquisition"
+                  },
+                  "sourceEvidence": {
+                    "type": "array",
+                    "items": {
+                      "$ref": "#/$defs/assetSourceEvidence"
+                    }
+                  },
+                  "sourceUrls": {
+                    "type": "array",
+                    "minItems": 1,
+                    "uniqueItems": true,
+                    "items": {
+                      "type": "string",
+                      "format": "uri",
+                      "pattern": "^https?://"
+                    }
+                  },
+                  "registryDatasetId": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                }
+              }
+            },
+            "requirements": {
+              "description": "Complete eight-row scientific material inventory. Required for newly compiled preflight 0.3 plans.",
+              "type": "array",
+              "minItems": 8,
+              "maxItems": 8,
+              "items": {
+                "$ref": "#/$defs/assetRequirement"
+              }
+            }
+          }
+        }
+      }
+    },
+    "requiredReproductionScope": {
+      "enum": [
+        "low",
+        "medium",
+        "high"
+      ]
+    },
+    "reproductionLevel": {
+      "enum": [
+        "directional",
+        "official-checkpoint",
+        "full-training",
+        "artifact-evaluation",
+        "experiment-rerun",
+        "workflow-rebuild"
+      ]
+    },
+    "reconstructionFidelity": {
+      "enum": [
+        "exact",
+        "faithful",
+        "approximate",
+        "proxy"
+      ]
+    },
+    "computeRequirement": {
+      "$ref": "#/$defs/computeRequirement"
+    },
+    "agent": {
+      "type": "object",
+      "properties": {
+        "runtime": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "model": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "subagentModel": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "autoCompactWindow": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "effort": {
+          "type": "string"
+        },
+        "reasoningMode": {
+          "enum": [
+            "standard",
+            "pro"
+          ]
+        },
+        "maxTurns": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "maxBudgetUsd": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "budgetCaps": {
+          "description": "Hard per-contract ceilings that deployment-level Agent presets cannot raise.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "maxTurns",
+            "maxBudgetUsd"
+          ],
+          "properties": {
+            "maxTurns": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "maxBudgetUsd": {
+              "type": "number",
+              "exclusiveMinimum": 0
+            }
+          }
+        },
+        "validationRetries": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "environment": {
+      "type": "object",
+      "required": [
+        "image",
+        "timeoutMinutes",
+        "cpus",
+        "memoryGb",
+        "shmGb",
+        "gpu",
+        "networkAccess"
+      ],
+      "properties": {
+        "image": {
+          "type": "string",
+          "minLength": 1
+        },
+        "timeoutMinutes": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "cpus": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "memoryGb": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "shmGb": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "gpu": {
+          "enum": [
+            "none",
+            "all"
+          ]
+        },
+        "networkAccess": {
+          "const": true
+        }
+      }
+    },
+    "contractDigest": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    }
+  },
+  "not": {
+    "required": [
+      "target"
+    ]
+  },
+  "$defs": {
+    "assetRequirement": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "required",
+        "reason",
+        "assetIds",
+        "checkIds",
+        "repository"
+      ],
+      "properties": {
+        "kind": {
+          "enum": [
+            "author_code",
+            "model",
+            "tokenizer",
+            "training_data",
+            "evaluation_data",
+            "evaluator",
+            "configuration",
+            "dependencies"
+          ]
+        },
+        "required": {
+          "type": "boolean"
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1
+        },
+        "assetIds": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "checkIds": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "repository": {
+          "type": "boolean"
+        }
+      }
+    },
+    "assetAcquisition": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "mode"
+      ],
+      "properties": {
+        "mode": {
+          "enum": [
+            "auto",
+            "metadata",
+            "selective",
+            "full",
+            "stream"
+          ]
+        },
+        "revision": {
+          "type": "string",
+          "minLength": 1
+        },
+        "requiredPaths": {
+          "type": "array",
+          "description": "Backward-compatible selective prefetch hints. Entries may describe alternative formats; an unmatched entry does not block the reproduction Agent.",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "excludedPaths": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "expectedDownloadBytes": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "expectedExpandedBytes": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "maximumDownloadBytes": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "maximumExpandedBytes": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "supportsStreaming": {
+          "type": "boolean"
+        }
+      }
+    },
+    "assetSourceEvidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "source",
+        "locator"
+      ],
+      "properties": {
+        "source": {
+          "enum": [
+            "paper",
+            "repository",
+            "dataset_registry"
+          ]
+        },
+        "locator": {
+          "type": "string",
+          "minLength": 1
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "commit": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "computeRequirement": {
+      "type": "object",
+      "required": [
+        "schemaVersion",
+        "source",
+        "classification",
+        "accelerator",
+        "cpuCores",
+        "memoryGb",
+        "gpuCount",
+        "cpuFallbackAllowed",
+        "estimatedDurationMinutes",
+        "rationale"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "0.1"
+        },
+        "source": {
+          "enum": [
+            "research-declared",
+            "research-derived"
+          ]
+        },
+        "classification": {
+          "enum": [
+            "cpu-only",
+            "gpu-optional",
+            "gpu-required"
+          ]
+        },
+        "accelerator": {
+          "enum": [
+            "none",
+            "optional",
+            "required"
+          ]
+        },
+        "cpuCores": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "memoryGb": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "gpuCount": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "minVramGb": {
+          "type": [
+            "number",
+            "null"
+          ],
+          "exclusiveMinimum": 0
+        },
+        "preferredGpuTypes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "cpuFallbackAllowed": {
+          "type": "boolean"
+        },
+        "preemptionSafe": {
+          "type": "boolean"
+        },
+        "estimatedDurationMinutes": {
+          "type": "object",
+          "properties": {
+            "cpu": {
+              "type": [
+                "number",
+                "null"
+              ],
+              "exclusiveMinimum": 0
+            },
+            "gpu": {
+              "type": [
+                "number",
+                "null"
+              ],
+              "exclusiveMinimum": 0
+            }
+          }
+        },
+        "rationale": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  }
+}