0.4.0: the argument vector is passed unaltered, and the suite observes it

The implementation prepended the path to the argument vector, so a started
program received the caller's argv[0] at index 1 and could not be given the
name it observes as its own. Clause 7.6 of openkal 0.4 now states that the
vector is complete and is passed unaltered, and this is that change.

The suite did not detect it, and the reason is worth recording. It started
/bin/true and read the status, and /bin/true ignores its arguments — so the
same result was produced whether the vector arrived intact or shifted by one.
A test that starts a program without observing what the program received tests
the starting and not the vector.

The assertion added here starts a shell instead. `sh -c <script>` takes $0 from
its own argv[0] when no further argument is given, so the script observes the
name the caller chose; an implementation that prepended the path would give the
shell an extra argument, which it would read as a script file to open. The
assertion was confirmed to fail against the previous behaviour before the
behaviour was changed.

Three defects in continuous integration are also fixed, and they share a shape.

The specification version was stated twice, in the manifest and again in the
workflow, and the two drifted: the manifest moved to 0.3.0 while the workflow
compared against the 0.2.0 surface, so four names this implementation is
required to export were reported as unspecified. It is now read from the
manifest, which is the one place it is declared.

The assertion that the suites ran named two of the five present. Its purpose is
to catch a suite that discovers nothing and reports success, and a hand-written
list defeats that purpose the moment a suite is added. The list is now derived
from the files present.

The step that ran the example asserted a line the example does not print, in
support of an operation that no longer exists. It had never run: the step
before it failed first, and a step that never runs asserts nothing while
appearing to. It is replaced by the portable program, taken from the
specification at the version the manifest names rather than copied here.

The surface comparison is now --complete: this implementation claims every
interface, so a name it fails to export is a failure rather than an interface it
declines to provide. It exports all 47.

Author: speak-agent

.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
       # package uses modules, exported extern "C" declarations and ordinary
       # dependencies, none of which is recent; the pin exists for reproducibility
       # rather than because an older mcpp is known to fail.
-      MCPP_VERSION: 2026.8.19.3
+      MCPP_VERSION: 2026.8.19.4
       XLINGS_VERSION: v2026.8.17.2
       XLINGS_NON_INTERACTIVE: '1'
     steps:
@@ -35,30 +35,78 @@ jobs:
           mcpp --version
           mcpp self config --mirror GLOBAL
 
