RECALL: Live Schema, Strict Mode, and the Idea That Emerged

The Compiler as the Documentation

The first version of RECALL compiled source to HTML. That was the job. Declare the page in COBOL-inspired syntax, get a self-contained HTML file out. Clean, fast, zero dependencies.

The problem that surfaced quickly: the language was growing faster than any human could track. New elements, new clause variants, new PIC types. A developer working with RECALL needed to know what was valid — not from a doc site that might be out of date, but from the actual compiler, right now.

The answer was recall schema. Not documentation generated from source. The source queried directly — the live element registry that the compiler itself uses to validate every program it compiles. If an element exists in the schema, it exists in the compiler. They cannot drift. They are the same thing.

$ recall schema

HEADING-1    PIC X        Display a primary heading
HEADING-2    PIC X        Display a secondary heading
PARAGRAPH    PIC X        Paragraph of body text
CODE-BLOCK   PIC X        Syntax-highlighted code block
CALLOUT      PIC X        Callout panel with TYPE clause
TABLE        GROUP        Data table from an ITEMS group
STAT-GRID    GROUP        Metric grid from an ITEMS group
...

Machine-readable with --json. Queryable by anything — editors, AI tools, CI pipelines. The compiler is the documentation. Drift between them is structurally impossible.

This was the first step toward something I hadn't named yet.

Strict Mode: No Silent Failures

Compilers that fail silently are worse than compilers that don't exist. A silent failure lets bad output reach production. It teaches the author that the language is unpredictable. It makes debugging a guessing game.

RECALL's strict mode (v0.7) made a firm commitment: every diagnostic is a structured, stable, queryable code. Not a string. Not a hint. A code — like RCL-001 for type mismatch, RCL-002 for value overflow, RCL-017 for a missing required component parameter.

$ recall check my-site.rcl

ERROR [RCL-001] type-mismatch — my-site.rcl:14:8
  DISPLAY HEADING-1 VISIT-COUNT
                    ^^^^^^^^^^^
  Type mismatch
  HEADING-1 expects PIC X — VISIT-COUNT is PIC 9(6)
  Hint: use DISPLAY LABEL VISIT-COUNT for numeric display

Every code is documented. Every code is lookupable:

$ recall explain RCL-001

RCL-001 — type-mismatch
Category: type
Severity: error
Message:  Element received a field of the wrong PIC type.
Hint:     Check the element's expected PIC type with recall schema.

The compiler became a colleague, not an adversary. It tells you exactly what is wrong, where, and how to fix it. And because the codes are stable, AI tools can interpret them too — not by parsing ANSI escape sequences from terminal output, but by reading structured JSON.

$ recall check my-site.rcl --format json

{
  "errors": 1,
  "warnings": 0,
  "diagnostics": [{
    "code": "RCL-001",
    "severity": "error",
    "line": 14, "col": 8,
    "message": "Type mismatch",
    "source": "DISPLAY HEADING-1 VISIT-COUNT",
    "caret": "                  ^^^^^^^^^^^"
  }]
}

Structured output for structured problems. The second step.

The COMMENT Clause: Intent as a First-Class Type

Data fields in RECALL carry PIC types — PIC X for text, PIC 9 for numbers, PIC DATE, PIC URL. The compiler knows what a field is.

What it didn't know was what a field means. A field named FETCH-SCORE is a number. But what kind of number? Higher is better or lower? What does it represent in the business context? What should an AI tool do with it?

The COMMENT clause (v0.8) answered that:

01 FETCH-SCORE PIC X(10) VALUE "2978"
   COMMENT "CAL fetch score — higher is better; cascade header uses this".

01 REVIEW-DATE PIC DATE VALUE "2027-09-30"
   COMMENT "Scheduled review window — re-evaluate thesis at this date".

Not a code comment. A structured clause — part of the field declaration, queryable via recall check --inspect, surfaced in JSON output under fieldIntent. No effect on compiled output. Full effect on any tool reading the source.

Intent became a type. Not metaphorically — structurally. A RECALL field now carries what it is (PIC type), what it contains (VALUE), and what it means (COMMENT). Three layers, all queryable, all validated by the compiler.

I didn't know it at the time, but this was the third step.

What the Chain of Steps Was Building

Taken individually, each of these features solved an immediate problem:

recall schema — stopped documentation drift. Strict mode — stopped silent failures. COMMENT — gave fields semantic context. recall check --inspect — made the full DATA symbol table visible before compilation.

What I didn't see until I was looking back at all of them together: every step was building the infrastructure for an AI compositor to operate inside RECALL with formal guarantees.

The schema gives the AI the element vocabulary — what it can produce. The DATA DIVISION gives the AI the content contract — what it has to work with. The COMMENT clauses give the AI field-level intent — what each piece of data means. The compiler validates whatever the AI produces — the human doesn't have to.

The language was quietly becoming AI-first. Not by design from day one — by disciplined iteration that kept arriving at the same underlying requirement: make intent legible to anything that reads it.

The Idea That Emerged

The natural completion of this chain is a primitive that doesn't exist yet in any publishing language:

PROCEDURE DIVISION.

   RENDER.
      DISPLAY HERO
         WITH INTENT "dramatic opening, single product, urgency without hype"
         WITH DATA PRODUCT-NAME, PRODUCT-TAGLINE, CTA-PRIMARY.

   STOP RUN.

The author declares what the block should feel like and what data it has to work with. An AI compositor — querying the live schema, reading the COMMENT clauses, respecting the ENVIRONMENT theme — expands that into valid RECALL source. The compiler validates the output. The expanded source is preserved alongside the intent clause.

What makes this different from every prompt-to-UI tool on the market is the contract. The AI cannot invent elements that don't exist in the schema. It cannot override the theme. It cannot reference fields that weren't declared. The compiler will reject invalid output with a stable diagnostic code — before the human ever sees it.

The AI is not a code generator that hands off to a human reviewer. It is a compositor operating inside a formally defined language, with the compiler as the validation layer. The human sets intent. The machine composes. The compiler enforces correctness.

That combination — constrained AI composition in a publishing language with a live schema and compiler validation — doesn't exist anywhere else in this form. It emerged from solving smaller problems in sequence, each one building the scaffolding the next one needed. The COBOL discipline made it possible: encode intent precisely enough that the machine can be trusted with it.

The idea is documented. The language is approaching 1.0. The implementation comes after.