Event Directive¶

Overview¶

The event directive tracks the value of a named variable over time. Events are useful for recording non-financial information that changes throughout the ledger's timeline.

Syntax¶

event = date WHITESPACE "event" WHITESPACE name WHITESPACE value
        (NEWLINE metadata)*

name  = string
value = string

Components¶

Date¶

The date the event occurs or the value changes.

Name¶

A string identifying the type of event (the variable being tracked).

Value¶

A string representing the new value of the variable.

Examples¶

Location Tracking¶

2024-01-01 event "location" "New York, USA"
2024-03-15 event "location" "London, UK"
2024-06-01 event "location" "Berlin, Germany"
2024-09-01 event "location" "New York, USA"

Employment Status¶

2020-06-01 event "employer" "Acme Corp"
2022-09-15 event "employer" "TechStart Inc"
2024-01-01 event "employer" "BigCo"

Life Events¶

2023-05-20 event "status" "married"
2024-02-15 event "status" "parent"

Tax Residence¶

2024-01-01 event "tax-residence" "USA"
2024-07-01 event "tax-residence" "Germany"

With Metadata¶

2024-03-15 event "location" "London, UK"
  reason: "work assignment"
  duration: "3 months"
  visa-type: "work"

Use Cases¶

Travel Tracking¶

; Track trips for tax or expense allocation
2024-01-01 event "location" "Home"
2024-02-10 event "location" "Conference - Las Vegas"
2024-02-14 event "location" "Home"
2024-03-01 event "location" "Client Site - Chicago"
2024-03-05 event "location" "Home"

Project Tracking¶

; Track active projects
2024-01-01 event "project" "Website Redesign"
2024-04-01 event "project" "Mobile App"
2024-07-01 event "project" "API Integration"

Vehicle Tracking¶

2020-01-15 event "car" "2020 Toyota Camry"
2024-03-01 event "car" "2024 Tesla Model 3"

Address History¶

2020-06-01 event "address" "123 Main St, Apt 4B, New York, NY 10001"
2023-08-15 event "address" "456 Oak Ave, Brooklyn, NY 11201"

Querying Events¶

Events can be queried in BQL:

-- Get all location changes
SELECT date, value FROM events WHERE type = "location"

-- Get location at specific date
SELECT value FROM events
WHERE type = "location" AND date <= 2024-06-15
ORDER BY date DESC LIMIT 1

Reporting¶

Events enable time-based reporting:

; Expenses by location
2024-01-01 event "location" "New York"
2024-01-15 * "Lunch"
  Expenses:Food  25 USD
  Assets:Cash

2024-02-01 event "location" "London"
2024-02-15 * "Lunch"
  Expenses:Food  20 GBP
  Assets:Cash

; Report can show:
; New York: 25 USD in expenses
; London: 20 GBP in expenses

Event vs. Metadata¶

Use events for: - Values that change over time - Information spanning multiple transactions - Variables you want to query across the ledger

Use metadata for: - Static information attached to specific directives - Per-transaction details - Non-temporal attributes

Validation¶

Events have no specific validation errors. All fields are free-form strings.

However, implementations MAY warn about: - Duplicate events (same name/value on same date) - Events with empty values

Common Event Types¶

Event Name	Purpose
`location`	Physical location tracking
`employer`	Employment history
`address`	Residence address
`status`	Life status changes
`project`	Active project tracking
`tax-residence`	Tax jurisdiction
`vehicle`	Vehicle ownership

Implementation Notes¶

Store events in a timeline indexed by name
Enable lookup of value at any date
Support querying event history
Events don't affect financial calculations
Consider indexing for efficient date-range queries