Add a .NET SDK layer

.github/workflows/ci.yml

@@ -213,10 +213,81 @@ jobs:
           dotnet-version: |
             8.0.x
             10.0.x
-      - name: Run independent .NET adapter against Core
+      - name: Run independent .NET adapter and SDK against Core
         run: |
           dotnet test test/JacquardHost.Tests -f net8.0
           dotnet test test/JacquardHost.Tests -f net10.0
         working-directory: dotnet
         env:
           JACQUARD_REQUIRE_LIVE: "1"
+      - name: Run the four example projects through the .NET SDK
+        working-directory: dotnet
+        run: |
+          set -euo pipefail
+          # The SDK refuses a program cache under a directory another user
+          # could write; check $RUNNER_TEMP's ancestry here by the same rule,
+          # so a runner set up otherwise fails clearly rather than inside the
+          # SDK. A group-writable level passes only when its group is the
+          # user's private group: the user's primary group, named as the user,
+          # no other listed member, and no access ACL; and getent passwd
+          # succeeds, prints at most 16 MiB ending in a newline, lists at most
+          # 100,000 well-formed entries with no name twice, lists the user
+          # with that primary group, and lists no account of another uid
+          # with it.
+          me=$(id -un); uid=$(id -u); gid=$(id -g)
+          private=no
+          listing=$(mktemp)
+          trap 'rm -f "$listing"' EXIT
+          passwd_status=0
+          # At most one byte over the cap is kept; a longer listing fails (getent is stopped) and is refused.
+          getent passwd | head -c 16777217 > "$listing" || passwd_status=$?
+          size=$(wc -c < "$listing")
+          group_status=0
+          group_entry=$(getent group "$gid") || group_status=$?
+          if [ "$passwd_status" = 0 ] && [ "$group_status" = 0 ] \
+            && [ "$size" -gt 0 ] && [ "$size" -le 16777216 ] \
+            && [ "$(tail -c 1 "$listing" | od -An -tx1 | tr -d ' \n')" = 0a ] \
+            && awk -F: -v n="$me" -v u="$uid" -v g="$gid" '
+                NF != 7 || $1 == "" || $3 !~ /^(0|[1-9][0-9]*)$/ || $4 !~ /^(0|[1-9][0-9]*)$/ || seen[$1]++ { bad = 1; exit }
+                $1 == n { if ($3 != u || $4 != g) { bad = 1; exit }; listed = 1; next }
+                $4 == g && $3 != u { bad = 1; exit }
+                END { exit (bad || !listed || NR > 100000) }' "$listing" \
+            && [ "$(printf '%s\n' "$group_entry" | cut -d: -f1)" = "$me" ] \
+            && [ -z "$(printf '%s\n' "$group_entry" | cut -d: -f4 | tr , '\n' | grep -vx "$me")" ]; then
+            private=yes
+          fi
+          rm -f "$listing"
+          d=$(realpath "$RUNNER_TEMP")
+          while :; do
+            mode=$(stat -c %a "$d"); owner=$(stat -c %u "$d"); group=$(stat -c %g "$d")
+            bad=
+            if [ "$owner" != "$uid" ] && [ "$owner" != 0 ]; then
+              bad="owned by another user"
+            elif [ $((0$mode & 01000)) = 0 ] && [ $((0$mode & 02)) != 0 ]; then
+              bad="writable by others"
+            elif [ $((0$mode & 01000)) = 0 ] && [ $((0$mode & 020)) != 0 ]; then
+              if [ "$group" != "$gid" ] || [ "$private" != yes ]; then
+                bad="writable by its group, which is not your private group"
+              elif ls -ld "$d" | cut -c11 | grep -q '+'; then
+                bad="writable by its group, with an access control list"
+              fi
+            fi
+            if [ -n "$bad" ]; then
+              echo "::error::$d (mode $mode, owner $owner, group $group) is $bad; the .NET SDK refuses a cache under it" >&2
+              exit 1
+            fi
+            [ "$d" = / ] && break
+            d=$(dirname "$d")
+          done
+          dotnet build examples/JacquardExamples
+          run() { dotnet examples/JacquardExamples/bin/Debug/net8.0/JacquardExamples.dll --workdir "$RUNNER_TEMP/dotnet-examples" "$@"; }
+          run quickstart
+          run planner | grep -q '"score": 16'
+          run triage | grep -q '"urgency": "WATCH"'
+          run fulfillment | grep -q '"$tag": "Fulfilled"'
+          run fulfillment | grep -q '"$tag": "DuplicateOrder"'
+          status=0
+          run --workdir "$RUNNER_TEMP/dotnet-recovery" --fault publish-failed fulfillment || status=$?
+          test "$status" = 1
+          run --workdir "$RUNNER_TEMP/dotnet-recovery" --deliver-pending fulfillment | grep -q '{"delivered":1}'
+          run --workdir "$RUNNER_TEMP/dotnet-recovery" --deliver-pending fulfillment | grep -q '{"delivered":0}'

