five/docs/five-philosophy-en.md

# Five — Code Fades, but Thought Endures

> *"Good code is not what machines execute, but what humans read."*
> — Charles KWON OhJun

---

## Prologue: The Weight of 30 Years

In the 1990s, a quiet revolution was happening in small offices around the world. Not in Silicon Valley — in accounting departments, warehouses, and municipal offices. A language called xBase, born from dBASE and evolved through Clipper and Harbour, was running the machinery of daily commerce.

It calculated payroll. It tracked inventory. It generated invoices. It reconciled bank statements at midnight. It printed reports that made decisions possible. In South Korea, Brazil, Spain, Russia, and dozens of other countries, xBase was the invisible engine behind millions of small and medium businesses.

The developers who wrote this code weren't computer scientists. They were accountants who learned to program. Warehouse managers who automated their own work. Small business owners who couldn't afford enterprise software. They wrote code that was practical, direct, and human-readable — because they had to understand it themselves.

Then the world changed. Java arrived with its enterprise promises. .NET came with its corporate backing. Python charmed the academic world. JavaScript conquered the web. Each new wave declared everything before it obsolete.

But those payroll systems kept running. That inventory code kept counting. Thirty years later, PRG code written by an accountant in 1995 still calculates someone's salary today. Not because it's perfect — because it works, and because no one dares to touch what works.

**Should we throw it away?**

The technology industry says yes. Modernize. Rewrite. Migrate.

I say no. And Five is my answer.

---

## Chapter 1: The Cost of Starting Over

### The Rewrite Fallacy

Every few years, the software industry reinvents itself and declares a great migration. COBOL to Java. Java to microservices. Monoliths to cloud. Each time, the promise is the same: rewrite it in the new thing, and everything will be better.

The reality is different.

In 2003, a European bank spent €200 million rewriting its COBOL core banking system in Java. After five years and three failed launches, they went back to COBOL. The original developers had retired. The business rules encoded in those COBOL programs were undocumented — they existed only in the code. The Java team couldn't replicate them, because they couldn't read the old code, and the people who could were gone.

This story repeats everywhere. A Brazilian logistics company rewrites its Clipper system in Python. The new system works — but calculates ICMS tax differently by 0.03%. This costs them R$400,000 in fines before anyone notices. The original Clipper code had a special case for interstate transfers that was never documented. It was in an `IF` block that a programmer added in 1997 after an audit.

**The code was the documentation. When the code was discarded, the knowledge was lost.**

This is not a technology problem. It is an epistemology problem. Code is not just instructions for machines — it is crystallized knowledge. Every bug fix, every edge case, every workaround represents a lesson that someone learned the hard way. Throwing away working code is burning a library because you prefer a different filing system.

**Five's First Principle: Don't change a single line of existing code.**

```prg
// Written in 1997 by an accountant who learned to program.
// Contains 23 years of tax regulation changes.
// Nobody fully understands why line 847 checks for February 29th.
// But it has never been wrong.
USE tax_tables NEW
SET FILTER TO year >= Year(Date()) - 5
GO TOP
DO WHILE !Eof()
   IF tax_type == "ICMS" .AND. state_from != state_to
      nRate := special_rate     // Line 847. Don't touch this.
   ENDIF
   SKIP
ENDDO

// In Five, this runs unchanged.
// AND in the same file, you can now add:
IMPORT "net/http"
// Serve this calculation as a REST API.
```

---

## Chapter 2: Why Go — A 50-Year Bet

### The Graveyard of Languages

The technology industry has a short memory. Languages rise and fall like empires. ActionScript. CoffeeScript. Perl 6. Objective-C. Each was once "the future."

When choosing the foundation for code that must survive decades, you cannot follow trends. You must follow principles.

### Three Questions That Filter Everything

**1. Will it still be alive in 10 years?**

Go was created by Rob Pike, Ken Thompson, and Robert Griesemer at Google in 2009. Pike co-created UTF-8 and Plan 9. Thompson co-created Unix and C. These are people who think in decades, not quarters.

But Google's backing is not why Go will survive. **Simplicity** is.

Go has approximately 25 keywords. Python has 35. Java has 67. C++ has over 90.

Go had no generics for 13 years. This was not an oversight — it was philosophy. Every feature has a cost. A feature that makes 5% of programs elegant makes 95% of programs harder to read. The Go team waited until they found a design that didn't sacrifice simplicity.

