Publish quixos-protocol from 286ada5419c4fc2184b387cea4715fae1a74bde5

.quixos-subtree-source.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
   "sourceRepo": "https://gitea-external.egads.tutti.syntaxblitz.net/quixos/quixos",
-  "sourceCommit": "d1ab9c912133511cfd3de65550965e0e8806678f",
+  "sourceCommit": "286ada5419c4fc2184b387cea4715fae1a74bde5",
   "sourcePath": "quixos-protocol",
   "exportName": "quixos-protocol",
   "mirrorRemote": "https://gitea-external.egads.tutti.syntaxblitz.net/quixos/quixos-protocol.git"

src/execution-world/README.md

@@ -1,5 +1,11 @@
 # Closed execution plans and artifacts
 
+This page documents current compiler/runtime representations. Its universal
+artifact inventory, React metadata and overlapping world/installation structures
+are [known architectural gaps](../../../docs/ARCHITECTURE_STATUS.md), not the
+[core package contract](../../../docs/ARCHITECTURE.md). Historical LF task numbers
+refer to the original implementation sequence, not an active queue.
+
 `compileExecutionPlan` validates a workspace, links its checked queries, resolves
 public forwarding, and emits one versioned plan with an SHA-256 digest. It retains
 exact interface/package revisions and generic applications, owner initialization,
@@ -60,11 +66,11 @@ the core codec's canonical ordering and domain-separated SHA-256 framing. The
 monorepo `camino-execution-world` check compares the compiler and core implementations.
 No machine-local Nix path enters the world descriptor.
 
-The current binding schema is the closed workspace schema. This is conservative:
-an unrelated contract change can require checking/rebuilding several packages.
-LF-05 may narrow it to exact checked per-package closures, but must use the same
-schema for generation, receipts, and world validation. It must not substitute an
-older package schema just because the source revision did not change.
+Reusable package compilation now receives a canonical per-package build contract;
+exact source provenance and workspace linking remain separate. See
+[package build contracts](../../../docs/PACKAGE_BUILD_CONTRACTS.md). Generation,
+receipts and checking must agree on that contract; unchanged source alone does
+not justify reusing an incompatible binding schema.
 
 ## Transaction-port ABI
 

src/execution-world/candidate.ts

@@ -2,7 +2,11 @@ import { graphExecutionRepresentation } from "./graph-execution.js";
 import { lstat } from "node:fs/promises";
 import { join } from "node:path";
 import { hexDigest, ExecutionPlanError, type ExecutionPlan } from "./plan.js";
-import { loadExecutionInstallation, type PackageInstallationSelection } from "./installation.js";
+import {
+  loadExecutionInstallation,
+  createClientContractCatalog,
+  type PackageInstallationSelection,
+} from "./installation.js";
 import {
   candidateMetadataBudget,
   readCandidateMetadata,
@@ -153,6 +157,7 @@ export async function loadCheckedInstallationCandidate(
         programs: artifacts.programs,
       }),
     };
