Merge branch 'main' of https://git.joeac.net/joeac/schist

39 files changed, 279 insertions, 44 deletions

diff --git a/requirements/cardi/ass-001.md b/requirements/assumptions/ass-001.md
index d478b4c..d478b4c 100644
--- a/requirements/cardi/ass-001.md
+++ b/requirements/assumptions/ass-001.md
diff --git a/requirements/cardi/ass-002.md b/requirements/assumptions/ass-002.md
index bac06f4..bac06f4 100644
--- a/requirements/cardi/ass-002.md
+++ b/requirements/assumptions/ass-002.md
diff --git a/requirements/cardi/ass-003.md b/requirements/assumptions/ass-003.md
index 2e7238a..2e7238a 100644
--- a/requirements/cardi/ass-003.md
+++ b/requirements/assumptions/ass-003.md
diff --git a/requirements/cardi/ass-004.md b/requirements/assumptions/ass-004.md
index 0f37751..0f37751 100644
--- a/requirements/cardi/ass-004.md
+++ b/requirements/assumptions/ass-004.md
diff --git a/requirements/cardi/ass-005.md b/requirements/assumptions/ass-005.md
index 0aba515..0aba515 100644
--- a/requirements/cardi/ass-005.md
+++ b/requirements/assumptions/ass-005.md
diff --git a/requirements/cardi/ass-006.md b/requirements/assumptions/ass-006.md
index 0041795..0041795 100644
--- a/requirements/cardi/ass-006.md
+++ b/requirements/assumptions/ass-006.md
diff --git a/requirements/cardi/ass-007.md b/requirements/assumptions/ass-007.md
index 32722b9..32722b9 100644
--- a/requirements/cardi/ass-007.md
+++ b/requirements/assumptions/ass-007.md
diff --git a/requirements/assumptions/ass-008.md b/requirements/assumptions/ass-008.md
new file mode 100644
index 0000000..2d2f9dd
--- /dev/null
+++ b/requirements/assumptions/ass-008.md
@@ -0,0 +1,4 @@
+# ass-008
+
+The accurate balance of a bucket is the difference between the amounts of the
+drips into it and the amounts of the transactions out of it.
\ No newline at end of file
diff --git a/requirements/catalogue/req-000.md b/requirements/catalogue/req-000.md
index 6f54440..02ee740 100644
--- a/requirements/catalogue/req-000.md
+++ b/requirements/catalogue/req-000.md
@@ -1,6 +1,6 @@
 # req-000
 
-As a user, I want my incomings to equal my outgoings in the long run, so that I
-don't go bankrupt.
+As a user, I want my outgoings not to exceed my incomings in the long run, so
+that I don't go bankrupt.
 
-Source: user need.
+Source: need-000
diff --git a/requirements/catalogue/req-001.md b/requirements/catalogue/req-001.md
index 12bef30..2161790 100644
--- a/requirements/catalogue/req-001.md
+++ b/requirements/catalogue/req-001.md
@@ -2,4 +2,4 @@
 
 As a user, I want to control what I do with my money, so that I use money well.
 
-Source: user need.
+Source: need-001
diff --git a/requirements/catalogue/req-002.md b/requirements/catalogue/req-002.md
index 36bc9f8..55fcb43 100644
--- a/requirements/catalogue/req-002.md
+++ b/requirements/catalogue/req-002.md
@@ -6,5 +6,3 @@ and I want having such buckets and pipes to enable me to control what I do with
 my money, so that I control what I do with my money.
 
 Source: req-001
-
-Satisfied by: req-003, req-006, req-017, ass-001, ass-002
diff --git a/requirements/catalogue/req-003.md b/requirements/catalogue/req-003.md
index dc746a8..0ec877e 100644
--- a/requirements/catalogue/req-003.md
+++ b/requirements/catalogue/req-003.md
@@ -1,10 +1,11 @@
 # req-003
 
