@ixo/topic-protocol 0.6.0 → 0.8.0

package/dist/src/work-bridge/types.d.ts

@@ -0,0 +1,232 @@
+export declare const EXTERNAL_WORK_STATES: readonly ["planned", "ready", "in_progress", "blocked", "handoff_ready", "handed_off", "cancelled"];
+export declare const EXTERNAL_WORKFLOW_CATEGORIES: readonly ["triage", "backlog", "unstarted", "started", "completed", "canceled"];
+export declare const EXTERNAL_WORK_HEALTH_STATES: readonly ["up_to_date", "changes_pending", "degraded", "disconnected", "conflicted", "permission_lost"];
+export type ExternalWorkState = (typeof EXTERNAL_WORK_STATES)[number];
+export type ExternalWorkflowCategory = (typeof EXTERNAL_WORKFLOW_CATEGORIES)[number];
+export interface ExternalWorkStateMapping {
+    readonly workflowStateId: string;
+    readonly category: ExternalWorkflowCategory;
+    readonly workState: ExternalWorkState;
+}
+export interface ExternalWorkStateMapV1 {
+    readonly version: 1;
+    readonly profileId: string;
+    readonly provider: string;
+    readonly organizationId: string;
+    readonly teamId: string;
+    readonly mappings: readonly ExternalWorkStateMapping[];
+}
+export interface ExternalWorkflowStateInput {
+    readonly workflowStateId: string;
+    readonly category: ExternalWorkflowCategory;
+}
+export interface ExternalWorkStateMappingResult {
+    readonly workState: ExternalWorkState;
+    readonly mappingProfileId: string;
+    readonly mappingVersion: 1;
+    readonly workflowStateId: string;
+}
+export type Sha256Digest = `sha256:${string}`;
+export type ExternalWorkHealth = (typeof EXTERNAL_WORK_HEALTH_STATES)[number];
+export interface ExternalWorkCheckpoint {
+    readonly topicRevision: string;
+    readonly effectiveContractDigest?: Sha256Digest;
+    readonly externalUpdatedAt?: string;
+    readonly externalSnapshotDigest?: Sha256Digest;
+    readonly lastEventId?: string;
+    readonly syncedAt: string;
+}
+export interface ExternalWorkBindingV1 {
+    readonly version: 1;
+    readonly bindingId: string;
+    readonly topicId: string;
+    readonly role: "primary" | "child" | "related" | "verification" | "delivery";
+    readonly createdFrom: "topic" | "external";
+    readonly external: {
+        readonly provider: string;
+        readonly resourceType: string;
+        readonly organizationId: string;
+        readonly teamId?: string;
+        readonly resourceId: string;
+        readonly identifier: string;
+        readonly url: string;
+    };
+    readonly syncPolicy: {
+        readonly mode: "link_only" | "governed_projection";
+        readonly direction: "external_to_topic" | "topic_to_external" | "bidirectional";
+        readonly comments: "none" | "explicit_promote";
+        readonly files: "none" | "reference_only" | "explicit_ingest";
+        readonly delete: "tombstone";
+        readonly fieldPolicy: {
+            readonly id: string;
+            readonly version: number;
+            readonly digest: Sha256Digest;
+        };
+    };
+    readonly workState: ExternalWorkState;
+    readonly checkpoint: ExternalWorkCheckpoint;
+    readonly identity: {
+        readonly bridgeDid: string;
+        readonly externalAppActorId?: string;
+    };
+    readonly health: ExternalWorkHealth;
+    readonly createdBy: string;
+    readonly createdAt: string;
+    readonly extensions?: Readonly<Record<string, unknown>>;
+}
+export interface ProjectedExternalWorkBinding extends ExternalWorkBindingV1 {
+    readonly lastOperationId: string;
+    readonly updatedBy?: string;
+    readonly updatedAt?: string;
+    readonly tombstone?: {
+        readonly reason: string;
+        readonly unlinkedBy: string;
+        readonly unlinkedAt: string;
+        readonly operationId: string;
+    };
+}
+export interface ExternalWorkSync {
+    readonly bindingId: string;
+    readonly workState: ExternalWorkState;
+    readonly health: ExternalWorkHealth;
+    readonly checkpoint: ExternalWorkCheckpoint;
+}
+export interface ExternalWorkTombstone {
+    readonly bindingId: string;
+    readonly reason: string;
+}
+export interface WorkArtifactReference {
+    readonly type: string;
+    readonly uri: string;
+    readonly digest: Sha256Digest;
+    readonly label?: string;
+    readonly mediaType?: string;
+}
+export interface WorkEvidenceReference extends Omit<WorkArtifactReference, "mediaType"> {
+    readonly provenanceClass: "claimant_provided" | "client_assisted" | "server_verified" | "third_party_attested";
+}
+export interface WorkItemSnapshotV1 extends Readonly<Record<string, unknown>> {
+    readonly version: 1;
+    readonly snapshotId: string;
+    readonly bindingId: string;
+    readonly topicId: string;
+    readonly digest: Sha256Digest;
+}
+export interface DeliveryPacketV1 {
+    readonly version: 1;
+    readonly deliveryPacketId: string;
+    readonly sequence: number;
+    readonly topicId: string;
+    readonly bindingId: string;
+    readonly supersedes?: string;
+    readonly contract: {
+        readonly revision: string;
+        readonly digest: Sha256Digest;
+        readonly status: "accepted";
+    };
+    readonly workItemSnapshot: {
+        readonly snapshotId: string;
+        readonly ref: string;
+        readonly digest: Sha256Digest;
+    };
+    readonly deliverables: readonly WorkArtifactReference[];
+    readonly evidence: readonly WorkEvidenceReference[];
+    readonly traces: readonly WorkArtifactReference[];
+    readonly paymentTerms?: {
+        readonly ref: string;
+        readonly digest: Sha256Digest;
+    };
+    readonly submittedBy: string;
+    readonly submittedAt: string;
+    readonly capability: string;
+    readonly status: "submitted";
+    readonly digest: Sha256Digest;
+    readonly extensions?: Readonly<Record<string, unknown>>;
+}
+export interface DeliveryDecisionV1 {
+    readonly version: 1;
+    readonly decisionId: string;
+    readonly topicId: string;
+    readonly deliveryPacketId: string;
+    readonly deliveryPacketDigest: Sha256Digest;
+    readonly decision: "accepted" | "returned" | "rejected";
+    readonly reasons?: readonly string[];
+    readonly decidedBy: string;
+    readonly decidedAt: string;
+    readonly capability: string;
+    readonly digest: Sha256Digest;
+    readonly extensions?: Readonly<Record<string, unknown>>;
+}
+export interface EvaluationAssertionV1 extends Readonly<Record<string, unknown>> {
+    readonly version: 1;
+    readonly evaluationId: string;
+    readonly topicId: string;
+    readonly deliveryPacketId: string;
+    readonly deliveryPacketDigest: Sha256Digest;
+    readonly evidenceDigests: readonly Sha256Digest[];
+    readonly traceDigests: readonly Sha256Digest[];
+    readonly outcome: "supported" | "refuted" | "insufficient_evidence" | "human_review" | "disputed" | "superseded";
+    readonly evaluatorDid: string;
+    readonly evaluatedAt: string;
+    readonly digest: Sha256Digest;
+}
+export interface ApprovalDecisionV1 extends Readonly<Record<string, unknown>> {
+    readonly version: 1;
+    readonly approvalId: string;
+    readonly topicId: string;
+    readonly deliveryPacketId: string;
+    readonly deliveryPacketDigest: Sha256Digest;
+    readonly evaluationIds: readonly string[];
+    readonly decision: "approved" | "rejected" | "changes_requested" | "superseded";
+    readonly decidedAt: string;
+    readonly digest: Sha256Digest;
+}
+export interface ClaimRecordV1 extends Readonly<Record<string, unknown>> {
+    readonly version: 1;
+    readonly claimId: string;
+    readonly topicId: string;
+    readonly deliveryPacketId: string;
+    readonly deliveryPacketDigest: Sha256Digest;
+    readonly evaluationIds: readonly string[];
+    readonly approvalId: string;
+    readonly claimantDid: string;
+    readonly requested: {
+        readonly amount: string;
+        readonly asset: string;
+        readonly recipient: string;
+    };
+    readonly status: "pending" | "approved" | "rejected" | "disputed" | "invalidated" | "flagged";
+    readonly replayKey: string;
+    readonly source: {
+        readonly provider: string;
+        readonly ref: string;
+    };
+    readonly recordedAt: string;
+    readonly digest: Sha256Digest;
+}
+export interface SettlementReceiptV1 extends Readonly<Record<string, unknown>> {
+    readonly version: 1;
+    readonly settlementId: string;
+    readonly topicId: string;
+    readonly claimId: string;
+    readonly deliveryPacketId: string;
+    readonly deliveryPacketDigest: Sha256Digest;
+    readonly evaluationIds: readonly string[];
+    readonly approvalId: string;
+    readonly idempotencyKey: string;
+    readonly amount: string;
+    readonly asset: string;
+    readonly recipient: string;
+    readonly state: "unfunded" | "funded" | "held" | "authorised" | "submitted" | "confirmed" | "failed" | "refunded";
+    readonly recordedAt: string;
+    readonly digest: Sha256Digest;
+}
+export interface TopicWorkBridgeProjection {
+    readonly bindings: readonly ProjectedExternalWorkBinding[];
+    readonly deliveryPackets: readonly DeliveryPacketV1[];
+    readonly deliveryDecisions: readonly DeliveryDecisionV1[];
+    readonly evaluations: readonly EvaluationAssertionV1[];
+    readonly approvals: readonly ApprovalDecisionV1[];
+    readonly claims: readonly ClaimRecordV1[];
+    readonly settlements: readonly SettlementReceiptV1[];
+}

