Hostované ledgery teraz spracúvajú spravované cenové includes

Vaše pozície už v ledgeri sú. Ich ceny sú tou časťou, ktorú stále prepisujete.

Táto asymetria je najstaršia otrava v plain-text účtovníctve. Nákup sa zapíše raz a platí naveky: 120 NWRB {41.80 USD, 2024-03-12} zaznamenáva množstvo, náklad a dátum, a nič, čo sa stane neskôr, nezmení ani jedno z toho. Cena je opak — správna jeden deň, potom ticho nesprávna, a nesprávna spôsobom, ktorý žiadna kontrola zostatku nikdy nezachytí, pretože zastaraná cena stále perfektne sedí. Beancountova vlastná odpoveď bola vždy tá, že ich načítate nástrojom a výsledok commitnete, čo funguje a čo si mnohí zautomatizovali. Stále je to však skript, ktorý vlastníte, cron záznam, ktorý udržiavate, a súbor, ktorý zlučujete.

Ledger engine beancount.io teraz toto spracovanie robí sám, pre ledgery hostované u nás. Tento príspevok je o tom, čo skutočne vyšlo, čoho sa zámerne nedotýka a — rovnako dôležité — čo ešte nie je postavené.

Čo vyšlo​

Hostovaný ledger beancount.io môže niesť include, ktorého cieľom je namiesto názvu súboru URL:

; main.bean, in a hosted beancount.io ledger.
;
; The managed line is shown commented out on purpose: upstream `include` takes a
; file glob, so this file still loads if you copy it to your own machine. Only
; the hosted engine resolves the URL form.
 
option "title" "Taxable brokerage"
option "operating_currency" "USD"
 
include "accounts.bean"
; include "https://beancount.io/prices/ACME-USD"
 
include "transactions/purchases.bean"
include "transactions/sales.bean"

Upstream Beancount include preberá názov súboru — „zadaná cesta môže byť absolútny alebo relatívny názov súboru" je celá špecifikácia — takže URL include nie je obyčajný Beancount a ani sa tak netvári. Je to správanie hostovaného enginu, a tu je presne to, čo s ním engine robí:

• Feed materializuje ako read-only virtuálny súbor. URL sa vyrieši cez vlastnú cestu spracovania include enginu, presne tam, kde by skončil lokálny súbor, takže každá direktíva si zachová skutočné umiestnenie zdroja. Vaše bajty sa nikdy neprepisujú. Súbor, ktorý ste napísali, zostáva súborom, ktorý ste napísali.
• Načítané telo sa validuje ako obsahujúce iba ceny. price direktívy, komentáre a štyri povolené metadátové kľúče — price-source, price-kind, observed-at a provisional — a nič iné. Čokoľvek navyše zamietne celé telo. Neexistuje čiastočné načítanie, takže feed nikdy nemôže prepašovať transakciu do vašich kníh.
• Feedy sa cachujú ako nemenná revízia plus pohyblivý ukazovateľ. Obnovenie je riadené časovou značkou, nie expiráciou cache, čo znamená, že výpadok na strane poskytovateľa nemôže vziať so sebou vašu poslednú dobrú revíziu. Neúspešné obnovenie nikdy nenahradí dobrú revíziu ničím.
• Čerstvosť sa počíta pri čítaní ledgera, nie ukladá: recent, stale alebo unavailable, spolu s časom pozorovania, ktorý nahlásil samotný feed. Cena, ktorú neviete datovať, je cena, ktorú neviete auditovať.
• Spravované záznamy sú read-only. Ich úprava alebo vymazanie je odmietnuté s chybou, ktorá pomenuje spravovaný zdroj, a nezapočítavajú sa do limitov direktív — feed nesmie spotrebúvať rozpočet vášho ledgera.

Všetko v tomto zozname beží v rámci služby hostovaného ledgera. Nič z toho nemení to, čo price direktíva znamená: stále určuje výmenný kurz medzi základnou komoditou a kótovanou komoditou, presne tak, ako to definuje jazyková referencia. Úlohou enginu je iba postaviť pred loader správne, datované a priraditeľné záznamy.

Vaša vlastná cena vždy vyhráva​

Toto je tá časť, ktorá rozhoduje o tom, či je feed použiteľný pre niekoho, kto svoj ledger berie vážne, takže bude povedaná presne.

