lock_periodWritesClose the books through a date so nothing changes them later
You just finished reconciling last month and you don't want a stray categorization or a forgotten transaction quietly changing numbers you already reported.
Closing a month is only meaningful if closed actually means closed. lock_period sets a date on a book, and after that, nothing — no categorization, no manual journal entry, no reversal — can post on or before it. That includes your assistant: if it tries to categorize a transaction dated inside a locked period, that attempt is rejected with a clear reason, not silently allowed.
The lock only moves in one direction: forward. Once you've locked through May 31st, you can extend the lock to June 30th later, but you can never move it back to May 15th — a closed period is meant to stay closed, permanently, not get reopened because it would be convenient for one transaction. If you genuinely need to fix something in a locked period, the honest path is reverse_entry followed by a manual post_journal_entry dated after the lock, not unlocking the past or recategorizing — categorize_transactions always reuses the original transaction's own date, so it cannot re-post something dated inside a lock no matter how the entry behind it was corrected.
This pairs naturally with reconcile_account: reconcile first, confirm the ledger matches the statement, then lock through that date. That order matters — locking before reconciling just means you'll find a discrepancy you can no longer fix without going through a workaround.
Like every other tool that writes to the ledger, this previews first: it shows you the current lock (if any) and what it would become, and only actually locks the period when you confirm.
What this does not do
- A lock can only move forward. There is no way to move it backward or unlock a period once set, short of a database-level migration outside this tool.
- Locking blocks new postings dated in the locked range, but does not retroactively validate or reconcile anything that was already posted there.
Arguments
| Name | Type | Required | What it is |
|---|---|---|---|
bookId | uuid | Required | — |
lockedThrough | string | Required | Everything on or before this date becomes read-only. |
confirm | boolean | Required | — |
Generated from the tool definition, so it cannot describe arguments the tool does not accept. Unrecognised arguments are rejected rather than ignored.
Common questions
- Can I unlock a period if I need to fix something in it?
- No — a lock can only move forward, never backward, and there is no unlock. The way to correct something in a locked period is to reverse the original entry, then post a manual journal entry with the correct lines dated after the lock — categorize_transactions cannot do this step, since it always reuses the transaction's own date.
- What happens if I try to post something dated before the lock?
- It's rejected outright, with a clear reason pointing to the lock. Nothing silently slips through into a closed period.
- Should I reconcile before or after locking?
- Before. Reconcile the account, confirm it matches the statement, and only then lock through that date — locking first just means finding a problem later that you can no longer fix in place.