From 041a9e26adfcf625183831c279e445c1b5cf69f5 Mon Sep 17 00:00:00 2001 From: "Timothy J. Aveni" Date: Fri, 9 Oct 2026 10:09:17 -0700 Subject: [PATCH 1/2] Document package architecture and organize current guidance and project backlog --- src/execution-world/README.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/src/execution-world/README.md b/src/execution-world/README.md index 740aaa0..a3b1fa5 100644 --- a/src/execution-world/README.md +++ b/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 From 2ae7f00acb847b85f72bb295b25c9555a673e0e2 Mon Sep 17 00:00:00 2001 From: "Timothy J. Aveni" Date: Fri, 9 Oct 2026 16:50:50 -0700 Subject: [PATCH 2/2] Reuse checked bootstrap catalogs and coordinate execution deadlines --- src/execution-world/candidate.ts | 13 ++++- src/execution-world/inspection.ts | 31 ++++++------ src/execution-world/installation.ts | 74 ++++++++++++++++++++++++++++- test/presentations.test.ts | 54 +++++++++++++++++++++ 4 files changed, 154 insertions(+), 18 deletions(-) diff --git a/src/execution-world/candidate.ts b/src/execution-world/candidate.ts index ec6fbe7..fea5cd4 100644 --- a/src/execution-world/candidate.ts +++ b/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) { diff --git a/src/execution-world/inspection.ts b/src/execution-world/inspection.ts index 1155b51..8806873 100644 --- a/src/execution-world/inspection.ts +++ b/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[] = []; diff --git a/src/execution-world/installation.ts b/src/execution-world/installation.ts index a6eafc3..0cb526a 100644 --- a/src/execution-world/installation.ts +++ b/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(revisions); + let catalog: ClientContractCatalog | undefined; + let release: (() => void) | undefined; + let closed = false; + const freeze = (value: unknown, seen = new WeakSet()) => { + 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 }; diff --git a/test/presentations.test.ts b/test/presentations.test.ts index c908779..b9d16c5 100644 --- a/test/presentations.test.ts +++ b/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 }); }