@aikdna/kdna-core 0.17.0 → 0.19.0

package/schema/agent-host-receipt.schema.json

@@ -0,0 +1,371 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/aikdna/kdna/specs/agent-host-receipt.schema.json",
+  "title": "KDNA Agent Host Receipt",
+  "description": "Correlated Host response envelope. A matched runtime receipt proves only that the Host boundary accepted the exact Runtime Capsule value; it does not prove semantic consumption or conformance.",
+  "type": "object",
+  "required": ["protocol", "protocol_version", "request_id", "runtime_receipt", "outcome"],
+  "additionalProperties": false,
+  "properties": {
+    "protocol": {
+      "const": "kdna.agent-host"
+    },
+    "request_id": {
+      "type": "string",
+      "pattern": "^host_[0-9a-f]{24}$"
+    },
+    "runtime_receipt": {
+      "$ref": "#/$defs/runtimeReceipt"
+    },
+    "outcome": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/outcome"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "protocol_version": {
+      "const": "0.1.0"
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "runtime_receipt": {
+            "properties": {
+              "provider_execution_status": {
+                "const": "completed"
+              }
+            },
+            "required": ["provider_execution_status"]
+          }
+        },
+        "required": ["runtime_receipt"]
+      },
+      "then": {
+        "properties": {
+          "outcome": {
+            "$ref": "#/$defs/outcome"
+          }
+        }
+      },
+      "else": {
+        "properties": {
+          "outcome": {
+            "type": "null"
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "runtimeReceipt": {
+      "type": "object",
+      "required": [
+        "type",
+        "contract_version",
+        "capsule_version",
+        "capsule_digest_profile",
+        "capsule_digest_profile_version",
+        "sender_capsule_delivery_digest",
+        "host_recomputed_capsule_delivery_digest",
+        "echoed_capsule_delivery_digest",
+        "capsule_delivery_comparison",
+        "capsule_schema_validation",
+        "asset_id_correlation",
+        "provider_execution_status",
+        "usage",
+        "semantic_consumption",
+        "model_identity"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "const": "kdna.agent-host.runtime-receipt"
+        },
+        "capsule_version": {
+          "const": "0.1.0"
+        },
+        "capsule_digest_profile": {
+          "const": "kdna.canonicalization.runtime-capsule-jcs"
+        },
+        "sender_capsule_delivery_digest": {
+          "$ref": "#/$defs/sha256"
+        },
+        "host_recomputed_capsule_delivery_digest": {
+          "$ref": "#/$defs/sha256"
+        },
+        "echoed_capsule_delivery_digest": {
+          "$ref": "#/$defs/sha256"
+        },
+        "capsule_delivery_comparison": {
+          "enum": ["matched", "mismatched"]
+        },
+        "capsule_schema_validation": {
+          "const": "passed"
+        },
+        "asset_id_correlation": {
+          "const": "matched"
+        },
+        "provider_execution_status": {
+          "enum": ["completed", "not_started", "failed", "cancelled", "timed_out"]
+        },
+        "usage": {
+          "$ref": "#/$defs/observedUsage"
+        },
+        "semantic_consumption": {
+          "$ref": "#/$defs/semanticConsumption"
+        },
+        "model_identity": {
+          "$ref": "#/$defs/modelIdentity"
+        },
+        "contract_version": {
+          "const": "0.1.0"
+        },
+        "capsule_digest_profile_version": {
+          "const": "0.1.0"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "capsule_delivery_comparison": {
+                "const": "matched"
+              }
+            },
+            "required": ["capsule_delivery_comparison"]
+          },
+          "then": {
+            "properties": {
+              "provider_execution_status": {
+                "enum": ["completed", "failed", "cancelled", "timed_out"]
+              }
+            }
+          },
+          "else": {
+            "properties": {
+              "provider_execution_status": {
+                "const": "not_started"
+              },
+              "usage": {
+                "properties": {
+                  "tokens_used": {
+                    "type": "null"
+                  },
+                  "model_calls": {
+                    "type": "null"
+                  },
+                  "basis": {
+                    "const": "not_observed"
+                  }
+                }
+              },
+              "model_identity": {
+                "properties": {
+                  "value": {
+                    "type": "null"
+                  },
+                  "basis": {
+                    "const": "not_observed"
+                  }
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "semanticConsumption": {
+      "type": "object",
+      "required": ["state", "basis"],
+      "additionalProperties": false,
+      "properties": {
+        "state": {
+          "const": "not_observed"
+        },
+        "basis": {
+          "type": "null"
+        }
+      }
+    },
+    "observedUsage": {
+      "type": "object",
+      "required": ["elapsed_ms", "elapsed_basis", "tokens_used", "model_calls", "basis"],
+      "additionalProperties": false,
+      "properties": {
+        "elapsed_ms": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "elapsed_basis": {
+          "const": "host_monotonic"
+        },
+        "tokens_used": {
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "model_calls": {
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "basis": {
+          "enum": ["host_reported", "not_observed"]
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "basis": {
+                "const": "host_reported"
+              }
+            },
+            "required": ["basis"]
+          },
+          "then": {
+            "properties": {
+              "tokens_used": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "model_calls": {
+                "type": "integer",
+                "minimum": 0
+              }
+            }
+          },
+          "else": {
+            "properties": {
+              "tokens_used": {
+                "type": "null"
+              },
+              "model_calls": {
+                "type": "null"
+              }
+            }
+          }
+        }
+      ]
+    },
+    "modelIdentity": {
+      "type": "object",
+      "required": ["value", "basis"],
+      "additionalProperties": false,
+      "properties": {
+        "value": {
+          "type": ["string", "null"],
+          "minLength": 1
+        },
+        "basis": {
+          "enum": ["host_reported", "not_observed"]
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "basis": {
+                "const": "host_reported"
+              }
+            },
+            "required": ["basis"]
+          },
+          "then": {
+            "properties": {
+              "value": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "else": {
+            "properties": {
+              "value": {
+                "type": "null"
+              }
+            }
+          }
+        }
+      ]
+    },
+    "outcome": {
+      "type": "object",
+      "required": ["judgment", "usage"],
+      "additionalProperties": false,
+      "properties": {
+        "judgment": {
+          "$ref": "#/$defs/judgment"
+        },
+        "usage": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/usage"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "judgment": {
+      "type": "object",
+      "required": ["answer", "reasoning", "confidence"],
+      "additionalProperties": false,
+      "properties": {
+        "answer": {
+          "type": "string",
+          "minLength": 1
+        },
+        "reasoning": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "confidence": {
+          "type": ["string", "null"],
+          "minLength": 1
+        }
+      }
+    },
+    "usage": {
+      "type": "object",
+      "required": ["tokens_used", "model_calls"],
+      "additionalProperties": false,
+      "properties": {
+        "tokens_used": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "model_calls": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    }
+  }
+}

package/schema/agent-host-request.schema.json

@@ -0,0 +1,223 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/aikdna/kdna/specs/agent-host-request.schema.json",
+  "title": "KDNA Agent Host Request",
+  "description": "Agent Host request carrying one exact Runtime Capsule, plan correlation, detached delivery digest P, projection/result contracts, and enforceable limits.",
+  "type": "object",
+  "required": [
+    "protocol",
+    "protocol_version",
+    "request_id",
+    "plan_ref",
+    "runtime_contract",
+    "projection_contract",
+    "result_contract",
+    "budget",
+    "constraints",
+    "phase",
+    "task",
+    "authority",
+    "asset",
+    "capsule"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "protocol": {
+      "const": "kdna.agent-host"
+    },
+    "request_id": {
+      "type": "string",
+      "pattern": "^host_[0-9a-f]{24}$"
+    },
+    "plan_ref": {
+      "$ref": "#/$defs/planRef"
+    },
+    "runtime_contract": {
+      "$ref": "#/$defs/runtimeContract"
+    },
+    "projection_contract": {
+      "$ref": "#/$defs/projectionContract"
+    },
+    "result_contract": {
+      "$ref": "#/$defs/resultContract"
+    },
+    "budget": {
+      "$ref": "#/$defs/budget"
+    },
+    "constraints": {
+      "$ref": "#/$defs/constraints"
+    },
+    "phase": {
+      "const": "single_judgment"
+    },
+    "task": {
+      "$ref": "#/$defs/task"
+    },
+    "authority": {
+      "$ref": "#/$defs/authority"
+    },
+    "asset": {
+      "$ref": "#/$defs/asset"
+    },
+    "capsule": {
+      "$ref": "https://github.com/aikdna/kdna/specs/runtime-capsule.schema.json"
+    },
+    "protocol_version": {
+      "const": "0.1.0"
+    }
+  },
+  "$defs": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "assetId": {
+      "type": "string",
+      "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*(:[a-zA-Z0-9_.-]+)+$"
+    },
+    "semver": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+([+-].+)?$"
+    },
+    "planRef": {
+      "type": "object",
+      "required": ["plan_id", "plan_digest_profile", "plan_digest_profile_version", "plan_digest"],
+      "additionalProperties": false,
+      "properties": {
+        "plan_id": {
+          "type": "string",
+          "pattern": "^plan_[0-9a-f]{16}$"
+        },
+        "plan_digest_profile": {
+          "const": "kdna.canonicalization.consumption-plan-jcs"
+        },
+        "plan_digest": {
+          "$ref": "#/$defs/sha256"
+        },
+        "plan_digest_profile_version": {
+          "const": "0.1.0"
+        }
+      }
+    },
+    "runtimeContract": {
+      "type": "object",
+      "required": [
+        "capsule_version",
+        "capsule_digest_profile",
+        "capsule_digest_profile_version",
+        "capsule_delivery_digest"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "capsule_version": {
+          "const": "0.1.0"
+        },
+        "capsule_digest_profile": {
+          "const": "kdna.canonicalization.runtime-capsule-jcs"
+        },
+        "capsule_delivery_digest": {
+          "$ref": "#/$defs/sha256"
+        },
+        "capsule_digest_profile_version": {
+          "const": "0.1.0"
+        }
+      }
+    },
+    "projectionContract": {
+      "type": "object",
+      "required": [
+        "profile",
+        "required_digest_profile",
+        "required_digest_profile_version",
+        "require_packaged_asset"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "profile": {
+          "enum": ["index", "compact", "scenario", "full"]
+        },
+        "required_digest_profile": {
+          "const": "kdna.digest-evidence"
+        },
+        "require_packaged_asset": {
+          "const": true
+        },
+        "required_digest_profile_version": {
+          "const": "0.1.0"
+        }
+      }
+    },
+    "resultContract": {
+      "type": "object",
+      "required": ["shape"],
+      "additionalProperties": false,
+      "properties": {
+        "shape": {
+          "const": "structured_judgment"
+        }
+      }
+    },
+    "budget": {
+      "$ref": "https://github.com/aikdna/kdna/specs/consumption-plan.schema.json#/$defs/budget"
+    },
+    "constraints": {
+      "$ref": "https://github.com/aikdna/kdna/specs/consumption-plan.schema.json#/$defs/constraints"
+    },
+    "task": {
+      "$ref": "https://github.com/aikdna/kdna/specs/consumption-plan.schema.json#/$defs/task"
+    },
+    "authority": {
+      "type": "object",
+      "required": ["asset_id", "role", "final_decision"],
+      "additionalProperties": false,
+      "properties": {
+        "asset_id": {
+          "$ref": "#/$defs/assetId"
+        },
+        "role": {
+          "const": "primary"
+        },
+        "final_decision": {
+          "const": true
+        }
+      }
+    },
+    "asset": {
+      "type": "object",
+      "required": [
+        "asset_id",
+        "asset_uid",
+        "version",
+        "judgment_version",
+        "access",
+        "role",
+        "expected_digests"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "asset_id": {
+          "$ref": "#/$defs/assetId"
+        },
+        "asset_uid": {
+          "type": "string",
+          "format": "uri"
+        },
+        "version": {
+          "$ref": "#/$defs/semver"
+        },
+        "judgment_version": {
+          "$ref": "#/$defs/semver"
+        },
+        "access": {
+          "enum": ["public", "licensed", "remote"]
+        },
+        "role": {
+          "const": "primary"
+        },
+        "expected_digests": {
+          "$ref": "https://github.com/aikdna/kdna/specs/consumption-plan.schema.json#/$defs/expectedDigests"
+        }
+      }
+    }
+  }
+}

package/schema/{bundle-profile-v1.schema.json → bundle-profile.schema.json}

@@ -1,16 +1,20 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/aikdna/kdna/schema/bundle-profile-v1.schema.json",
-  "title": "Bundle Profile v1",
+  "$id": "https://github.com/aikdna/kdna/schema/bundle-profile.schema.json",
+  "title": "KDNA Bundle Payload Profile",
   "description": "Schema for the payload entry of a KDNA bundle container.",
   "type": "object",
-  "required": ["profile", "components"],
+  "required": ["profile", "profile_version", "components"],
   "additionalProperties": true,
   "properties": {
     "profile": {
       "type": "string",
-      "const": "bundle-profile-v1",
-      "description": "Profile identifier. Must be the literal string 'bundle-profile-v1'."
+      "const": "kdna.payload.bundle",
+      "description": "Profile identifier. Must be the literal string 'kdna.payload.bundle'."
+    },
+    "profile_version": {
+      "const": "0.1.0",
+      "description": "Compatibility coordinate for the bundle payload profile."
     },
     "components": {
       "type": "array",

package/schema/checksums.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/aikdna/kdna/schema/checksums.schema.json",
-  "title": "KDNA Checksums v1",
+  "title": "KDNA Checksums",
   "description": "Per-entry digests for a .kdna container. Stored as checksums.json at the container root.",
   "type": "object",
   "required": ["algorithm"],
@@ -16,7 +16,46 @@
       "pattern": "^[a-f0-9]{64}$"
     }
   },
+  "allOf": [
+    {
+      "if": {
+        "anyOf": [
+          { "required": ["digest_profile"] },
+          { "required": ["covered_entries"] }
+        ]
+      },
+      "then": {
+        "required": [
+          "digest_profile",
+          "digest_profile_version",
+          "covered_entries",
+          "manifest_digest",
+          "payload_digest",
+          "entry_set_digest"
+        ]
+      }
+    }
+  ],
   "properties": {
+    "digest_profile": {
+      "const": "kdna.digest-basis.runtime-entry-set",
+      "description": "Algorithm and coverage profile for entry_set_digest."
+    },
+    "digest_profile_version": {
+      "const": "0.1.0",
+      "description": "Compatibility coordinate for the entry-set digest basis."
+    },
+    "covered_entries": {
+      "type": "array",
+      "description": "Ordered entries covered by kdna.digest-basis.runtime-entry-set.",
+      "prefixItems": [
+        { "const": "kdna.json" },
+        { "const": "payload.kdnab" }
+      ],
+      "items": false,
+      "minItems": 2,
+      "maxItems": 2
+    },
     "algorithm": {
       "type": "string",
       "description": "Hash algorithm. Phase 1 uses sha256.",
@@ -30,8 +69,8 @@
       "description": "Digest of the payload.kdnab entry.",
       "$ref": "#/$defs/sha256Digest"
     },
-    "asset_digest": {
-      "description": "Digest of the whole container (per-entry digests combined deterministically).",
+    "entry_set_digest": {
+      "description": "Digest of the protected runtime entry set, combined deterministically from kdna.json and payload.kdnab entry digests.",
       "$ref": "#/$defs/sha256Digest"
     },
     "entries": {