CHANGELOG.md

@@ -78,8 +78,7 @@
   codecs that parse integers exactly from their text, the session state
   machine, a bounded process carrier for `jacquard host worker`, and a `Host`
   with a closed operation registry. It carries the pinned kit as embedded
-  resources and replays all 21 recordings. It is protocol-level only, with no
-  SDK layer. .NET cannot start the worker in its own process group or
+  resources and replays all 21 recordings. .NET cannot start the worker in its own process group or
   interrupt a pipe read or write, so the carrier never calls one that can
   block: it waits on the C library's `poll(2)` and runs workers on Linux and
   macOS only. It kills the worker's process tree with `Process.Kill(true)`,
@@ -88,6 +87,48 @@
   `scripts/core_pin.py` now generates `dotnet/src/JacquardHost/Compat.cs` and
   keeps the .NET kit copy in sync, and CI runs the offline tests on .NET 8 and
   10 and the live tests against the pinned Core.
+- .NET SDK (`JacquardLang.Host.Sdk`): prepares and caches checked programs
+  with Core's public commands, maps .NET values through explicit `Codec<T>`
+  objects (records through field readers and a constructor function,
+  enumerations, type hierarchies, `Option<T>`, `Unit`, lazy codecs for
+  recursive types, and `Dynamic` for untyped code) without reflection over
+  members (enumeration codecs read `Enum` names and values, and hierarchy
+  codecs check case types with `Type`), binds
+  handlers to exact operation identities with the `HandlerContext` and its
+  `CancellationToken`, checks arguments against the checked signature before a
+  worker starts, and keeps each invocation's raw evidence. `MapBatches` runs
+  explicit batches. There is no `decimal` mapping: money crosses as integer
+  minor units, and `decimal`, `ulong`, `nuint`, `char`, `float`, and the
+  other numeric types with no Jacquard type do not compile as arguments.
+  Caller names over 4,096 chars are refused before they are looked up.
+  Core's commands run on the caller's thread through `poll(2)`, bounded in
+  time and output, and on Linux through `setsid`, whose process group is
+  killed when a command exits or is stopped; without `setsid`, descendants
+  are recorded from `/proc` within entry and byte caps, and on a stop Core
+  is frozen with `SIGSTOP` before the last record and the cleanup ends
+  within 750 ms. Only the cache's owner may write it: the root, each entry,
+  and each file must be owned by the current user and not group- or
+  world-writable, every directory above the root must be owned by the user
+  or root and not group- or world-writable unless it is sticky or the group
+  is the user's private group (Debian OpenSSH's rule, which looks for
+  another account with that primary group in the password database, listed
+  here by `getent passwd` in a separate process, with it and the `setsid`
+  it runs through root's alone, at most once per preparation or save,
+  limited to 5 seconds (then stopped within 750 ms) and 16 MiB, stopped by
+  the token, and refused on any failure or malformed entry; with stricter conditions, so a clone made with a `umask` of 002
+  under user-private groups is accepted), a refusal names
+  every such directory and creates nothing, and the root's device and inode
+  are checked again before each use, each worker a prepared program starts
+  included. Replacement by the same user is not covered.
+  Every binding is derived again from Core's cached output on load, and a
+  preparation during which the Core executable or prelude changed is
+  refused. `Invocation.Save` refuses a target directory another user could
+  write, by the same directory rule, writes a new owner-only file through one
+  exclusively created handle, flushes it, checks the file at its path is the
+  one written, and renames it over the target.
+  The four example projects run through a `JacquardExamples` command in
+  `dotnet/examples/`, and CI runs them and the SDK's live tests against the
+  pinned Core.
 
 ## 0.2.0 — 2026-10-25
 