Pre rovnaký dátum a rovnaký pár komodít — a pre recipročný pár — cena, ktorú ste napísali sami, vyhráva nad spravovaným feedom, bez ohľadu na poradie include.

Nie „zvyčajne", a nie „ak dáte svoj include na koniec". Rozhodnutie o zatienení sa robí predtým, než sa zostaví cenová mapa, takže nezávisí od toho, kde sa include v súbore nachádza. Presuňte ho na začiatok, presuňte ho na koniec, rozdeľte ho do troch súborov: odpoveď je rovnaká.

; include "https://beancount.io/prices/ACME-USD"   ; hosted-engine form, again shown commented
 
; A price you wrote yourself, for the same date and pair.
; This one wins — above the include or below it, it makes no difference.
2026-09-16 price ACME 93.40 USD

(ACME je fiktívny emitent z príkladového ledgera nižšie; číslo je vymyslené, nie trhové pozorovanie.)

Prečo toto pravidlo a nie to druhé: cena vo vašom vlastnom súbore je rozhodnutie. Môže to byť zatváracia cena, ktorú váš broker vytlačil na výpise, proti ktorému odsúhlasujete, aktuálna kvóta pre riedko obchodovanú pozíciu, alebo číslo, ktoré vám prikázal použiť váš účtovník. Feed o ničom z toho nevie, a systém, ktorý ticho prepisuje človekom vytvorené číslo, prestal byť ledgerom a stal sa názorom. Feed vypĺňa medzery; neopravuje vás.

Ceny hýbu ocenením a ničím iným​

Druhé uistenie je štrukturálne, nie je to voľba politiky, a stojí za to ho ukázať na skutočných číslach, nie len tvrdiť. Tu je príkladový krypto ledger — datované loty, staking, mining, DeFi pozície, airdropy:

Vezmite z neho jeden záznam. Príde airdrop governančného tokenu a je zaznamenaný ako príjem v reálnej trhovej hodnote v deň, keď pristane:

2024-03-20 * "Uniswap" "Receive UNI governance token airdrop"
  Assets:Crypto:Wallet:MetaMask:UNI          50.00 UNI {12.50 USD, 2024-03-20}
  Income:Crypto:Airdrops                      -625.00 USD

Tých $625,00 príjmu a báza $12,50 na jednotku priradená k lotu sú teraz fakty o 2024-03-20. Každá price direktíva v ledgeri — spravovaná, ručne napísaná alebo úplne chýbajúca — necháva obe nedotknuté. Ceny menia trhovú hodnotu; nikdy nemenia množstvá, nákladovú bázu, peňažné toky, poplatky ani realizované zisky. Preto je cenový feed v prvom rade bezpečná vec, s ktorou prijmete pomoc: to najhoršie, čo môže nesprávna cena spraviť, je nesprávne vykázať, čo dnes pozícia stojí, a nikdy nemôže poškodiť číslo, ktoré dáte do daňového priznania.

Kde vás nesprávny cenový model skutočne zvádza na scestie​

Príkladový ledger s akciami a ETF ukazuje ostrejšiu verziu toho istého bodu:

Obsahuje rozdelenie akcií 4:1 a toto rozdelenie je zaznamenané správnym spôsobom — ako zmena množstva, ktorá zachováva celkovú bázu a nedotýka sa žiadneho príjmového účtu:

2025-07-15 * "Broker" "NWRB 4-for-1 share split — quantity change, not income"
  Assets:Brokerage:NWRB                   -120 NWRB {41.80 USD, 2024-03-12}
  Assets:Brokerage:NWRB                    480 NWRB {10.45 USD, 2024-03-12}

Obe strany sú $5 016,00. Trhová hodnota sa počas rozdelenia nemení — 120 akcií za $62,00 deň predtým, 480 akcií za $15,50 deň potom, $7 440,00 v oboch prípadoch — a dátum nadobudnutia v zátvorkách prežije, čo je to, čo drží predaj týchto akcií v roku 2026 ako dlhodobý.

