Publish quixos-nix-helpers from e25eee6ce4f13702b2454a9354bc79a29eb2e4a1

Enable evolution by default for source-backed workspaces. Add stable
conformance ownership, semantic-major review, candidate typechecking,
and durable fenced cutover with explicit migrations and forward recovery.

Independently supervise package runtimes so unchanged resource owners keep
their processes and connections across cutover. Add scoped invocation
authority, resource sessions, and typed callback rebinding.

Wire opaque object references through generated bindings and RPCs. Add
canonical relationship sets, keyed maps, and ordered lists with scoped
transactional mutations, revision checks, and inverse consistency. Support
planned cascade deletion, protection, tombstones, and lifecycle foundations.

Add journaled structural edits, package/function/migration scaffolding,
managed repository creation, and resumable bottom-up dependency pin
publication. Document lifetime boundaries, revision pinning, prototype
compatibility policy, commands, and deferred work.

Validate with 210 tests, user-systemd process/connection continuity,
generated-package TypeScript checks, and Nix host/protocol checks.
TTL handoff, physical reclamation, general multi-step migrations, and
root-systemd migration isolation acceptance remain deferred.

.quixos-subtree-source.json

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "sourceRepo": "https://gitea-external.egads.tutti.syntaxblitz.net/quixos/quixos",
+  "sourceCommit": "e25eee6ce4f13702b2454a9354bc79a29eb2e4a1",
+  "sourcePath": "quixos-instance/quixos-nix-helpers",
+  "exportName": "quixos-nix-helpers",
+  "mirrorRemote": "https://gitea-external.egads.tutti.syntaxblitz.net/quixos/quixos-nix-helpers.git"
+}

check-receipt.mjs

@@ -0,0 +1,17 @@
+import fs from "node:fs";
+import crypto from "node:crypto";
+const [schemaPath, packageRevisionId, bindingOutput, generatorPath, output] = process.argv.slice(2);
+if (!schemaPath || !packageRevisionId || !bindingOutput || !generatorPath || !output) throw new Error("Missing candidate check receipt inputs");
+const canonical = (value) => Array.isArray(value) ? value.map(canonical) : value && typeof value === "object"
+  ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, entry]) => [key, canonical(entry)])) : value;
+const hash = (value) => `sha256:${crypto.createHash("sha256").update(JSON.stringify(canonical(value))).digest("hex")}`;
+const schema = JSON.parse(fs.readFileSync(schemaPath, "utf8"));
+if (!schema.packages.some((entry) => entry.revisionId === packageRevisionId)) throw new Error("Checked binding schema lacks the package");
+const generated = fs.readFileSync(bindingOutput, "utf8");
+if (generated !== fs.readFileSync(".qx-checked-bindings", "utf8")) throw new Error("Build replaced candidate-generated bindings; its check is not evidence for this candidate");
+const receipt = {
+  schemaVersion: 1, packageRevisionId, success: true, bindingSchema: schema,
+  bindingSchemaDigest: hash(schema), generatedDigest: hash(generated),
+  checkerDigest: hash({ generatorPath, compiler: JSON.parse(fs.readFileSync("node_modules/typescript/package.json", "utf8")), lock: fs.readFileSync("yarn.lock", "utf8") }),
+};
+fs.writeFileSync(output, `${JSON.stringify(receipt, null, 2)}\n`, { flag: "wx" });

checked-package.nix

@@ -0,0 +1,13 @@
+# The caller has compiled this package and its exact recursive candidate graph.
+# No credentials, mutable references, or workspace-wide unrelated schema enter
+# the package derivation. Ordinary #server builds are not promotion evidence.
+{ source, schema, generator, packageRevisionId, system ? builtins.currentSystem }:
+let
+  package = builtins.getFlake ("path:" + source);
+  checked = package.quixosPackages.${system}.checkedServer or
+    (throw "Package ${packageRevisionId} lacks checkedServer. Upgrade its Nix helper and adopt generated implementation bindings before cutover.");
+in checked {
+  inherit packageRevisionId;
+  schema = builtins.path { path = /. + schema; name = "candidate-package-bindings.json"; };
+  generator = builtins.storePath generator;
+}

quixos-package-helpers.nix

@@ -510,6 +510,20 @@ EOF
       '';
     };
 