Go has no exceptions. Instead, it returns errors as values. This seems primitive. But it means every error is visible in the code. You cannot accidentally ignore an error — it's right there, demanding to be handled. Twenty years of Java `catch(Exception e) {}` blocks prove that invisible error handling is worse than verbose error handling.

Go has no inheritance. It has interfaces and composition. This eliminates entire categories of bugs (fragile base class, diamond inheritance, deep hierarchies) that have plagued object-oriented programming for 30 years.

**A language that rejects complexity does not follow fashion. It survives fashion.**

C was created in 1972. It is still the foundation of every operating system. Its survival is not despite its simplicity — it is because of it. Go is the C of the 21st century.

**2. Does it align with the future of hardware?**

Moore's Law is dead. Clock speeds have plateaued at 4-5 GHz since 2005. What grows is core count. A modern server has 64, 128, or 256 cores. A smartphone has 8.

Most programming languages were designed for single-threaded execution. Concurrency was bolted on afterward — threads in Java, asyncio in Python, goroutines in... wait. Goroutines weren't bolted on. They were the reason Go was created.

Go was designed from the first line of its specification to run on many cores. goroutines are not threads — they are lightweight, multiplexed across OS threads, and communicate through channels. Creating a million goroutines costs less memory than creating a thousand Java threads.

Five brings this power to PRG syntax:

```prg
// One line. All CPU cores utilized. No thread pools. No mutexes.
PARALLEL FOR i := 1 TO 100000
   aResult[i] := ProcessItem(aData[i])
NEXT

// Channel communication — data flows like water through pipes
ch := Channel()
SPAWN {|| ch <- ExpensiveCalculation() }
? "Working on other things..."
result := <- ch    // Result arrives when ready
```

In Java, this requires ExecutorService, Future, CompletableFuture, and 30 lines of boilerplate. In Five, it reads like English.

**3. Is the output self-contained?**

Go compiles to a single static binary. No JVM. No interpreter. No runtime. No shared libraries. No package manager on the target machine.

```bash
# Build for Linux on a Mac
GOOS=linux GOARCH=amd64 five build payroll.prg -o payroll

# Deploy
scp payroll server:/usr/local/bin/
ssh server "chmod +x /usr/local/bin/payroll"

# Done. Nothing else to install. Ever.
```

This matters more than most developers realize. Every dependency is a risk. Every runtime is a maintenance burden. Every package manager is a potential supply chain attack. Docker exists largely because deploying applications with dependencies became unmanageable.

A Go binary — and therefore a Five binary — needs nothing. It runs on a bare Linux kernel. It runs in a minimal container. It runs on a Raspberry Pi. It runs on a cloud VM. The same binary, everywhere, with zero configuration.

**Your code depends on nothing except itself. That is true independence.**

---

## Chapter 3: Code in the Age of AI

### The Paradox of Artificial Intelligence

In 2024, AI crossed a threshold: it became capable of writing functional code. GitHub Copilot, Claude, ChatGPT — they generate code that compiles, passes tests, and solves problems.

This is both a miracle and a danger.

The miracle: a junior developer can produce code at 10x speed. A non-programmer can build a working prototype. The barrier to creation has fallen to nearly zero.

The danger: **the barrier to understanding has not fallen at all.**

AI generates code that works. But when it breaks — and all code eventually breaks — someone must understand it to fix it. And here lies the paradox: the more AI writes code, the fewer humans practice reading it. We are creating a generation of developers who can prompt AI to generate code but cannot debug what it generates.

### The Readability Gap

Consider this real-world scenario. An AI generates a discount calculation in Go:

```go
func calculateDiscount(items []CartItem, membership string,
    promoCode string, seasonalMultiplier float64) float64 {
    var total, discount float64
    for _, item := range items {
        price := item.Price * float64(item.Qty)
        if item.Category == "electronics" && seasonalMultiplier > 1.0 {
            price *= (1.0 - math.Min(0.15, seasonalMultiplier-1.0))
        }
        total += price
    }
    switch {
    case membership == "gold" && total > 500:
        discount = total * 0.12
    case membership == "silver" && total > 200:
        discount = total * 0.07
    case total > 1000:
        discount = total * 0.05
    }
    if promoCode != "" {
        if d, ok := promoDatabase[promoCode]; ok {
            discount = math.Max(discount, total*d.Percentage)
        }
    }
    return math.Round(discount*100) / 100
}
```

