Add agreements, events, and options

Agreements

An agreement is attached to an entity and may have date bounds and named terms:

import { agreement, agreementTerm, cashflow, currencies, defineModel, entity, inflow, periods, schedule } from "deccf";

const property = entity.asset();
const landlord = entity.party();
const tenant = entity.party();
const monthlyRent = agreementTerm(12_000);
const lease = agreement({
  subject: property,
  parties: { landlord, tenant },
  from: "2026-01",
  to: "2027-12",
  terms: { monthlyRent },
});
const rent = cashflow({
  owner: property,
  agreement: lease,
  direction: inflow,
  schedule: schedule.monthly(),
  amount: (ctx) => ctx.term(lease, monthlyRent),
});
const model = defineModel({
  name: "rental-agreement",
  currency: currencies.SEK,
  timeline: periods.monthly({ from: "2026-01", count: 24 }),
  entities: { property, landlord, tenant },
  agreements: { lease },
  flows: { rent },
});
return model;

subject is the entity the agreement concerns. parties maps agreement roles to party entities. A cashflow with agreement: lease is limited to the agreement's active dates. Read a term with ctx.term(lease, monthlyRent). Agreements do not create payments: declare each cashflow separately and link it to the agreement.

An ongoing balance is an Account, not an entity or a cashflow. With multiple-account postings, declare debit and credit rows and put reporting categories on the accounts. The engine then records both account balances and category movements. ctx.previous(accountRef) reads the opening balance for the current period, and result.account(accountRef) returns closing balances. See Post cashflows to accounts for sign conventions.

For simpler models, moves: accountRef still links a cashflow to one balance. The account's side (owed or due) decides whether a signed cashflow increases or decreases that balance. This form does not create double-entry postings or account-category movements.

Events and actions

An event can run when a condition changes from false to true or at scheduled dates. It can change state, update a numeric field, or activate/deactivate a cashflow.

Open in calculator

import { actions, cashflow, currencies, defineModel, entity, event, inflow, lifecycle, periods, schedule, state } from "deccf";

const available = state("available");
const sold = state("sold");
const life = lifecycle({
  states: [available, sold],
  initial: available,
  transitions: [{ from: available, to: sold, when: (ctx) => ctx.time.index === 11 }],
});
const property = entity.asset({ lifecycle: life });
const rent = cashflow({ owner: property, direction: inflow, schedule: schedule.monthly(), amount: 2_000 });
const closeEvent = event({
  when: (ctx) => ctx.isInState(property, sold),
  actions: [actions.deactivate(rent)],
});
const model = defineModel({
  name: "stop-rent-after-sale",
  currency: currencies.SEK,
  timeline: periods.monthly({ from: "2026-01", count: 24 }),
  entities: { property },
  flows: { rent },
  events: { closeEvent },
});
return model;

An event without a schedule fires on the false-to-true transition; it does not repeat while the condition remains true. A scheduled event checks its condition in scheduled periods. Same-period changes follow the engine's order between state updates, agreement boundaries, events, and cashflow evaluation.

Options

An option has an exercise condition, a payoff function, and optional subject, direction, currency, schedule, and exercise limit. Without a schedule, it is checked at period end every period. The engine exercises it when the condition changes from false to true at a check. The default limit is one exercise. For another exercise, the condition must become false and then true again, within the maxExercises limit.

Open in calculator

import { currencies, defineModel, entity, field, inflow, option, periods, schedule } from "deccf";

const propertyValue = field({ initial: 1_800_000, next: (previous) => previous * 1.03 });
const property = entity.asset({ fields: { propertyValue } });
const exit = option({
  subject: property,
  direction: inflow,
  currency: currencies.SEK,
  when: (ctx) => ctx.get(propertyValue) >= 2_000_000,
  payoff: (ctx) => ctx.get(propertyValue),
});
const model = defineModel({
  name: "property-exit-option",
  currency: currencies.SEK,
  timeline: periods.annual({ from: "2026-01", count: 12 }),
  entities: { property },
  options: { exit },
});
return model;

The payoff is published as a separate result series. It does not automatically change other cashflows.

Next: Declare allocations and fund needs.