-As a user, I want how much money is in my beer bucket to influence how much I
-spend on beer, so that having buckets and pipes which express how I want to
-distribute, and have previously distributed, my incomings and outgoings enables
-me to control my spending.
+As a user, given I have a beer bucket and pipes which express how much I want
+to spend on beer, I want how much money is in my beer bucket to influence how
+much I spend on beer, so that having buckets and pipes which express how I want
+to distribute, and have previously distributed, my incomings and outgoings
+enables me to control my spending.
 
-Source: req-002
+Source: req-028
 
 Satisfied by: req-004
diff --git a/requirements/catalogue/req-004.md b/requirements/catalogue/req-004.md
index e28a256..e39e58a 100644
--- a/requirements/catalogue/req-004.md
+++ b/requirements/catalogue/req-004.md
@@ -1,8 +1,9 @@
 # req-004
 
-As a user, I want to consider how much money is in my beer bucket when I decide
-how much to spend on beer at the bar, so that how much money is in my beer
-bucket influences how much I spend on beer.
+As a user, given I have a beer bucket and pipes which express how much I want to
+spend on beer, I want to consider how much money is in my beer bucket when I
+decide how much to spend on beer at the bar, so that how much money is in my
+beer bucket influences how much I spend on beer.
 
 Source: req-003
 
diff --git a/requirements/catalogue/req-005.md b/requirements/catalogue/req-005.md
index 79f00c7..523c285 100644
--- a/requirements/catalogue/req-005.md
+++ b/requirements/catalogue/req-005.md
@@ -1,6 +1,7 @@
 # req-005
 
-As a user, I want to know how much money is in my beer bucket when I'm at the
+As a user, given I have a beer bucket and pipes which express how much I want to
+spend on beer, I want to know how much money is in my beer bucket when I'm at the
 bar, so that I can consider how much money is in my beer bucket when I decide
 how much to spend on beer at the bar.
 
diff --git a/requirements/catalogue/req-006.md b/requirements/catalogue/req-006.md
index 9b97791..be53d48 100644
--- a/requirements/catalogue/req-006.md
+++ b/requirements/catalogue/req-006.md
@@ -5,6 +5,6 @@ I spend on holidays, so that having buckets and pipes which express how I want
 to distribute, and have previously distributed, my incomings and outgoings
 enables me to control what I do with my money.
 
-Source: req-002
+Source: req-028
 
 Satisfied by: req-007
diff --git a/requirements/catalogue/req-018.md b/requirements/catalogue/req-018.md
index 9b9db42..225fc5d 100644
--- a/requirements/catalogue/req-018.md
+++ b/requirements/catalogue/req-018.md
@@ -1,8 +1,9 @@
 # req-018
 
-As a user, I want to know how much money is in my beer bucket when I'm at the
-bar and I have access to my phone, so that I can know how much money is in my
-beer bucket when I'm at the bar.
+As a user, given I have a beer bucket and pipes which express how much I want
+to spend on beer, I want to know how much money is in my beer bucket when I'm at
+the bar and I have access to my phone, so that I can know how much money is in
+my beer bucket when I'm at the bar.
 
 Source: req-005
 
diff --git a/requirements/catalogue/req-019.md b/requirements/catalogue/req-019.md
index a4d908a..35a7162 100644
--- a/requirements/catalogue/req-019.md
+++ b/requirements/catalogue/req-019.md
@@ -1,8 +1,9 @@
 # req-019
 
-As a user, I want to know how much money is in my beer bucket when I'm at the
-bar and I don't have access to my phone, so that I can know how much money is
-in my beer bucket when I'm at the bar.
+As a user, given I have a beer bucket and pipes which express how much I want to
+spend on beer, I want to know how much money is in my beer bucket when I'm at
+the bar and I don't have access to my phone, so that I can know how much money
+is in my beer bucket when I'm at the bar.
 
 Source: req-005
 
diff --git a/requirements/catalogue/req-020.md b/requirements/catalogue/req-020.md
index a745400..1e3eeb0 100644
--- a/requirements/catalogue/req-020.md
+++ b/requirements/catalogue/req-020.md
@@ -1,7 +1,10 @@
 # req-020
 