Now the same logic in Five:

```prg
FUNCTION CalcDiscount(aItems, cMember, cPromo, nSeason)
   LOCAL nTotal, nDiscount, i

   // Step 1: Calculate total (with seasonal electronics adjustment)
   nTotal := 0
   FOR i := 1 TO Len(aItems)
      nPrice := aItems[i]["price"] * aItems[i]["qty"]
      IF aItems[i]["category"] == "electronics" .AND. nSeason > 1.0
         nPrice := nPrice * (1.0 - Min(0.15, nSeason - 1.0))
      ENDIF
      nTotal += nPrice
   NEXT

   // Step 2: Membership discount tiers
   nDiscount := 0
   DO CASE
   CASE cMember == "gold" .AND. nTotal > 500
      nDiscount := nTotal * 0.12          // Gold: 12% over $500
   CASE cMember == "silver" .AND. nTotal > 200
      nDiscount := nTotal * 0.07          // Silver: 7% over $200
   CASE nTotal > 1000
      nDiscount := nTotal * 0.05          // Anyone: 5% over $1000
   ENDCASE

   // Step 3: Promo code (takes the better deal)
   IF !Empty(cPromo)
      nPromoRate := GetPromoRate(cPromo)
      nDiscount := Max(nDiscount, nTotal * nPromoRate)
   ENDIF

   RETURN Round(nDiscount, 2)
```

Both are correct. Both pass tests. But:

- A business manager can read the Five version and verify: *"Gold members get 12% over $500 — is that right?"*
- A QA tester can spot that promo codes override membership discounts (takes the higher of the two) — *"Is that the intended behavior?"*
- A new developer can understand the flow in 30 seconds without knowing the codebase.

The Go version requires a developer to mentally parse type signatures, range loops, switch expressions, and map lookups. The Five version reads like a business document with line numbers.

### AI's Blind Spot

AI can generate both versions equally well. But AI cannot verify business logic — only humans can.

The most dangerous bugs are not syntax errors or crashes. They are **logic errors that produce plausible but wrong results**:

- A tax calculation that's off by 0.01% — correct for 99.99% of cases, wrong for the edge case that triggers an audit
- An inventory system that allows fractional quantities — works fine until someone ships 0.7 of a refrigerator
- A date comparison that ignores leap years — passes every test except once every four years

These bugs survive automated testing. They survive AI code review. They are caught only when **a human reads the code and thinks about what it means**.

Five makes that human verification possible — not just for developers, but for the business people who understand the domain.

**Five's Second Principle: Code must be readable by humans — especially non-developers.**

---

## Chapter 4: Building the Bridge

### The False Choice

The technology industry presents a false binary: legacy or modern. Old code or new code. xBase or Go. Past or future.

But reality is not binary. A business needs its proven payroll logic **and** a REST API. It needs its battle-tested inventory tracking **and** real-time WebSocket updates. It needs code that has survived 30 years of audits **and** code that runs on 64 cores.

Five rejects the false choice. **It builds a bridge.**

### Not a Transpiler — A Fusion Language

A transpiler converts code from one language to another. CoffeeScript transpiles to JavaScript. TypeScript transpiles to JavaScript. They are translation layers — useful, but limited by the source language's concepts.

Five is different. Five is a **fusion language** — it doesn't translate Harbour into Go. It creates a new language that natively speaks both.

TypeScript added types to JavaScript's world. Kotlin removed pain points from Java's world. **Five places Go's future on top of xBase's 30-year foundation, and the join is seamless.**

```prg
// Past: xBase — data processing that has worked for decades
USE customers NEW
INDEX ON Upper(name) TO cust_idx
SEEK "CHARLES"
? customers->name, customers->balance

// Present: Go ecosystem — modern capabilities
IMPORT "database/sql"
IMPORT "net/http"
db := sql.Open("postgres", connStr)
db:Exec("INSERT INTO audit_log VALUES (?, ?, ?)", Date(), Time(), "access")

// Future: Concurrency — the next decade of hardware
SPAWN {|| SyncToCloud(db) }
WATCH
CASE msg := <- chUpdates
   ProcessRealTimeUpdate(msg)
CASE <- chTimeout
   FlushBatchUpdates()
END WATCH
```