+      # The version of the specification this implementation is written against
+      # is stated once, in the manifest, and read from there. Stating it a second
+      # time in this file is what allowed the two to drift: the manifest moved to
+      # 0.3.0 and this file compared against the 0.2.0 surface, so four names
+      # this implementation is required to export were reported as unspecified.
+      - name: Read the specification version from the manifest
+        run: |
+          v="$(sed -n 's/^openkal[[:space:]]*=[[:space:]]*"\([^"]*\)".*/\1/p' mcpp.toml | head -1)"
+          test -n "$v" || { echo "the manifest does not name openkal" >&2; exit 1; }
+          echo "OPENKAL_VERSION=$v" >> "$GITHUB_ENV"
+          echo "written against openkal $v"
+
       - name: Conformance
         run: |
           mcpp test 2>&1 | tee conformance.log
-          # A suite that discovered nothing reports success. Both cases are
-          # asserted to have run.
-          grep -q 'conformance_stream ... ok' conformance.log
-          grep -q 'conformance_memory ... ok' conformance.log
+
+          # A suite that discovered nothing reports success, so every suite is
+          # asserted to have run. The list is derived from the files present
+          # rather than written out here: a hand-written list names the suites
+          # that existed when it was written, and a suite added afterwards
+          # escapes the assertion silently. This assertion named two of five.
+          missing=0
+          for f in tests/*.cpp; do
+            name="$(basename "$f" .cpp)"
+            if ! grep -q "^$name \.\.\. ok" conformance.log; then
+              echo "suite did not run, or did not pass: $name" >&2
+              missing=1
+            fi
+          done
+          test "$missing" -eq 0
+
+      - name: The specification, at the version the manifest names
+        uses: actions/checkout@v4
+        with:
+          repository: mcpplibs/openkal
+          ref: ${{ env.OPENKAL_VERSION }}
+          path: .spec
 
       - name: The exported surface matches the specification
-        env:
-          OPENKAL_VERSION: 0.2.0
         run: |
-          # Clause 9.3. The list is fetched from the specification repository at
-          # the version this implementation is written against, so that the
-          # comparison has one source rather than a copy that can drift.
-          base="https://raw.githubusercontent.com/mcpplibs/openkal/$OPENKAL_VERSION"
-          curl -fsSL --retry 3 --retry-all-errors -o SURFACE.txt "$base/SURFACE.txt"
-          curl -fsSL --retry 3 --retry-all-errors -o check-surface.sh "$base/tools/check-surface.sh"
-          bash check-surface.sh SURFACE.txt $(find target -name '*.o' | tr '\n' ' ')
+          # Clause 9.3. The list and the checker come from the specification
+          # itself rather than from a copy kept here, so that the comparison has
+          # one source. --complete because this implementation claims every
+          # interface: a name it fails to export is a failure, not an interface
+          # it declines to provide.
+          bash .spec/tools/check-surface.sh --complete .spec/SURFACE.txt \
+            $(find target -name '*.o' | tr '\n' ' ')
 
-      - name: The example runs
-        working-directory: examples/hello
+      # The program is taken from the specification rather than copied here. A
+      # copy in each implementation is a copy that can diverge, and the value of
+      # the program is precisely that every implementation runs the same one.
+      #
+      # The manifest is written here because naming the implementation is the
+      # manifest's job and not the program's, which is the arrangement the
+      # program exists to demonstrate.
+      - name: The portable program runs
         run: |
+          sed -i 's|^openkal = ".*"$|openkal = { path = ".spec" }|' mcpp.toml
+          cat > .spec/examples/portable/mcpp.toml <<'TOML'
+          [package]
+          name    = "portable"
+          version = "0.1.0"
+
+          [dependencies]
+          openkal = { path = "../.." }
+          openkal-linux = { path = "../../.." }
+          TOML
+          cd .spec/examples/portable
           mcpp run 2>&1 | tee run.log
-          grep -q 'openkal: hello' run.log
-          grep -q 'openkal: allocation succeeded' run.log
-          grep -q 'openkal: vectored writes unavailable' run.log
+          # Both directions: that the program reported, and that nothing it
+          # observed failed to hold. Asserting only the first would pass for a
+          # program that printed its failures.
+          grep -q 'openkal: the portable program, above eight interfaces' run.log
+          grep -q 'openkal: observations that did not hold: 0' run.log
+          ! grep -q 'NOT HELD' run.log

mcpp.toml

@@ -1,14 +1,14 @@
 [package]
 namespace   = "mcpplibs"
 name        = "openkal-linux"
-version     = "0.3.0"
+version     = "0.4.0"
 description = "The reference implementation of openkal for Linux. It is both a usable backend and the worked example other implementations follow."
 license     = "Apache-2.0"
 authors     = ["mcpplibs"]
 repo        = "https://github.com/mcpplibs/openkal-linux"
 
 [dependencies]
-openkal = "0.3.0"
+openkal = "0.4.0"
 
 # The package contributes definitions and no modules. The interface it
 # implements is declared by the specification package, which this package

src/process.cpp

@@ -68,7 +68,10 @@ int kal_process_spawn(kal_dir base,
     if (!p.ok) return kal_err_invalid;
 
     vector args, envs;
-    args.add(p.buf, path_len);                       // the started program's own name
+    // The vector is passed unaltered. Clause 7.6: argv[0] is the name the
+    // started program observes as its own, and it is the caller's to choose —
+    // the started program reads it through kal_env_arg(0), so a caller that did
+    // not supply it could not predict what the program would read.
     for (kal_uintptr i = 0; i < argc; ++i) args.add(argv[i], argv_lens[i]);
     for (kal_uintptr i = 0; i < envc; ++i) envs.add(envp[i], envp_lens[i]);
     if (!args.ok || !envs.ok) return kal_err_no_memory;

tests/conformance_process_task.cpp

@@ -85,6 +85,39 @@ int main() {
             check(status != 0, "a non-zero status is reported as such");
             kal_process_close(q);
         }
+
+        // Clause 7.6: the vector is passed unaltered, and argv[0] is the name
+        // the started program observes as its own.
+        //
+        // The programs started above ignore their arguments, so they cannot
+        // distinguish an implementation that passes the vector from one that
+        // prepends the path — which is how that defect survived a suite that
+        // started programs and read their statuses. A shell does distinguish
+        // them: `sh -c <script>` takes $0 from its own argv[0] when no further
+        // argument is given, so the script observes the name the caller chose.
+        // An implementation that prepended the path would give the shell an
+        // extra argument, which it would read as a script file to open, and the
+        // status would be non-zero.
+        const char* sh_paths[] = { "bin/sh", "usr/bin/sh" };
+        const kal_uintptr sh_lens[] = { 6, 10 };
+        const char* script = "test \"$0\" = openkal-observed-argv0";
+        kal_uintptr script_len = 0; while (script[script_len]) ++script_len;
+
+        kal_process r{};
+        const char*       rargv[] = { "openkal-observed-argv0", "-c", script };
+        const kal_uintptr rlens[] = { 22, 2, script_len };
+        int rrc = kal_err_invalid;
+        for (int i = 0; i < 2 && rrc != kal_ok; ++i)
+            rrc = kal_process_spawn(slash, sh_paths[i], sh_lens[i], rargv, rlens, 3,
+                                    nullptr, nullptr, 0, nullptr, &r);
+        check(rrc == kal_ok, "a shell is started");
+        if (rrc == kal_ok) {
+            int status = -1, terminated = -1;
+            kal_process_wait(r, &status, &terminated);
+            check(status == 0 && terminated == 0,
+                  "the started program observes the argument vector the caller supplied, unaltered");
+            kal_process_close(r);
+        }
     }
 
     // A name that ascends is refused here as it is in the file system.