@ixo/topic-protocol 0.6.0 → 0.8.0

package/README.md

@@ -9,7 +9,7 @@ identity of a discussion.
 
 ## Status
 
-**Version:** 0.6.0
+**Version:** 0.8.0
 
 **Maturity:** Draft implementation candidate  
 **Execution source of truth:** [Linear Topic Protocol project](https://linear.app/ixo-world/project/topic-protocol-4ea58bc7910d)
@@ -24,6 +24,7 @@ and external action execution require their dedicated conformance evidence.
 - [Architecture decisions](docs/adr/README.md)
 - [Why Topics matter](docs/topics-feature-guide.md) — a non-technical feature guide
 - [Extending Topic Kinds](docs/extending-topic-kinds.md) — third-party custom Kind and Kind Profile guide
+- [Decision-to-Pay templates](templates/decision-to-pay/README.md) — governed payment decision contract pack
 - [Protocol chapters](docs/protocol/README.md)
 - [Machine-readable contracts](contracts/README.md)
 - [Reference implementation](docs/reference-implementation.md)
@@ -40,7 +41,7 @@ key-value adapter at its integration boundary.
 
 The package includes:
 
-- strict Draft 2020-12 validation for all 20 contracts, including Kind Profiles and Job Cards;
+- strict Draft 2020-12 validation for all 32 contracts, including Kind Profiles, Job Cards, payment terms, payable obligations, external work, delivery, evaluation, claims, and settlement receipts;
 - pinned, declarative Kind Profiles with safe standard-Kind fallback;
 - deterministic Topic-index reconciliation, structured search, and personal ranking;
 - deterministic Topic projection from a root and authorised operations;
@@ -50,6 +51,8 @@ The package includes:
 - restart-safe two-event Topic creation with duplicate suppression;
 - append-only Matrix operation parsing and room-upgrade anchor selection;
 - explicit conflict, duplicate-delivery, unauthorised, and unreachable handling;
+- governed external-work bindings and immutable Delivery Packet handoff with separate evaluation, approval, claim, and settlement axes;
+- fail-closed settlement projection that cannot promote tracker completion into approval or payment;
 - immutable caller inputs and typed protocol errors.
 
 Topics retain a singular conversational `kind` while linking any number of
@@ -145,6 +148,7 @@ examples/             Valid reference vectors
 api/                  OpenAPI and MCP contract surfaces
 scripts/              Dependency-free validation and integrity tooling
 checksums/            Reproducible SHA-256 manifest
+templates/            Machine-readable Topic Template packs
 src/                  TypeScript contract and projection reference library
 test/                 TDD contract, behavior, and edge-case tests
 ```

package/dist/schemas/action-receipt.schema.json

@@ -3,16 +3,110 @@
     "$id": "https://topic-protocol.ixo.world/schemas/action-receipt.schema.json",
     "title": "Action receipt",
     "type": "object",
-    "required": ["receiptId", "topicId", "action", "actor", "status", "idempotencyKey", "createdAt"],
-    "properties": {
-        "receiptId": { "type": "string", "minLength": 1 },
+    "required": [],
+    "properties": {},
+    "oneOf": [{ "$ref": "#/$defs/v1" }, { "$ref": "#/$defs/v2" }],
+    "$defs": {
         "topicId": { "type": "string", "pattern": "^ixo:topic:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
-        "action": { "type": "string", "minLength": 1 },
-        "actor": { "type": "string", "minLength": 1 },
-        "status": { "type": "string", "enum": ["requested", "confirmed", "succeeded", "failed", "rejected"] },
-        "idempotencyKey": { "type": "string", "minLength": 1 },
-        "createdAt": { "type": "string", "format": "date-time" },
-        "capability": { "type": "string" }
-    },
-    "additionalProperties": true
+        "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+        "reference": {
+            "type": "object",
+            "required": ["digest"],
+            "properties": {
+                "digest": { "$ref": "#/$defs/digest" },
+                "ref": { "type": "string", "minLength": 1 },
+                "summary": { "type": "object", "maxProperties": 20 }
+            },
+            "additionalProperties": false
+        },
+        "v1": {
+            "type": "object",
+            "required": ["receiptId", "topicId", "action", "actor", "status", "idempotencyKey", "createdAt"],
+            "properties": {
+                "receiptId": { "type": "string", "minLength": 1 },
+                "topicId": { "$ref": "#/$defs/topicId" },
+                "action": { "type": "string", "minLength": 1 },
+                "actor": { "type": "string", "minLength": 1 },
+                "status": { "enum": ["requested", "confirmed", "succeeded", "failed", "rejected"] },
+                "idempotencyKey": { "type": "string", "minLength": 1 },
+                "createdAt": { "type": "string", "format": "date-time" },
+                "capability": { "type": "string" }
+            },
+            "additionalProperties": true
+        },
+        "v2": {
+            "type": "object",
+            "required": ["version", "receiptId", "sequence", "requestId", "topicId", "topicRevision", "action", "runtime", "actorDid", "executorDid", "status", "idempotencyKey", "occurredAt", "authorization", "input", "issuerDid", "signature"],
+            "properties": {
+                "version": { "const": 2 },
+                "receiptId": { "type": "string", "minLength": 1 },
+                "sequence": { "type": "integer", "minimum": 1 },
+                "requestId": { "type": "string", "minLength": 1 },
+                "topicId": { "$ref": "#/$defs/topicId" },
+                "topicRevision": { "type": "string", "minLength": 1 },
+                "action": {
+                    "type": "object",
+                    "required": ["type", "can", "registryVersion", "contractDigest"],
+                    "properties": {
+                        "type": { "type": "string", "pattern": "^qi/" },
+                        "can": { "type": "string", "minLength": 3 },
+                        "registryVersion": { "type": "string", "minLength": 1 },
+                        "contractDigest": { "$ref": "#/$defs/digest" }
+                    },
+                    "additionalProperties": false
+                },
+                "runtime": {
+                    "type": "object",
+                    "required": ["provider", "executionId"],
+                    "properties": {
+                        "provider": { "enum": ["qi-flow", "qiforge", "mcp"] },
+                        "bindingId": { "type": "string", "minLength": 1 },
+                        "flowUri": { "type": "string", "minLength": 1 },
+                        "sessionRunId": { "type": "string", "minLength": 1 },
+                        "nodeId": { "type": "string", "minLength": 1 },
+                        "executionId": { "type": "string", "minLength": 1 }
+                    },
+                    "additionalProperties": false
+                },
+                "actorDid": { "type": "string", "pattern": "^did:" },
+                "executorDid": { "type": "string", "pattern": "^did:" },
+                "status": { "enum": ["requested", "awaiting_confirmation", "running", "succeeded", "failed", "rejected", "cancelled", "needs_verification"] },
+                "idempotencyKey": { "type": "string", "minLength": 1 },
+                "occurredAt": { "type": "string", "format": "date-time" },
+                "authorization": {
+                    "type": "object",
+                    "required": ["capability"],
+                    "properties": {
+                        "capability": { "type": "string", "minLength": 1 },
+                        "invocation": { "type": "string", "minLength": 1 },
+                        "confirmation": { "type": "string", "minLength": 1 }
+                    },
+                    "additionalProperties": false
+                },
+                "input": { "$ref": "#/$defs/reference" },
+                "output": { "$ref": "#/$defs/reference" },
+                "proof": {
+                    "type": "object",
+                    "required": ["kind", "digest"],
+                    "properties": {
+                        "kind": { "enum": ["fields", "custom", "host-receipt"] },
+                        "digest": { "$ref": "#/$defs/digest" },
+                        "refs": { "type": "array", "uniqueItems": true, "maxItems": 50, "items": { "type": "string", "minLength": 1 } }
+                    },
+                    "additionalProperties": false
+                },
+                "evidenceRefs": { "type": "array", "uniqueItems": true, "maxItems": 100, "items": { "type": "string", "minLength": 1 } },
+                "traceRef": { "type": "string", "minLength": 1 },
+                "error": {
+                    "type": "object",
+                    "required": ["message"],
+                    "properties": { "code": { "type": "string", "maxLength": 80 }, "message": { "type": "string", "maxLength": 2000 } },
+                    "additionalProperties": false
+                },
+                "issuerDid": { "type": "string", "pattern": "^did:" },
+                "signature": { "type": "string", "minLength": 1 }
+            },
+            "additionalProperties": false
+        }
+    }
 }

package/dist/schemas/approval-decision.schema.json

@@ -0,0 +1,30 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/approval-decision.schema.json",
+    "title": "Outcome approval decision v1",
+    "type": "object",
+    "required": ["version", "approvalId", "topicId", "deliveryPacketId", "deliveryPacketDigest", "evaluationIds", "decision", "policy", "decidedBy", "decidedAt", "capability", "digest"],
+    "properties": {
+        "version": { "const": 1 },
+        "approvalId": { "$ref": "#/$defs/uuidV7" },
+        "topicId": { "$ref": "#/$defs/topicId" },
+        "deliveryPacketId": { "$ref": "#/$defs/uuidV7" },
+        "deliveryPacketDigest": { "$ref": "#/$defs/digest" },
+        "evaluationIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/uuidV7" } },
+        "decision": { "enum": ["approved", "rejected", "changes_requested", "superseded"] },
+        "reasons": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1, "maxLength": 2000 } },
+        "policy": { "type": "object", "required": ["ref", "version", "digest"], "properties": { "ref": { "type": "string", "format": "uri" }, "version": { "type": "string", "minLength": 1 }, "digest": { "$ref": "#/$defs/digest" } }, "additionalProperties": false },
+        "decidedBy": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "pattern": "^did:[a-z0-9]+:.+" } },
+        "decidedAt": { "type": "string", "format": "date-time" },
+        "capability": { "type": "string", "minLength": 1 },
+        "digest": { "$ref": "#/$defs/digest" },
+        "extensions": { "type": "object" }
+    },
+    "$defs": {
+        "uuidV7": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+        "topicId": { "type": "string", "pattern": "^ixo:topic:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+        "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+    },
+    "additionalProperties": false,
+    "allOf": [{ "if": { "properties": { "decision": { "enum": ["rejected", "changes_requested"] } }, "required": ["decision"] }, "then": { "properties": { "reasons": { "type": "array", "minItems": 1 } }, "required": ["reasons"] } }]
+}

package/dist/schemas/claim-record.schema.json

@@ -0,0 +1,30 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/claim-record.schema.json",
+    "title": "Outcome claim record v1",
+    "type": "object",
+    "required": ["version", "claimId", "topicId", "deliveryPacketId", "deliveryPacketDigest", "evaluationIds", "approvalId", "claimantDid", "requested", "status", "replayKey", "source", "recordedAt", "digest"],
+    "properties": {
+        "version": { "const": 1 },
+        "claimId": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "topicId": { "$ref": "#/$defs/topicId" },
+        "deliveryPacketId": { "$ref": "#/$defs/uuidV7" },
+        "deliveryPacketDigest": { "$ref": "#/$defs/digest" },
+        "evaluationIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/uuidV7" } },
+        "approvalId": { "$ref": "#/$defs/uuidV7" },
+        "claimantDid": { "type": "string", "pattern": "^did:[a-z0-9]+:.+" },
+        "requested": { "type": "object", "required": ["amount", "asset", "recipient"], "properties": { "amount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$" }, "asset": { "type": "string", "minLength": 1, "maxLength": 128 }, "recipient": { "type": "string", "minLength": 1, "maxLength": 256 } }, "additionalProperties": false },
+        "status": { "enum": ["pending", "approved", "rejected", "disputed", "invalidated", "flagged"] },
+        "replayKey": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "source": { "type": "object", "required": ["provider", "ref"], "properties": { "provider": { "type": "string", "pattern": "^[a-z][a-z0-9.-]{0,63}$" }, "ref": { "type": "string", "minLength": 1 } }, "additionalProperties": false },
+        "recordedAt": { "type": "string", "format": "date-time" },
+        "digest": { "$ref": "#/$defs/digest" },
+        "extensions": { "type": "object" }
+    },
+    "$defs": {
+        "uuidV7": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+        "topicId": { "type": "string", "pattern": "^ixo:topic:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+        "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+    },
+    "additionalProperties": false
+}

package/dist/schemas/decision-to-pay-template.schema.json

@@ -0,0 +1,346 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/decision-to-pay-template.schema.json",
+    "title": "IXO Decision-to-Pay Topic Template manifest v1",
+    "type": "object",
+    "required": [
+        "$schema",
+        "version",
+        "id",
+        "templateVersion",
+        "label",
+        "description",
+        "maturity",
+        "compatibility",
+        "topic",
+        "actors",
+        "resources",
+        "protocolContracts",
+        "operations",
+        "gates",
+        "settlement",
+        "privacy",
+        "acceptanceCriteria"
+    ],
+    "properties": {
+        "$schema": { "type": "string", "minLength": 1 },
+        "version": { "const": 1 },
+        "id": { "type": "string", "pattern": "^urn:ixo:decision-to-pay:template:[a-z0-9-]+$" },
+        "templateVersion": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+        "label": { "type": "string", "minLength": 1, "maxLength": 120 },
+        "description": { "type": "string", "minLength": 1, "maxLength": 1000 },
+        "maturity": { "enum": ["draft", "incubating", "candidate", "stable"] },
+        "compatibility": { "$ref": "#/$defs/compatibility" },
+        "topic": { "$ref": "#/$defs/topic" },
+        "topology": { "$ref": "#/$defs/topology" },
+        "actors": {
+            "type": "array",
+            "minItems": 2,
+            "items": { "$ref": "#/$defs/actor" }
+        },
+        "resources": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "$ref": "#/$defs/resource" }
+        },
+        "protocolContracts": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "$ref": "#/$defs/protocolContract" }
+        },
+        "operations": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "$ref": "#/$defs/topicOperation" }
+        },
+        "gates": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "$ref": "#/$defs/gate" }
+        },
+        "settlement": { "$ref": "#/$defs/settlement" },
+        "privacy": { "$ref": "#/$defs/privacy" },
+        "acceptanceCriteria": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "$ref": "#/$defs/acceptanceCriterion" }
+        },
+        "extensions": { "type": "object" }
+    },
+    "additionalProperties": false,
+    "$defs": {
+        "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+        "did": { "type": "string", "pattern": "^did:[a-z0-9]+:.+" },
+        "jsonPointer": { "type": "string", "pattern": "^/" },
+        "compatibility": {
+            "type": "object",
+            "required": ["protocolPackage", "protocolVersion", "sourceCommit", "implementationStatus", "requiredExtensions"],
+            "properties": {
+                "protocolPackage": { "const": "@ixo/topic-protocol" },
+                "protocolVersion": { "const": "0.7.0" },
+                "sourceCommit": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+                "implementationStatus": {
+                    "enum": ["draft_contract_extension", "design_ready", "design_ready_extension_required", "implemented"]
+                },
+                "requiredExtensions": {
+                    "type": "array",
+                    "uniqueItems": true,
+                    "items": { "type": "string", "minLength": 1 }
+                },
+                "constraints": {
+                    "type": "array",
+                    "items": { "type": "string", "minLength": 1 }
+                }
+            },
+            "additionalProperties": false
+        },
+        "persistedKind": {
+            "enum": ["task", "agent_task", "proposal", "evaluation", "claims", "question", "discussion", "incident"]
+        },
+        "recipe": {
+            "enum": ["project", "flow", "proposal", "evaluation", "claims", "research", "discussion", "incident"]
+        },
+        "kindRef": {
+            "oneOf": [
+                {
+                    "type": "object",
+                    "required": ["source", "kind"],
+                    "properties": {
+                        "source": { "const": "standard" },
+                        "kind": { "$ref": "#/$defs/persistedKind" }
+                    },
+                    "additionalProperties": false
+                },
+                {
+                    "type": "object",
+                    "required": ["source", "customId", "label", "baseKind"],
+                    "properties": {
+                        "source": { "const": "custom" },
+                        "customId": { "type": "string", "pattern": "^[a-z][a-z0-9.-]+$" },
+                        "label": { "type": "string", "minLength": 1, "maxLength": 80 },
+                        "baseKind": { "$ref": "#/$defs/persistedKind" }
+                    },
+                    "additionalProperties": false
+                }
+            ]
+        },
+        "kindProfile": {
+            "type": "object",
+            "required": ["id", "version", "schema", "digest"],
+            "properties": {
+                "id": { "type": "string", "format": "uri" },
+                "version": { "type": "string", "minLength": 1 },
+                "schema": { "type": "string", "format": "uri" },
+                "digest": { "$ref": "#/$defs/digest" }
+            },
+            "additionalProperties": false
+        },
+        "topic": {
+            "type": "object",
+            "required": ["primaryRole", "kindRef", "recipe", "workingMode", "temporalMode", "acceptance", "lifecyclePolicy"],
+            "properties": {
+                "primaryRole": { "enum": ["work_case", "delivery_case", "payable_milestone", "payment_claim"] },
+                "kindRef": { "$ref": "#/$defs/kindRef" },
+                "kindProfile": { "$ref": "#/$defs/kindProfile" },
+                "recipe": { "$ref": "#/$defs/recipe" },
+                "workingMode": { "enum": ["solo", "team", "client"] },
+                "temporalMode": { "enum": ["finite", "ongoing"] },
+                "acceptance": {
+                    "type": "object",
+                    "required": ["requiredTopicContractPaths", "allowHonestDraft"],
+                    "properties": {
+                        "requiredTopicContractPaths": {
+                            "type": "array",
+                            "uniqueItems": true,
+                            "items": { "$ref": "#/$defs/jsonPointer" }
+                        },
+                        "allowHonestDraft": { "const": true }
+                    },
+                    "additionalProperties": false
+                },
+                "lifecyclePolicy": {
+                    "type": "object",
+                    "required": ["separateTopicContractOutcomeAxes", "resolveRule"],
+                    "properties": {
+                        "separateTopicContractOutcomeAxes": { "const": true },
+                        "resolveRule": { "type": "string", "minLength": 1 },
+                        "waitingRule": { "type": "string", "minLength": 1 }
+                    },
+                    "additionalProperties": false
+                }
+            },
+            "additionalProperties": false
+        },
+        "topology": {
+            "type": "object",
+            "required": ["requiresParentTopic", "onePayableUnitPerTopic"],
+            "properties": {
+                "requiresParentTopic": { "type": "boolean" },
+                "parentBaseKind": { "$ref": "#/$defs/persistedKind" },
+                "relation": { "enum": ["branches_from", "merged_into", "redirects_to", "references", "produced"] },
+                "onePayableUnitPerTopic": { "type": "boolean" }
+            },
+            "additionalProperties": false
+        },
+        "actor": {
+            "type": "object",
+            "required": ["role", "label", "required", "identity", "capabilities"],
+            "properties": {
+                "role": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" },
+                "label": { "type": "string", "minLength": 1 },
+                "required": { "type": "boolean" },
+                "identity": { "const": "did" },
+                "capabilities": {
+                    "type": "array",
+                    "uniqueItems": true,
+                    "items": { "type": "string", "minLength": 1 }
+                },
+                "constraints": {
+                    "type": "array",
+                    "items": { "type": "string", "minLength": 1 }
+                }
+            },
+            "additionalProperties": false
+        },
+        "resource": {
+            "type": "object",
+            "required": ["role", "type", "required", "binding", "authority", "availability", "confidentiality"],
+            "properties": {
+                "role": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" },
+                "type": { "type": "string", "minLength": 1 },
+                "required": { "type": "boolean" },
+                "binding": { "enum": ["kind_resource", "typed_context", "vfs_attachment", "protocol_record", "external_reference"] },
+                "authority": { "enum": ["topic_contract", "bound_resource", "external_system", "protocol_record"] },
+                "availability": { "enum": ["topic_protocol_0.7", "contract_pack", "proposed_extension", "external"] },
+                "schemaRef": { "type": "string", "format": "uri-reference" },
+                "confidentiality": { "enum": ["room_encrypted", "vfs_ucan", "external_authority", "public"] },
+                "notes": { "type": "string", "minLength": 1 }
+            },
+            "additionalProperties": false
+        },
+        "protocolContract": {
+            "type": "object",
+            "required": ["name", "source", "schemaRef"],
+            "properties": {
+                "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+                "source": { "enum": ["topic_protocol", "contract_pack", "proposed_extension"] },
+                "schemaRef": { "type": "string", "format": "uri-reference" },
+                "required": { "type": "boolean" }
+            },
+            "additionalProperties": false
+        },
+        "topicOperation": {
+            "enum": [
+                "propose-contract",
+                "update-contract",
+                "accept-contract",
+                "supersede-contract",
+                "bind-external-work",
+                "sync-external-work",
+                "unlink-external-work",
+                "submit-delivery",
+                "record-delivery-decision",
+                "record-evaluation",
+                "record-approval",
+                "record-claim",
+                "record-settlement",
+                "record-decision",
+                "change-status",
+                "redirect",
+                "branch",
+                "merge",
+                "resolve-conflict"
+            ]
+        },
+        "gateCondition": {
+            "type": "object",
+            "required": ["contract", "path", "operator"],
+            "properties": {
+                "contract": {
+                    "enum": [
+                        "topic-contract-state",
+                        "payment-terms",
+                        "payable-obligation",
+                        "external-work-binding",
+                        "delivery-packet",
+                        "delivery-decision",
+                        "evaluation-assertion",
+                        "approval-decision",
+                        "claim-record",
+                        "settlement-receipt",
+                        "operator-verification"
+                    ]
+                },
+                "path": { "$ref": "#/$defs/jsonPointer" },
+                "operator": { "enum": ["exists", "equals", "min_count", "all_equal", "digest_matches"] },
+                "value": {}
+            },
+            "additionalProperties": false
+        },
+        "gate": {
+            "type": "object",
+            "required": ["id", "stage", "description", "all", "onFailure"],
+            "properties": {
+                "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+                "stage": { "enum": ["terms", "delivery", "evaluation", "approval", "claim", "settlement", "exception"] },
+                "description": { "type": "string", "minLength": 1 },
+                "all": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": { "$ref": "#/$defs/gateCondition" }
+                },
+                "onFailure": { "enum": ["block", "human_review", "return_for_changes", "open_incident"] }
+            },
+            "additionalProperties": false
+        },
+        "settlement": {
+            "type": "object",
+            "required": ["movesFunds", "requiresExternalAdapter", "failClosed", "requiredAxes", "exactMatchFields", "terminalState"],
+            "properties": {
+                "movesFunds": { "const": false },
+                "requiresExternalAdapter": { "const": true },
+                "failClosed": { "const": true },
+                "requiredAxes": {
+                    "type": "array",
+                    "minItems": 4,
+                    "uniqueItems": true,
+                    "items": { "enum": ["delivery", "evaluation", "approval", "claim", "settlement"] }
+                },
+                "exactMatchFields": {
+                    "type": "array",
+                    "minItems": 3,
+                    "uniqueItems": true,
+                    "items": { "enum": ["topicId", "deliveryPacketId", "deliveryPacketDigest", "evaluationIds", "approvalId", "claimId", "amount", "asset", "recipient"] }
+                },
+                "terminalState": { "const": "confirmed" }
+            },
+            "additionalProperties": false
+        },
+        "privacy": {
+            "type": "object",
+            "required": ["topicIsConfidentialityBoundary", "topicCapabilityGrantsVfsAccess", "sensitiveResourceStorage", "minimumRoomVisibleFields"],
+            "properties": {
+                "topicIsConfidentialityBoundary": { "const": false },
+                "topicCapabilityGrantsVfsAccess": { "const": false },
+                "sensitiveResourceStorage": { "const": "encrypted_room_or_ucan_vfs" },
+                "minimumRoomVisibleFields": {
+                    "type": "array",
+                    "uniqueItems": true,
+                    "items": { "type": "string", "minLength": 1 }
+                }
+            },
+            "additionalProperties": false
+        },
+        "acceptanceCriterion": {
+            "type": "object",
+            "required": ["id", "statement"],
+            "properties": {
+                "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+                "statement": { "type": "string", "minLength": 1 },
+                "verification": { "type": "string", "minLength": 1 }
+            },
+            "additionalProperties": false
+        }
+    }
+}

package/dist/schemas/delivery-decision.schema.json

@@ -0,0 +1,28 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/delivery-decision.schema.json",
+    "title": "Delivery handoff decision v1",
+    "type": "object",
+    "required": ["version", "decisionId", "topicId", "deliveryPacketId", "deliveryPacketDigest", "decision", "decidedBy", "decidedAt", "capability", "digest"],
+    "properties": {
+        "version": { "const": 1 },
+        "decisionId": { "$ref": "#/$defs/uuidV7" },
+        "topicId": { "$ref": "#/$defs/topicId" },
+        "deliveryPacketId": { "$ref": "#/$defs/uuidV7" },
+        "deliveryPacketDigest": { "$ref": "#/$defs/digest" },
+        "decision": { "enum": ["accepted", "returned", "rejected"] },
+        "reasons": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1, "maxLength": 2000 } },
+        "decidedBy": { "type": "string", "pattern": "^did:[a-z0-9]+:.+" },
+        "decidedAt": { "type": "string", "format": "date-time" },
+        "capability": { "type": "string", "minLength": 1 },
+        "digest": { "$ref": "#/$defs/digest" },
+        "extensions": { "type": "object" }
+    },
+    "$defs": {
+        "uuidV7": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+        "topicId": { "type": "string", "pattern": "^ixo:topic:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+        "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+    },
+    "additionalProperties": false,
+    "allOf": [{ "if": { "properties": { "decision": { "enum": ["returned", "rejected"] } }, "required": ["decision"] }, "then": { "properties": { "reasons": { "type": "array", "minItems": 1 } }, "required": ["reasons"] } }]
+}