Past, present, and future coexist in a single `.prg` file. There is no migration project. There is no rewrite phase. There is only continuous evolution.

### The Philosophy of IMPORT

```prg
IMPORT "database/sql"
```

This single line is Five's most radical design decision.

In other bridged languages, accessing the host language requires ceremony. JNI in Java requires C header generation, native compilation, and manual memory management. Python's ctypes requires structure definitions and calling convention specifications. Node.js N-API requires C++ wrapper classes.

Five requires one word: `IMPORT`.

After that word, Go's entire ecosystem — 500,000+ packages for databases, HTTP, cryptography, image processing, machine learning, blockchain, and everything else — is available in PRG syntax. No wrappers. No code generation. No FFI declarations.

```prg
IMPORT "strings"

? strings.ToUpper("hello")   // Just works. As PRG. In PRG.
```

This is not a technical trick. It is a philosophical statement: **the boundary between languages should not exist.** When a developer needs a capability, the language should provide it, not force them to step outside the language to get it.

What other languages call "foreign function interface," Five calls **"just IMPORT."**

---

## Chapter 5: What Was Designed

Five is not a collection of features. It is a system of principles, each reinforcing the others.

### Principle 1: Compatibility is Non-Negotiable

232 out of 236 Harbour test files parse correctly (98%). Every xBase command — `USE`, `SEEK`, `SKIP`, `REPLACE`, `INDEX ON` — works as expected. 351 Harbour RTL functions are implemented. DBF, NTX, and CDX index engines were reimplemented in Go from scratch, reading the same binary file formats that Clipper created in 1987.

This was the hardest part. Not technically — the algorithms are well-documented. Hard because of the temptation to "improve" things. To change `USE` to something "better." To replace `SKIP` with an iterator pattern. To modernize the syntax.

We resisted. **Every deviation from Harbour compatibility is a broken promise to every developer who trusted xBase with their career.**

### Principle 2: The Boundary Must Be Invisible

When a Five developer writes `db := sql.Open("sqlite", ":memory:")`, they don't think "I'm calling Go code." They think "I'm opening a database." When they write `db:Exec("CREATE TABLE ...")`, they don't think "I'm using reflect-based method dispatch." They think "I'm creating a table."

Beneath the surface, Five's Go bridge performs type conversion, method caching, and FastPath optimization to achieve within 2x of native Go performance. But the developer never sees this. The boundary between Harbour and Go is invisible.

This required three layers of optimization:
- **FastPath**: Common function signatures (string→string, string,string→bool) bypass reflection entirely — 11x faster
- **Method Cache**: Go object method lookups are cached by type+name — 1.8x faster
- **Auto Type Conversion**: Harbour Values and Go types convert automatically — zero developer effort

**The best integration is one you don't notice.**

### Principle 3: Powerful Things Need Not Be Difficult

Go's concurrency model is arguably the best in any mainstream language. But it requires understanding goroutines, channels, select statements, WaitGroups, and Mutexes. A typical concurrent Go program is 50-100 lines of carefully synchronized code.

Five reduces this to vocabulary:

| Concept | Go | Five |
|---------|----|----|
| Launch parallel work | `go func() { ... }()` | `SPAWN {|| ... }` |
| Send to channel | `ch <- value` | `ch <- value` |
| Receive from channel | `value := <-ch` | `value := <- ch` |
| Wait for multiple | `select { case ... }` | `WATCH / CASE ... / END WATCH` |
| Parallel loop | 30 lines of goroutine+WaitGroup | `PARALLEL FOR ... NEXT` |
| Async operation | goroutine + channel + error handling | `future := ASYNC expr` |
| Wait for result | `<-ch` + error check | `result := AWAIT future` |
| Timeout | `context.WithTimeout` + 10 lines | `WITH TIMEOUT 3 ... END` |

A developer who has never heard of goroutines can write concurrent code in Five. Not dumbed-down concurrency — real goroutine-based parallelism, with channels and select. The power is the same; only the complexity of expression is reduced.

### Principle 4: Code That's Hard to Get Wrong is Good Code

Every safety feature in Five was added because of a real failure mode observed in production Harbour/xBase systems:

