Arkitekturregel

Ett användargränssnitt är en konsument av ledgerctl, inte en alternativ budgetmotor.

En konsument ska:

• starta dokumenterade ledgerctl budget ... --format json-kommandon,
• kontrollera schema_version,
• behandla pengar som exakta decimalsträngar,
• använda revisionen för mutationsskydd,
• visa backendens fel och diagnostik tydligt.

En konsument ska inte:

• importera Python-moduler direkt från parse-engine/modules,
• tolka hLedger-journalerna själv,
• räkna om kuvertbalanser eller invarianten,
• skriva funding.journal eller auto.journal.

Annars uppstår två system som kan ge olika svar om samma pengar.

Läs-API

Status

ledgerctl budget status --month 2026-07 --format json

Det aktuella statuskontraktet använder schema_version: 3. Viktiga fält är bland annat:

• schema_version,
• generated_by,
• revision,
• period,
• currency,
• balances,
• balanced och difference,
• mutation_policy, som beskriver periodskydd och blockerande orsak,
• coverage, som beskriver otäckta eller tvetydiga utgifter,
• envelopes.

Pengar ser ut så här:

{
  "budgeted": "700.00",
  "spent": "910.00",
  "remaining": "-210.00"
}

De är strängar för att undvika flyttalsfel.

Historik

ledgerctl budget history books \
  --month 2026-07 \
  --months 12 \
  --format json

Kontraktet innehåller både historikrader, definierade snittfönster och bidragande transaktioner. Konsumenten ska inte anta att en kortare visningslista räcker för att själv räkna ett 12-månaderssnitt.

Analytics för diagram och analys

ledgerctl budget analytics books \
  --month 2026-07 \
  --months 12 \
  --format json

Detta kontrakt är avsett för tunna konsumenter. ledgerctl räknar fram exakta belopp, förbrukningsgrad, analystillstånd och snitt. Historiken levereras i kronologisk ordning. Emacs eller webben väljer endast presentation, exempelvis SVG, Unicode eller ASCII.

Insights för hela ekonomin

ledgerctl budget insights \
  --month 2026-07 \
  --months 12 \
  --format json

Version 2 samlar månadens totaler, utgifter per kuvert, utgifter per merchant och en kronologisk månadstrend i ett enda revisionskonsistent dokument. Den innehåller dessutom jämförelser mot föregående månad och medianen för högst sex tidigare månader, explicit budgetavvikelse per kuvert och en fördelning av positiva köp efter beloppsstorlek.

Pengar och procenttal är exakta decimalsträngar. Konsumenterna får inte själva räkna om rangordning, andelar, netto, median, differens eller budgetavvikelse.

Budget Doctor

ledgerctl budget doctor --format json

Exitkod 0 betyder inga health-check-fel. Exitkod 1 betyder en korrekt JSON- rapport som innehåller ett eller flera fel. Andra exitkoder är operativa fel.

Mutations-API

Mutationer följer samma livscykel:

status/revision
    │
    ▼
preview utan --apply
    │ validera kontrakt och visa konsekvens
    ▼
användarbekräftelse
    │
    ▼
samma operation + samma revision + --apply
    │
    ▼
full omläsning av status

Konsumenten ska jämföra den relevanta operationssignaturen mellan preview och apply. Den ska inte låta användaren bekräfta en konsekvens och sedan skicka andra argument.

Larin CLI-konsumenten

bin/larin är en synkron, användarvänlig terminalkonsument. Den:

• visar status och Budget Doctor från JSON,
• listar merchants och kuvert genom respektive API,
• registrerar köp genom Purchase API:t,
• skapar merchants och kuvert samt uppdaterar kuvert genom admin-API:ernas preview/apply-flöden,
• erbjuder readline-baserad TAB-komplettering,
• läser eller skriver aldrig arbetsytans datafiler direkt.

Larin CLI använder mänsklig textutdata. Program som behöver stabilt maskinformat ska anropa ledgerctl --format json direkt.

Se Larin terminalklient för hela användarflödet.

Emacs-konsumenten

consumers/emacs/ledgerctl-budget.el implementerar en asynkron kontrollpanel. Den läser status och analytics via JSON och använder preview/apply för fem budgetmutationer:

• tilldela från Ej fördelat,
• sätt månadens budget,
• flytta mellan kuvert,
• spegla off-budget-drift,
• svep positiva månadssaldon,
• guidad driftreparation före budgetredigering,
• omklassificering av manuella köp som behöver uppmärksamhet,
• uppdatering av merchantprofil i administrationsvyn.

Emacs skriver aldrig journalerna direkt.

Arbetsytemedvetna filbuffertar

