Where payment status comes from

The answer to “which code”

One function, one statement

All five in lib/LedgerSMB/Workflow/Persister.pm. Notably, lib/LedgerSMB/Scripts/payment.pm — the file whose name suggests it owns this — contains no status write at all. Searching for the word “payment” is what makes this trace hard.

Requirement 1

Data lineage

The dashed hop is declared in workflows/persisters.xml:12 as extra_table="transactions": the ExtraData persister keys each workflow row to a transaction id. Nothing in the database enforces it, so it is invisible to schema introspection — and it is precisely the link that makes the trace feel impossible from the DB side alone.

Requirement 3 · the three places, reconciled

What each source actually holds

The invoice templates under templates/ are the fourth place people look and the one place status never lives: they render a posted transaction, and hold no state of their own.

The allowed transitions

Payment state machine

Whether approve or batch-approve fires is decided by one condition, is-batch-member, defined at workflows/payment.conditions.xml:2 as the test $context->{'batch-id'} — evaluated against the JSON in workflow_context. That is the whole reason a payment “fails” to approve individually: it belongs to a batch.

Requirement 3 · proof

Every claim, and where it came from

The economics

Why this needed a compiler, not a search

A capable model with grep can reach this answer. The question is what it costs to reach it, whether the same question costs that again tomorrow, and whether the answer arrives with its evidence attached or has to be re-verified by hand.

The amortisation is the real argument. Compiling LedgerSMB read roughly 2.3 M tokens’ worth of source once and produced 6,807 objects, 3,114 relationships and 7,677 evidence records. Every question after that is answered from the compiled model, not from the source. The first question is roughly break-even with a careful manual search; the tenth is not close.

And one hop is not findable by search at all. The link from transactions to workflow is not a foreign key and not a string either side would match — it is the attribute extra_table="transactions" in a persister configuration file. No amount of grepping payment or status reaches it, because neither word appears. It is reachable only by knowing the workflow engine is involved, which is what the compiled graph tells you first.

Runbook

Reproduce this on your own repository

Six ordered steps. Each stage of the pipeline writes the artifacts the next one consumes, so the order is not a suggestion. Steps 2 and 4 exist because the two failures that matter most in this tool are silent ones.

1. Install

   Rust 2024 edition. The Cargo workspace root is ekos/, not the repository root.

   git clone https://github.com/alexeyban/EKOS.git
   # the Cargo workspace root is the ekos/ subdirectory, not the repo root
   cd EKOS/ekos
   cargo build --release
   
   # optional — put `ekos` on your PATH
   cargo install --path crates/cli

2. Write ekos.toml in your project root

   Three settings decide whether the compile succeeds. All three failed silently in this project before they were set correctly.

   # Scope of observation
   [workspace]
   root = "."
   
   [observe]
   # Use "." — NOT a list of subdirectories. Observers run once per entry with that
   # entry as their root, and the git connector only checks <root>/.git. A list like
   # ["src", "sql"] silently yields ZERO commits.
   paths = ["."]
   
   # Matched against exact path COMPONENTS — not globs. Filenames count too, so
   # "favicon.ico" works but "*.png" never will. Prune binaries and generated output.
   ignore-patterns = [
       ".ekos", ".git", "node_modules", "target",
       "images", "css", "img",          # binary assets
       "locale",                        # translation catalogues
       "dist", "build", "coverage",     # generated output
       ".venv", "site-packages",        # third-party code is NOT your architecture
   ]
   
   # Load-bearing. The wrong dialect fails the whole-file parse and your entire
   # schema disappears behind one buried SQL001 warning.
   [recover.sql]
   default-dialect = "postgres"   # or mysql / mssql / snowflake / databricks / clickhouse
   
   # Per-folder override, first path-glob match wins:
   # [[recover.sql.dialect-rules]]
   # path-glob = "warehouse/**"
   # dialect   = "snowflake"

   Two optional blocks. Without either, the pipeline makes no model calls at all and every structural fact in this report is still recovered — the schema, the foreign keys, the lineage and the author-written descriptions are all deterministic.

   A · Language model — pick one

   # Local, free, no key. Slowest, and needs RAM.
   [llm]
   provider = "ollama"
   model    = "llama3:latest"
   # context-window = 8192   # sent as num_ctx; Ollama otherwise truncates silently
   
   # ── or ── OpenAI proper
   [llm]
   provider    = "openai"
   model       = "gpt-4o-mini"
   api-key-env = "OPENAI_API_KEY"   # default; the key is read from the env, never stored here
   
   # ── or ── any OpenAI-compatible host: OpenCode Zen, OpenRouter,
   #         DeepSeek, Groq, a self-hosted vLLM or llama.cpp server
   [llm]
   provider    = "openai"
   base-url    = "https://opencode.ai/zen/v1"
   model       = "deepseek-v4-flash"
   api-key-env = "OPENCODE_API_KEY"
   
   # Only if SQL004 reports a response hitting its ceiling. Unset = a budget
   # computed per file from its own table and foreign-key count.
   # max-tokens = 32768

   Precedence for each value is [llm] first, then the env var (OPENAI_MODEL, OPENAI_BASE_URL), then the built-in default. A base-url takes no trailing slash; requests go to {base-url}/chat/completions.

   B · Embeddings — what turns on --mode vector and --mode hybrid

   # Local, free. The safe default, and unrelated to which chat model you use.
   [embeddings]
   enabled  = true
   provider = "ollama"
   model    = "nomic-embed-text"     # provider default
   cache    = true                   # default — .ekos/embed-cache/
   
   # ── or ── OpenAI embeddings
   [embeddings]
   enabled     = true
   provider    = "openai"
   model       = "text-embedding-3-small"   # provider default
   api-key-env = "OPENAI_API_KEY"

   Embeddings are built by a post-commit pass, so after adding this block re-run ekos commit — the vector index does not exist until you do. commit then prints Vector embeddings: N embedded.

   Two traps in this block specifically

   Omitting provider It falls back to [llm] provider, and if that is also unset, to mock — deterministic nonsense vectors. Hybrid search will appear to work and rank meaninglessly. Always name the provider explicitly.

   Cloud chat ≠ cloud embeddings [embeddings] provider = "openai" posts to api.openai.com and ignores [llm] base-url. Running chat through Zen or OpenRouter and leaving embeddings to inherit means the embed pass hits OpenAI with the wrong key. Pair a non-OpenAI chat host with provider = "ollama" here.