-As a user, I want to find out my beer bucket balance in Schist using SMS, so
-that I can know how much money is in my beer bucket when I'm at the bar and I
+As a user, given I have a beer bucket and pipes which express how much I want
+to spend on beer, I want to find out my beer bucket balance in Schist using SMS,
+so that I can know how much money is in my beer bucket when I'm at the bar and I
 have access to my phone.
 
 Source: req-018
+
+Satisfied by: req-024, req-029
diff --git a/requirements/catalogue/req-024.md b/requirements/catalogue/req-024.md
index 612132f..efbc3a6 100644
--- a/requirements/catalogue/req-024.md
+++ b/requirements/catalogue/req-024.md
@@ -1,6 +1,9 @@
 # req-023
 
-As a user, I want Schist to have an accurate record of the balance of my beer
+As a user, given I have a beer bucket and pipes which express how much I want to
+spend on beer, I want Schist to be able to infer the accurate balance of my beer
 bucket, so that I can find out my beer balance in Schist using SMS.
 
 Source: req-020
+
+Satisfied by: req-032
diff --git a/requirements/catalogue/req-025.md b/requirements/catalogue/req-025.md
new file mode 100644
index 0000000..b0cacd8
--- /dev/null
+++ b/requirements/catalogue/req-025.md
@@ -0,0 +1,6 @@
+# req-025
+
+As a user, I want my incomings not to exceed my outgoings in the long run, so
+that I can use my money well.
+
+Source: need-001
\ No newline at end of file
diff --git a/requirements/catalogue/req-026.md b/requirements/catalogue/req-026.md
new file mode 100644
index 0000000..f74cf18
--- /dev/null
+++ b/requirements/catalogue/req-026.md
@@ -0,0 +1,8 @@
+# req-026
+
+Buckets must have a `name` property, which describes a real-world category of
+spending.
+
+Source: req-017
+
+Satisfied by: dml-bucket
\ No newline at end of file
diff --git a/requirements/catalogue/req-027.md b/requirements/catalogue/req-027.md
new file mode 100644
index 0000000..83208a7
--- /dev/null
+++ b/requirements/catalogue/req-027.md
@@ -0,0 +1,9 @@
+# req-027
+
+Buckets must have a `balance` property, which represents the amount of money
+currently in the bucket, that is, the difference between the amount of money
+which has flowed in from a pipe less the amount taken out by my transactions.
+
+Source: req-017
+
+Satisfied by: dml-bucket
diff --git a/requirements/catalogue/req-028.md b/requirements/catalogue/req-028.md
new file mode 100644
index 0000000..e86c525
--- /dev/null
+++ b/requirements/catalogue/req-028.md
@@ -0,0 +1,12 @@
+# req-028
+
+As a user, given my buckets and pipes express how I want to distribute my
+incomings and outgoings, I want how much money is in my buckets to influence
+how much I spend on the real categories of spending which they represent, so
+that having buckets and pipes which express how I want to distribute, and have
+previously distributed, my incomings and outgoings enables me to control my
+spending.
+
+Source: req-002
+
+Satisfied by: req-003, req-006, ass-001, req-026, req-027
diff --git a/requirements/catalogue/req-029.md b/requirements/catalogue/req-029.md
new file mode 100644
index 0000000..26bf701
--- /dev/null
+++ b/requirements/catalogue/req-029.md
@@ -0,0 +1,7 @@
+# req-029
+
+Given the user's buckets and pipes express how the user wants to distribute
+their incomings and outgoings, Schist must have an SMS interface for a
+procedure which returns the accurate balance of a given bucket.
+
+Source: req-020
\ No newline at end of file
diff --git a/requirements/catalogue/req-030.md b/requirements/catalogue/req-030.md
new file mode 100644
index 0000000..e09a281
--- /dev/null
+++ b/requirements/catalogue/req-030.md
@@ -0,0 +1,26 @@
+# req-030
+
+Schist must implement the procedure described below as `calculate_bucket_balance`.
+
+## calculate_bucket_balance
+
+Inputs:
+
+-   A bucket name, `name`
+
+1. If no bucket exists with the name, `name`, then return empty.
+2. If more than one bucket exists with the name, `name`, then panic.
+3. Let `bucket` be the bucket with the given name.
+4. Let `cache_key = bucket.balance_cache_key`.
+5. Let `is_up_to_date` be the result of the procedure,
+   `is_bucket_balance_up_to_date(bucket)`, as described in req-035.
+6. If `is_up_to_date = TRUE`, then return `bucket.balance`.
+7. Carry out the procedure, `update_bucket_drips(bucket)`, as described in
+   req-037.
+8. Let `transaction_sum` be the sum over the property, `amount`, of all
+   transactions `t` such that `t.bucket_id = bucket.id`.
+9.  Let `drip_sum` be the sum over the property, `amount`, of all drips `d` such
+   that `d.bucket_id = bucket.id`.
+10. Return `drip_sum - transaction_sum`.
+
+Source: req-029
diff --git a/requirements/catalogue/req-031.md b/requirements/catalogue/req-031.md
new file mode 100644
index 0000000..11a2f29
--- /dev/null
+++ b/requirements/catalogue/req-031.md
@@ -0,0 +1,6 @@
+# req-031
+
+Schist must have an SMS interface for the procedure, `calculate_bucket_balance`
+as described in req-030.
+
+Source: req-029
\ No newline at end of file
diff --git a/requirements/catalogue/req-032.md b/requirements/catalogue/req-032.md
new file mode 100644
index 0000000..6f173ac
--- /dev/null
+++ b/requirements/catalogue/req-032.md
@@ -0,0 +1,9 @@
+# req-032
+
+Given the user's buckets and pipes express how the user wants to distribute
+their incomings and outgoings, Schist must be able to infer the accurate balance
+of any given bucket.
+
+Source: req-024
+
+Satisfied by: req-030, req-034, ass-008, req-036
\ No newline at end of file
diff --git a/requirements/catalogue/req-033.md b/requirements/catalogue/req-033.md
new file mode 100644
index 0000000..fce9092
--- /dev/null
+++ b/requirements/catalogue/req-033.md
@@ -0,0 +1,5 @@
+# req-033
+
+Whenever the user makes a transaction, they must be able to enter it into Schist.
+
+Source: req-034
diff --git a/requirements/catalogue/req-034.md b/requirements/catalogue/req-034.md
new file mode 100644
index 0000000..9971dd2
--- /dev/null
+++ b/requirements/catalogue/req-034.md
@@ -0,0 +1,7 @@
+# req-034
+
+Schist must have an accurate record of my transactions.
+
+Source: req-032
+
+Satisfied by: req-033, ass-009
\ No newline at end of file
diff --git a/requirements/catalogue/req-035.md b/requirements/catalogue/req-035.md
new file mode 100644
index 0000000..15b797b
--- /dev/null
+++ b/requirements/catalogue/req-035.md
@@ -0,0 +1,27 @@
+# req-035
+
+Schist must implement the procedure described below as
+`is_bucket_balance_up_to_date`.
+
+## is_bucket_balance_up_to_date
+
+Inputs:
+
+-   A bucket, `bucket`
+
+1. Let `cache_key = bucket.balance_cache_key`.
+2. If `cache_key` is not in the format, `<string>:<string>`, then return FALSE.
+3. Let `drip_id` be the part of `cache_key` before the `:`.
+4. If there is no drip with the ID, `drip_id`, then return FALSE.
+5. Let `drip` be the drip with the ID, `drip_id`.
+6. If there is a drip, `drip_2`, such that `drip_2.timestamp > drip.timestamp`
+   and `drip.bucket_id = bucket.id`, then return FALSE.
+7. Let `transaction_id` be the part of `cache_key` after the `:`.
+8. If there is no transaction with the ID, `transaction_id`, then return FALSE.
+9. Let `transaction` be the transaction with the ID, `transaction_id`.
+10. If there is a transaction, `transaction_2`, such that
+    `transaction_2.timestamp >= transaction.timestamp` and
+    `transaction.bucket_id = bucket.id`, then return FALSE.
+11. Return TRUE.
+
+Source: req-030
\ No newline at end of file
diff --git a/requirements/catalogue/req-036.md b/requirements/catalogue/req-036.md
new file mode 100644
index 0000000..db3f4dd
--- /dev/null
+++ b/requirements/catalogue/req-036.md
@@ -0,0 +1,7 @@
+# req-036
+
+Given a bucket, `bucket`, if the procedure
+`is_bucket_balance_up_to_date(bucket)` as described in req-035 returns TRUE,
+then the accurate balance of `bucket` is equal to `bucket.balance`.
+
+Sources: req-030, req-032
\ No newline at end of file
diff --git a/requirements/catalogue/req-037.md b/requirements/catalogue/req-037.md
new file mode 100644
index 0000000..0d27984
--- /dev/null
+++ b/requirements/catalogue/req-037.md
@@ -0,0 +1,48 @@
+# req-037
+
+Schist must implement the procedure, described below as
+`update_budget_drips_for_bucket`.
+
+## update_budget_drips_for_bucket
+
+Inputs:
+
+- A bucket, `bucket`
+
+1. For each pipe `p` such that `p.bucket_id = bucket.id`, carry out the
+   sub-procedure, `update_budget_drips_for_pipe(pipe)`, as described below.
+
+## update_budget_drips_for_pipe
+
+Inputs:
+
+- A pipe, `pipe`
+
+1. Let `prev_drip` be a drip `d` with a most recent value for the property
+   `date` such that `d.pipe_id = pipe.id`
+2. For each calendar date `d` in the range `(prev_drip.date, today]`, insert
+   a new drip for `pipe`:
+   - `bucket_id`: `pipe.bucket_id`
+   - `pipe_id`: `pipe.id`
+   - `date`: `d`
+   - `amount`: the result of the sub-procedure, `pipe_amount_for_day(pipe, d)`
+     as described below
+   - `timestamp`: now as a Unix timestamp
+
+## pipe_amount_for_date
+
+Inputs:
+
+- A pipe, `pipe`
+- A calendar date, `date`
+
+1. If `pipe.period` is `day`, return `pipe.amount`.
+2. If `pipe.period` is `week`, return `pipe.amount ÷ 7`.
+3. Let `days_in_month` be the number of days in the month to which `date`
+   belongs.
+4. If `pipe.period` is `month`, return `pipe.amount ÷ days_in_month`.
+5. Let `days_in_year` be the number of days in the year to which `date` belongs.
+6. If `period` is not `year`, panic.
+7. Return `pipe.amount ÷ days_in_year`.
+
+Source: req-030
\ No newline at end of file
diff --git a/requirements/catalogue/req-038.md b/requirements/catalogue/req-038.md
new file mode 100644
index 0000000..71b8d55
--- /dev/null
+++ b/requirements/catalogue/req-038.md
@@ -0,0 +1,6 @@
+# req-038
+
+Schist must have a record of pipes which accurately reflect how I want to
+distribute my incomings and outgoings.
+
+Source: req-032
\ No newline at end of file
diff --git a/requirements/data_models/dml-bucket.md b/requirements/data_models/dml-bucket.md
index b0d978f..3e33028 100644
--- a/requirements/data_models/dml-bucket.md
+++ b/requirements/data_models/dml-bucket.md
@@ -2,10 +2,18 @@
 
 A bucket represents a real category of spending, like beer or holidays.
 