När Emacs-konsumenten är laddad aktiveras normalt ledgerctl-workspace-global-mode. Om du öppnar exempelvis finance.journal, routes.conf eller en annan fil under budgetarbetsytan förblir filen öppen i sitt vanliga major mode och är fortfarande redigerbar. Larin ersätter alltså inte filen med budgetpanelen.

Arbetsytan identifieras asynkront genom det versionsmärkta JSON-kommandot:

ledgerctl workspace locate --format json

När upptäckten lyckas visas Larin[ARBETSYTA] i mode line och C-c l ger hela Larin-prefixet. Om which-key-mode är aktivt visas korta svenska namn i menyn i stället för de interna Emacs Lisp-funktionsnamnen. Tangent och funktion avskiljs med → för tydligare visuell gruppering:

Konsumenten tar bort ett eventuellt ärvt LEDGERCTL_CONFIG just för upptäcktsprocessen. Därmed avgör den besökta filens katalog vilken arbetsyta som hittas; en shellvariabel från en annan terminalsession kan inte koppla filen till fel budget.

Automatisk upptäckt sker endast under hemkatalogen som standard och kan utökas med ledgerctl-workspace-search-roots. Den kan stängas av genom att sätta ledgerctl-workspace-auto-enable till nil före require, eller genom M-x ledgerctl-workspace-global-mode.

Installation i Emacs

Lägg konsumentkatalogen i load-path. Om ledgerctl inte finns i Emacs processmiljös PATH ska programvägen sättas före require, så att även redan öppna filbuffertar kan upptäckas direkt:

(add-to-list 'load-path
             "/sökväg/till/Larin/consumers/emacs")
