Xero Ledger Review Gate

Compatibility: install elizabeth-anne-alexander, import elizabeth_anne_alexander, and run elizabeth-anne-alexander. These remain the supported names; no migration is required.

Scope and assurance boundary

This is a synthetic-only design demonstration. It accepts synthetic Xero-shaped trial-balance fixtures, not client exports or evidence from Xero. receipt.json is an adjacent, unkeyed local SHA-256 checksum binding. Anyone who can replace the artefacts can replace the receipt. It does not prove authorship, source system, origin, time, or immutability.

+----------------------------------------------------------------------+
|                       Xero Ledger Review Gate                        |
+----------------------------------------------------------------------+
|           Synthetic fixed-policy zero-network review gateway         |
+----------------------------------+-----------------------------------+
| DR  what it gives you            | CR  what it needs                 |
+----------------------------------+-----------------------------------+
| redacted variance review         | synthetic Xero-shaped TB fixture  |
| local review display data        | a review policy JSON file         |
| local checksum binding           | a human decision JSON file        |
+----------------------------------+-----------------------------------+

A fixed-policy, zero-network ledger-review boundary for AI, not an AI that operates Xero.

The maintained source is under packages/elizabeth-anne-alexander in the Accounting Review Pipeline. The elizabeth-anne-alexander distribution and command, and elizabeth_anne_alexander import, remain compatibility identifiers.

Xero Ledger Review Gate consumes synthetic Xero-shaped trial-balance fixtures and produces a bounded, redacted variance-review result alongside separate local review evidence. It deliberately features no network calls, no cloud telemetry, no LLM API clients, and zero accounting-system write operations.

Zero-network architecture

%%{init: {"themeVariables": {"lineColor": "#B1AFAD"}}}%%
flowchart TD
    subgraph ClientPerimeter ["Local Client Perimeter (Zero-Network)"]
        Raw["Synthetic Xero-Shaped Trial Balance Fixture"] --> Validate["Context & Hash Integrity Gate"]
        Validate --> Engine["Decimal Variance Review Engine<br/><i>(Fixed Policy v1)</i>"]
    end

    subgraph ArtifactSplit ["Deterministic Artefact Generation"]
        Engine --> Split{"Split Boundary"}
        Split --> Model["model-result.json<br/><i>(Redacted Bounded Values for AI)</i>"]
        Split --> Evidence["reviewer-evidence.json<br/><i>(Local Review Display Data)</i>"]
        Split --> Receipt["receipt.json<br/><i>(Local SHA-256 Checksum Binding)</i>"]
    end

    subgraph Governance ["Human-in-the-Loop Review"]
        Model --> LLM["AI Advisory Assessment"]
        Evidence & Receipt & LLM --> Reviewer["Human Accountant Review Gate"]
        Reviewer --> Decision{"Decision Status"}
        Decision -->|ACKNOWLEDGED| Done["Recorded Review Decision"]
        Decision -->|NEEDS_EVIDENCE / ESCALATED| Action["Further Investigation"]
    end

    style ClientPerimeter fill:#140E24,stroke:#4F485E,stroke-width:2px,color:#FFFFFF
    style ArtifactSplit fill:#1E1236,stroke:#5C2D91,stroke-width:2px,color:#FFFFFF
    style Governance fill:#2D184E,stroke:#8A4AC7,stroke-width:2px,color:#FFFFFF

Quick Demo

# Install package in editable development mode
pip install -e ".[dev]"

# Run deterministic evaluation
elizabeth-anne-alexander evaluate \
  --context samples/contexts/sample-monthly-variance.context.json \
  --request samples/requests/sample-revenue-variance.request.json \
  --policy policy/demo-policy-v1.json \
  --out build/demo

Validate a recorded human review decision

elizabeth-anne-alexander validate-review \
  --evidence build/demo/reviewer-evidence.json \
  --receipt build/demo/receipt.json \
  --decision samples/decisions/sample-review-decision.json

Exit codes

PARTIAL_DECISION_RECORDED is exit 0 deliberately: the pack was validated and some findings are still undecided. Read the status, not the exit code, to decide whether a human still has work to do.

