@hyperscale0/hsx 1.0.0-rc.1 → 1.0.123

package/std/reporting.hsx

@@ -0,0 +1,753 @@
+header reporting
+
+// Attach portfolio to one or more financing plans. Its only lifecycle action is
+// create; reports use the declared report request/read roles, not a money action.
+// Aging selects active facilities and includes earned profit when deciding arrears.
+// The default-rate report measures period-end stock, not new default incidence.
+// Paid facilities are excluded and write-offs counted separately. Amounts are SAR
+// minor units; declared scale and rounding govern ratios. Missing identity joins
+// or unreconciled schedule counts refuse.
+
+// Cost: portfolio.create declares no transfers, owned accounts or invocations.
+// That zero instruction count does not price report capture, rendering, storage or
+// release. The host owns those charges and their execution.
+
+instrument portfolio(on: ref<financing.installments>[], default_days: integer(1, 3650) = 90, retention_years: integer(1, 100) = 10, aging_first_days: integer(1, 3650) = 30, aging_second_days: integer(1, 3650) = 60, aging_third_days: integer(1, 3650) = 90, ratio_scale: integer(1, 1000000) = 10000, ratio_rounding: enum(floor, halfUp) = floor, lock_wait_ms: integer(1, 2000) = 2000, capture_ms: integer(1, 10000) = 10000, max_rows: integer(1, 100000) = 10000, max_join_rows: integer(1, 1000000) = 100000, max_bytes: integer(1024, 16777216) = 8388608) {
+  summary: "Declared financing reports evaluated over frozen Product facts."
+  fields {}
+  lifecycle { states: [declared], initial: declared }
+  action create {}
+  constraints { aging_first_days: less_than(aging_second_days), aging_second_days: less_than(aging_third_days) }
+  reports: [
+    {
+      identity: { id: "portfolio_aging", version: 1, description: "Period-end outstanding principal by oldest unpaid installment. Remaining scheduled profit is distinct from accrued profit. Restructuring evidence is unavailable." },
+      scope: { kind: "product", classification: "internal", currency: "SAR" },
+      datasets: [
+        {
+          id: "facilities",
+          source: "instrument",
+          instruments: on,
+          rowKey: "facilityId",
+          columns: [
+            {
+              name: "facilityId",
+              field: "id",
+              type: { kind: "text" },
+              required: true
+            },
+            {
+              name: "borrowerAccount",
+              field: "borrower",
+              type: { kind: "text" },
+              required: true
+            },
+            {
+              name: "state",
+              field: "status",
+              type: { kind: "text" },
+              required: true
+            },
+            {
+              name: "originalPrincipal",
+              field: "principal",
+              type: { kind: "money", currency: "SAR" },
+              required: true
+            },
+            {
+              name: "scheduleCount",
+              field: "months",
+              type: { kind: "integer" },
+              required: true
+            },
+            {
+              name: "recordedCreation",
+              field: "createdAt",
+              type: { kind: "date" },
+              required: true
+            }
+          ],
+          expressions: [
+            {
+              id: "activeState",
+              op: "literal",
+              type: { kind: "text" },
+              value: "active"
+            },
+            {
+              id: "paidState",
+              op: "literal",
+              type: { kind: "text" },
+              value: "paid"
+            },
+            {
+              id: "writtenState",
+              op: "literal",
+              type: { kind: "text" },
+              value: "written_off"
+            },
+            { id: "active", op: "equal", left: "state", right: "activeState" },
+            { id: "paid", op: "equal", left: "state", right: "paidState" },
+            { id: "writtenOff", op: "equal", left: "state", right: "writtenState" },
+            { id: "activeOrPaid", op: "or", left: "active", right: "paid" },
+            { id: "financed", op: "or", left: "active", right: "writtenOff" }
+          ],
+          selection: "active"
+        },
+        {
+          id: "schedule",
+          source: "instrument",
+          instruments: child(on, slice),
+          rowKey: "sliceId",
+          columns: [
+            {
+              name: "sliceId",
+              field: "id",
+              type: { kind: "text" },
+              required: true
+            },
+            {
+              name: "planId",
+              field: "plan",
+              type: { kind: "text" },
+              required: true
+            },
+            {
+              name: "due",
+              field: "dueAt",
+              type: { kind: "date" },
+              required: true
+            },
+            {
+              name: "principal",
+              field: "principalReceivable.balance",
+              type: { kind: "money", currency: "SAR" },
+              required: true
+            },
+            {
+              name: "profit",
+              field: "profitReceivable.balance",
+              type: { kind: "money", currency: "SAR" },
+              required: true
+            },
+            {
+              name: "earnedProfit",
+              field: "profitEarned.balance",
+              type: { kind: "money", currency: "SAR" },
+              required: true
+            },
+            {
+              name: "scheduledPrincipal",
+              field: "principal",
+              type: { kind: "money", currency: "SAR" },
+              required: true
+            }
+          ],
+          expressions: [
+            {
+              id: "zeroMoney",
+              op: "literal",
+              type: { kind: "money", currency: "SAR" },
+              value: "0"
+            },
+            {
+              id: "zeroDays",
+              op: "literal",
+              type: { kind: "integer" },
+              value: 0
+            },
+            { id: "observed", op: "parameter", name: "observationAt" },
+            { id: "scheduledOutstanding", op: "sum", left: "principal", right: "profit" },
+            { id: "totalOutstanding", op: "sum", left: "scheduledOutstanding", right: "earnedProfit" },
+            { id: "unpaid", op: "less", left: "zeroMoney", right: "totalOutstanding" },
+            { id: "elapsed", op: "daysBetween", left: "due", right: "observed" },
+            { id: "nonnegativeDays", op: "maximum", left: "elapsed", right: "zeroDays" },
+            { id: "daysPastDue", op: "choose", condition: "unpaid", yes: "nonnegativeDays", no: "zeroDays" }
+          ]
+        },
+        {
+          id: "borrowerAccounts",
+          source: "account",
+          instruments: [  ],
+          rowKey: "accountId",
+          columns: [
+            {
+              name: "accountId",
+              field: "id",
+              type: { kind: "text" },
+              required: true
+            },
+            {
+              name: "participant",
+              field: "ownerParticipantId",
+              type: { kind: "text" },
+              required: false
+            }
+          ],
+          expressions: [  ]
+        },
+        {
+          id: "borrowers",
+          source: "identity",
+          instruments: [  ],
+          rowKey: "customerId",
+          columns: [
+            {
+              name: "customerId",
+              field: "id",
+              type: { kind: "text" },
+              required: true
+            },
+            {
+              name: "participantId",
+              field: "participantId",
+              type: { kind: "text" },
+              required: true
+            },
+            {
+              name: "entityId",
+              field: "entityId",
+              type: { kind: "text" },
+              required: true
+            }
+          ],
+          expressions: [  ]
+        }
+      ],
+      time: { timezone: "Asia/Riyadh", boundary: "startInclusiveEndExclusive", observation: "periodEnd", history: "retainedOnly" },
+      selection: { dataset: "facilities" },
+      calculation: {
+        joins: [
+          {
+            dataset: "schedule",
+            local: "facilityId",
+            foreign: "planId",
+            cardinality: "many",
+            missing: "refuse",
+            aggregates: [
+              { name: "outstandingPrincipal", op: "sum", value: "principal" },
+              { name: "remainingScheduledProfit", op: "sum", value: "profit" },
+              { name: "scheduledPrincipalTotal", op: "sum", value: "scheduledPrincipal" },
+              { name: "capturedScheduleCount", op: "count" },
+              { name: "oldestUnpaidDays", op: "maximum", value: "daysPastDue" }
+            ]
+          },
+          {
+            dataset: "borrowerAccounts",
+            local: "borrowerAccount",
+            foreign: "accountId",
+            cardinality: "one",
+            missing: "refuse",
+            aggregates: [
+              { name: "borrowerParticipant", op: "minimum", value: "participant" }
+            ]
+          },
+          {
+            dataset: "borrowers",
+            local: "borrowerParticipant",
+            foreign: "participantId",
+            cardinality: "one",
+            missing: "refuse",
+            aggregates: [
+              { name: "borrowerEntity", op: "minimum", value: "entityId" }
+            ]
+          }
+        ],
+        expressions: [
+          {
+            id: "day0",
+            op: "literal",
+            type: { kind: "integer" },
+            value: 0
+          },
+          {
+            id: "day30",
+            op: "literal",
+            type: { kind: "integer" },
+            value: aging_first_days
+          },
+          {
+            id: "day60",
+            op: "literal",
+            type: { kind: "integer" },
+            value: aging_second_days
+          },
+          {
+            id: "day90",
+            op: "literal",
+            type: { kind: "integer" },
+            value: aging_third_days
+          },
+          {
+            id: "band0",
+            op: "literal",
+            type: { kind: "text" },
+            value: "current"
+          },
+          {
+            id: "band30",
+            op: "literal",
+            type: { kind: "text" },
+            value: "first"
+          },
+          {
+            id: "band60",
+            op: "literal",
+            type: { kind: "text" },
+            value: "second"
+          },
+          {
+            id: "band90",
+            op: "literal",
+            type: { kind: "text" },
+            value: "third"
+          },
+          {
+            id: "bandLate",
+            op: "literal",
+            type: { kind: "text" },
+            value: "later"
+          },
+          { id: "current", op: "atMost", left: "oldestUnpaidDays", right: "day0" },
+          { id: "first", op: "atMost", left: "oldestUnpaidDays", right: "day30" },
+          { id: "second", op: "atMost", left: "oldestUnpaidDays", right: "day60" },
+          { id: "third", op: "atMost", left: "oldestUnpaidDays", right: "day90" },
+          { id: "lateBand", op: "choose", condition: "third", yes: "band90", no: "bandLate" },
+          { id: "secondBand", op: "choose", condition: "second", yes: "band60", no: "lateBand" },
+          { id: "firstBand", op: "choose", condition: "first", yes: "band30", no: "secondBand" },
+          { id: "agingBand", op: "choose", condition: "current", yes: "band0", no: "firstBand" }
+        ],
+        groupBy: [ "agingBand" ],
+        aggregates: [
+          { name: "facilities", op: "count" },
+          { name: "principalMinor", op: "sum", value: "outstandingPrincipal" },
+          { name: "scheduledProfitMinor", op: "sum", value: "remainingScheduledProfit" }
+        ],
+        resultExpressions: [  ]
+      },
+      validation: {
+        empty: "noEligibleFacilities",
+        required: [ "borrowerEntity" ],
+        reconcile: [  ],
+        rowReconcile: [
+          { left: "originalPrincipal", right: "scheduledPrincipalTotal" },
+          { left: "scheduleCount", right: "capturedScheduleCount" }
+        ],
+        unavailableFacts: [  ],
+        lockTimeoutMs: lock_wait_ms,
+        captureTimeoutMs: capture_ms,
+        maxRows: max_rows,
+        maxJoinRows: max_join_rows,
+        maxBytes: max_bytes
+      },
+      output: {
+        profile: "internal.v1",
+        formats: [ "json", "csv" ],
+        columns: [
+          {
+            name: "agingBand",
+            label: "agingBand",
+            type: { kind: "text" }
+          },
+          {
+            name: "facilities",
+            label: "facilities",
+            type: { kind: "integer" }
+          },
+          {
+            name: "principalMinor",
+            label: "principalMinor",
+            type: { kind: "money", currency: "SAR" }
+          },
+          {
+            name: "scheduledProfitMinor",
+            label: "scheduledProfitMinor",
+            type: { kind: "money", currency: "SAR" }
+          }
+        ],
+        sort: [ "agingBand" ]
+      },
+      authority: {
+        request: [ "owner", "finance" ],
+        read: [ "owner", "admin", "operations", "finance", "viewer" ],
+        release: [  ],
+        retention: { policy: "report_replay", years: retention_years }
+      }
+    },
+    {
+      identity: { id: "period_end_outstanding_principal_default_rate", version: 1, description: "Current active facilities with any unpaid installment at least the declared default days past due, observed at period end. Cure when arrears clear. Count and outstanding-principal weighted rates in the declared scale exclude paid and written-off facilities; write-offs are counted separately. This is a stock measure, not a new-default incidence or origination cohort rate." },
+      scope: { kind: "product", classification: "internal", currency: "SAR" },
+      datasets: [
+        {
+          id: "facilities",
+          source: "instrument",
+          instruments: on,
+          rowKey: "facilityId",
+          columns: [
+            {
+              name: "facilityId",
+              field: "id",
+              type: { kind: "text" },
+              required: true
+            },
+            {
+              name: "borrowerAccount",
+              field: "borrower",
+              type: { kind: "text" },
+              required: true
+            },
+            {
+              name: "state",
+              field: "status",
+              type: { kind: "text" },
+              required: true
+            },
+            {
+              name: "originalPrincipal",
+              field: "principal",
+              type: { kind: "money", currency: "SAR" },
+              required: true
+            },
+            {
+              name: "scheduleCount",
+              field: "months",
+              type: { kind: "integer" },
+              required: true
+            },
+            {
+              name: "recordedCreation",
+              field: "createdAt",
+              type: { kind: "date" },
+              required: true
+            }
+          ],
+          expressions: [
+            {
+              id: "activeState",
+              op: "literal",
+              type: { kind: "text" },
+              value: "active"
+            },
+            {
+              id: "paidState",
+              op: "literal",
+              type: { kind: "text" },
+              value: "paid"
+            },
+            {
+              id: "writtenState",
+              op: "literal",
+              type: { kind: "text" },
+              value: "written_off"
+            },
+            { id: "active", op: "equal", left: "state", right: "activeState" },
+            { id: "paid", op: "equal", left: "state", right: "paidState" },
+            { id: "writtenOff", op: "equal", left: "state", right: "writtenState" },
+            { id: "activeOrPaid", op: "or", left: "active", right: "paid" },
+            { id: "financed", op: "or", left: "active", right: "writtenOff" }
+          ],
+          selection: "financed"
+        },
+        {
+          id: "schedule",
+          source: "instrument",
+          instruments: child(on, slice),
+          rowKey: "sliceId",
+          columns: [
+            {
+              name: "sliceId",
+              field: "id",
+              type: { kind: "text" },
+              required: true
+            },
+            {
+              name: "planId",
+              field: "plan",
+              type: { kind: "text" },
+              required: true
+            },
+            {
+              name: "due",
+              field: "dueAt",
+              type: { kind: "date" },
+              required: true
+            },
+            {
+              name: "principal",
+              field: "principalReceivable.balance",
+              type: { kind: "money", currency: "SAR" },
+              required: true
+            },
+            {
+              name: "profit",
+              field: "profitReceivable.balance",
+              type: { kind: "money", currency: "SAR" },
+              required: true
+            },
+            {
+              name: "earnedProfit",
+              field: "profitEarned.balance",
+              type: { kind: "money", currency: "SAR" },
+              required: true
+            },
+            {
+              name: "scheduledPrincipal",
+              field: "principal",
+              type: { kind: "money", currency: "SAR" },
+              required: true
+            }
+          ],
+          expressions: [
+            {
+              id: "zeroMoney",
+              op: "literal",
+              type: { kind: "money", currency: "SAR" },
+              value: "0"
+            },
+            {
+              id: "zeroDays",
+              op: "literal",
+              type: { kind: "integer" },
+              value: 0
+            },
+            { id: "observed", op: "parameter", name: "observationAt" },
+            { id: "scheduledOutstanding", op: "sum", left: "principal", right: "profit" },
+            { id: "totalOutstanding", op: "sum", left: "scheduledOutstanding", right: "earnedProfit" },
+            { id: "unpaid", op: "less", left: "zeroMoney", right: "totalOutstanding" },
+            { id: "elapsed", op: "daysBetween", left: "due", right: "observed" },
+            { id: "nonnegativeDays", op: "maximum", left: "elapsed", right: "zeroDays" },
+            { id: "daysPastDue", op: "choose", condition: "unpaid", yes: "nonnegativeDays", no: "zeroDays" }
+          ]
+        },
+        {
+          id: "borrowerAccounts",
+          source: "account",
+          instruments: [  ],
+          rowKey: "accountId",
+          columns: [
+            {
+              name: "accountId",
+              field: "id",
+              type: { kind: "text" },
+              required: true
+            },
+            {
+              name: "participant",
+              field: "ownerParticipantId",
+              type: { kind: "text" },
+              required: false
+            }
+          ],
+          expressions: [  ]
+        },
+        {
+          id: "borrowers",
+          source: "identity",
+          instruments: [  ],
+          rowKey: "customerId",
+          columns: [
+            {
+              name: "customerId",
+              field: "id",
+              type: { kind: "text" },
+              required: true
+            },
+            {
+              name: "participantId",
+              field: "participantId",
+              type: { kind: "text" },
+              required: true
+            },
+            {
+              name: "entityId",
+              field: "entityId",
+              type: { kind: "text" },
+              required: true
+            }
+          ],
+          expressions: [  ]
+        }
+      ],
+      time: { timezone: "Asia/Riyadh", boundary: "startInclusiveEndExclusive", observation: "periodEnd", history: "retainedOnly" },
+      selection: { dataset: "facilities" },
+      calculation: {
+        joins: [
+          {
+            dataset: "schedule",
+            local: "facilityId",
+            foreign: "planId",
+            cardinality: "many",
+            missing: "refuse",
+            aggregates: [
+              { name: "outstandingPrincipal", op: "sum", value: "principal" },
+              { name: "remainingScheduledProfit", op: "sum", value: "profit" },
+              { name: "scheduledPrincipalTotal", op: "sum", value: "scheduledPrincipal" },
+              { name: "capturedScheduleCount", op: "count" },
+              { name: "oldestUnpaidDays", op: "maximum", value: "daysPastDue" }
+            ]
+          },
+          {
+            dataset: "borrowerAccounts",
+            local: "borrowerAccount",
+            foreign: "accountId",
+            cardinality: "one",
+            missing: "refuse",
+            aggregates: [
+              { name: "borrowerParticipant", op: "minimum", value: "participant" }
+            ]
+          },
+          {
+            dataset: "borrowers",
+            local: "borrowerParticipant",
+            foreign: "participantId",
+            cardinality: "one",
+            missing: "refuse",
+            aggregates: [
+              { name: "borrowerEntity", op: "minimum", value: "entityId" }
+            ]
+          }
+        ],
+        expressions: [
+          {
+            id: "threshold",
+            op: "literal",
+            type: { kind: "integer" },
+            value: default_days
+          },
+          {
+            id: "zero",
+            op: "literal",
+            type: { kind: "integer" },
+            value: 0
+          },
+          {
+            id: "one",
+            op: "literal",
+            type: { kind: "integer" },
+            value: 1
+          },
+          {
+            id: "zeroMoney",
+            op: "literal",
+            type: { kind: "money", currency: "SAR" },
+            value: "0"
+          },
+          { id: "pastThreshold", op: "atMost", left: "threshold", right: "oldestUnpaidDays" },
+          { id: "isDefault", op: "and", left: "active", right: "pastThreshold" },
+          { id: "activeCount", op: "choose", condition: "active", yes: "one", no: "zero" },
+          { id: "defaultCount", op: "choose", condition: "isDefault", yes: "one", no: "zero" },
+          { id: "writeOffCount", op: "choose", condition: "writtenOff", yes: "one", no: "zero" },
+          { id: "activePrincipal", op: "choose", condition: "active", yes: "outstandingPrincipal", no: "zeroMoney" },
+          { id: "defaultPrincipal", op: "choose", condition: "isDefault", yes: "outstandingPrincipal", no: "zeroMoney" }
+        ],
+        groupBy: [  ],
+        aggregates: [
+          { name: "activeFacilities", op: "sum", value: "activeCount" },
+          { name: "defaultFacilities", op: "sum", value: "defaultCount" },
+          { name: "writtenOffFacilities", op: "sum", value: "writeOffCount" },
+          { name: "activePrincipalMinor", op: "sum", value: "activePrincipal" },
+          { name: "defaultPrincipalMinor", op: "sum", value: "defaultPrincipal" }
+        ],
+        resultExpressions: [
+          { id: "countRate", op: "ratio", numerator: "defaultFacilities", denominator: "activeFacilities", scale: ratio_scale, rounding: ratio_rounding, zero: "null" },
+          { id: "principalRate", op: "ratio", numerator: "defaultPrincipalMinor", denominator: "activePrincipalMinor", scale: ratio_scale, rounding: ratio_rounding, zero: "null" },
+          {
+            id: "restructuringEvidence",
+            op: "literal",
+            type: { kind: "text" },
+            value: "unavailable"
+          },
+          {
+            id: "defaultDays",
+            op: "literal",
+            type: { kind: "integer" },
+            value: default_days
+          },
+          {
+            id: "rateScale",
+            op: "literal",
+            type: { kind: "integer" },
+            value: ratio_scale
+          }
+        ]
+      },
+      validation: {
+        empty: "refuse",
+        required: [ "borrowerEntity" ],
+        reconcile: [  ],
+        rowReconcile: [
+          { left: "originalPrincipal", right: "scheduledPrincipalTotal" },
+          { left: "scheduleCount", right: "capturedScheduleCount" }
+        ],
+        unavailableFacts: [  ],
+        lockTimeoutMs: lock_wait_ms,
+        captureTimeoutMs: capture_ms,
+        maxRows: max_rows,
+        maxJoinRows: max_join_rows,
+        maxBytes: max_bytes
+      },
+      output: {
+        profile: "internal.v1",
+        formats: [ "json", "csv" ],
+        columns: [
+          {
+            name: "activeFacilities",
+            label: "activeFacilities",
+            type: { kind: "integer" }
+          },
+          {
+            name: "defaultFacilities",
+            label: "defaultFacilities",
+            type: { kind: "integer" }
+          },
+          {
+            name: "writtenOffFacilities",
+            label: "writtenOffFacilities",
+            type: { kind: "integer" }
+          },
+          {
+            name: "activePrincipalMinor",
+            label: "activePrincipalMinor",
+            type: { kind: "money", currency: "SAR" }
+          },
+          {
+            name: "defaultPrincipalMinor",
+            label: "defaultPrincipalMinor",
+            type: { kind: "money", currency: "SAR" }
+          },
+          {
+            name: "countRate",
+            label: "countRate",
+            type: { kind: "integer" }
+          },
+          {
+            name: "principalRate",
+            label: "principalRate",
+            type: { kind: "integer" }
+          },
+          {
+            name: "restructuringEvidence",
+            label: "restructuringEvidence",
+            type: { kind: "text" }
+          },
+          {
+            name: "defaultDays",
+            label: "defaultDays",
+            type: { kind: "integer" }
+          },
+          {
+            name: "rateScale",
+            label: "rateScale",
+            type: { kind: "integer" }
+          }
+        ],
+        sort: [ "activeFacilities" ]
+      },
+      authority: {
+        request: [ "owner", "finance" ],
+        read: [ "owner", "admin", "operations", "finance", "viewer" ],
+        release: [  ],
+        retention: { policy: "report_replay", years: retention_years }
+      }
+    }
+  ]
+}