Provide the three operations openkal 0.8 adds to openkal.process

ADDING TO AN EXISTING INTERFACE OBLIGES EVERY IMPLEMENTATION OF IT, and adding a
new interface obliges none. Clause 6.1 makes an interface a backend does not
provide absent at the link and not a deviation; it makes one provided IN PART a
deviation. The five interfaces version 0.8 adds are therefore free to decline,
and the three names added to openkal.process are not.

The specification's own surface checker said so before anything else noticed:

    openkal.process is provided in part: 3 of 8 names are not exported --
        kal_process_channel
        kal_process_channel_close
        kal_process_spawn_with

kal_process_channel is CreatePipe. THIS ENVIRONMENT DECIDES INHERITANCE PER
HANDLE AND NOT PER EXEC, which is the opposite of the other two: there every
handle is inherited unless marked otherwise, so those implementations mark both
ends close-on-exec and let the spawn place the far one. Here the default is not
to inherit, so the far end is created inheritable and the near end is withdrawn
afterwards --- otherwise the started program would hold both ends and the writer
would never observe the end of input.

kal_process_spawn_with refuses a non-empty set of grants, and the refusal is the
honest answer rather than a gap. A preopened directory is a handle a started
program reads back by NUMBER, and this environment has no numbering: a handle
crosses a spawn by being inheritable, and the started program learns of it
through a mechanism the parent arranges. There is no correspondence to descriptor
three.

Clause 6.2 is what makes that conforming: the operation exists, reports
kal_err_not_supported, and the property word does not claim
KAL_PROCESS_PROP_GRANT_DIR --- so a caller learns from the word what it would
otherwise learn from a failed call. A count of zero is still answered, by the
ordinary spawn, because a program with no preopens is what this environment
starts anyway.

Author: speak-agent

src/process.cpp

@@ -177,6 +177,81 @@ int kal_process_spawn(kal_dir base,
     return kal_ok;
 }
 
+// A channel: a pair of streams of which one end is meant to cross a spawn.
+//
+// THIS ENVIRONMENT DECIDES INHERITANCE PER HANDLE AND NOT PER EXEC, which is the
+// opposite of the other two and is why the far end is created inheritable while
+// the near end is not. On a descriptor system every handle is inherited unless
+// marked otherwise, so those implementations mark the ends close-on-exec and let
+// the spawn place the far one deliberately. Here the default is not to inherit,
+// so the far end must be marked to be inheritable and the near end must be left
+// alone --- otherwise the started program would hold both ends and the writer
+// would never observe the end of input.
+int kal_process_channel(kal_stream* mine, kal_stream* theirs) {
+    if (mine == nullptr || theirs == nullptr) return kal_err_invalid;
+
+    SECURITY_ATTRIBUTES sa{};
+    sa.nLength = sizeof sa;
+    sa.bInheritHandle = TRUE;
+
+    HANDLE reading = nullptr, writing = nullptr;
+    if (!CreatePipe(&reading, &writing, &sa, 0))
+        return okw::translate_win32(GetLastError());
+
+    // The near end is withdrawn from inheritance after the fact, because
+    // CreatePipe applies one set of attributes to both.
+    SetHandleInformation(reading, HANDLE_FLAG_INHERIT, 0);
+
+    // Bare handles rather than packed ones, because openkal.stream's transfer
+    // operations take what this environment takes. kal_fs_stream reports a
+    // file's stream the same way and for the same reason.
+    *mine   = kal_stream{ reinterpret_cast<kal_uintptr>(reading) };
+    *theirs = kal_stream{ reinterpret_cast<kal_uintptr>(writing) };
+    return kal_ok;
+}
+
+void kal_process_channel_close(kal_stream s) {
+    void* h = reinterpret_cast<void*>(s.h);
+    if (h == nullptr || h == INVALID_HANDLE_VALUE) return;
+    // The standard streams are borrowed. Closing one through this operation
+    // would take a stream away from the whole program.
+    if (h == GetStdHandle(STD_INPUT_HANDLE)  ||
+        h == GetStdHandle(STD_OUTPUT_HANDLE) ||
+        h == GetStdHandle(STD_ERROR_HANDLE)) return;
+    CloseHandle(h);
+}
+
+// Starting a program that receives exactly the directories named.
+//
+// ⚠️ NOT PROVIDED, AND THE REFUSAL IS THE HONEST ANSWER RATHER THAN A GAP. A
+// preopened directory is a handle a started program reads back through
+// kal_fs_preopen by NUMBER, and this environment has no numbering: a handle
+// crosses a spawn by being inheritable, and the started program learns of it
+// through a mechanism the parent has to arrange itself. There is no
+// correspondence here to descriptor three.
+//
+// Clause 6.2 is what makes the refusal conforming rather than a deviation: the
+// operation exists, reports kal_err_not_supported, and the property word does
+// not claim KAL_PROCESS_PROP_GRANT_DIR. A caller therefore learns from the word
+// what it would otherwise learn from a failed call.
+int kal_process_spawn_with(kal_dir base,
+                           const char* path, kal_uintptr path_len,
+                           const char** argv, const kal_uintptr* argv_lens, kal_uintptr argc,
+                           const char** envp, const kal_uintptr* envp_lens, kal_uintptr envc,
+                           const kal_spawn_streams* streams,
+                           const kal_preopen* grants, kal_uintptr grant_count,
+                           kal_process* out) {
+    // A count of zero asks for a program with no preopens, which this
+    // environment gives a started program anyway --- it has none to pass. That
+    // request is therefore answerable, and is answered by the ordinary spawn.
+    if (grant_count == 0)
+        return kal_process_spawn(base, path, path_len,
+                                 argv, argv_lens, argc,
+                                 envp, envp_lens, envc, streams, out);
+    (void)grants;
+    return kal_err_not_supported;
+}
+
 int kal_process_wait(kal_process p, int* status, int* terminated) {
     void* h = okw::unpack(p.h);
     if (!h) return kal_err_invalid;
@@ -212,8 +287,12 @@ void kal_process_close(kal_process p) {
     if (h) { okw::retire(p.h); CloseHandle(h); }
 }
 
+// KAL_PROCESS_PROP_GRANT_DIR is deliberately absent: kal_process_spawn_with
+// refuses a non-empty set of grants here, and a word claiming a facility the
+// next call refuses is the disagreement clause 6.2 exists to prevent.
 const kal_uintptr kal_process_props =
     KAL_PROCESS_PROP_TERMINATE | KAL_PROCESS_PROP_STREAM_PASSING
-  | KAL_PROCESS_PROP_EXIT_STATUS;
+  | KAL_PROCESS_PROP_EXIT_STATUS
+  | KAL_PROCESS_PROP_CHANNEL;
 
 }

src/win32.h

@@ -244,6 +244,9 @@ OKW_IMPORT BOOL   OKW_API CloseHandle(HANDLE);
 OKW_IMPORT DWORD  OKW_API GetLastError(void);
 OKW_IMPORT DWORD  OKW_API GetFileType(HANDLE);
 OKW_IMPORT BOOL   OKW_API SetHandleInformation(HANDLE, DWORD, DWORD);
+// For kal_process_channel. The security attributes decide whether the ends are
+// inheritable, which is what makes one of them able to cross a spawn.
+OKW_IMPORT BOOL   OKW_API CreatePipe(HANDLE*, HANDLE*, SECURITY_ATTRIBUTES*, DWORD);
 OKW_IMPORT BOOL   OKW_API GetConsoleMode(HANDLE, DWORD*);
 OKW_IMPORT BOOL   OKW_API SetConsoleMode(HANDLE, DWORD);