package/dist/src/work-bridge/types.js

@@ -0,0 +1,26 @@
+export const EXTERNAL_WORK_STATES = [
+    "planned",
+    "ready",
+    "in_progress",
+    "blocked",
+    "handoff_ready",
+    "handed_off",
+    "cancelled",
+];
+export const EXTERNAL_WORKFLOW_CATEGORIES = [
+    "triage",
+    "backlog",
+    "unstarted",
+    "started",
+    "completed",
+    "canceled",
+];
+export const EXTERNAL_WORK_HEALTH_STATES = [
+    "up_to_date",
+    "changes_pending",
+    "degraded",
+    "disconnected",
+    "conflicted",
+    "permission_lost",
+];
+//# sourceMappingURL=types.js.map

package/dist/src/work-bridge/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/work-bridge/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,SAAS;IACT,OAAO;IACP,aAAa;IACb,SAAS;IACT,eAAe;IACf,YAAY;IACZ,WAAW;CACH,CAAC;AAEX,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,QAAQ;IACR,SAAS;IACT,WAAW;IACX,SAAS;IACT,WAAW;IACX,UAAU;CACF,CAAC;AAEX,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,YAAY;IACZ,iBAAiB;IACjB,UAAU;IACV,cAAc;IACd,YAAY;IACZ,iBAAiB;CACT,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/topic-protocol",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Reference contracts and deterministic projection for IXO Topics",
   "type": "module",
   "sideEffects": false,
