Getting Started with BLT: Recovering a Functional Spec from 4GL

BLT (Business Logic Transformer) reads an Informix® 4GL application — source, screen forms, SPL stored procedures, compiled binaries, and schema DDL — and recovers a functional specification: what each function does to the database, which screens bind to which columns, what validation rules guard which operations, and what messages a user sees on which path. It is not a decompiler. Every claim in the output cites the evidence it was derived from and carries an explicit confidence level, so a reviewer can tell recovered fact from inference at a glance.

Install and validate a config

BLT ships as a single, self-contained blt binary — no Python runtime or dependency install required on the target machine. Before running anything against real source, validate the YAML config against the JSON Schema so configuration drift fails fast rather than mid-run:

$ blt validate-config printers.yaml
config OK

A minimal config for a source-plus-schema run looks like this:

mode: recovery
inputs:
  source_4gl:
    paths:
      - printers.4gl
      - printers.per
  schema_ddl:
    paths:
      - printers.sql
output:
  directory: ./report/

Pick a mode

The mode field trades strictness for coverage. strict aborts the run (exit code 3) the moment it hits a stripped binary and never lets a LOW-confidence claim through — use it as a CI gate before publishing a spec. recovery (the default) keeps going on a stripped binary, emitting a diagnostic instead of failing, and lets LOW-confidence claims pass through for a human to weigh. forensic goes one step further and permits speculative claims — heuristic SQL strings recovered straight from a compiled binary's .rodata section when no source is available at all. Forensic-mode claims are always flagged for review; they are a starting point for investigation, not a verified fact.

Run the pipeline

$ blt run printers.yaml
mode: recovery
facts: 165
claims: 50
review items: 0
output: /home/user/report

Facts are the raw, per-statement observations the analyzers emit — one per SQL statement, screen field, menu command, IF predicate, and so on. Claims are the typed, evidence-cited conclusions the rule engine infers from those facts (a function performs this CRUD operation on this table; this screen field binds to this column; this IF predicate guards this INSERT). Review items are the claims that land at or below the configured confidence threshold and need a human to look at them before anyone treats them as ground truth.

Read the output

Every successful run writes to output.directory:

• spec.json — the canonical, machine-readable functional spec. Sorted-key JSON, byte-identical across re-runs on the same input, so a plain diff against yesterday's run is a real regression signal, not noise.
• spec.md — the same content rendered as Markdown, for a human reading top to bottom.
• review.md — everything that needs a second look: claims at or below the review threshold, unresolved bindings, tables the source references but the DDL doesn't define, binary diagnostics, and an evidence index so every claim traces back to the exact source line it came from.
• code_spec.json — a streamlined, code-shaped projection (tables, screens, menus, functions, workflows, SQL fragments) sized for feeding into an LLM or a downstream migration tool, with fact IDs, evidence lists, confidence scores, and review flags stripped out. Written every run, alongside one <binary>_code_spec.json slice per program the run discovers.
• evidence.jsonl (when output.emit_evidence: true) — every underlying fact, one per line, in canonical form — the full audit trail behind every claim in review.md.

Cross-source corroboration

Add a compiled binary alongside the 4GL source and BLT cross-checks the two. A database operation that would otherwise cap at MEDIUM confidence — because the resolver couldn't match it to a table in the schema DDL — gets lifted back to HIGH when the binary's own recovered SQL strings independently name the same table and operation. The lifted claim's payload records corroborated_by_binary: true and cites the matching binary-side evidence, so the confidence bump is itself auditable, not a black box:

mode: recovery
inputs:
  source_4gl:
    paths: [printers.4gl]
  binary:
    paths: [Printers.4ge]
output:
  directory: ./report/
  emit_evidence: true

Binary-only mode

When no source tree is available at all — only the compiled ELF and the schema DDL — configure binary without source_4gl. Only binary_analyzer and schema_loader run: symbols, strings, basic-block CFG, call edges, and heuristic SQL candidates recovered straight from the binary. Coverage is necessarily lower than a source-plus-binary run, and in forensic mode those heuristic candidates surface as review-flagged speculative_db_op claims rather than ordinary database-operation claims — a starting point for investigation, never presented as verified fact.

Where to go next

The worked examples walk a complete CRUD application end to end, input files and output spec side by side. The BLT product page covers licensing and download, and the interactive demo lets you try a run without installing anything locally.