;; Behövs bara när ledgerctl inte finns i PATH:
;; (setq ledgerctl-budget-program "/sökväg/till/Larin/bin/ledgerctl")
(require 'ledgerctl-budget)

Ange arbetsyta explicit:

(setq ledgerctl-budget-workspace-directory "~/budget/")

När variabeln är nil kan dashboardens äldre direkta öppningskommando söka uppåt från aktuell bufferts default-directory. I vanliga besökta filbuffertar använder däremot ledgerctl-workspace-mode alltid ledgerctl workspace locate --format json och skickar den returnerade arbetsytan vidare till budget, administration, Doctor och insights. Den arbetsytan låses därefter till respektive panelbuffert.

Öppna panelen

M-x ledgerctl-budget-open

Välj period med prefixargument:

C-u M-x ledgerctl-budget-open

Tangenter i huvudvyn

I kuvertdetaljen fungerar månadsskifte, omläsning, köp, administration, Doctor och diagnostik. b eller q går tillbaka.

Adaptiva diagram

Kuvertdetaljen hämtar budget analytics. Ekonomiöversikten hämtar budget insights. Båda renderar validerad data på olika sätt beroende på Emacs-ramens kapacitet:

• grafisk Emacs med SVG-stöd: in-memory SVG,
• terminal med blocktecken: Unicode-staplar,
• enklare terminal: ASCII.

Valet kan tvingas:

(setq ledgerctl-budget-chart-renderer 'auto)
;; Alternativ: 'svg, 'unicode eller 'ascii

All ekonomisk analys kommer från ledgerctl. Emacs gör endast geometrisk skalning och presentation.

Hur panelen skyddar data

• Alla processer startas asynkront med make-process.
• Ett gammalt, långsamt svar får inte skriva över en nyare månadsvy.
• Mutationer blockeras medan en annan mutation pågår.
• Historiska månader är skrivskyddade; framtida månader tillåter endast planering av budgetmål.
• Preview och apply använder samma datum, request och revision.
• Statusens mutation_policy avgör vilket guidat arbetsflöde som visas.
• Larin/Emacs förlitar sig på ledgerctl:s kuvertmatchning och läser aldrig envelopes.conf för att fatta ekonomiska beslut.
• Efter lyckad apply hämtas hela statusen på nytt från sanningskällan.
• Emacs räknar inte själv fram den auktoritativa differensen.

Tilldela från Ej fördelat

Stå på ett kuvert och tryck a. Panelen:

1. frågar efter positivt belopp,
2. kör en JSON-preview av budget fund,
3. visar före/efter,
4. frågar om apply,
5. skickar samma datum, belopp och revision med --apply,
6. läser om status.

Ändra budgetbelopp

Stå på kuvertet och tryck e. Operationen gäller kuvertet under markören och den månad som visas. Aktuell och framtida månad är redigerbara; historik är skrivskyddad. Panelen visar hur kuvertets budget, kvar och Ej fördelat förändras innan någon skrivning sker.

Om statusens mutation_policy rapporterar budgetdrift erbjuder Emacs reparera och fortsätt, Doctor eller avbryt. Reparationen är en vanlig mirror-preview som måste godkännas. Efter apply läses den valda månaden om och den ursprungliga e-operationen fortsätter automatiskt.

Flytta mellan kuvert

Tryck m på källkuvertet. Mål väljs med completion. Panelen visar båda kuvertens före/efter och att Ej fördelat är oförändrat.

Spegla off-budget-förändring

Tryck M. Välj Ej fördelat eller ett särskilt kuvert som destination. Om invarianten redan håller avslutas operationen utan skrivning.

Svep månad

Tryck S i aktuell månad. Emacs stoppar om invarianten är bruten eller ett kuvert är negativt. För bekräftelse krävs den starka texten SVEP. UI:t exponerar inte backendens --force.

Registrera köp i Emacs

Tryck p i huvudvyn eller kuvertdetaljen, eller kör:

M-x ledgerctl-purchase-create

Emacs hämtar merchantlistan genom JSON, erbjuder completion, frågar efter belopp, datum och anteckning, visar Purchase API:ts preview och applicerar exakt samma request med revision och request_digest. Med prefixargument registreras köpet som cleared.

Klassificera om köp som behöver uppmärksamhet

Tryck C i huvudvyn eller kuvertdetaljen, eller kör:

M-x ledgerctl-purchase-reclassify-attention

Emacs hämtar ledgerctl purchase list --needs-attention och visar manuella köp som ligger i Att kategorisera eller saknar entydigt kuvert. Du väljer köp och sedan ett konto från Envelope API:t. Previewn visar konto, kuvert och journalblock före/efter. Apply återanvänder samma request, digest och revision.

Administrera merchants och kuvert i Emacs

Tryck A eller kör:

M-x ledgerctl-admin-open

Administrationsvyn läser Merchant API och Envelope API och skriver aldrig merchant-db.json, envelopes.conf eller auto.journal direkt.

Alla skrivningar använder preview och apply med revisionsskydd.

Budget Doctor i Emacs

Tryck ! eller kör:

M-x ledgerctl-budget-doctor

Vyn visar varje kontroll, sammanfattning, revision och berörda sökvägar. g kör om och D visar rå JSON och stderr.

Diagnostik

När panelen visar ett fel:

1. tryck D,
2. kontrollera exakt arbetskatalog och LEDGERCTL_CONFIG,
3. kopiera backendkommandot,
4. kör samma kommando i terminal,
5. åtgärda backend eller konfiguration innan UI-koden ändras.

Det förhindrar att ett dataproblem felaktigt behandlas som ett Emacsproblem.

Tester

consumers/emacs/run-tests.sh

Testerna använder ett temporärt backendprogram för processlivscykeln och validerar status-, history-, analytics-, insights-, doctor- och mutationskontrakten utan att skriva i din verkliga budgetarbetsyta.

Statisk webbkonsument

Webbkonsumenten exporterar en helt statisk och skrivskyddad snapshot genom samma JSON-kontrakt. För varje månad exporteras även data/insights/ÅÅÅÅ-MM.json med rangordning per kuvert och merchant samt månadstrend:

./consumers/web/export-site \
  --workspace ~/budget \
  --output ~/private-web/larin \
  --month 2026-07 \
  --months 13 \
  --history-months 12 \
  --title "Larin — Min budget"

Visa exporten lokalt genom den medföljande loopback-servern:

./consumers/web/serve-site ~/private-web/larin 8000

Öppna därefter http://127.0.0.1:8000/. Öppna inte endast index.html med file:// eftersom webbläsaren behöver läsa JSON-filer med fetch().

En mindre känslig export utan transaktioner och kuvertdetaljer:

./consumers/web/export-site \
  --workspace ~/budget \
  --output ~/private-web/larin-summary \
  --summary-only

Webbplatsen kan inte ändra budgeten, men den innehåller fortfarande privat ekonomisk information. Publicera den endast bakom ett skydd du faktiskt litar på, exempelvis privat nät, VPN eller autentisering.

Webb och framtida konsumenter

Den statiska webbkonsumenten exporterar en read-only-snapshot. Samma kontrakt kan senare användas av exempelvis:

• en mobil klient,
• ett separat desktopgränssnitt,
• ett PETSCII-gränssnitt.

En läsande konsument behöver normalt budget status och, beroende på vy, budget insights, budget analytics eller budget history. En skrivande konsument måste implementera hela preview/revision/apply-modellen och återanvända exakt samma request. Det är inte säkert att bara lägga till en "Spara"-knapp.