docs(openkal): the design record in academic register, and current through 0.4 (#463)

The design document was written across four rounds and accumulated the register
of working notes: emphasis carried by symbols rather than by sentences, second
person, and colloquial phrasing. It is rewritten as declarative prose. No
technical claim is removed and no measurement is dropped; the changes are to how
the document reads, and to what it covers.

Three substantive additions accompany the rewrite.

A summary places the eight assessment dimensions at the head of the document,
each with the section that argues it: architecture, stability, simplicity,
consumer experience, compatibility, portability, consistency, and upgrade without
disruption. Previously the dimensions were argued in the text and nowhere
collected, so the document could not be read as an assessment.

The record now runs through 0.4 rather than stopping at 0.2. Three sections are
added: what the extension to eight interfaces derived and from what; the two
rules 0.4 states that 0.3 did not; and what a second implementation and a C
library above the stack establish — together with what they do not, since both
implementations were written by one author and their agreement on the argument
vector was both unanimous and wrong.

A section on consistency records that openkal was implemented twice without
modifying mcpp, and enumerates the mechanisms used: conditional dependencies,
platform-selected development dependencies, absence of a module as a compile-time
capability check, and a static comparison of the exported surface. None is new.
That every declaration a project makes resides in its `mcpp.toml` is the
constraint under which the capability configuration file was removed.

The completeness plan gains the dimension it was missing — consistency — and a
record of where the work stands against its own five criteria for completeness.
Two are met, one is partly met, one is not met and not attempted, and one is not
met for a reason worth stating: a second implementation by the same author is not
the second implementation that criterion asks for.

Co-authored-by: speak-agent <x.d2learn.org@gmail.com>

Author: Sunrisepeak

.agents/docs/2026-08-20-openkal-completeness-plan.md

@@ -295,7 +295,20 @@ namespace, a hosted system without one, a capability-based kernel, and a
 freestanding target. An interface that any of the four could satisfy only by
 constructing a compatibility layer is decomposed again rather than admitted.
 
-### 4.7 Upgrade
+### 4.7 Consistency
+
+The extension introduces no vocabulary the ecosystem does not already have. An
+implementation is selected by a conditional dependency, an interface it does not
+provide is absent as a module, and the exported surface is compared against a
+list of names. None of these is new, and none required a change to the build
+system: openkal was implemented, twice, without modifying mcpp.
+
+The constraint that admits no exception is that every declaration a project makes
+resides in its `mcpp.toml`. A configuration file accompanying the capability
+record was drafted and removed for violating it, and the rule that replaced the
+record was chosen partly because it requires no file at all.
+
+### 4.8 Upgrade
 
 An implementation adds interfaces without altering those it already provides. A
 program observes the addition through dependency resolution. No existing
@@ -322,6 +335,37 @@ Criterion 3 is the one that distinguishes this work from a portable C library.
 A specification satisfied only by environments resembling the one it was written
 against has not been validated, however many programs it hosts.
 
+### 5.1 State against these criteria, recorded 2026-08-20
+
+| Criterion | State |
+| --- | --- |
+| 1. A C library retargeted onto openkal | Partially met. `openkal-libc` 0.2.0 performs the two adaptations the specification places outside itself — resolving a global name against the supplied directories, and constructing synchronisation objects from the suspension primitive — and a program above it reads a file by global path, consults a variable, measures an interval and starts another program without containing any of that. Its output agrees with the system's own counter field by field. musl itself has not been retargeted. |
+| 2. A compiler toolchain above that library | Not met, and not attempted. It follows criterion 1 and is the subject of the next round. |
+| 3. A second implementation for an environment without a global path namespace | Not met. `openkal-macos` 0.2.0 is a second implementation and records four divergences from the first, but both environments have a global path namespace and both were written by one author. Section 5.2 records what that limits. |
+| 4. A conformance suite covering behaviour, absence, and the capability words | Met for the operations and the exported surface: five suites per implementation, and a surface comparison in `--complete` mode confirming all 47 names. The agreement between a capability word and the behaviour it describes is asserted for `openkal.time` and not yet for the others. |
+| 5. No implementation requires a table, a registry or a name resolver | Met. Neither implementation maintains a translation table; the handle carries an index and a generation directly. Name resolution resides in `openkal-libc`, which is where the specification places it. |
+
+### 5.2 What two implementations by one author establish, and what they do not
+
+`openkal-macos` records four divergences from the Linux implementation, and each
+is a place where an interface could have assumed a mechanism: the monotonic clock
+continues during suspension where the other stops, names are compared without
+regard to case, the spawn has no attribute setting the working directory, and
+there is no suspension primitive a program may use. These establish that the
+capability words and the interface shapes that accommodate them are necessary.
+
+The two implementations also agreed on a question the specification had not
+settled, and their agreement was worth nothing: both prepended the path to the
+argument vector, because both were written by one author from one reading. A
+second implementation by the same author establishes less than a second
+implementation by another, and criterion 3 is written as it is for that reason.
+
+The consequence for the conformance suite is recorded in
+[the portable-program findings](2026-08-20-openkal-portable-program-findings.md):
+a test that does not observe the thing cannot detect the thing. The suite started
+a program that ignores its arguments and read its status, which produced the same
+result whether the vector arrived intact or shifted by one.
+
 ## 6. Matters this plan does not settle
 
 | Matter | Status |