+    const catalog = createClientContractCatalog(plan, installation, scope, kernel);
     return {
       reference,
       workspace: plan.definition.workspace.workspaceId,
@@ -165,11 +170,15 @@ export async function loadCheckedInstallationCandidate(
       queries,
       installation,
       executionPlan: plan as ExecutionPlan,
+      clientContractCatalog: catalog.select,
       metadata: {
         get bytes() {
           return scope.bytes;
         },
-        release: scope.release,
+        release: () => {
+          catalog.close();
+          scope.release();
+        },
       },
     };
   } catch (error) {

src/execution-world/inspection.ts

@@ -35,20 +35,23 @@ export interface InspectionTemplate {
 }
 /** A finite installed template per interface/lane, not a per-client query compiler.
  * Flags select public cache boundaries; normal scope identity bounds specialization. */
-export function compileInspectionTemplates(plan: ExecutionPlan) {
-  const kernel = compileKernelProgram(plan) as {
-    operations: {
-      key: string;
-      atom: string;
-      interface: string;
-      operation: string;
-      effect: string;
-      targets: string[];
-      unsupported: string | null;
-      output: unknown;
-      binding: { kind: string };
-    }[];
-  };
+export interface InspectionKernel {
+  operations: {
+    key: string;
+    atom: string;
+    interface: string;
+    operation: string;
+    effect: string;
+    targets: string[];
+    unsupported: string | null;
+    output: unknown;
+    binding: { kind: string };
+  }[];
+}
+export function compileInspectionTemplates(
+  plan: ExecutionPlan,
+  kernel: InspectionKernel = compileKernelProgram(plan) as InspectionKernel,
+) {
   const queries: unknown[] = [],
     contracts: PublicQueryContract[] = [],
     templates: InspectionTemplate[] = [];

src/execution-world/installation.ts

@@ -1,4 +1,4 @@
-import { compileInspectionTemplates, type InspectionTemplate } from "./inspection.js";
+import { compileInspectionTemplates, type InspectionTemplate, type InspectionKernel } from "./inspection.js";
 import path from "node:path";
 import { loadCheckedArtifactWorld } from "./receipts.js";
 import { contentArtifactUrl, loadArtifactWorld, type LoadedArtifactWorld } from "./files.js";
@@ -45,6 +45,7 @@ export function clientContractCatalog(
   plan: ExecutionPlan,
   installation: ExecutionInstallation,
   requestedPackages: readonly string[],
+  checkedKernel?: InspectionKernel,
 ): ClientContractCatalog {
   if (installation.plan !== plan.digest || hexDigest(plan.definition) !== plan.digest)
     throw new ExecutionPlanError(
@@ -69,7 +70,7 @@ export function clientContractCatalog(
           .map((operation) => publicOperationContract(iface, operation)),
       ),
     );
-  const inspection = compileInspectionTemplates(plan);
+  const inspection = compileInspectionTemplates(plan, checkedKernel);
   return {
     inspections: inspection.templates,
     resultInterfaces: Object.fromEntries(
@@ -98,6 +99,75 @@ export function clientContractCatalog(
   };
 }
 
+/** Candidate-owned compiler output, never graph state or authorization. Compile
+ * once, then project each requested package set without hashing/recompiling the
+ * plan. Reserve bounded metadata before compilation; disposal releases both the
+ * catalog and its charge. Callers must supply the candidate's checked inputs. */
+export function createClientContractCatalog(
+  plan: ExecutionPlan,
+  installation: ExecutionInstallation,
+  metadata: CandidateMetadataScope,
+  checkedKernel?: InspectionKernel,
+) {
+  const revisions = plan.definition.workspace.packageImports.map((pkg) => pkg.revisionId);
+  const installed = new Set<string>(revisions);
+  let catalog: ClientContractCatalog | undefined;
+  let release: (() => void) | undefined;
+  let closed = false;
+  const freeze = (value: unknown, seen = new WeakSet<object>()) => {
+    if (!value || typeof value !== "object" || seen.has(value)) return;
+    seen.add(value);
+    for (const child of Object.values(value)) freeze(child, seen);
+    Object.freeze(value);
+  };
+  return {
+    select(requestedPackages: readonly string[]): ClientContractCatalog {
+      if (closed) throw Error("CANDIDATE_METADATA_CLOSED");
+      for (const revision of requestedPackages)
+        if (!installed.has(revision))
+          throw new ExecutionPlanError("UNINSTALLED_PACKAGE", revision, "Requested catalog package is not installed");
+      if (!catalog) {
+        // Like other candidate admission charges, this is an allocation estimate,
+        // not a V8 heap limit. The process/cgroup ceiling bounds transient work.
+        const reservation = metadata.reserve(32 * 1024 * 1024);
+        try {
+          const compiled = clientContractCatalog(plan, installation, revisions, checkedKernel);
+          const bytes = Buffer.byteLength(JSON.stringify(compiled));
+          if (bytes > 8 * 1024 * 1024) throw Error("CANDIDATE_CATALOG_LIMIT");
+          freeze(compiled);
+          // No await between reservations: replacing the transient upper bound
+          // with a smaller retained estimate cannot race another admission.
+          reservation();
+          release = metadata.reserve(Math.max(64 * 1024, bytes * 4));
+          catalog = compiled;
+        } catch (error) {
+          reservation();
+          throw error;
+        }
+      }
+      const requested = new Set(requestedPackages);
+      return {
+        inspections: catalog.inspections,
+        resultInterfaces: catalog.resultInterfaces,
+        operations: catalog.operations,
+        queries: [
+          ...catalog.queries.filter((query) => !installed.has(query.package)),
+          ...requestedPackages.flatMap((revision) => catalog!.queries.filter((query) => query.package === revision)),
+        ],
+        components: catalog.components.filter((component) => requested.has(component.packageRevision)),
+        moduleBindings: catalog.moduleBindings.filter((binding) => requested.has(binding.packageRevision)),
+        presentations: catalog.presentations.filter((presentation) => requested.has(presentation.packageRevision)),
+      };
+    },
+    close() {
+      closed = true;
+      catalog = undefined;
+      release?.();
+      release = undefined;
+    },
+  };
+}
+
 export interface PackageInstallationSelection {
   readonly browser?: { readonly id?: string };
   readonly service?: { readonly id?: string };

test/presentations.test.ts

@@ -19,12 +19,16 @@ import {
   expectedArtifactReceipt,
   checkExecutionInstallation,
   clientContractCatalog,
+  createClientContractCatalog,
+  CandidateMetadataBudget,
+  compileKernelProgram,
   type ComponentArtifact,
   type PackageArtifacts,
 } from "../src/execution-world/index.js";
 import { validateWorkspaceRevision } from "../src/capability-model/index.js";
 import { presentationDeclarations, preparationArtifact } from "../src/react-build/declarations.js";
 import { compileQueryComposition } from "../src/query/composition.js";
+import type { InspectionKernel } from "../src/execution-world/inspection.js";
 
 const source = { repository: "https://example.test/components.git", commit: "a".repeat(40) };
 const contract = (name: string) => {
@@ -255,6 +259,56 @@ test("checked component-only artifacts install without a service and reject miss
       () => clientContractCatalog(plan, { ...installation, plan: "bad" }, [pkg.revision]),
       /CATALOG_PLAN_MISMATCH/,
     );
+    const budget = new CandidateMetadataBudget();
+    const scope = budget.acquire("catalog-test");
+    const prepared = createClientContractCatalog(
+      plan,
+      installation,
+      scope,
+      compileKernelProgram(plan) as InspectionKernel,
+    );
+    try {
+      assert.throws(() => prepared.select(["absent"]), /UNINSTALLED_PACKAGE/);
+      assert.equal(scope.bytes, 0, "Unknown requests do not allocate compiler metadata");
+      assert.deepEqual(prepared.select([pkg.revision]), catalog);
+      const retained = scope.bytes;
+      assert.ok(retained > 0);
+      assert.ok(retained < 32 * 1024 * 1024, "Small catalogs retain a proportional metadata charge");
+      const full = prepared.select([pkg.revision]);
+      const empty = prepared.select([]);
+      assert.deepEqual(empty.components, []);
+      assert.deepEqual(empty.presentations, []);
+      assert.deepEqual(empty.moduleBindings, []);
+      assert.equal(empty.operations, full.operations, "Shared compiled metadata is reused");
+      assert.equal(Object.isFrozen(full.operations), true);
+      // Any plan access now would reveal a repeated digest/compile on the warm path.
+      const definition = plan.definition;
+      Object.defineProperty(plan, "definition", {
+        configurable: true,
+        get() {
+          throw Error("RECOMPILED_PLAN");
+        },
+      });
+      try {
+        assert.deepEqual(prepared.select([pkg.revision]), full);
+        assert.equal(scope.bytes, retained, "Package projections do not accumulate cache entries");
+      } finally {
+        Object.defineProperty(plan, "definition", { configurable: true, value: definition });
+      }
+      prepared.close();
+      assert.equal(scope.bytes, 0);
+      assert.throws(() => prepared.select([pkg.revision]), /CANDIDATE_METADATA_CLOSED/);
+    } finally {
+      prepared.close();
+      scope.release();
+    }
+    const tight = new CandidateMetadataBudget({ bytes: 1000, ownerBytes: 1000, candidates: 1 });
+    const tightScope = tight.acquire("catalog-test");
+    const refused = createClientContractCatalog(plan, installation, tightScope);
+    assert.throws(() => refused.select([pkg.revision]), /CANDIDATE_METADATA_LIMIT/);
+    assert.equal(tightScope.bytes, 0);
+    refused.close();
+    tightScope.release();
   } finally {
     await rm(root, { recursive: true, force: true });
   }