@@ -18,6 +18,7 @@
   "files": [
     "dist",
     "profiles",
+    "templates",
     "README.md"
   ],
   "exports": {
@@ -26,7 +27,8 @@
       "import": "./dist/src/index.js"
     },
     "./schemas/*": "./dist/schemas/*",
-    "./profiles/*": "./profiles/*"
+    "./profiles/*": "./profiles/*",
+    "./templates/*": "./templates/*"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/templates/decision-to-pay/README.md

@@ -0,0 +1,59 @@
+# Decision-to-Pay Topic template pack
+
+This directory publishes four draft, machine-readable Topic Templates for
+consequential payment decisions:
+
+1. [Verified Work Payment](verified-work-payment.template.json)
+2. [Payment on Delivery](payment-on-delivery.template.json)
+3. [Milestone Payment Release](milestone-payment-release.template.json)
+4. [Outcome Payment Claim](outcome-payment-claim.template.json)
+
+The manifests extend the Topic kinds, recipes, and external-work contracts in
+`@ixo/topic-protocol` 0.7.0. Their compatibility block pins the reviewed
+baseline commit and names every additional contract, capability policy, and
+adapter needed by an implementation.
+
+## Shared contracts
+
+- [`decision-to-pay-template.schema.json`](../../schemas/decision-to-pay-template.schema.json)
+  validates each template manifest.
+- [`payment-terms.schema.json`](../../schemas/payment-terms.schema.json) defines
+  immutable commercial and control terms for one payable unit.
+- [`payable-obligation.schema.json`](../../schemas/payable-obligation.schema.json)
+  defines a payment-case envelope with separate delivery, evaluation, approval,
+  claim, and settlement projections.
+- Matching synthetic reference vectors live in [`examples/`](../../examples).
+
+## Trust boundary
+
+These artifacts are draft contract extensions. They do not grant a capability,
+verify a signature, establish eligibility, approve a claim, or move money.
+Topic Protocol operations and their referenced records remain authoritative for
+delivery, evaluation, approval, claim, and settlement state. A conforming
+runtime must verify DIDs, delegated capabilities, signatures, revocation,
+replay protection, funding, KYC or sanctions requirements, dispute holds,
+trusted time, and payment-rail finality before accepting a settlement receipt.
+
+The Payable Obligation is an envelope and index over those separate axes. Its
+`axisProjection` must be derived from referenced protocol records; it is not an
+alternative settlement authority.
+
+## Draft and privacy rules
+
+- A Topic may begin as an honest Draft with only a title and Kind.
+- Missing intent, owner, outcome, authority, evidence, amount, or deadline must
+  remain visibly missing until supplied or accepted.
+- A template names required capabilities but never grants them.
+- Confidential evidence stays in an appropriately scoped encrypted room or a
+  UCAN-protected VFS resource. Topic membership does not grant VFS byte access.
+- The example fixtures set `notRealEvidence: true`; zero digests and example
+  identifiers must never be treated as verified evidence.
+
+## Compatibility notes
+
+The Job Card profile and external-work contracts support the strongest path for
+Verified Work Payment. Physical delivery still needs a delivery-order resource
+or profile. The milestone template uses one child Topic per payable milestone,
+so corrections do not become new milestones. Outcome Payment Claim assumes a
+Delivery Packet for the underlying intervention; claims without external work
+need a future generalised obligation handoff.

