@ixo/topic-protocol 0.6.0 → 0.8.0

package/templates/decision-to-pay/verified-work-payment.template.json

@@ -0,0 +1,283 @@
+{
+  "$schema": "../../schemas/decision-to-pay-template.schema.json",
+  "version": 1,
+  "id": "urn:ixo:decision-to-pay:template:verified-work-payment",
+  "templateVersion": "0.1.0",
+  "label": "Verified Work Payment",
+  "description": "Commission work, preserve the accepted terms and evidence, review the immutable delivery handoff, and allow settlement only after evaluation, approval, and claim gates agree.",
+  "maturity": "draft",
+  "compatibility": {
+    "protocolPackage": "@ixo/topic-protocol",
+    "protocolVersion": "0.7.0",
+    "sourceCommit": "40d1ce5160757553cd57f670b5b1708a5c0d0ea3",
+    "implementationStatus": "draft_contract_extension",
+    "requiredExtensions": [
+      "org.ixo.payment-terms/v1",
+      "org.ixo.payable-obligation/v1",
+      "ixo.payment capability policy/v1",
+      "payment-rail adapter"
+    ],
+    "constraints": [
+      "The Job Card and external-work bridge are shipped protocol contracts; the shared payment resources are draft extensions to the 0.7 baseline and do not establish deployed payment support.",
+      "External work completion may produce handoff_ready only and never directly produces delivery acceptance, claim approval, or settlement confirmation."
+    ]
+  },
+  "topic": {
+    "primaryRole": "work_case",
+    "kindRef": {
+      "source": "custom",
+      "customId": "org.ixo.job-card",
+      "label": "Job",
+      "baseKind": "task"
+    },
+    "kindProfile": {
+      "id": "https://topic-protocol.ixo.world/profiles/job-card",
+      "version": "1.0.0",
+      "schema": "https://topic-protocol.ixo.world/schemas/topic-kind-profile.schema.json",
+      "digest": "sha256:0991eb565e1253c5caf92e7f06a392edacda6d9d90c3b3111ebfa6bf65b8eaf5"
+    },
+    "recipe": "project",
+    "workingMode": "client",
+    "temporalMode": "finite",
+    "acceptance": {
+      "requiredTopicContractPaths": [
+        "/intent/text",
+        "/outcome/statement/text",
+        "/ownerId",
+        "/completion/definition",
+        "/completion/acceptanceAuthorityIds",
+        "/kindResource/value/jobNumber",
+        "/kindResource/value/phase"
+      ],
+      "allowHonestDraft": true
+    },
+    "lifecyclePolicy": {
+      "separateTopicContractOutcomeAxes": true,
+      "waitingRule": "The Topic may be waiting while delivery, evaluation, approval, claim, or payment confirmation is outstanding.",
+      "resolveRule": "Resolve only under the accepted completion rule; do not infer resolution from an external tracker state or a settlement receipt alone."
+    }
+  },
+  "actors": [
+    {
+      "role": "payer",
+      "label": "Client or payer",
+      "required": true,
+      "identity": "did",
+      "capabilities": ["ixo.payment/accept-terms"]
+    },
+    {
+      "role": "work_provider",
+      "label": "Work provider and claimant",
+      "required": true,
+      "identity": "did",
+      "capabilities": ["topic/write", "ixo.payment/submit-delivery", "ixo.payment/record-claim"]
+    },
+    {
+      "role": "delivery_acceptor",
+      "label": "Delivery acceptance authority",
+      "required": true,
+      "identity": "did",
+      "capabilities": ["ixo.payment/accept-delivery"]
+    },
+    {
+      "role": "evaluator",
+      "label": "Authorised evaluator",
+      "required": true,
+      "identity": "did",
+      "capabilities": ["ixo.payment/evaluate"]
+    },
+    {
+      "role": "payment_approver",
+      "label": "Payment approval authority",
+      "required": true,
+      "identity": "did",
+      "capabilities": ["ixo.payment/approve"]
+    },
+    {
+      "role": "settlement_controller",
+      "label": "Settlement controller",
+      "required": true,
+      "identity": "did",
+      "capabilities": ["ixo.payment/record-settlement"],
+      "constraints": ["Must not be inferred from room membership, external tracker access, or payment recipient identity."]
+    }
+  ],
+  "resources": [
+    {
+      "role": "job_card",
+      "type": "org.ixo.job-card",
+      "required": true,
+      "binding": "kind_resource",
+      "authority": "bound_resource",
+      "availability": "topic_protocol_0.7",
+      "schemaRef": "https://topic-protocol.ixo.world/schemas/job-card.schema.json",
+      "confidentiality": "room_encrypted"
+    },
+    {
+      "role": "payment_terms",
+      "type": "org.ixo.payment-terms",
+      "required": true,
+      "binding": "typed_context",
+      "authority": "bound_resource",
+      "availability": "contract_pack",
+      "schemaRef": "https://topic-protocol.ixo.world/schemas/payment-terms.schema.json",
+      "confidentiality": "vfs_ucan"
+    },
+    {
+      "role": "payable_obligation",
+      "type": "org.ixo.payable-obligation",
+      "required": true,
+      "binding": "typed_context",
+      "authority": "bound_resource",
+      "availability": "contract_pack",
+      "schemaRef": "https://topic-protocol.ixo.world/schemas/payable-obligation.schema.json",
+      "confidentiality": "room_encrypted",
+      "notes": "The envelope projects separate authoritative protocol records and cannot approve or settle itself."
+    },
+    {
+      "role": "external_work",
+      "type": "ixo.external-work-binding",
+      "required": true,
+      "binding": "protocol_record",
+      "authority": "external_system",
+      "availability": "topic_protocol_0.7",
+      "schemaRef": "https://topic-protocol.ixo.world/schemas/external-work-binding.schema.json",
+      "confidentiality": "room_encrypted"
+    },
+    {
+      "role": "delivery_evidence",
+      "type": "ixo.vfs",
+      "required": true,
+      "binding": "vfs_attachment",
+      "authority": "bound_resource",
+      "availability": "topic_protocol_0.7",
+      "schemaRef": "https://topic-protocol.ixo.world/schemas/topic-file-attachment.schema.json",
+      "confidentiality": "vfs_ucan"
+    }
+  ],
+  "protocolContracts": [
+    {"name": "topic-contract-state", "source": "topic_protocol", "schemaRef": "https://topic-protocol.ixo.world/schemas/topic-contract-state.schema.json", "required": true},
+    {"name": "job-card", "source": "topic_protocol", "schemaRef": "https://topic-protocol.ixo.world/schemas/job-card.schema.json", "required": true},
+    {"name": "external-work-binding", "source": "topic_protocol", "schemaRef": "https://topic-protocol.ixo.world/schemas/external-work-binding.schema.json", "required": true},
+    {"name": "delivery-packet", "source": "topic_protocol", "schemaRef": "https://topic-protocol.ixo.world/schemas/delivery-packet.schema.json", "required": true},
+    {"name": "delivery-decision", "source": "topic_protocol", "schemaRef": "https://topic-protocol.ixo.world/schemas/delivery-decision.schema.json", "required": true},
+    {"name": "evaluation-assertion", "source": "topic_protocol", "schemaRef": "https://topic-protocol.ixo.world/schemas/evaluation-assertion.schema.json", "required": true},
+    {"name": "approval-decision", "source": "topic_protocol", "schemaRef": "https://topic-protocol.ixo.world/schemas/approval-decision.schema.json", "required": true},
+    {"name": "claim-record", "source": "topic_protocol", "schemaRef": "https://topic-protocol.ixo.world/schemas/claim-record.schema.json", "required": true},
+    {"name": "settlement-receipt", "source": "topic_protocol", "schemaRef": "https://topic-protocol.ixo.world/schemas/settlement-receipt.schema.json", "required": true},
+    {"name": "payment-terms", "source": "contract_pack", "schemaRef": "https://topic-protocol.ixo.world/schemas/payment-terms.schema.json", "required": true},
+    {"name": "payable-obligation", "source": "contract_pack", "schemaRef": "https://topic-protocol.ixo.world/schemas/payable-obligation.schema.json", "required": true}
+  ],
+  "operations": [
+    "propose-contract",
+    "update-contract",
+    "accept-contract",
+    "supersede-contract",
+    "bind-external-work",
+    "sync-external-work",
+    "submit-delivery",
+    "record-delivery-decision",
+    "record-evaluation",
+    "record-approval",
+    "record-claim",
+    "record-settlement",
+    "change-status",
+    "resolve-conflict"
+  ],
+  "gates": [
+    {
+      "id": "terms-accepted",
+      "stage": "terms",
+      "description": "The Topic contract and pinned Payment Terms must both be accepted before work can become payable.",
+      "all": [
+        {"contract": "topic-contract-state", "path": "/contracts/effective/body/status", "operator": "equals", "value": "accepted"},
+        {"contract": "payment-terms", "path": "/status", "operator": "equals", "value": "accepted"}
+      ],
+      "onFailure": "block"
+    },
+    {
+      "id": "delivery-submitted",
+      "stage": "delivery",
+      "description": "An immutable Delivery Packet must bind the accepted contract, work snapshot, deliverables, evidence, and payment terms.",
+      "all": [
+        {"contract": "delivery-packet", "path": "/status", "operator": "equals", "value": "submitted"},
+        {"contract": "delivery-packet", "path": "/contract/digest", "operator": "digest_matches", "value": "effective_topic_contract"},
+        {"contract": "delivery-packet", "path": "/paymentTerms/digest", "operator": "digest_matches", "value": "accepted_payment_terms"}
+      ],
+      "onFailure": "return_for_changes"
+    },
+    {
+      "id": "delivery-accepted",
+      "stage": "delivery",
+      "description": "The authorised delivery decision must accept the exact submitted packet.",
+      "all": [
+        {"contract": "delivery-decision", "path": "/decision", "operator": "equals", "value": "accepted"},
+        {"contract": "delivery-decision", "path": "/deliveryPacketDigest", "operator": "digest_matches", "value": "current_delivery_packet"}
+      ],
+      "onFailure": "block"
+    },
+    {
+      "id": "evaluation-supported",
+      "stage": "evaluation",
+      "description": "Every settlement-referenced evaluation must support the delivery under an approved rubric.",
+      "all": [
+        {"contract": "evaluation-assertion", "path": "/outcome", "operator": "all_equal", "value": "supported"},
+        {"contract": "evaluation-assertion", "path": "/rubric/governanceStatus", "operator": "all_equal", "value": "approved"}
+      ],
+      "onFailure": "human_review"
+    },
+    {
+      "id": "payment-approved",
+      "stage": "approval",
+      "description": "An authorised approval decision must approve the exact packet and evaluation set.",
+      "all": [
+        {"contract": "approval-decision", "path": "/decision", "operator": "equals", "value": "approved"},
+        {"contract": "approval-decision", "path": "/evaluationIds", "operator": "all_equal", "value": "settlement_evaluation_ids"}
+      ],
+      "onFailure": "block"
+    },
+    {
+      "id": "claim-approved",
+      "stage": "claim",
+      "description": "The current claim must be approved for the exact payer-approved amount, asset, and recipient.",
+      "all": [
+        {"contract": "claim-record", "path": "/status", "operator": "equals", "value": "approved"},
+        {"contract": "claim-record", "path": "/requested", "operator": "digest_matches", "value": "payable_obligation_requested"}
+      ],
+      "onFailure": "block"
+    },
+    {
+      "id": "settlement-operator-ready",
+      "stage": "settlement",
+      "description": "Funding, identity, dispute, replay, and payment-rail checks remain external operator gates.",
+      "all": [
+        {"contract": "operator-verification", "path": "/funding", "operator": "equals", "value": "passed"},
+        {"contract": "operator-verification", "path": "/identity", "operator": "equals", "value": "passed"},
+        {"contract": "operator-verification", "path": "/disputeHold", "operator": "equals", "value": false},
+        {"contract": "operator-verification", "path": "/idempotencyKey", "operator": "exists"}
+      ],
+      "onFailure": "block"
+    }
+  ],
+  "settlement": {
+    "movesFunds": false,
+    "requiresExternalAdapter": true,
+    "failClosed": true,
+    "requiredAxes": ["delivery", "evaluation", "approval", "claim", "settlement"],
+    "exactMatchFields": ["topicId", "deliveryPacketId", "deliveryPacketDigest", "evaluationIds", "approvalId", "claimId", "amount", "asset", "recipient"],
+    "terminalState": "confirmed"
+  },
+  "privacy": {
+    "topicIsConfidentialityBoundary": false,
+    "topicCapabilityGrantsVfsAccess": false,
+    "sensitiveResourceStorage": "encrypted_room_or_ucan_vfs",
+    "minimumRoomVisibleFields": ["jobNumber", "phase", "priority", "scheduled.start"]
+  },
+  "acceptanceCriteria": [
+    {"id": "honest-draft", "statement": "The template can create a Draft from title and Kind without inventing commercial terms, authority, evidence, amount, or deadline."},
+    {"id": "immutable-handoff", "statement": "A correction creates a superseding Delivery Packet and never rewrites the accepted packet."},
+    {"id": "tracker-is-not-authority", "statement": "External work completion cannot set delivery, evaluation, approval, claim, or settlement state."},
+    {"id": "fail-closed-payment", "statement": "Settlement is blocked unless all exact-match and operator gates pass."},
+    {"id": "separate-statuses", "statement": "The UI renders Topic, contract, outcome, external work, delivery, evaluation, approval, claim, and settlement statuses separately."}
+  ]
+}