-| Field   | Type   | Description                                           |
-| ------- | ------ | ----------------------------------------------------- |
-| id      | string |                                                       |
-| name    | string | A short description of the real category of spending. |
-| balance | number | The amount of money currently in the bucket.          |
+| Field             | Type   | Description                                           |
+| ----------------- | ------ | ----------------------------------------------------- |
+| name              | string | A short description of the real category of spending. |
+| balance           | number | The amount of money currently in the bucket.          |
+| balance_cache_key | string | A cache key for the balance. See notes.               |
 
-Source: req-017
+Constraints:
+
+-   `name` must be unique.
+
+Notes:
+
+- `balance_cache_key` must be of the format: `<drip_id>:<transaction_id>`.
+
+Sources: req-027, req-028, req-030
diff --git a/requirements/data_models/dml-drip.md b/requirements/data_models/dml-drip.md
new file mode 100644
index 0000000..127c73e
--- /dev/null
+++ b/requirements/data_models/dml-drip.md
@@ -0,0 +1,15 @@
+# dml-drip
+
+A drip represents a single daily transaction from the tank into a bucket as a
+result of a pipe.
+
+| Field     | Type   | Description                                                   |
+| --------- | ------ | ------------------------------------------------------------- |
+| id        | string | A unique ID.                                                  |
+| bucket_id | string | The ID of the bucket into which this drip drap.               |
+| pipe_id   | string | The ID of the pipe which from which this drip drap.           |
+| date      | date   | The date on which this drip drap.                             |
+| amount    | number | The amount of money which dripped.                            |
+| timestamp | number | The time on which this drip was inserted as a Unix timestamp. |
+
+Sources: req-030, req-037
diff --git a/requirements/data_models/dml-pipe.md b/requirements/data_models/dml-pipe.md
index a7d2e8a..d889b0a 100644
--- a/requirements/data_models/dml-pipe.md
+++ b/requirements/data_models/dml-pipe.md
@@ -3,10 +3,19 @@
 A pipe represents how much money the user wants to come in or go out of a
 bucket. In other words, it represents a flow of money from the tank to a bucket.
 
