journal_proposals

JournalProposalRow captures one journal entry waiting on operator approval before it posts to the external GL. Stored in ledgers.journal_proposals. Migration: 005_journal_proposals_subledger.sql.

runbook builds JournalLine[]
    ↓ (commit step)
JournalProposalRow stored in ledgers.journal_proposals
    ↓ (post step, idempotent)
JournalProposalRow.propose_for_gl(...) → JournalProposal (GL handoff)
    ↓
GLProvider.journal_entries.create(proposal, external_id=...)

from ntro.subledger.types.journal_proposals import JournalProposalRow

The class is auto-registered as the "journal_proposals" subledger type on import.

Type-specific fields

Field	Type	Purpose
`description`	`str \| None`	Narrative the GL stores as `memo` / `description`. Operator-facing.
`posting_date`	`date \| None`	Date the journal posts on. Distinct from `period` — a March journal might post on the 31st, a year-end adjustment on the prior day. Required for GL commit; if absent we derive last-day-of-period at handoff.
`currency`	`str \| None`	ISO-4217. Optional — the GL provider uses the entity’s default when omitted.
`lines`	`list[dict]`	List of `{account_code, description, debit, credit, tax_code?}` dicts. Stored as JSONB. Strict typing happens at GL handoff.

GL-handoff fields

Mirrors ExpenseRow. Populated by the post step, never written by runbook code directly.

Field	Type	Purpose
`approved_at`	`datetime \| None`	Set by the HITL approval step.
`posted_to_gl`	`bool`	True once the GL post succeeded.
`posted_journal_ref`	`str \| None`	Provider-assigned journal id.

Why `lines` is a list of dicts (not a typed sub-model)

Matches the existing ledgers.journal_proposals.lines JSONB column shape — keeps the migration cheap.
Line shape evolves per-runbook. nav-monthly-journals carries account_code/description/debit/credit/tax_code today. Other runbooks may add cost_centre or tracking_categories. Loose dict here, strict typing happens at propose_for_gl time when we land in the unified JournalEntryLineItem.

Validation rules

Two model validators run at row construction:

`_strict_fields_present_when_not_needs_attention`

Outside NEEDS_ATTENTION, lines must be non-empty AND each line must:

Have a non-empty account_code.
Have non-negative debit and credit.
Have a non-zero amount on exactly one side (debit XOR credit > 0). Both zero → invalid; both positive → invalid.

NEEDS_ATTENTION rows are the only status allowed to be empty (placeholder for HITL fix-up).

`_balanced_when_approved`

A journal posted to the GL MUST balance (Σ debits == Σ credits). Enforced only on APPROVED / POSTED rows so the runbook can store an in-progress draft mid-HITL before the user adds the balancing line.

GL handoff — `JournalProposalRow.propose_for_gl`

from uuid import UUID
from ntro.subledger.types.journal_proposals import JournalProposalRow

proposal = JournalProposalRow.propose_for_gl(
    rows=[approved_row],
    task_id=UUID("…"),
)
# proposal: ntro.subledger.proposals.JournalProposal
# Hand off via your GLProvider:
result = await provider.journal_entries.create(
    proposal, external_id=proposal.idempotency_key
)

Converts one or more APPROVED subledger rows to a single JournalProposal for GL commit. nav-monthly-journals calls this with one row (the approved monthly allocation journal). Other runbooks may pass multiple rows when the GL provider’s batched-journal model suits — e.g. a period-close runbook posting all true-up journals as one batch. When multiple rows are passed:

lines are merged into a single journal entry.
description and posting_date come from the first row (caller’s responsibility to pre-validate they share these).

Field mapping:

Row	→	GL (`JournalEntry`)
line `account_code`	→	`JournalEntryLineItem.ledger_account.nominal_code`
line `debit` / `credit`	→	`JournalEntryLineItem.type` (`"Debit"` / `"Credit"`) + `total_amount`
line `description`	→	`JournalEntryLineItem.description`
`description`	→	`memo`
`currency`	→	`currency`
`posting_date` (or last-day-of-period default)	→	`posted_at` (datetime, midnight UTC)

Idempotency key follows the canonical convention: "journal_proposals:{task_id}:{row.id}" for single-row proposals. Multi-row uses the first row’s id (deterministic across re-invocations as long as the row order is stable). Rejects non-APPROVED rows — only signed-off journals go to the GL.

Subledgers overview

Row base + SubledgerStatus lifecycle.

expenses

The other shipped platform type.

Accounting

JournalLine / JournalProposal proposal-builder helpers.

General ledgers

Posting the JournalProposal via provider.journal_entries.create.

Get Started

Tooling

Building workflows

Ntro SDK

API Reference

Deploy & Run

journal_proposals

Type-specific fields

GL-handoff fields

Why `lines` is a list of dicts (not a typed sub-model)

Validation rules

`_strict_fields_present_when_not_needs_attention`

`_balanced_when_approved`

GL handoff — `JournalProposalRow.propose_for_gl`

Subledgers overview

expenses

Accounting

General ledgers

​Type-specific fields

​GL-handoff fields

​Why lines is a list of dicts (not a typed sub-model)

​Validation rules

​_strict_fields_present_when_not_needs_attention

​_balanced_when_approved

​GL handoff — JournalProposalRow.propose_for_gl

​Related

Subledgers overview

expenses

Accounting

General ledgers

Type-specific fields

GL-handoff fields

Why `lines` is a list of dicts (not a typed sub-model)

Validation rules

`_strict_fields_present_when_not_needs_attention`

`_balanced_when_approved`

GL handoff — `JournalProposalRow.propose_for_gl`

Related