Bežnou chybou je zaznamenať rozdelenie ako cenovú udalosť a spoľahnúť sa na „split-adjusted" sériu, aby ocenenie vyšlo správne. To funguje len dovtedy, kým je každá cena, ktorú kedy uvidíte, upravená rovnakým spôsobom. Vo chvíli, keď príde neupravené číslo — stará potvrdenka, snímka obrazovky, séria tretej strany, ktorá nič neprepočítava — pozícia je ocenená na štvornásobok svojej hodnoty a počet akcií v ledgeri už nezodpovedá výpisu brokera, takže kontrolný výraz na konci roka, ktorý by to zachytil, nemôže zabrať.

Toto je skutočný argument pre cenový feed s deklarovaným zdrojom, deklarovaným typom a viditeľným časom pozorovania: nie pohodlie, ale vedomie, podľa akej konvencie bolo vypočítané číslo, ktoré ste práve importovali. Vlastný cenový súbor príkladového ledgera je zámerne neupravený a hovorí to o sebe, a jeho dve direktívy obopínajúce rozdelenie sú napísané ako kontrola, ktorú overíte okom.

Jedna úprimná poznámka k kliknutiu do oboch embedov: prehliadač hostovaného ledgera zobrazuje zostatky účtov v nákladovej hodnote a na stránke neponúka žiadny ovládací prvok ocenenia. Ledgery vyššie sú tam, aby vám ukázali ledgery — loty, rozdelenie, predaje konkrétnych lotov — nie trhové ocenenie, ktoré prehliadač momentálne nekreslí. Oba sú verejné a oba sa dajú klonovať a spustiť lokálne.

Čo tu ešte nie je​

Záznam v changelogu má hodnotu menšiu než nič, ak vám dovolí uveriť niečomu, čo nie je pravda, takže tu je druhá polovica, jasne a bez dátumu pripojeného k čomukoľvek z toho.

• Cenový endpoint nie je verejný. Anonymná požiadavka na https://beancount.io/prices/<ALIAS> je presmerovaná na prihlasovaciu stránku. Neexistuje žiadny verejný katalóg aliasov.
• Takže toto nie je niečo, čo dnes môžete vložiť do vlastného súboru. Engine spracuje include; cesta, ktorú spracúva, ešte nie je otvorená. Keď bude, bude to mať vlastný záznam v changelogu.
• Lokálne CLI bea nespracúva URL includes. Číta súbory z disku, takže URL include lokálne zlyhá ako file glob, ktorý nezodpovedá žiadnym súborom. Podpora v loaderi tohto CLI je pomenovaný follow-up.
• Neexistuje žiadne API rozhranie. Žiadne REST, GraphQL ani MCP pole pre spravované ceny.
• Neexistuje žiadne dashboard rozhranie. Žiadna obrazovka na pripojenie feedu a žiadny štítok čerstvosti v UI; čerstvosť, ktorú engine počíta, zatiaľ nemá kde byť zobrazená.
• Snapshots a export nie sú postavené, rovnako ako katalóg nástrojov či endpoint manuálneho obnovenia.

Čo vyšlo, je vrstva enginu: spracovanie include, validácia, revízna cache, pravidlo precedencie a výpočet čerstvosti. To je tá časť, na ktorej musí stáť všetko ostatné, a je to tá časť, ktorú je najťažšie neskôr zmeniť, a preto išla prvá.

Kam sa pozrieť ďalej​

Oba ledgery vyššie sú súčasťou galérie príkladov, šiestich vypracovaných vzorov, ktoré môžete klonovať a spustiť lokálne — oba tieto zámerne obsahujú statické, do repozitára vložené cenové súbory, takže klon vytvorený o dva roky vyprodukuje ten istý report ako dnes. Všetko ostatné, čo vydávame, je na changelogu.

Ak stále udržiavate ceny aktuálne pomocou vlastného načítavača, pre lokálny ledger to zostáva správnou odpoveďou, a Beancountova vlastná dokumentácia o načítavaní cien plus udržiavaný nástroj beanprice sú miestom, kde začať.

Nechajte nudnú časť nudnou​

Dôvod, prečo sa ceny oplatí automatizovať, je ten, že sú jedinou časťou plain-text ledgera, ktorá chátra sama od seba. Beancount.io vám dáva plain-text účtovníctvo, ktoré zostáva vaše — auditovateľné, verzionované a nikdy prepísané za vaším chrbtom, čo je presne štandard, ktorý musel spravovaný feed splniť, kým sme nejaký vydali. Začnite zadarmo a majte svoje knihy v súboroch, ktoré viete čítať.