-| Field  | Type   | Description                                              |
-| ------ | ------ | -------------------------------------------------------- |
-| id     | string |                                                          |
-| amount | number | The amount of money flowing through the pipe.            |
-| period | string | How long it takes for `amount` to flow through the pipe. |
+| Field     | Type   | Description                                              |
+| --------- | ------ | -------------------------------------------------------- |
+| id        | string |                                                          |
+| amount    | number | The amount of money flowing through the pipe.            |
+| period    | string | How long it takes for `amount` to flow through the pipe. |
+| bucket_id | string | The ID of the bucket to which this pipe corresponds.     |
 
-Source: req-017
+Constraints:
+
+- `period` must be one of these options:
+  - `day`
+  - `week`
+  - `month`
+  - `year`
+
+Sources: req-017, req-037
diff --git a/requirements/data_models/dml-transaction.md b/requirements/data_models/dml-transaction.md
index db7d1ed..b6b76f7 100644
--- a/requirements/data_models/dml-transaction.md
+++ b/requirements/data_models/dml-transaction.md
@@ -3,12 +3,13 @@
 A transaction represents a real transaction, such as buying a beer or depositing
 a wage slip. It may be associated with at most one bucket.
 
-| Field        | Type    | Description                                        |
-| ------------ | ------- | -------------------------------------------------- |
-| id           | string  |                                                    |
-| amount       | number  | The amount of money involved in the transaction.   |
-| date         | date    | The calendar date when the transaction took place. |
-| counterparty | string  | The other party in the transaction.                |
-| bucket       | string? | The bucket associated with the transaction.        |
+| Field        | Type    | Description                                                |
+| ------------ | ------- | ---------------------------------------------------------- |
+| id           | string  |                                                            |
+| amount       | number  | The amount of money involved in the transaction.           |
+| date         | date    | The calendar date when the transaction took place.         |
+| counterparty | string  | The other party in the transaction.                        |
+| bucket_id    | string? | The bucket associated with the transaction.                |
+| timestamp    | number  | The time the transaction was inserted as a Unix timestamp. |
 
 Source: req-010, req-017
diff --git a/requirements/needs/need-000.md b/requirements/needs/need-000.md
new file mode 100644
index 0000000..64bebfb
--- /dev/null
+++ b/requirements/needs/need-000.md
@@ -0,0 +1,3 @@
+# need-000
+
+As a user, I want to not go bankrupt.
diff --git a/requirements/needs/need-001.md b/requirements/needs/need-001.md
new file mode 100644
index 0000000..cc8e568
--- /dev/null
+++ b/requirements/needs/need-001.md
@@ -0,0 +1,3 @@
+# need-001
+
+As a user, I want to use my money well.