Build checked portable package artifacts and shared runtime assets

2026-09-20 00:25:53 -07:00
parent 0c3c9c6ad8
commit f352ac0c3b
5 changed files with 474 additions and 0 deletions
@@ -0,0 +1,56 @@
+# Checked portable artifacts
+
+`mkCaminoPortableArtifacts` is the fresh package builder. It regenerates candidate
+bindings, typechecks the entry's dependency closure, bundles declared targets,
+generates a process service when requested, and emits content manifests and
+receipts. It has no migration step or package-defined shell hooks.
+
+```nix
+# Inside a per-system flake output:
+quixosPackages.checkedArtifacts =
+  { plan, generator, core, sharedRuntime, typescript, packageRevisionId }:
+  helpers.mkCaminoPortableArtifacts {
+    inherit pkgs plan core sharedRuntime typescript packageRevisionId;
+    protocol = generator;
+    src = ./.;
+    portable = {
+      entry = "src/portable.ts";
+      bindingOutput = "src/gen/qx.ts";
+      registryExport = "registry";
+      targets = [ "browser" "server" ];
+    };
+  };
+```
+
+The handler entry exports `registry = createRegistry(handlers)` from the generated
+bindings. One registry contains many exports. The builder always supplies a server
+implementation for the generated process service. A service-only package instead
+omits `portable` and supplies `service.entry`, an ordinary JavaScript process entry
+using the versioned stdin/stdout protocol. Custom services own their lifecycle and
+may hold external resources. This first helper supports JavaScript custom service
+entries; other languages can emit the same checked artifact contract independently.
+
+Additional portable source dependencies can be provided as a locked `nodeModules` directory.
+The workspace supplies the exact SDK and compiler; packages cannot replace those
+with their own versions. Authored source symlinks and non-bundled portable imports
+other than the SDK and server Node builtins are rejected. This is build closure
+checking, not a purity proof or security sandbox.
+
+The core/Automerge bundle and Replicache bundle are built once. Browser modules
+import the core through a content-addressed gateway URL, independent of package
+identity. Each manifest covers the shared bytes it uses. The gateway retains its
+workspace authentication and explicit file registry; it never interprets an HTTP
+path as a Nix store path. Applications cannot import Replicache through the SDK.
+
+`checked-artifacts.nix` evaluates a package's `checkedArtifacts` output without
+activation. `loadCheckedArtifactWorld` then verifies manifest bytes, the trusted
+generator identity, and exact regenerated binding sources. Receipts are consistency
+evidence from a trusted Nix build, not cryptographic attestations of remote builds.
+The separate manifest-only loader is useful for candidate diagnostics; activation
+must use the checked loader.
+
+The root `camino-artifact-builds` check exercises actual reader/service outputs,
+module and process execution, browser shared imports, rejection recovery, and
+altered receipt rejection. No running workspace uses these outputs yet. Installing
+the new world into the coordinator/replica host is LF-08/LF-11 integration work;
+no adapter pretends this ABI works in the old server dispatcher.