CONTRIBUTING.md

@@ -146,30 +146,54 @@ fails if they differ).
 
 ## .NET
 
-The independent .NET adapter lives in `dotnet/` as package `JacquardLang.Host`
-(`dotnet/src/JacquardHost`). It targets .NET 8, has no runtime dependencies
-beyond the .NET base class library, and does not call Python, Node.js, Go,
-Rust, or Java; it calls the C library's `poll(2)` and runs workers on Linux
-and macOS only. NUnit, its adapter, and the test SDK are its only (test)
-dependencies. The .NET 8 or 10 SDK is required.
+The independent .NET adapter and SDK live in `dotnet/` as package
+`JacquardLang.Host` (`dotnet/src/JacquardHost`, the SDK in its `Sdk/`
+directory). It targets .NET 8, has no runtime dependencies beyond the .NET base
+class library, and does not call Python, Node.js, Go, Rust, or Java; it calls
+the C library (`poll(2)`, and for the SDK `kill(2)`, `geteuid(2)`, `mkdir(2)`,
+`statx(2)` or `stat(2)`, `getpwuid_r(3)`, `getgrgid_r(3)`, and `lgetxattr(2)`; it also runs `getent passwd`) and runs on Linux and macOS only. On Linux the
+SDK runs Core's commands through util-linux `setsid` when one is installed.
+NUnit, its adapter, and the test SDK are its only (test) dependencies. The
+.NET 8 or 10 SDK is required.
 
 ```sh
 cd dotnet
 dotnet test test/JacquardHost.Tests -f net8.0
 dotnet test test/JacquardHost.Tests -f net10.0   # with a .NET 10 SDK
 # With the pinned Core configured (eval "$(python3 ../scripts/core_pin.py install)"):
 JACQUARD_REQUIRE_LIVE=1 dotnet test test/JacquardHost.Tests -f net8.0
+dotnet build examples/JacquardExamples
+dotnet examples/JacquardExamples/bin/Debug/net8.0/JacquardExamples.dll quickstart
 ```
 
-CI runs the offline tests on .NET 8 and 10, and the live tests on both in the
-shared pinned-Core job. The build treats warnings as errors, with nullable
+The example command's program cache is under `dotnet/.scratch/`, and the SDK
+refuses it when another user could write a directory above it: one writable
+by others, or by its group unless that group is your private group (named
+after you, listing no other member, and no other account in the password
+database having it as its primary group; a clone made with a `umask` of 002
+under user-private groups passes). The refusal names every such directory;
+run `chmod go-w` on each, or pass `--workdir` under directories only you or
+root may write.
+
+The SDK tests make their scratch directories under `TMPDIR` when neither a
+group nor another user may write it or any directory above it (unless
+sticky), and otherwise under `/tmp` when that holds, so the refusals they
+expect name only the levels they make; when neither does, they fail asking
+for such a `TMPDIR`.
+
+CI runs the offline tests on .NET 8 and 10, and the live tests on both and the
+four example projects in the shared pinned-Core job. The build treats warnings as errors, with nullable
 reference types and the `8.0-recommended` analyzers.
 `dotnet/src/JacquardHost/Compat.cs` is generated and
 `dotnet/src/JacquardHost/kit/` is a byte copy of the pinned kit.
 `scripts/core_pin.py` maintains both; do not edit them by hand. The
 `JacquardHost.StandIn` program under `dotnet/test/` is a fixture for the