package/templates/decision-to-pay/milestone-payment-release.template.json

@@ -0,0 +1,195 @@
+{
+  "$schema": "../../schemas/decision-to-pay-template.schema.json",
+  "version": 1,
+  "id": "urn:ixo:decision-to-pay:template:milestone-payment-release",
+  "templateVersion": "0.1.0",
+  "label": "Milestone Payment Release",
+  "description": "Create one governed child Topic for each payable milestone so its terms, handoff, evaluation, claim, settlement, corrections, and disputes remain independently auditable.",
+  "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": [
+      "One child Topic represents one payable milestone; Delivery Packet sequence numbers represent corrections and not additional milestones.",
+      "Parent project completion, child milestone acceptance, and payment settlement remain separate statuses."
+    ]
+  },
+  "topic": {
+    "primaryRole": "payable_milestone",
+    "kindRef": {"source": "standard", "kind": "task"},
+    "recipe": "project",
+    "workingMode": "client",
+    "temporalMode": "finite",
+    "acceptance": {
+      "requiredTopicContractPaths": [
+        "/intent/text",
+        "/outcome/statement/text",
+        "/outcome/successCriteria",
+        "/ownerId",
+        "/completion/definition",
+        "/completion/acceptanceAuthorityIds"
+      ],
+      "allowHonestDraft": true
+    },
+    "lifecyclePolicy": {
+      "separateTopicContractOutcomeAxes": true,
+      "waitingRule": "A milestone Topic may wait on dependencies, delivery correction, evaluation, approval, claim, or settlement without changing the parent project outcome.",
+      "resolveRule": "Resolve the milestone under its own accepted closure rule; never infer parent project completion from one paid child."
+    }
+  },
+  "topology": {
+    "requiresParentTopic": true,
+    "parentBaseKind": "task",
+    "relation": "branches_from",
+    "onePayableUnitPerTopic": true
+  },
+  "actors": [
+    {"role": "payer", "label": "Project client or payer", "required": true, "identity": "did", "capabilities": ["ixo.payment/accept-terms"]},
+    {"role": "milestone_owner", "label": "Milestone owner and claimant", "required": true, "identity": "did", "capabilities": ["topic/write", "ixo.payment/submit-delivery", "ixo.payment/record-claim"]},
+    {"role": "milestone_acceptor", "label": "Milestone acceptance authority", "required": true, "identity": "did", "capabilities": ["ixo.payment/accept-delivery"]},
+    {"role": "evaluator", "label": "Milestone 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"]}
+  ],
+  "resources": [
+    {"role": "parent_topic", "type": "ixo.topic", "required": true, "binding": "external_reference", "authority": "topic_contract", "availability": "topic_protocol_0.7", "confidentiality": "room_encrypted", "notes": "Linked by an append-only Topic relation; the parent does not own this child's payment state."},
+    {"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"},
+    {"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": "milestone_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": "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": [
+    "branch",
+    "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": "milestone-terms-accepted",
+      "stage": "terms",
+      "description": "The child Topic must pin one milestone, one amount rule, dependencies, evidence, acceptance authority, and payment timing.",
+      "all": [
+        {"contract": "topic-contract-state", "path": "/contracts/effective/body/status", "operator": "equals", "value": "accepted"},
+        {"contract": "payment-terms", "path": "/calculation/model", "operator": "equals", "value": "milestone"},
+        {"contract": "payment-terms", "path": "/status", "operator": "equals", "value": "accepted"}
+      ],
+      "onFailure": "block"
+    },
+    {
+      "id": "milestone-delivery-submitted",
+      "stage": "delivery",
+      "description": "The Delivery Packet must bind only this milestone's accepted contract, work snapshot, deliverables, and evidence.",
+      "all": [
+        {"contract": "delivery-packet", "path": "/status", "operator": "equals", "value": "submitted"},
+        {"contract": "delivery-packet", "path": "/contract/digest", "operator": "digest_matches", "value": "effective_child_contract"},
+        {"contract": "delivery-packet", "path": "/paymentTerms/digest", "operator": "digest_matches", "value": "accepted_milestone_terms"}
+      ],
+      "onFailure": "return_for_changes"
+    },
+    {
+      "id": "milestone-accepted",
+      "stage": "delivery",
+      "description": "The authorised acceptance decision must accept the current packet under the child's completion criteria.",
+      "all": [
+        {"contract": "delivery-decision", "path": "/decision", "operator": "equals", "value": "accepted"},
+        {"contract": "delivery-decision", "path": "/deliveryPacketDigest", "operator": "digest_matches", "value": "current_delivery_packet"}
+      ],
+      "onFailure": "return_for_changes"
+    },
+    {
+      "id": "milestone-evaluation-supported",
+      "stage": "evaluation",
+      "description": "Every required success criterion must be supported by the approved milestone 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": "milestone-payment-approved",
+      "stage": "approval",
+      "description": "Approval must reference the exact child packet and supported 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": "milestone-claim-approved",
+      "stage": "claim",
+      "description": "The claim must be approved for this milestone's exact 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": "milestone-settlement-clear",
+      "stage": "settlement",
+      "description": "Dependencies, disputes, funding, identity, and replay checks must pass for this child Topic only.",
+      "all": [
+        {"contract": "operator-verification", "path": "/dependencies", "operator": "equals", "value": "satisfied"},
+        {"contract": "operator-verification", "path": "/disputeHold", "operator": "equals", "value": false},
+        {"contract": "operator-verification", "path": "/funding", "operator": "equals", "value": "passed"},
+        {"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": ["milestone label", "milestone phase", "target date"]
+  },
+  "acceptanceCriteria": [
+    {"id": "one-payable-unit", "statement": "Each child Topic contains exactly one payable milestone and one Payment Terms resource."},
+    {"id": "correction-not-milestone", "statement": "A corrected handoff supersedes the prior Delivery Packet and never creates a second payable milestone."},
+    {"id": "parent-child-separation", "statement": "Parent project, child milestone, claim, and settlement states remain independently visible."},
+    {"id": "dependency-gate", "statement": "Unmet accepted dependencies block payment without fabricating milestone failure."},
+    {"id": "exact-amount", "statement": "The claim and settlement must exactly match the accepted milestone amount, asset, and recipient."}
+  ]
+}