@hyperscale0/udl 1.0.0-beta.1 → 1.0.0

package/conformance/invalid/not-an-object.expected.json

@@ -1,7 +1,7 @@
 {
   "issues": [
     {
-      "code": "invalid_shape",
+      "code": "UDL1003",
       "path": "$"
     }
   ],

package/conformance/invalid/payout-reconcile-not-a-bank-debit.expected.json

@@ -0,0 +1,10 @@
+{
+  "issues": [
+    {
+      "code": "UDL5005",
+      "path": "$.instruments[0].actions.settle.reconcile[0].evidence"
+    }
+  ],
+  "summary": "Bank evidence for payouts: an instrument that owns a payout closes it against a debit statement line, never against the provider confirmation of our own instruction.",
+  "verdict": "invalid"
+}

package/conformance/invalid/payout-reconcile-not-a-bank-debit.udl

@@ -0,0 +1,259 @@
+{
+  "instruments": [
+    {
+      "actionOrder": [
+        "create",
+        "instruct",
+        "settle"
+      ],
+      "actions": {
+        "create": {
+          "moves": [],
+          "publicAction": "createSupplierPayout",
+          "steps": [],
+          "summary": "Create a supplier payout"
+        },
+        "instruct": {
+          "moves": [],
+          "payout": {
+            "amount": "fields.netPayable",
+            "beneficiaryField": "supplierBeneficiaryId",
+            "beneficiaryPartyField": "supplierAccountId",
+            "capture": "payoutId",
+            "currencyField": "currency",
+            "sourceAccountField": "treasuryAccountId",
+            "speed": "standard"
+          },
+          "publicAction": "instructSupplierPayout",
+          "steps": [],
+          "summary": "Instruct the payout to the supplier"
+        },
+        "settle": {
+          "due": {
+            "field": "settleBy"
+          },
+          "moves": [],
+          "reconcile": [
+            {
+              "amount": "fields.netPayable",
+              "capture": "settlementEvidenceId",
+              "counterpartyRef": "payoutId",
+              "currencyField": "currency",
+              "direction": "debit",
+              "evidence": "provider_confirmation",
+              "exception": {
+                "amountField": "unmatchedAmount",
+                "childInstrumentId": "supplier_payout_break",
+                "maxOpen": 1,
+                "reasonField": "breakReason",
+                "refField": "supplierPayoutId"
+              },
+              "match": {
+                "dial": "settlement_tolerance",
+                "law": "tolerance",
+                "minorUnits": 100
+              },
+              "within": {
+                "field": "settleBy"
+              }
+            }
+          ],
+          "steps": [],
+          "summary": "Match the bank's debit against what the instruction promised"
+        }
+      },
+      "description": "A payout the instrument owns end to end: one instruction, one expectation about the debit it will produce, and one break when the debit never matches",
+      "dials": [
+        {
+          "key": "settlement_tolerance",
+          "kind": "reconcile_tolerance",
+          "maxMinorUnits": 500,
+          "summary": "Largest difference between the instructed amount and the settled debit that still counts as matched.",
+          "title": "Settlement tolerance"
+        }
+      ],
+      "fields": {
+        "currency": {
+          "description": "ISO 4217 currency code",
+          "maxLength": 3,
+          "minLength": 3,
+          "pattern": "^[A-Z]{3}$",
+          "type": "string"
+        },
+        "netPayable": {
+          "description": "Amount instructed to the supplier in minor units",
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string"
+        },
+        "settleBy": {
+          "description": "Instant the expectation stops waiting and the unmatched amount becomes a break",
+          "format": "hyperscale-date-time",
+          "type": "string"
+        },
+        "supplierAccountId": {
+          "description": "The supplier account",
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string",
+          "x-hyperscale-reference-filter": {
+            "column": "role",
+            "values": [
+              "customer_balance"
+            ]
+          }
+        },
+        "supplierBeneficiaryId": {
+          "description": "Beneficiary ID for the payout instruction",
+          "pattern": "^ben_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string"
+        },
+        "treasuryAccountId": {
+          "description": "The treasury account the payout leaves",
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string",
+          "x-hyperscale-reference-filter": {
+            "column": "role",
+            "values": [
+              "customer_balance"
+            ]
+          }
+        }
+      },
+      "id": "supplier_payout",
+      "idPrefix": "sp",
+      "lifecycle": {
+        "initial": "created",
+        "states": [
+          "created",
+          "instructed",
+          "settled"
+        ],
+        "transitions": {
+          "instruct": {
+            "from": [
+              "created"
+            ],
+            "to": "instructed"
+          },
+          "settle": {
+            "from": [
+              "instructed"
+            ],
+            "to": "settled"
+          }
+        }
+      },
+      "parties": {
+        "beneficiary": "supplierAccountId",
+        "payer": "treasuryAccountId"
+      },
+      "required": [
+        "netPayable",
+        "supplierAccountId",
+        "supplierBeneficiaryId",
+        "currency",
+        "treasuryAccountId",
+        "settleBy"
+      ],
+      "summary": "Payout from treasury to supplier that is not done until the bank agrees",
+      "title": "Supplier payout"
+    },
+    {
+      "actionOrder": [
+        "create",
+        "carry"
+      ],
+      "actions": {
+        "carry": {
+          "moves": [],
+          "publicAction": "carrySupplierPayoutBreak",
+          "requiresRefs": [
+            {
+              "field": "supplierPayoutId",
+              "match": {
+                "fields.currency": "fields.currency"
+              },
+              "statuses": [
+                "instructed"
+              ]
+            }
+          ],
+          "steps": [],
+          "summary": "Carry the break to whoever owns it"
+        },
+        "create": {
+          "moves": [],
+          "publicAction": "createSupplierPayoutBreak",
+          "requiresRefs": [
+            {
+              "field": "supplierPayoutId",
+              "match": {
+                "fields.currency": "fields.currency"
+              },
+              "statuses": [
+                "instructed"
+              ]
+            }
+          ],
+          "steps": [],
+          "summary": "Raise a break against an instructed payout"
+        }
+      },
+      "description": "One break raised when a payout expectation reached its window with no matching debit; it is carried, never silently dropped",
+      "fields": {
+        "breakReason": {
+          "description": "Why the expectation went unmatched",
+          "maxLength": 180,
+          "minLength": 1,
+          "type": "string"
+        },
+        "currency": {
+          "description": "ISO 4217 currency code",
+          "maxLength": 3,
+          "minLength": 3,
+          "pattern": "^[A-Z]{3}$",
+          "type": "string"
+        },
+        "supplierPayoutId": {
+          "description": "Payout whose expectation broke",
+          "pattern": "^sp_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string"
+        },
+        "unmatchedAmount": {
+          "description": "Difference between the instructed amount and the evidence, in minor units",
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string"
+        }
+      },
+      "id": "supplier_payout_break",
+      "idPrefix": "spbk",
+      "lifecycle": {
+        "initial": "created",
+        "states": [
+          "created",
+          "carried"
+        ],
+        "transitions": {
+          "carry": {
+            "from": [
+              "created"
+            ],
+            "to": "carried"
+          }
+        }
+      },
+      "required": [
+        "breakReason",
+        "currency",
+        "unmatchedAmount",
+        "supplierPayoutId"
+      ],
+      "summary": "Unmatched settlement expectation carried as its own row",
+      "title": "Supplier payout Break"
+    }
+  ],
+  "product": "supplier_settlement",
+  "subjects": [],
+  "title": "Supplier settlement",
+  "udl": 1,
+  "version": 1
+}

package/conformance/invalid/quote-freeze-set-incomplete.expected.json

@@ -0,0 +1,10 @@
+{
+  "issues": [
+    {
+      "code": "UDL5006",
+      "path": "$.instruments[0].actions.quote.quote.baseField"
+    }
+  ],
+  "summary": "Freeze set completeness: an offer must freeze the base amount it prices and the account it pays, or the commit fingerprints values the price never pinned.",
+  "verdict": "invalid"
+}

package/conformance/invalid/quote-freeze-set-incomplete.udl

@@ -0,0 +1,261 @@
+{
+  "instruments": [
+    {
+      "actionOrder": [
+        "create",
+        "fund",
+        "dispute",
+        "quote",
+        "refund"
+      ],
+      "actions": {
+        "create": {
+          "description": "Opens escrow against an active listing and provisions its dedicated product escrow account. The amount, currency, and seller are derived from the locked listing -- never caller-supplied -- so escrow economics are the listing's by construction.",
+          "moves": [],
+          "steps": [
+            {
+              "bind": {
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "owner.id": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "owner.type": {
+                  "from": "const",
+                  "value": "product"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "role": {
+                  "from": "const",
+                  "value": "product_escrow"
+                }
+              },
+              "capture": {
+                "escrowAccountId": "accountId"
+              },
+              "operation": "account.escrow.provision"
+            }
+          ],
+          "summary": "Create an escrow order"
+        },
+        "dispute": {
+          "description": "Freezes the fully funded escrow before either milestone releases, preserving the entire balance while the parties decide what happens next.",
+          "moves": [],
+          "steps": [],
+          "summary": "Dispute an escrow order"
+        },
+        "fund": {
+          "description": "Moves the full purchase amount from the buyer account into the dedicated escrow account while the listing remains active.",
+          "moves": [
+            {
+              "bind": {
+                "amount": {
+                  "from": "instance",
+                  "path": "fields.amount"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "destinationAccountId": {
+                  "from": "instance",
+                  "path": "refs.escrowAccountId"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "sourceAccountId": {
+                  "from": "instance",
+                  "path": "fields.buyerAccountId"
+                }
+              },
+              "capture": {
+                "fundTransferId": "transferId"
+              },
+              "key": "transfer",
+              "operation": "internal_transfer.create"
+            }
+          ],
+          "sandboxFailurePoint": "funding",
+          "steps": [],
+          "summary": "Fund an escrow order"
+        },
+        "quote": {
+          "description": "Calculates the full buyer refund while disputed and parks the escrow for explicit confirmation. No money moves at quote time.",
+          "moves": [],
+          "quote": {
+            "baseField": "amount",
+            "chargeRef": "unwindPenalty",
+            "charges": [
+              {
+                "bps": 0
+              }
+            ],
+            "expires": {
+              "offset": "PT15M"
+            },
+            "fixes": [
+              "buyerAccountId"
+            ],
+            "netDestinationField": "buyerAccountId",
+            "netRef": "unwindRefund"
+          },
+          "steps": [],
+          "summary": "Quote an escrow refund"
+        },
+        "refund": {
+          "commit": "quote",
+          "description": "Confirms the quoted retreat and returns the full held amount from escrow to the buyer.",
+          "moves": [
+            {
+              "bind": {
+                "amount": {
+                  "from": "instance",
+                  "path": "refs.unwindRefund"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "destinationAccountId": {
+                  "from": "instance",
+                  "path": "fields.buyerAccountId"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "sourceAccountId": {
+                  "from": "instance",
+                  "path": "refs.escrowAccountId"
+                }
+              },
+              "capture": {
+                "refundTransferId": "transferId"
+              },
+              "key": "transfer",
+              "operation": "internal_transfer.create"
+            }
+          ],
+          "steps": [],
+          "summary": "Refund an escrow order"
+        }
+      },
+      "callerParkedStates": {
+        "created": "expire fires only when fundBy is set; without a funding deadline the escrow waits on the buyer to fund or cancel",
+        "disputed": "dispute resolution is a human judgment; the parties resume the escrow or quote a refund",
+        "funded": "releasing or disputing held value is a party decision; escrow deliberately holds until the parties act",
+        "refund_quoted": "a quoted refund moves money only when the caller confirms it"
+      },
+      "description": "An escrow order holds the full purchase amount and releases it to the seller exactly once. Before release, a dispute freezes the full balance until work resumes or a quoted refund is confirmed.",
+      "fields": {
+        "amount": {
+          "description": "Positive minor-unit integer amount serialized as a string (at most 18 digits)",
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string"
+        },
+        "buyerAccountId": {
+          "description": "Hyperscale account ID",
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string",
+          "x-hyperscale-reference-filter": {
+            "column": "role",
+            "values": [
+              "customer_balance"
+            ]
+          }
+        },
+        "currency": {
+          "description": "ISO 4217 currency code",
+          "maxLength": 3,
+          "minLength": 3,
+          "pattern": "^[A-Z]{3}$",
+          "type": "string"
+        },
+        "fundBy": {
+          "format": "hyperscale-date-time",
+          "type": "string"
+        },
+        "memo": {
+          "maxLength": 180,
+          "minLength": 1,
+          "type": "string"
+        },
+        "sellerAccountId": {
+          "description": "Hyperscale account ID",
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string",
+          "x-hyperscale-reference-filter": {
+            "column": "role",
+            "values": [
+              "customer_balance"
+            ]
+          }
+        }
+      },
+      "id": "escrow_order",
+      "idPrefix": "eord",
+      "lifecycle": {
+        "initial": "created",
+        "states": [
+          "created",
+          "funded",
+          "disputed",
+          "refunded",
+          "refund_quoted"
+        ],
+        "transitions": {
+          "dispute": {
+            "from": [
+              "funded"
+            ],
+            "to": "disputed"
+          },
+          "fund": {
+            "from": [
+              "created"
+            ],
+            "to": "funded"
+          },
+          "quote": {
+            "from": [
+              "disputed"
+            ],
+            "to": "refund_quoted"
+          },
+          "refund": {
+            "from": [
+              "refund_quoted"
+            ],
+            "to": "refunded"
+          }
+        }
+      },
+      "parties": {
+        "beneficiary": "sellerAccountId",
+        "payer": "buyerAccountId"
+      },
+      "required": [
+        "buyerAccountId",
+        "sellerAccountId",
+        "amount",
+        "currency"
+      ],
+      "summary": "An escrow order whose refund quote omits its own base field.",
+      "templateId": "escrow",
+      "title": "Escrow order"
+    }
+  ],
+  "product": "quote_freeze_set",
+  "subjects": [],
+  "title": "Quote freeze set",
+  "udl": 1,
+  "version": 1
+}

package/conformance/invalid/quote-named-reference-gate.expected.json

@@ -0,0 +1,10 @@
+{
+  "issues": [
+    {
+      "code": "UDL5001",
+      "path": "$.instruments[0].actions.quote.requiresRefs[0].field"
+    }
+  ],
+  "summary": "An action named quote does not change the code for an ordinary reference-gate defect.",
+  "verdict": "invalid"
+}

package/conformance/invalid/quote-named-reference-gate.udl

@@ -0,0 +1,50 @@
+{
+  "instruments": [
+    {
+      "actionOrder": ["create", "quote"],
+      "actions": {
+        "create": {
+          "moves": [],
+          "steps": [],
+          "summary": "File the note."
+        },
+        "quote": {
+          "moves": [],
+          "requiresRefs": [
+            {
+              "field": "reference",
+              "statuses": ["open"]
+            }
+          ],
+          "steps": [],
+          "summary": "Close the note."
+        }
+      },
+      "fields": {
+        "reference": {
+          "type": "string"
+        }
+      },
+      "id": "note",
+      "idPrefix": "note",
+      "lifecycle": {
+        "initial": "open",
+        "states": ["open", "closed"],
+        "transitions": {
+          "quote": {
+            "from": ["open"],
+            "to": "closed"
+          }
+        }
+      },
+      "required": ["reference"],
+      "summary": "A note a tenant files and later closes.",
+      "title": "Note"
+    }
+  ],
+  "product": "quote_named_reference_gate",
+  "subjects": [],
+  "title": "Quote named reference gate",
+  "udl": 1,
+  "version": 1
+}

package/conformance/invalid/reconcile-named-reference-gate.expected.json

@@ -0,0 +1,10 @@
+{
+  "issues": [
+    {
+      "code": "UDL5001",
+      "path": "$.instruments[0].actions.reconcile.requiresRefs[0].field"
+    }
+  ],
+  "summary": "An action named reconcile does not change the code for an ordinary reference-gate defect.",
+  "verdict": "invalid"
+}

package/conformance/invalid/reconcile-named-reference-gate.udl

@@ -0,0 +1,50 @@
+{
+  "instruments": [
+    {
+      "actionOrder": ["create", "reconcile"],
+      "actions": {
+        "create": {
+          "moves": [],
+          "steps": [],
+          "summary": "File the note."
+        },
+        "reconcile": {
+          "moves": [],
+          "requiresRefs": [
+            {
+              "field": "reference",
+              "statuses": ["open"]
+            }
+          ],
+          "steps": [],
+          "summary": "Close the note."
+        }
+      },
+      "fields": {
+        "reference": {
+          "type": "string"
+        }
+      },
+      "id": "note",
+      "idPrefix": "note",
+      "lifecycle": {
+        "initial": "open",
+        "states": ["open", "closed"],
+        "transitions": {
+          "reconcile": {
+            "from": ["open"],
+            "to": "closed"
+          }
+        }
+      },
+      "required": ["reference"],
+      "summary": "A note a tenant files and later closes.",
+      "title": "Note"
+    }
+  ],
+  "product": "reconcile_named_reference_gate",
+  "subjects": [],
+  "title": "Reconcile named reference gate",
+  "udl": 1,
+  "version": 1
+}

package/conformance/invalid/unknown-key.expected.json

@@ -1,7 +1,7 @@
 {
   "issues": [
     {
-      "code": "invalid_shape",
+      "code": "UDL1003",
       "path": "$"
     }
   ],