@ixo/topic-protocol 0.7.0 → 1.0.0-rc.1

package/README.md

@@ -9,7 +9,10 @@ identity of a discussion.
 
 ## Status
 
-**Version:** 0.7.0
+**Version:** 1.0.0-rc.1
+
+The normative Topic Shape progression and Portal Now projection are defined in
+[Topic Shape Framework v1](docs/topic-shape-framework.md).
 
 **Maturity:** Draft implementation candidate  
 **Execution source of truth:** [Linear Topic Protocol project](https://linear.app/ixo-world/project/topic-protocol-4ea58bc7910d)
@@ -24,6 +27,8 @@ 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
+- [Topic Outcome Achievement evaluation kit](evaluation-kits/topic-outcome-achievement/README.md) — ledger-ready deterministic outcome evaluation release
 - [Protocol chapters](docs/protocol/README.md)
 - [Machine-readable contracts](contracts/README.md)
 - [Reference implementation](docs/reference-implementation.md)
@@ -40,7 +45,7 @@ key-value adapter at its integration boundary.
 
 The package includes:
 
-- strict Draft 2020-12 validation for all 29 contracts, including Kind Profiles, Job Cards, external work, delivery, evaluation, claims, and settlement receipts;
+- 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;
@@ -147,6 +152,8 @@ 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
+evaluation-kits/      Ledger-ready governed evaluation releases
 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/decision-to-pay-template-v2.schema.json

@@ -0,0 +1,301 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://topic-protocol.ixo.world/schemas/decision-to-pay-template-v2.schema.json",
+    "title": "IXO Decision-to-Pay Topic Template manifest v2",
+    "description": "A Claims-native Decision-to-Pay template. The Topic binds and projects the work case; the Deed and IXO Claims module remain authoritative.",
+    "type": "object",
+    "required": [
+        "$schema",
+        "version",
+        "id",
+        "templateVersion",
+        "label",
+        "description",
+        "maturity",
+        "compatibility",
+        "topic",
+        "authorities",
+        "actors",
+        "resources",
+        "lifecycle",
+        "capabilityPolicy",
+        "pilotPolicy",
+        "settlement",
+        "privacy",
+        "acceptanceCriteria"
+    ],
+    "properties": {
+        "$schema": { "type": "string", "minLength": 1 },
+        "version": { "const": 2 },
+        "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" },
+        "authorities": { "$ref": "#/$defs/authorities" },
+        "actors": {
+            "type": "array",
+            "minItems": 4,
+            "items": { "$ref": "#/$defs/actor" }
+        },
+        "resources": {
+            "type": "array",
+            "minItems": 7,
+            "items": { "$ref": "#/$defs/resource" }
+        },
+        "lifecycle": {
+            "type": "array",
+            "minItems": 10,
+            "items": { "$ref": "#/$defs/lifecycleStep" }
+        },
+        "capabilityPolicy": { "$ref": "#/$defs/capabilityPolicy" },
+        "pilotPolicy": { "$ref": "#/$defs/pilotPolicy" },
+        "settlement": { "$ref": "#/$defs/settlement" },
+        "privacy": { "$ref": "#/$defs/privacy" },
+        "acceptanceCriteria": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "$ref": "#/$defs/acceptanceCriterion" }
+        }
+    },
+    "additionalProperties": false,
+    "$defs": {
+        "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+        "jsonPointer": { "type": "string", "pattern": "^/" },
+        "compatibility": {
+            "type": "object",
+            "required": ["protocolPackage", "protocolVersion", "sourceCommit", "claimsModule", "sdkVersion", "implementationStatus", "requiredExtensions"],
+            "properties": {
+                "protocolPackage": { "const": "@ixo/topic-protocol" },
+                "protocolVersion": { "const": "0.8.0" },
+                "sourceCommit": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+                "claimsModule": { "enum": ["v7", "v8"] },
+                "sdkVersion": { "const": "3.0.0" },
+                "implementationStatus": { "enum": ["design_ready", "candidate_contract", "implemented"] },
+                "requiredExtensions": {
+                    "type": "array",
+                    "minItems": 2,
+                    "uniqueItems": true,
+                    "items": { "type": "string", "minLength": 1 }
+                },
+                "constraints": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+            },
+            "additionalProperties": false
+        },
+        "topic": {
+            "type": "object",
+            "required": ["kind", "profile", "domain", "role", "bindingPaths", "lifecyclePolicy"],
+            "properties": {
+                "kind": { "const": "org.ixo.job-card" },
+                "profile": { "const": "https://topic-protocol.ixo.world/profiles/job-card" },
+                "domain": { "const": "deed" },
+                "role": { "const": "contract_binder_and_message_thread" },
+                "bindingPaths": {
+                    "type": "object",
+                    "required": ["deed", "claimCollection", "manifest", "claimSchema", "rubric"],
+                    "properties": {
+                        "deed": { "const": "/bindings/deed" },
+                        "claimCollection": { "const": "/bindings/claimCollection" },
+                        "manifest": { "const": "/bindings/verifiedWorkPaymentManifest" },
+                        "claimSchema": { "const": "/bindings/claimSchema" },
+                        "rubric": { "const": "/bindings/rubric" }
+                    },
+                    "additionalProperties": false
+                },
+                "lifecyclePolicy": {
+                    "type": "object",
+                    "required": ["topicIsProjection", "chainStateIsAuthoritative", "resolveRule"],
+                    "properties": {
+                        "topicIsProjection": { "const": true },
+                        "chainStateIsAuthoritative": { "const": true },
+                        "resolveRule": { "type": "string", "minLength": 1 }
+                    },
+                    "additionalProperties": false
+                }
+            },
+            "additionalProperties": false
+        },
+        "authorities": {
+            "type": "object",
+            "required": ["workPackage", "conversation", "claims", "evaluation", "orchestration"],
+            "properties": {
+                "workPackage": { "const": "deed" },
+                "conversation": { "const": "job_topic" },
+                "claims": { "const": "ixo.claims.v1beta1" },
+                "evaluation": { "const": "ixo_evaluation_engine" },
+                "orchestration": { "const": "ixo_portal" }
+            },
+            "additionalProperties": false
+        },
+        "actor": {
+            "type": "object",
+            "required": ["role", "identity", "capabilities"],
+            "properties": {
+                "role": { "enum": ["deed_owner", "payer", "service_agent", "evaluation_engine", "human_evaluator", "adjudicator"] },
+                "identity": { "const": "did" },
+                "required": { "type": "boolean" },
+                "capabilities": {
+                    "type": "array",
+                    "minItems": 1,
+                    "uniqueItems": true,
+                    "items": { "type": "string", "minLength": 1 }
+                },
+                "constraints": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+            },
+            "additionalProperties": false
+        },
+        "resource": {
+            "type": "object",
+            "required": ["role", "type", "required", "authority", "binding", "confidentiality"],
+            "properties": {
+                "role": { "enum": ["deed", "payment_terms", "payable_obligation", "bid_schema", "claim_schema", "claim_collection", "rubric", "evaluation_receipt", "evidence"] },
+                "type": { "type": "string", "minLength": 1 },
+                "required": { "type": "boolean" },
+                "authority": { "enum": ["deed", "bound_resource", "ixo_claims_module", "evaluation_engine"] },
+                "binding": { "enum": ["topic_binding", "deed_linked_resource", "claims_record", "content_addressed_receipt", "vfs_attachment"] },
+                "schemaRef": { "type": "string", "format": "uri-reference" },
+                "confidentiality": { "enum": ["public", "room_encrypted", "vfs_ucan", "claims_module"] },
+                "notes": { "type": "string", "minLength": 1 }
+            },
+            "additionalProperties": false
+        },
+        "lifecycleStep": {
+            "type": "object",
+            "required": ["sequence", "id", "authority", "result"],
+            "properties": {
+                "sequence": { "type": "integer", "minimum": 1, "maximum": 20 },
+                "id": { "enum": ["validate-deed", "create-job-topic", "submit-bid", "accept-bid-and-grant", "claim-intent", "submit-claim", "evaluate-evidence", "record-evaluation", "project-payment", "dispute-and-adjudicate"] },
+                "authority": { "enum": ["deed", "job_topic", "bids_service", "cosmos_authz", "ixo_claims_module", "evaluation_engine", "ixo_portal"] },
+                "messageType": {
+                    "enum": [
+                        "/ixo.claims.v1beta1.MsgClaimIntent",
+                        "/ixo.claims.v1beta1.MsgSubmitClaim",
+                        "/ixo.claims.v1beta1.MsgEvaluateClaim",
+                        "/ixo.claims.v1beta1.MsgDisputeClaim",
+                        "/ixo.claims.v1beta1.MsgAdjudicateDispute",
+                        "/cosmos.authz.v1beta1.MsgGrant"
+                    ]
+                },
+                "preconditions": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+                "result": { "type": "string", "minLength": 1 }
+            },
+            "additionalProperties": false
+        },
+        "capabilityPolicy": {
+            "type": "object",
+            "required": ["submitClaimAuthorization", "evaluateClaimAuthorization", "engineUcan", "revocationTriggers"],
+            "properties": {
+                "submitClaimAuthorization": {
+                    "type": "object",
+                    "required": ["typeUrl", "requiredConstraints", "deriveFromAcceptedBid", "expiryBound"],
+                    "properties": {
+                        "typeUrl": { "const": "/ixo.claims.v1beta1.SubmitClaimAuthorization" },
+                        "requiredConstraints": {
+                            "type": "array",
+                            "minItems": 5,
+                            "uniqueItems": true,
+                            "items": { "enum": ["collectionId", "agentQuota", "maxAmount", "intentDurationNs", "memberAddress"] }
+                        },
+                        "deriveFromAcceptedBid": { "const": true },
+                        "expiryBound": { "const": "min(job_end,collection_end)" }
+                    },
+                    "additionalProperties": false
+                },
+                "evaluateClaimAuthorization": {
+                    "type": "object",
+                    "required": ["typeUrl", "requiredConstraints", "expiryBound"],
+                    "properties": {
+                        "typeUrl": { "const": "/ixo.claims.v1beta1.EvaluateClaimAuthorization" },
+                        "requiredConstraints": {
+                            "type": "array",
+                            "minItems": 4,
+                            "uniqueItems": true,
+                            "items": { "enum": ["collectionId", "claimIds", "agentQuota", "beforeDate", "maxCustomAmount"] }
+                        },
+                        "expiryBound": { "const": "collection_end" }
+                    },
+                    "additionalProperties": false
+                },
+                "engineUcan": {
+                    "type": "object",
+                    "required": ["abilities", "audienceBound", "resourceBound", "timeBound", "revocable", "environmentBound"],
+                    "properties": {
+                        "abilities": {
+                            "type": "array",
+                            "minItems": 1,
+                            "uniqueItems": true,
+                            "items": { "enum": ["ixo:matrix-claims-bot", "subscriptions/read"] }
+                        },
+                        "audienceBound": { "const": true },
+                        "resourceBound": { "const": true },
+                        "timeBound": { "const": true },
+                        "revocable": { "const": true },
+                        "environmentBound": { "const": true }
+                    },
+                    "additionalProperties": false
+                },
+                "revocationTriggers": {
+                    "type": "array",
+                    "minItems": 4,
+                    "uniqueItems": true,
+                    "items": { "enum": ["job_cancelled", "job_completed", "job_expired", "bidder_removed", "security_incident"] }
+                }
+            },
+            "additionalProperties": false
+        },
+        "pilotPolicy": {
+            "type": "object",
+            "required": ["intentPolicy", "assetType", "payoutTimeoutNs", "mainnetEvaluationMode", "testnetAutomation", "deferredFeatures"],
+            "properties": {
+                "intentPolicy": { "const": "REQUIRED" },
+                "assetType": { "const": "native" },
+                "payoutTimeoutNs": { "const": "0" },
+                "mainnetEvaluationMode": { "const": "HUMAN_SIGNED" },
+                "testnetAutomation": { "const": "CAPPED" },
+                "deferredFeatures": {
+                    "type": "array",
+                    "minItems": 4,
+                    "uniqueItems": true,
+                    "items": { "enum": ["cw20", "cw1155", "team_budgets", "delayed_withdrawal", "mainnet_automation", "other_decision_to_pay_templates"] }
+                }
+            },
+            "additionalProperties": false
+        },
+        "settlement": {
+            "type": "object",
+            "required": ["templateMovesFunds", "claimsModuleMovesFunds", "authority", "adapter", "approvalTrigger", "disputeRecourse"],
+            "properties": {
+                "templateMovesFunds": { "const": false },
+                "claimsModuleMovesFunds": { "const": true },
+                "authority": { "const": "ixo.claims.v1beta1" },
+                "adapter": { "const": "canonical_impactxclient_sdk" },
+                "approvalTrigger": { "const": "MsgEvaluateClaim(APPROVED)" },
+                "disputeRecourse": { "const": "deposit_slashing_and_adjudication_not_payment_reversal" }
+            },
+            "additionalProperties": false
+        },
+        "privacy": {
+            "type": "object",
+            "required": ["topicIsConfidentialityBoundary", "topicCapabilityGrantsVfsAccess", "sensitiveResourceStorage", "receiptExcludesPii"],
+            "properties": {
+                "topicIsConfidentialityBoundary": { "const": false },
+                "topicCapabilityGrantsVfsAccess": { "const": false },
+                "sensitiveResourceStorage": { "const": "encrypted_room_or_ucan_vfs" },
+                "receiptExcludesPii": { "const": true }
+            },
+            "additionalProperties": false
+        },
+        "acceptanceCriterion": {
+            "type": "object",
+            "required": ["id", "statement", "verification"],
+            "properties": {
+                "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+                "statement": { "type": "string", "minLength": 1 },
+                "verification": { "type": "string", "minLength": 1 }
+            },
+            "additionalProperties": false
+        }
+    }
+}