quixos-nix-helpers/PORTABLE_ARTIFACTS.md

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.

# 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.