- **Analyzer warns on undeclared variables** → because misspelled variable names (`nToatl` instead of `nTotal`) have caused financial errors in production systems, silently creating new PRIVATE variables
- **DEFER guarantees resource cleanup** → because database connections left open by error paths have crashed production servers at 3 AM
- **VM Shutdown auto-closes all databases** → because Ctrl+C during a write operation has corrupted DBF files, losing months of data
- **Signal handlers restore terminal** → because a crash in raw terminal mode has rendered terminals unusable, requiring SSH session restarts

These aren't theoretical concerns. They are battle scars from decades of xBase deployment.

### Principle 5: Even When AI Creates, Humans Must Own

Hungarian notation — `cName`, `nAge`, `lActive`, `aItems`, `dBirthday` — is considered outdated by modern programming. Five embraces it deliberately.

When AI generates a function, the variable names tell you the types:
```prg
FUNCTION CalcShipping(cCountry, nWeight, lExpress, aItems, dShipDate)
```

Without reading a single line of the body, you know:
- `cCountry` is a string (character)
- `nWeight` is a number
- `lExpress` is a boolean (logical)
- `aItems` is an array
- `dShipDate` is a date

This is self-documenting code at the variable level. AI can generate it, and humans can verify it — instantly, without IDE support, without documentation, without asking the AI what it meant.

**In the AI era, code ownership means code readability. If you can't read it, you don't own it.**

---

## Chapter 6: Toward the Future

### The World Five Envisions

Imagine this:

A payroll system written in 1995 by an accountant in São Paulo. It has survived currency changes (Cruzeiro → Real), tax reforms, labor law amendments, and three generations of hardware.

In 2026, without changing a single line of the original code, it now:
- Serves payroll data through a REST API (`IMPORT "net/http"`)
- Stores backups in PostgreSQL (`IMPORT "database/sql"`)
- Processes 10,000 employees in parallel (`PARALLEL FOR`)
- Sends results to mobile apps via WebSocket
- Runs as a single binary on a cloud VM with zero dependencies

The accountant who wrote the original code retired in 2010. But a new developer, hired yesterday, can read the payroll calculation and understand it — because it's written in PRG, and PRG reads like a business document.

**This is not "maintaining legacy code." This is living code that grows.**

### The Independence Manifesto

The technology industry has a dependency problem. Modern applications depend on cloud services that can change pricing, package repositories that can be compromised, frameworks that release breaking changes, and AI services that can be discontinued.

Five is designed for independence:

- **No runtime dependency**: Single binary. No JVM, no interpreter, no container runtime.
- **No cloud dependency**: Runs on any Linux/macOS/Windows machine. Compiles for ARM, x86, RISC-V.
- **No framework dependency**: The language is the framework. `USE`, `IMPORT`, `SPAWN` — they're keywords, not library calls.
- **No AI dependency**: Code is human-readable. When the AI service goes down, you can still read, debug, and modify your code.

**Your code must remain yours. Regardless of what happens to the services, platforms, and tools you used to create it.**

### On the Shoulders of Giants

Five did not emerge from nothing. It stands on the shoulders of:

- **dBASE** (1979) — Wayne Ratliff's vision that databases should be as easy as spreadsheets
- **Clipper** (1985) — Nantucket's proof that xBase could be compiled, not just interpreted
- **Harbour** (1999) — The open-source community's gift of xBase freedom
- **Go** (2009) — Pike, Thompson, and Griesemer's bet that simplicity wins
- **Every xBase developer** who trusted this family of languages with their career and their clients' businesses

Five is the next chapter. Not a replacement — a continuation.

---

## Epilogue: The Question

In 50 years, when someone examines the code that ran the world's businesses in the 2020s, what will they find?

Will they find tangled microservices in languages that no longer exist, deployed on cloud platforms that have been acquired and shut down, depending on packages from registries that have been compromised?

Or will they find this:

```prg
USE customers NEW
GO TOP
DO WHILE !Eof()
   IF balance > 10000
      ? name, balance
   ENDIF
   SKIP
ENDDO
```

And understand it immediately.

**We cannot predict the future. But we can write code that the future can still read.**

---

> *"The measure of a language is not what it can express,*
> *but what it allows a stranger to understand."*
>
> — Five, 2026

---

*Five is created by Charles KWON OhJun (권오준).*
*A fusion of 30 years of xBase heritage and Go's vision for the next 50.*
*Written for the developers who build the systems that people depend on.*