docs: Finch, the author's language, for SchOS's own programs

A plan, deferred behind the 1.0 freeze like everything else here: what
Finch is today (measured from its repository: LLVM, self-hosting boot/
compiler, C import, targets), what SchOS would need, and the open
question of what "finishing" it means.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015f73FesGZGYPkmDvUcj6QX

docs/plan/README.md

@@ -48,6 +48,12 @@ And the one the hybrid mechanisms were built for:
 | ~~ldls.md~~ | **Built.** The Linux Driver Layer for SchOS: someone else's drivers, in a process, reached through `/dev/pci`. `ping` works over `8139too` and over `e1000`. The description moved to [../architecture/ldls.md](../architecture/ldls.md). |
 | ~~debugger.md~~ | **Built**, all of it, including the network transport. A debugger that observes rather than halts and answers in this kernel's own vocabulary: symbols, a log that outlives the kernel, `/dev/dbg`, `whose`, hardware watchpoints, and `schdbgd`. The description moved to [../architecture/debugging.md](../architecture/debugging.md). |
 
+And one for after 1.0, recorded so the decision is not lost:
+
+| | |
+|---|---|
+| **[finch.md](finch.md)** | **Later.** The author's own LLVM language, Finch, for SchOS's applications and tools in place of C. Already self-hosting; the plan is a target, bindings generated from `include/uapi/`, and the compiler in the image. |
+
 Two longer-horizon documents sit behind these: [schapi.md](schapi.md), the API
 layering and the compatibility promise, and [roadmap.md](roadmap.md), which holds
 everything still open that is not one of the three above.

docs/plan/finch.md

@@ -0,0 +1,68 @@
+# Finch, for SchOS's own programs
+
+**Later. Not being worked on** — it is behind [1.0.md](1.0.md)'s freeze like
+everything else here that is not named there. This records the decision so it
+is not rediscovered.
+
+Finch is the author's own language: <https://pandor.pl/git/nexoniarz/Finch>
+(GitHub mirror: `Nexoniarz/Finch`). The plan is to write SchOS's own
+applications and tools in it, in place of C, and so leave behind what C does
+badly: silent narrowing, signed/unsigned mixing, undefined behaviour on an
+out-of-range index, a forgotten `free`.
+
+## What it is today (version 2.4.0)
+
+Measured from the repository, not from its README alone:
+
+- **LLVM front end**, C-like syntax, no semicolons, no headers, no preprocessor.
+  It compiles through LLVM's `-O2` pipeline to native code; there is no
+  garbage collector.
+- **Values, not references:** lists, text and structs copy on assignment and
+  are freed at the end of their block. Out-of-range indexes, division by zero
+  and null pointers stop with a runtime error rather than undefined behaviour.
+- **Errors as values** (`int(s) or 0`, `try read_file(p)`), maps, methods,
+  modules.
+- **C interop through libclang:** `import "foo.h"` plus `link "foo"` calls any C
+  library, structs by value and callbacks included. That is the way in to
+  everything SchOS already has — musl, the `/dev/*` interfaces, Alpine's
+  libraries.
+- **Targets:** Linux, macOS, Windows, on x86-64 and ARM64 (`src/target.cpp`;
+  the System V, AAPCS64 and Microsoft x64 ABIs are in `src/abi.cpp`).
+- **Tooling:** a language server (`finch lsp`), VS Code and Kate support, 74
+  tests.
+- **Self-hosting:** `boot/` is a Finch compiler written in Finch (about 3,100
+  lines, against about 5,000 for the C++ one in `src/`) that builds itself to a
+  byte-identical result — `tests/boot.sh`.
+
+## What SchOS would need to do
+
+1. **A `schos` target.** `finch` picks a triple, a C compiler and a linker per
+   target. SchOS runs unmodified Alpine binaries and Alpine's musl
+   (see [alpine.md](alpine.md)), so the first target is **the existing
+   `x86_64-unknown-linux-musl`**, and a Finch program built on the host should
+   run on SchOS before anything in Finch is made SchOS-specific. Test that
+   before writing a line of target code.
+2. **The compiler on SchOS.** Needs LLVM 21 and libclang, both of which Alpine
+   packages. That is a question of apk and memory, not of SchOS.
+3. **`boot/` as the SchOS-hosted compiler.** The C++ compiler needs LLVM's C++
+   libraries; the one in `boot/` is the candidate for being the compiler that
+   ships in the image, once it emits through LLVM's C API or a smaller
+   back end.
+4. **Bindings** for SchOS's own interfaces (`/dev/pci`, `/dev/netdev`,
+   schinit's job protocol, the framebuffer) — generated by the C importer from
+   the headers in `include/uapi/`, so they are not hand-written and cannot
+   drift from the kernel.
+
+## What "finishing Finch" means is not settled
+
+The repository has no list of what is unfinished. Before work starts, the
+author names it. Candidates seen in the tree: `note.txt` and `notatka.txt` are
+scratch files; `OpenGL.fn` was deleted in the last commit; the `boot/` compiler
+is shorter than the C++ one, so some language features may exist only in the
+latter. **The first task is to diff the two feature sets**, not to guess.
+
+## Rules
+
+- Nothing in the kernel is rewritten in Finch. It is for applications and tools.
+- No new capability starts until [the register of unfinished work](1.0.md#the-freeze-and-the-register-of-unfinished-work)
+  is empty; this document is a plan, not an exception to that.