+  # Language-neutral, offline schema compilation. Snapshot directories must be
+  # fixed Nix inputs matching the resource lock's complete dependency closure.
+  mkQxBindingSchema = { pkgs, protocol, src, repository, commit, resources ? [ ] }:
+    let
+      snapshots = pkgs.writeText "qx-binding-snapshots.json" (builtins.toJSON { inherit resources; });
+    in pkgs.runCommand "qx-binding-schema.json" { } ''
+      ${protocol}/bin/quixos-resource-compile \
+        --root ${src} --kind package \
+        --repository ${pkgs.lib.escapeShellArg repository} \
+        --commit ${pkgs.lib.escapeShellArg commit} \
+        --checkout-root "$TMPDIR/checkouts" \
+        --snapshot-map ${snapshots} --snapshot-only true --schema-out "$out" > /dev/null
+    '';
+
   mkCaminoTsYarnNixifyFlake =
     {
       inputs,
@@ -521,8 +535,14 @@ EOF
       promptName ? null,
       nodejsAttr ? "nodejs_24",
       buildCommand ? "yarn build",
-      sourcePortals ? { },
       buildEnv ? { },
+      # An exact, compiler-produced BindingSchema JSON artifact and a backend.
+      # Other language helpers can consume the same schema with their own generator/runtime.
+      bindings ? null,
+      bindingOptions ? { },
+      # A dedicated entrypoint calling SDK serveMigration; never start the
+      # normal package server in the isolated migration execution boundary.
+      migrationEntrypoint ? null,
       nativeBuildInputs ? [ ],
       devShellPackages ? [ ],
       devShellHook ? "",
@@ -532,6 +552,8 @@ EOF
     flake-utils.lib.eachDefaultSystem (
       system:
       let
+        outputsFor = candidateBindings:
+        let
         pkgs = import nixpkgs { inherit system; };
         lib = pkgs.lib;
         nodejs = pkgs.${nodejsAttr};
@@ -561,12 +583,29 @@ EOF
               attrs
           );
 
-        portalLinksFor = attrs:
-          lib.concatStringsSep "\n" (
-            lib.mapAttrsToList
-              (target: source: "ln -sfn ${source} ${lib.escapeShellArg target}")
-              attrs
-          );
+        bindingConfig = if candidateBindings != null then candidateBindings
+          else if bindings == null then null else callOption bindings;
+        bindingSchema = if bindingConfig == null then null else bindingConfig.schema or (mkQxBindingSchema {
+          inherit pkgs;
+          protocol = bindingConfig.generator;
+          src = packageRoot;
+          inherit (bindingConfig) repository commit;
+          resources = bindingConfig.resources or [ ];
+        });
+        bindingOutput = if bindingConfig == null then "src/gen/qx.ts" else bindingConfig.output or "src/gen/qx.ts";
+        bindingOptionsFile = if bindingConfig == null then null else
+          pkgs.writeText "qx-typescript-options.json" (builtins.toJSON (bindingConfig.options or bindingOptions));
+        bindingCommand = if bindingConfig == null then "" else ''
+          mkdir -p ${lib.escapeShellArg (dirOf bindingOutput)}
+          ${bindingConfig.generator}/bin/quixos-codegen-ts \
+            ${lib.escapeShellArg (toString bindingSchema)} \
+            ${lib.escapeShellArg bindingConfig.packageRevisionId} \
+            ${lib.escapeShellArg bindingOutput} ${bindingOptionsFile}
+        '';
+        generateBindings = pkgs.writeShellApplication {
+          name = "qx-generate-bindings";
+          text = bindingCommand;
+        };
 
         bundleConfig = if bundle == null then { } else bundle;
         bundleOutfile = bundleConfig.outfile or "server.mjs";
@@ -574,6 +613,14 @@ EOF
         bundleTarget = bundleConfig.target or "node24";
         bundleFormat = bundleConfig.format or "esm";
         bundleBanner = bundleConfig.banner or nodeRequireBanner;
+        bundleAliases = bundleConfig.aliases or {
+          "@automerge/automerge" = "./node_modules/@automerge/automerge/dist/mjs/entrypoints/fullfat_base64.js";
+        };
+        bundleAliasArgs = lib.concatStringsSep " " (
+          lib.mapAttrsToList
+            (from: to: "--alias:${from}=${lib.escapeShellArg to}")
+            bundleAliases
+        );
         nodeRequireBanner = "import { createRequire } from 'module';const require = createRequire(import.meta.url);";
         bundleCommand =
           if bundle == null
@@ -584,6 +631,7 @@ EOF
               --platform=${bundlePlatform} \
               --target=${bundleTarget} \
               --format=${bundleFormat} \
+              ${bundleAliasArgs} \
               ${lib.optionalString (bundleConfig.preserveSymlinks or true) "--preserve-symlinks \\"}
               --banner:js=${lib.escapeShellArg bundleBanner} \
               --outfile=${lib.escapeShellArg bundleOutfile}
@@ -595,12 +643,22 @@ EOF
           installConfig.libexecName or (lib.strings.sanitizeDerivationName packageNameFinal);
         serverFile = installConfig.serverFile or bundleOutfile;
         descriptorPath = installConfig.descriptorPath or "descriptor.quixos-package.txtpb";
+        extraFiles = installConfig.extraFiles or [ ];
+        installExtraFile = file:
+          let
+            source = toString file.source;
+            target = file.target or (baseNameOf source);
+            mode = file.mode or "0644";
+          in ''
+            install -Dm${toString mode} ${lib.escapeShellArg source} "$out/libexec/${serverLibexecName}/${target}"
+          '';
         installServerPhase =
           if installServer == null
           then null
           else ''
             runHook preInstall
             install -Dm755 ${lib.escapeShellArg serverFile} "$out/libexec/${serverLibexecName}/${serverFile}"
+            ${lib.concatMapStringsSep "\n" installExtraFile extraFiles}
             mkdir -p "$out/bin"
             cat > "$out/bin/${serverBin}" <<EOF
 #!${pkgs.runtimeShell}
@@ -610,6 +668,17 @@ EOF
             ${lib.optionalString (installConfig ? descriptorPath && descriptorPath != null) ''
               cp ${lib.escapeShellArg descriptorPath} "$out/${descriptorPath}"
             ''}
+            ${lib.optionalString (bindingConfig != null) ''
+              install -m 0444 quixos-check.json "$out/quixos-check.json"
+            ''}
+            ${lib.optionalString (migrationEntrypoint != null) ''
+              install -Dm444 migration.mjs "$out/libexec/${serverLibexecName}/migration.mjs"
+              cat > "$out/bin/migrate" <<EOF
+#!${pkgs.runtimeShell}
+exec ${nodejs}/bin/node --max-old-space-size=256 "$out/libexec/${serverLibexecName}/migration.mjs" "\$@"
+EOF
+              chmod +x "$out/bin/migrate"
+            ''}
             runHook postInstall
           '';
 
@@ -618,16 +687,26 @@ EOF
           overrideAttrs = old: {
             nativeBuildInputs =
               (old.nativeBuildInputs or [ ])
-              ++ lib.optional (bundle != null) pkgs.esbuild
+              ++ lib.optional (bundle != null || migrationEntrypoint != null) pkgs.esbuild
               ++ callOption nativeBuildInputs;
-            preConfigure = (old.preConfigure or "") + ''
-              ${portalLinksFor (callOption sourcePortals)}
-            '';
             buildPhase = ''
               runHook preBuild
               ${exportsFor (callOption buildEnv)}
+              ${bindingCommand}
+              ${lib.optionalString (bindingConfig != null) "yarn exec tsc --noEmit"}
+              ${lib.optionalString (bindingConfig != null) "cp ${lib.escapeShellArg bindingOutput} .qx-checked-bindings"}
               ${buildCommand}
+              ${lib.optionalString (bindingConfig != null) ''
+                yarn exec tsc --noEmit
+                node ${./check-receipt.mjs} ${lib.escapeShellArg (toString bindingSchema)} \
+                  ${lib.escapeShellArg bindingConfig.packageRevisionId} ${lib.escapeShellArg bindingOutput} \
+                  ${lib.escapeShellArg (toString bindingConfig.generator)} quixos-check.json
+              ''}
               ${bundleCommand}
+              ${lib.optionalString (migrationEntrypoint != null) ''
+                esbuild ${lib.escapeShellArg migrationEntrypoint} --bundle --platform=node --target=node24 --format=esm \
+                  ${bundleAliasArgs} --preserve-symlinks --banner:js=${lib.escapeShellArg nodeRequireBanner} --outfile=migration.mjs
+              ''}
               runHook postBuild
             '';
           } // lib.optionalAttrs (installServerPhase != null) {
@@ -662,11 +741,19 @@ EOF
         devShells.default = pkgs.mkShell {
           packages = [
             nodejs
-            pkgs.yarn-berry_4
-          ] ++ callOption devShellPackages;
+            project.yarn-freestanding
+          ] ++ lib.optional (bindingConfig != null) generateBindings ++ callOption devShellPackages;
+          # Explicit command keeps shell entry free of source mutations.
           shellHook = devShellHookBase + callOption devShellHook;
         };
-      } // maybeServerOutputs
+      } // maybeServerOutputs;
+      in (outputsFor null) // {
+        # The workspace supplies a compiler-produced schema for the exact
+        # candidate graph. Standalone builds may use checked-in authoring types,
+        # but only this build path regenerates and witnesses candidate contracts.
+        quixosPackages.checkedServer = { schema, generator, packageRevisionId }:
+          (outputsFor { inherit schema generator packageRevisionId; }).packages.server;
+      }
     );
 in
 {
@@ -675,5 +762,6 @@ in
     mkTsPackageServer
     mkSchemaSupport
     mkCaminoSourcePackage
+    mkQxBindingSchema
     mkCaminoTsYarnNixifyFlake;
 }