-offline tests. Copy the repository `NOTICE` to `dotnet/NOTICE` when it changes
-(a test fails if they differ).
+offline tests. The `JacquardExamples` command under `dotnet/examples/` reads the
+rules and inputs from `examples/` directly, so there is no copy to keep in
+sync. The README's C# examples are compiled test sources under
+`dotnet/test/JacquardHost.Tests/Readme/` (a test fails if they differ). Copy
+the repository `NOTICE` to `dotnet/NOTICE` when it changes (a test fails if
+they differ).
 
 ## Releasing
 

MANIFEST.in

@@ -25,3 +25,5 @@ prune dotnet/test/JacquardHost.Tests/bin
 prune dotnet/test/JacquardHost.Tests/obj
 prune dotnet/test/JacquardHost.StandIn/bin
 prune dotnet/test/JacquardHost.StandIn/obj
+prune dotnet/examples/JacquardExamples/bin
+prune dotnet/examples/JacquardExamples/obj

README.md

@@ -1,21 +1,22 @@
 # Jacquard Host
 
-Call checked Jacquard functions from Python, TypeScript, Go, Rust, or Java and implement
+Call checked Jacquard functions from Python, TypeScript, Go, Rust, Java, or .NET and implement
 their declared host operations with ordinary services. Jacquard owns the decision
 logic; the host owns persistence, I/O, and application lifetimes.
 
 The SDK prepares and caches checked programs, converts native Python values,
 binds services to exact operation identities, and retains the raw evidence for
-every invocation. Python 3.11+, Node.js 22+, Go 1.24+, Rust 1.88+, or Java 21+,
-with no third-party runtime dependencies. The [TypeScript SDK](typescript/README.md),
-the [Go SDK](go/README.md), the [Rust SDK](rust/README.md), and the
-[Java SDK](java/README.md) implement the pinned protocol independently. The
+every invocation. Python 3.11+, Node.js 22+, Go 1.24+, Rust 1.88+, Java 21+, or
+.NET 8+, with no third-party runtime dependencies. The
+[TypeScript SDK](typescript/README.md), the [Go SDK](go/README.md), the
+[Rust SDK](rust/README.md), the [Java SDK](java/README.md), and the
+[.NET SDK](dotnet/README.md) implement the pinned protocol independently. The
 TypeScript SDK supports async service methods, the Go SDK maps native Go types
 and context cancellation, the Rust SDK maps native Rust types through `record!`
-and `variants!` declarations, and the Java SDK maps records, enums, and sealed
-interfaces through explicit codecs. A protocol-level [.NET](dotnet/README.md)
-(.NET 8+) adapter also implements the pinned protocol independently. It has a
-closed operation registry and kit replay, but no SDK layer yet.
+and `variants!` declarations, the Java SDK maps records, enums, and sealed
+interfaces through explicit codecs, and the .NET SDK maps records, enumerations,
+and type hierarchies through explicit codecs without reflection over members,
+with `CancellationToken` cancellation.
 
 **Experimental:** the SDK targets Core's pinned `jacquard-host-v0` protocol.
 Core is installed separately. Each invocation runs one fresh, serial worker;
@@ -25,7 +26,8 @@ the host and operating system are trusted. See [limits](docs/LIMITS.md).
 
 For Node.js, follow the [TypeScript walkthrough](typescript/README.md); for Go,
 the [Go walkthrough](go/README.md); for Rust, the [Rust walkthrough](rust/README.md);
-for Java, the [Java walkthrough](java/README.md). For Python:
+for Java, the [Java walkthrough](java/README.md); for .NET, the
+[.NET walkthrough](dotnet/README.md). For Python:
 
 From a clone of this repository: