feat(ledger): statement cycle, outstanding lines and roll-forward on reconciliations

robosystems_client/api/robo_ledger_ledger_events/record_statement_balance.py

@@ -117,16 +117,19 @@ def sync_detailed(
   account, and reconcile the account to it. Give the balance as the statement shows it, as a positive
   number in the account's normal direction, with the statement's ending date. The ledger's balance at
   that date is set beside it, counting the drafts the close will post, and the result is recorded on
-  the account's statement reconciliation for the period the statement ends in. Attach the statement as
-  evidence by passing the `document_id` of its stored file (create-document-upload, then complete-
-  document-upload); recording it again with another document lapses a sign-off. Writes no books. The
-  first statement recorded for an account creates its reconciliation, which does not hold the close:
-  turn `required_for_close` on with set-reconciliation-policy to make every period's close wait for a
-  statement on that account. Recording the same account and date again replaces the earlier balance;
-  when more than one statement ends in a period, the one with the latest date stands. Recording a
-  balance that differs from one already signed off lapses that sign-off. A difference is not explained
-  here: it is activity one side has and the other does not yet, or an error on either. Returns the
-  reconciliation's standing for the period.
+  the account's statement reconciliation for the period the statement ends in. On an account a bank
+  feed keeps, ledger lines that did not come from the feed and are dated on or before the statement
+  are listed as outstanding and adjust the statement balance, since the bank had not cleared them; a
+  statement ending before the period's last day is carried to it by the feed's own lines
+  (`roll_forward`). Attach the statement as evidence by passing the `document_id` of its stored file
+  (create-document-upload, then complete-document-upload); recording it again with another document
+  lapses a sign-off. Writes no books. The first statement recorded for an account creates its
+  reconciliation, which does not hold the close: turn `required_for_close` on with set-reconciliation-
+  policy to make every period's close wait for a statement on that account. Recording the same account
+  and date again replaces the earlier balance; when more than one statement ends in a period, the one
+  with the latest date stands. Recording a balance that differs from one already signed off lapses
+  that sign-off. A difference left after the outstanding lines is activity one side has and the other
+  does not yet, or an error on either. Returns the reconciliation's standing for the period.
 
   **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours
   return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
@@ -171,16 +174,19 @@ def sync(
   account, and reconcile the account to it. Give the balance as the statement shows it, as a positive
   number in the account's normal direction, with the statement's ending date. The ledger's balance at
   that date is set beside it, counting the drafts the close will post, and the result is recorded on
-  the account's statement reconciliation for the period the statement ends in. Attach the statement as
-  evidence by passing the `document_id` of its stored file (create-document-upload, then complete-
-  document-upload); recording it again with another document lapses a sign-off. Writes no books. The
-  first statement recorded for an account creates its reconciliation, which does not hold the close:
-  turn `required_for_close` on with set-reconciliation-policy to make every period's close wait for a
-  statement on that account. Recording the same account and date again replaces the earlier balance;
-  when more than one statement ends in a period, the one with the latest date stands. Recording a
-  balance that differs from one already signed off lapses that sign-off. A difference is not explained
-  here: it is activity one side has and the other does not yet, or an error on either. Returns the
-  reconciliation's standing for the period.
+  the account's statement reconciliation for the period the statement ends in. On an account a bank
+  feed keeps, ledger lines that did not come from the feed and are dated on or before the statement
+  are listed as outstanding and adjust the statement balance, since the bank had not cleared them; a
+  statement ending before the period's last day is carried to it by the feed's own lines
+  (`roll_forward`). Attach the statement as evidence by passing the `document_id` of its stored file
+  (create-document-upload, then complete-document-upload); recording it again with another document
+  lapses a sign-off. Writes no books. The first statement recorded for an account creates its
+  reconciliation, which does not hold the close: turn `required_for_close` on with set-reconciliation-
+  policy to make every period's close wait for a statement on that account. Recording the same account
+  and date again replaces the earlier balance; when more than one statement ends in a period, the one
+  with the latest date stands. Recording a balance that differs from one already signed off lapses
+  that sign-off. A difference left after the outstanding lines is activity one side has and the other
+  does not yet, or an error on either. Returns the reconciliation's standing for the period.
 
   **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours
   return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
@@ -220,16 +226,19 @@ async def asyncio_detailed(
   account, and reconcile the account to it. Give the balance as the statement shows it, as a positive
   number in the account's normal direction, with the statement's ending date. The ledger's balance at
   that date is set beside it, counting the drafts the close will post, and the result is recorded on
-  the account's statement reconciliation for the period the statement ends in. Attach the statement as
-  evidence by passing the `document_id` of its stored file (create-document-upload, then complete-
-  document-upload); recording it again with another document lapses a sign-off. Writes no books. The
-  first statement recorded for an account creates its reconciliation, which does not hold the close:
-  turn `required_for_close` on with set-reconciliation-policy to make every period's close wait for a
-  statement on that account. Recording the same account and date again replaces the earlier balance;
-  when more than one statement ends in a period, the one with the latest date stands. Recording a
-  balance that differs from one already signed off lapses that sign-off. A difference is not explained
-  here: it is activity one side has and the other does not yet, or an error on either. Returns the
-  reconciliation's standing for the period.
+  the account's statement reconciliation for the period the statement ends in. On an account a bank
+  feed keeps, ledger lines that did not come from the feed and are dated on or before the statement
+  are listed as outstanding and adjust the statement balance, since the bank had not cleared them; a
+  statement ending before the period's last day is carried to it by the feed's own lines
+  (`roll_forward`). Attach the statement as evidence by passing the `document_id` of its stored file
+  (create-document-upload, then complete-document-upload); recording it again with another document
+  lapses a sign-off. Writes no books. The first statement recorded for an account creates its
+  reconciliation, which does not hold the close: turn `required_for_close` on with set-reconciliation-
+  policy to make every period's close wait for a statement on that account. Recording the same account
+  and date again replaces the earlier balance; when more than one statement ends in a period, the one
+  with the latest date stands. Recording a balance that differs from one already signed off lapses
+  that sign-off. A difference left after the outstanding lines is activity one side has and the other
+  does not yet, or an error on either. Returns the reconciliation's standing for the period.
 
   **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours
   return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
@@ -272,16 +281,19 @@ async def asyncio(
   account, and reconcile the account to it. Give the balance as the statement shows it, as a positive
   number in the account's normal direction, with the statement's ending date. The ledger's balance at
   that date is set beside it, counting the drafts the close will post, and the result is recorded on
-  the account's statement reconciliation for the period the statement ends in. Attach the statement as
-  evidence by passing the `document_id` of its stored file (create-document-upload, then complete-
-  document-upload); recording it again with another document lapses a sign-off. Writes no books. The
-  first statement recorded for an account creates its reconciliation, which does not hold the close:
-  turn `required_for_close` on with set-reconciliation-policy to make every period's close wait for a
-  statement on that account. Recording the same account and date again replaces the earlier balance;
-  when more than one statement ends in a period, the one with the latest date stands. Recording a
-  balance that differs from one already signed off lapses that sign-off. A difference is not explained
-  here: it is activity one side has and the other does not yet, or an error on either. Returns the
-  reconciliation's standing for the period.
+  the account's statement reconciliation for the period the statement ends in. On an account a bank
+  feed keeps, ledger lines that did not come from the feed and are dated on or before the statement
+  are listed as outstanding and adjust the statement balance, since the bank had not cleared them; a
+  statement ending before the period's last day is carried to it by the feed's own lines
+  (`roll_forward`). Attach the statement as evidence by passing the `document_id` of its stored file
+  (create-document-upload, then complete-document-upload); recording it again with another document
+  lapses a sign-off. Writes no books. The first statement recorded for an account creates its
+  reconciliation, which does not hold the close: turn `required_for_close` on with set-reconciliation-
+  policy to make every period's close wait for a statement on that account. Recording the same account
+  and date again replaces the earlier balance; when more than one statement ends in a period, the one
+  with the latest date stands. Recording a balance that differs from one already signed off lapses
+  that sign-off. A difference left after the outstanding lines is activity one side has and the other
+  does not yet, or an error on either. Returns the reconciliation's standing for the period.
 
   **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours
   return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.

robosystems_client/api/robo_ledger_ledger_events/refresh_reconciliations.py

@@ -118,15 +118,15 @@ def sync_detailed(
    Run every reconciliation that applies at a period end and record each result on its block. A ledger
   synced from QuickBooks is compared with QuickBooks' own trial balance, on one block for the whole
   ledger. Each asset account a schedule carries a balance on is compared with what its schedules say
-  it holds, on a block of its own. Each account with a statement balance recorded in the period
-  (record-statement-balance) is compared with that balance. A block reconciles for the period when its
-  difference is within its materiality. Running it again replaces the period's comparison, so the
-  answer is always as of the last run. A block is created the first time its check applies, and from
-  then on the period's close waits on it until set-reconciliation-policy releases it. The one
-  exception is an account block whose first comparison does not tie: it is created without holding the
-  close, so a difference found on first contact is reported and becomes a close requirement only when
-  you turn it on. Returns every reconciliation's standing for the period. Use preview-reconciliations
-  to see a comparison without recording it.
+  it holds, on a block of its own. Each account with a statement covering the period (record-
+  statement-balance; the latest within its statement cycle) is compared with that balance. A block
+  reconciles for the period when its difference is within its materiality. Running it again replaces
+  the period's comparison, so the answer is always as of the last run. A block is created the first
+  time its check applies, and from then on the period's close waits on it until set-reconciliation-
+  policy releases it. The one exception is an account block whose first comparison does not tie: it is
+  created without holding the close, so a difference found on first contact is reported and becomes a
+  close requirement only when you turn it on. Returns every reconciliation's standing for the period.
+  Use preview-reconciliations to see a comparison without recording it.
 
   **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours
   return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
@@ -170,15 +170,15 @@ def sync(
    Run every reconciliation that applies at a period end and record each result on its block. A ledger
   synced from QuickBooks is compared with QuickBooks' own trial balance, on one block for the whole
   ledger. Each asset account a schedule carries a balance on is compared with what its schedules say
-  it holds, on a block of its own. Each account with a statement balance recorded in the period
-  (record-statement-balance) is compared with that balance. A block reconciles for the period when its
-  difference is within its materiality. Running it again replaces the period's comparison, so the
-  answer is always as of the last run. A block is created the first time its check applies, and from
-  then on the period's close waits on it until set-reconciliation-policy releases it. The one
-  exception is an account block whose first comparison does not tie: it is created without holding the
-  close, so a difference found on first contact is reported and becomes a close requirement only when
-  you turn it on. Returns every reconciliation's standing for the period. Use preview-reconciliations
-  to see a comparison without recording it.
+  it holds, on a block of its own. Each account with a statement covering the period (record-
+  statement-balance; the latest within its statement cycle) is compared with that balance. A block
+  reconciles for the period when its difference is within its materiality. Running it again replaces
+  the period's comparison, so the answer is always as of the last run. A block is created the first
+  time its check applies, and from then on the period's close waits on it until set-reconciliation-
+  policy releases it. The one exception is an account block whose first comparison does not tie: it is
+  created without holding the close, so a difference found on first contact is reported and becomes a
+  close requirement only when you turn it on. Returns every reconciliation's standing for the period.
+  Use preview-reconciliations to see a comparison without recording it.
 
   **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours
   return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
@@ -217,15 +217,15 @@ async def asyncio_detailed(
    Run every reconciliation that applies at a period end and record each result on its block. A ledger
   synced from QuickBooks is compared with QuickBooks' own trial balance, on one block for the whole
   ledger. Each asset account a schedule carries a balance on is compared with what its schedules say
-  it holds, on a block of its own. Each account with a statement balance recorded in the period
-  (record-statement-balance) is compared with that balance. A block reconciles for the period when its
-  difference is within its materiality. Running it again replaces the period's comparison, so the
-  answer is always as of the last run. A block is created the first time its check applies, and from
-  then on the period's close waits on it until set-reconciliation-policy releases it. The one
-  exception is an account block whose first comparison does not tie: it is created without holding the
-  close, so a difference found on first contact is reported and becomes a close requirement only when
-  you turn it on. Returns every reconciliation's standing for the period. Use preview-reconciliations
-  to see a comparison without recording it.
+  it holds, on a block of its own. Each account with a statement covering the period (record-
+  statement-balance; the latest within its statement cycle) is compared with that balance. A block
+  reconciles for the period when its difference is within its materiality. Running it again replaces
+  the period's comparison, so the answer is always as of the last run. A block is created the first
+  time its check applies, and from then on the period's close waits on it until set-reconciliation-
+  policy releases it. The one exception is an account block whose first comparison does not tie: it is
+  created without holding the close, so a difference found on first contact is reported and becomes a
+  close requirement only when you turn it on. Returns every reconciliation's standing for the period.
+  Use preview-reconciliations to see a comparison without recording it.
 
   **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours
   return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.
@@ -267,15 +267,15 @@ async def asyncio(
    Run every reconciliation that applies at a period end and record each result on its block. A ledger
   synced from QuickBooks is compared with QuickBooks' own trial balance, on one block for the whole
   ledger. Each asset account a schedule carries a balance on is compared with what its schedules say
-  it holds, on a block of its own. Each account with a statement balance recorded in the period
-  (record-statement-balance) is compared with that balance. A block reconciles for the period when its
-  difference is within its materiality. Running it again replaces the period's comparison, so the
-  answer is always as of the last run. A block is created the first time its check applies, and from
-  then on the period's close waits on it until set-reconciliation-policy releases it. The one
-  exception is an account block whose first comparison does not tie: it is created without holding the
-  close, so a difference found on first contact is reported and becomes a close requirement only when
-  you turn it on. Returns every reconciliation's standing for the period. Use preview-reconciliations
-  to see a comparison without recording it.
+  it holds, on a block of its own. Each account with a statement covering the period (record-
+  statement-balance; the latest within its statement cycle) is compared with that balance. A block
+  reconciles for the period when its difference is within its materiality. Running it again replaces
+  the period's comparison, so the answer is always as of the last run. A block is created the first
+  time its check applies, and from then on the period's close waits on it until set-reconciliation-
+  policy releases it. The one exception is an account block whose first comparison does not tie: it is
+  created without holding the close, so a difference found on first contact is reported and becomes a
+  close requirement only when you turn it on. Returns every reconciliation's standing for the period.
+  Use preview-reconciliations to see a comparison without recording it.
 
   **Idempotency**: supply an `Idempotency-Key` header to make safe retries; replays within 24 hours
   return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.