3. Check the scope before you compile anything

   This reads no file contents and costs nothing. It is the cheapest place to catch a mis-scoped config.

   ekos config validate
   ekos config preview-scan

   across 1 root(s)git history will be observed. More than one root means it will not.

   file countWildly higher than your source tree? Something generated is being ingested.

   known false positivevalidate warns that a filename entry such as favicon.ico “matches nothing”. It does match — the check runs on every path component, filenames included. Verified against the compiled ledger; ignore the warning.

4. Run the pipeline, in order

   Each verb is a compiler stage. On a repository this size expect roughly ten minutes end to end, most of it in commit.

   ekos init
   ekos build      # observe files → content-addressed artifacts
   ekos recover    # artifacts → typed KIR (SQL, git, JS/TS, docs)
   ekos resolve    # merge duplicate identities; candidates go to review
   ekos compile    # KIR → Canonical Knowledge Model
   ekos commit     # CKM → append-only ledger + search index

5. Verify it actually worked

   A clean exit code is not success. Both failures this project hit exited zero.

   ekos status
   ekos ekl "FIND Object WHERE kind = 'Table' COUNT"
   grep -c SQL001 .ekos/diagnostics/recover.log

   Table countZero for a repo that plainly has a schema means the dialect is wrong — fix [recover.sql] and re-run from recover.

   Git commits analysedrecover prints this. Zero means paths is not ["."].

   SQL001“no tables found”. Expected for migration and view files; suspicious on your main schema file.

   SQL004Enrichment named fewer tables than the file declares. Raise [llm] max-tokens if it names a ceiling.

6. Ask your question, then produce the document

   Search narrows; the graph traverses; EKL filters. Run these from inside the workspace — the ledger is resolved from the working directory.

   # 1 — which objects are even involved (lexical works with no extra setup;
   #     --mode hybrid/vector needs [embeddings] enabled and a re-run of commit)
   ekos query find "payment status" --mode lexical
   
   # 2 — what it touches, N hops out (this is the part grep cannot do).
   #     Takes an object id from step 1, not a name.
   ekos query neighbourhood c600e4f4-f88b-5d21-94ac-7d918d48dcf3 --depth 2
   
   # 3 — structured filters over the compiled model
   #     entity is always Object/Relationship/Event; kind is a WHERE clause
   ekos ekl "FIND Object WHERE kind = 'Table' AND name CONTAINS 'payment'"
   ekos ekl "FIND Object WHERE kind = 'Table' COUNT"
   
   # 4 — a grounded natural-language answer with citations
   ekos ask "which code updates payment status?"

   For the document itself, either render one deterministically from the ledger — no model, no cost:

   ekos docs generate --layout solution-architect
   # → DependencyRiskReport.md, OnboardingGuide.md, FindingsMemo.md
   
   ekos docs generate --layout curated --format html --output doc
   # → README / Architecture / API / SequenceDiagrams

   …or expose the ledger to a coding agent over MCP and let it assemble a bespoke report, which is how this page was built:

   ekos mcp serve --workspace /path/to/project        # stdio
   ekos mcp serve --http 127.0.0.1:7331 --token-file .ekos/token

   The agent then has ekos_search, ekos_query, ekos_neighborhood, ekos_dependents, ekos_impact and ekos_ekl as read-only tools — it retrieves evidence instead of reading your repository.

When it goes wrong

The ledger is append-only. Re-running the pipeline adds a new version of every changed object rather than overwriting, so a rebuild is always safe and the previous state stays queryable with ekos diff.