Merge pull request #831 from smucclaw/thomasgorissen/update-libs-and-actus-docs

serrynaimo · web-flow · commit e6d34c999155 · 2026-02-23T21:24:56.000+08:00
Update core libraries and add ACTUS documentation
diff --git a/doc/reference/GLOSSARY.md b/doc/reference/GLOSSARY.md
@@ -253,6 +253,7 @@ For complete documentation, see **[Libraries Reference](libraries/README.md)**.
 | ----------------- | ------------------------------------ |
 | **prelude**       | Standard functions (always imported) |
 | **daydate**       | Date calculations and temporal logic |
+| **actus**         | ACTUS financial contract standards   |
 | **excel-date**    | Excel date compatibility             |
 | **math**          | Mathematical functions               |
 | **currency**      | ISO 4217 currency handling           |
diff --git a/doc/reference/libraries/README.md b/doc/reference/libraries/README.md
@@ -14,6 +14,7 @@ Core libraries are located in the [jl4-core/libraries/](https://github.com/smucc
 - **[legal-persons](legal-persons.md)** - Legal entity types and capacity
 - **[jurisdiction](jurisdiction.md)** - Jurisdiction definitions
 - **[holdings](holdings.md)** - Holdings and ownership
+- **[actus](actus.md)** - ACTUS financial contract types and evaluation
 - **[date-compat](date-compat.md)** - Legacy DATE syntax compatibility
 - **[llm](llm.md)** - LLM API integration
 
diff --git a/doc/reference/libraries/actus.md b/doc/reference/libraries/actus.md
@@ -0,0 +1,116 @@
+# ACTUS Library
+
+Algorithmic Contract Types Unified Standards ([actusfrf.org](https://www.actusfrf.org)) implementation in L4. Provides types and functions for modelling standardised financial contracts.
+
+Import with `IMPORT actus` to get all modules, or import individual modules selectively.
+
+### Location
+
+| File                                                                                                   | Purpose                                   |
+| ------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
+| [actus.l4](https://github.com/smucclaw/l4-ide/blob/main/jl4-core/libraries/actus.l4)                   | Main entry point (re-exports all modules) |
+| [actus-core.l4](https://github.com/smucclaw/l4-ide/blob/main/jl4-core/libraries/actus-core.l4)         | Core types (contract types, roles, enums) |
+| [actus-terms.l4](https://github.com/smucclaw/l4-ide/blob/main/jl4-core/libraries/actus-terms.l4)       | Contract term definitions                 |
+| [actus-state.l4](https://github.com/smucclaw/l4-ide/blob/main/jl4-core/libraries/actus-state.l4)       | Contract state variables                  |
+| [actus-events.l4](https://github.com/smucclaw/l4-ide/blob/main/jl4-core/libraries/actus-events.l4)     | Event types and operations                |
+| [actus-daycount.l4](https://github.com/smucclaw/l4-ide/blob/main/jl4-core/libraries/actus-daycount.l4) | Day count conventions and year fractions  |
+| [actus-schedule.l4](https://github.com/smucclaw/l4-ide/blob/main/jl4-core/libraries/actus-schedule.l4) | Schedule generation                       |
+
+### Core Types (`actus-core`)
+
+**Contract Type Taxonomy** (~32 ACTUS contract types organised into families):
+
+- `Basic Contract Type` — PAM, LAM, NAM, ANN, CLM, CSH, STK, UMP, COM
+- `Exotic Basic Contract Type` — LAX, NAX, ANX
+- `Combined Contract Type` — SWAPS, SWPPV, OPTNS, FUTUR, FXOUT, CAPFL, BCS
+- `Credit Enhancement Contract Type` — CEG, CEC, MAR
+
+**Contract Role** — RPA, RPL, CLO, CNO, COL, LG, ST, BUY, SEL, RFL, PFL, RF, PF
+
+- `` `role sign` `` — sign multiplier for payoff calculations (+1 or -1)
+
+**Contract Performance** — PF (performant), DL (delayed), DQ (delinquent), DF (default), MA (matured), TE (terminated)
+
+- `` `is non-performing` ``, `` `is active` `` — performance predicates
+
+**Day Count Convention** — AA, A360, A365, `30E360`, `30E360ISDA`, BUS252
+
+**Other Enums:**
+
+- `End of Month Convention` — EOM, SD, EOMP
+- `Business Day Convention` — SCR, SCRF, SCRP, SCRMF, SCRMP
+- `Calendar Type` — NoCalendar, MondayToFriday, Calendar
+- `Period Unit` — Days, Weeks, Months, Quarters, Years
+- `Stub Convention` — Long/Short Initial/Final
+- `Interest Payment Convention` — PayInterest, CapitalizeInterest
+- `Penalty Type` — NoPenalty, AbsolutePenalty, RelativePenalty, InterestPenalty
+- `Option Type` / `Option Exercise Type` — Call, Put, Straddle / European, American, Bermudan
+- `Scaling Effect` — NoScaling, InterestScaling, PrincipalScaling, BothScaling
+- `ACTUS Currency` — USD, EUR, GBP, JPY, CHF, CAD, AUD, CNY, HKD, SGD, or custom via `ACTUS Other`
+
+**Cycle** — record with `period`, `periodUnit`, `stub`; convenience constructors: `` `Monthly Cycle` ``, `` `Quarterly Cycle` ``, `` `Semi-Annual Cycle` ``, `` `Annual Cycle` ``
+
+### Contract Terms (`actus-terms`)
+
+- `ACTUS Contract Terms` — core contract parameters (ID, type, role, dates, principal, rate, day count convention)
+- `FXOUT Terms` — FX outright transaction parameters
+- `` `implied exchange rate` `` — derive rate from FX term amounts
+
+### Contract State (`actus-state`)
+
+- `Contract State` — runtime state (statusDate, contractPerformance, notionalPrincipal, accruedInterest, nominalInterestRate, feeAccrued)
+- `` `is fully paid` ``, `` `is in default` ``, `` `outstanding balance` `` — state predicates
+- `` `empty state` `` — default initial state
+
+### Contract Events (`actus-events`)
+
+**Event Types:** IED, PR, PP, MD, IP, IPCI, RR, RRF, FP, PY, TD, XD, STD, DV, CE, AD
+
+- `Contract Event` — record with eventType, eventDate, payoff, currency, notionalPrincipal, nominalInterestRate, accruedInterest
+- `` `make event` `` — event constructor
+- `` `event sequence` ``, `` `event name` ``, `` `event acronym` `` — event metadata
+- `` `is principal event` ``, `` `is interest event` ``, `` `has cash flow` `` — event predicates
+- `` `total payoff` `` — sum payoffs across a list of events
+
+### Day Count Conventions (`actus-daycount`)
+
+- `` `year fraction` `` — Y(S,E) calculation dispatching on convention
+- `` `year fraction A365` ``, `` `year fraction A360` `` — specific convention implementations
+- `` `days between` `` — raw day count between two dates
+- `` `accrued interest for period` `` — interest accrual given principal, rate, dates, and convention
+
+### Schedule Generation (`actus-schedule`)
+
+- `` `add months` ``, `` `add days` `` — date arithmetic with month-end clamping
+- `` `monthly schedule` `` — generate a list of monthly dates from a start date
+- `` `schedule length` `` — count dates in a schedule
+
+### Evaluation Engine (`actus`)
+
+**Payoff Functions (POF):**
+
+- `` `POF_IED` `` — Initial Exchange Date payoff
+- `` `POF_IP` `` — Interest Payment payoff
+- `` `POF_MD` `` — Maturity payoff
+- `` `POF_PR` `` — Principal Redemption payoff
+
+**State Transition Functions (STF):**
+
+- `` `STF_IED` `` — initialise state after initial exchange
+- `` `STF_IP` `` — reset accrued interest after payment
+- `` `STF_MD` `` — contract reaches maturity
+- `` `STF_PR` `` — reduce notional by redemption amount
+
+**Interest Accrual:**
+
+- `` `accrue interest to` `` — accrue interest from current state date to a target date
+
+**FX Transaction (FXOUT):**
+
+- `` `FXOUT pay event` ``, `` `FXOUT receive event` `` — generate FX cash flow events
+
+**Cash Flow Projection:**
+
+- `` `net cash flow` `` — sum all cash flows from a list of events
+
+**See the [actus.l4](https://github.com/smucclaw/l4-ide/blob/main/jl4-core/libraries/actus.l4) source and sub-modules for full details.**
diff --git a/doc/reference/libraries/date-compat.md b/doc/reference/libraries/date-compat.md
@@ -12,3 +12,13 @@ Provides the uppercase DATE constructor for code that used the old record-based
 
 **Legacy syntax:** DATE 15 3 1990
 **Modern syntax:** Date 15 3 1990
+
+### Field Accessor Helpers
+
+Named functions to extract date components:
+
+- `` `Day of` `` / `` `day of` `` — extract day from date (`DATE_DAY`)
+- `` `Month of` `` / `` `month of` `` — extract month from date (`DATE_MONTH`)
+- `` `Year of` `` / `` `year of` `` — extract year from date (`DATE_YEAR`)
+
+Each accessor has a capitalised primary name and a lowercase `AKA` alias.
diff --git a/doc/reference/libraries/daydate.md b/doc/reference/libraries/daydate.md
@@ -1,7 +1,7 @@
 # Daydate Library
 
 Date arithmetic and temporal logic for legal deadlines and time-based rules. Follows ISO 8601 conventions.
-Can be imported into L4 files with `IMPORT daydate`.
+Can be imported into L4 files with `IMPORT daydate`. Automatically imports `date-compat` for backwards-compatible DATE accessors.
 
 ### Location
 
diff --git a/doc/reference/libraries/prelude.md b/doc/reference/libraries/prelude.md
@@ -21,6 +21,7 @@ The prelude can be imported into every L4 program with `IMPORT prelude` and prov
 
 - `map` - Apply function to each element
 - `filter` - Keep elements matching predicate
+- `count` - Count number of elements in a list
 - `take` - First n elements
 - `drop` - All but first n elements
 - `takeWhile` / `dropWhile` - Conditional take/drop
diff --git a/jl4-core/libraries/date-compat.l4 b/jl4-core/libraries/date-compat.l4
@@ -14,9 +14,6 @@
 --
 -- If you need the old field accessor style, use the helpers below.
 
-IMPORT prelude
-IMPORT daydate
-
 §§ `DATE Constructor Alias`
 
 -- Provides DATE as an alias for Date for backwards compatibility
@@ -34,32 +31,14 @@ GIVETH A DATE
 
 §§ `Field Accessor Helpers`
 
--- These provide named functions to replace the old field accessor syntax
--- Usage: `day of` someDate  (instead of someDate's day)
-
-GIVEN date IS A DATE
-GIVETH A NUMBER
-`day of` MEANS DATE_DAY date
-
-GIVEN date IS A DATE
-GIVETH A NUMBER
-`month of` MEANS DATE_MONTH date
-
-GIVEN date IS A DATE
-GIVETH A NUMBER
-`year of` MEANS DATE_YEAR date
-
--- Alternative postfix style accessors
--- Usage: someDate's `the day`
-
 GIVEN date IS A DATE
 GIVETH A NUMBER
-`the day` date MEANS DATE_DAY date
+`Day of` AKA `day of` MEANS DATE_DAY date
 
 GIVEN date IS A DATE
 GIVETH A NUMBER
-`the month` date MEANS DATE_MONTH date
+`Month of` AKA `month of` MEANS DATE_MONTH date
 
 GIVEN date IS A DATE
 GIVETH A NUMBER
-`the year` date MEANS DATE_YEAR date
+`Year of` AKA `year of` MEANS DATE_YEAR date
diff --git a/jl4-core/libraries/daydate.l4 b/jl4-core/libraries/daydate.l4
@@ -5,7 +5,7 @@
 -- A week begins on Monday
 -- Check the test/daydate.l4 file to see examples
 
-
+IMPORT `date-compat`
 
 
 §§ `Constants`
@@ -322,7 +322,6 @@ GIVETH A NUMBER
 
 
 
-
 §§ `Weekday Functions`
 
 
diff --git a/jl4-core/libraries/prelude.l4 b/jl4-core/libraries/prelude.l4
@@ -96,6 +96,17 @@ filter f list MEANS
       THEN x FOLLOWED BY filter f xs
       ELSE filter f xs
 
+GIVEN a    IS A TYPE
+      list IS A LIST OF a
+GIVETH A NUMBER
+count list MEANS
+  go 0 list
+  WHERE
+    go acc l MEANS
+      CONSIDER l
+        WHEN EMPTY THEN acc
+        WHEN x FOLLOWED BY xs THEN go (acc + 1) xs
+
 GIVEN
   a    IS A TYPE
   list IS A LIST OF a