These are not the exit codes the rest of this repository uses. Every other component reserves 1 for malformed input and 2 for a non-passing status; this command has no 1 at all, so a file that will not parse and a gate that refused a well-formed file exit the same way, and a caller scripting several components cannot tell an operator error from a refusal without reading the message. The codes are a released contract, so they are documented here rather than changed; RELEASE_NOTES.md records the divergence as an open item for the owner.

Control boundary

• The canonical source contract has exactly 10 columns: ReportDate,Tenant,Section,AccountID,AccountName,AccountCode,Debit,Credit,YTDDebit,YTDCredit.
• The root contracts/xero-trial-balance-v1/ directory is the exporter-owned, fabricated xero-tb-csv.v1 corpus. Its SHA256SUMS file and every consumer's tests verify the same bytes locally, with no runtime network dependency.
• CSV schema, duplicate account IDs, reporting dates, balance pairs, source hashes, entity, basis, currency, tracking filters, and draft setting are all checked before review.
• Monetary values use Decimal, never binary floating point. Evaluation runs under its own fixed 28-digit context, and a CSV whose totals would round in it is refused instead of compared inexactly.
• evaluate writes amount strings in the model result and reviewer evidence with at least 2 decimal places, padded and never rounded, so a whole-dollar source emits "200.00" rather than "200". validate-review still accepts reviewer-evidence amounts in any decimal notation, subject to the same finiteness and supported-magnitude checks as source amounts, so evidence written by earlier versions continues to validate. The disclosure check holds current_ytd_net, prior_ytd_net, delta and percent_change to those number formats instead of comparing them with source values, so an account code that happens to equal an amount does not refuse the pack.
• percent_change in the model result is expressed in per cent and quantized to 4 decimal places ("18.3333" means 18.3333%). It is null when there is no prior balance to compare against.
• The model result states its own currency and sign_convention. Amounts are debit-positive (ytd_net = YTDDebit - YTDCredit), so a revenue, liability, or equity balance is negative and a revenue increase shows as a negative delta.
• Current and prior reports must sit in the same Australian financial year, or be the same day and month in different years. YTD columns reset on 1 July, so a comparison across the reset would report a whole prior-year balance as a movement.
• Current/prior trial balances are joined by stable AccountID, not account display name or code.
• An account changing section between periods fails closed instead of disappearing from, or being silently reclassified within, a section-scoped comparison.
• The model result never contains a tenant name, account name, account code, source file path, token, raw error, or free text copied from source data.
• Artefact timestamps (export.generated_at, reviewed_at) are accepted as YYYY-MM-DD, then T, t, or a space, then HH:MM with optional :SS and optional . plus one to 6 fractional digits, then Z, z, or +/-HH:MM with optional :SS. The gateway fixes that grammar itself rather than inheriting datetime.fromisoformat, whose accepted forms widened in Python 3.11: a bare +10 offset, a week date, a basic-format 20260809T000000+0000, and a fraction longer than 6 digits are refused on every interpreter, as is a separator character other than T, t, or a space.
• The 3 run artefacts are staged beside their destinations and moved into place only once all 3 are written, receipt last. The moves are not one atomic step, so an interrupted run can still leave one new file beside 2 old ones; validate-review refuses that pack because the receipt checksum binds the reviewer evidence and model result sitting beside it. This detects mismatched local files, but the adjacent unkeyed receipt provides no independent trust anchor.
• The package contains no network imports or mutation adapter. A future live connection must remain an authorised, read-only export handoff rather than an AI-controlled broad Xero tool set.

Scope and limitation

Every source manifest, review context, model result, reviewer evidence, and receipt is marked mode: synthetic. The policy, request, and human-decision files carry no mode key: each is validated against an exact key set, so adding one is rejected. The validate-review output carries no mode key either; it reports the decision status for a run whose artefacts were already checked. It is a local design demonstration, not a client-data processor, production security system, accounting service, or professional opinion. The reviewer evidence/model-result file split demonstrates disclosure minimisation only; it is not an access-control mechanism by itself.

Documentation and governance

• DATA-FLOW.md - Formal data-flow and zero-network security specification.
• CITATION.cff - Academic and industry citation metadata.
• LICENSE - MIT License.