Compare commits

...

29 Commits

Author SHA1 Message Date
Quixos Subtree Publisher 721b730263 Publish quixos-protocol from a61bdda658be4878403b8d60aecb71fe5a614ac0 2026-10-10 10:49:05 +00:00
Timothy J. Aveni c2c01a9878 Implement progressive query admission, session boundaries and event-driven Studio observations 2026-10-10 03:49:05 -07:00
Quixos Subtree Publisher 9fae801b7f Publish quixos-protocol from 286ada5419c4fc2184b387cea4715fae1a74bde5 2026-10-10 00:10:14 +00:00
Timothy J. Aveni 2ae7f00acb Reuse checked bootstrap catalogs and coordinate execution deadlines 2026-10-09 17:10:14 -07:00
Timothy J. Aveni 041a9e26ad Document package architecture and organize current guidance and project backlog 2026-10-09 10:33:39 -07:00
Quixos Subtree Publisher 7f3fdfe64e Publish quixos-protocol from d1ab9c912133511cfd3de65550965e0e8806678f 2026-10-08 19:32:06 +00:00
Timothy J. Aveni 0a7bdf7657 Qualify restricted SDK syntax independently of build architecture 2026-10-08 12:32:06 -07:00
Quixos Subtree Publisher 137dcaa101 Publish quixos-protocol from 2ef07e2524ed167421be56b81a5f498a2759ca5d 2026-10-08 19:30:33 +00:00
Timothy J. Aveni a86de3fe5b Qualify restricted SDK syntax independently of build architecture 2026-10-08 12:30:33 -07:00
Timothy J. Aveni 165510341d Repair packed agent startup and bound activation metadata retention 2026-10-08 11:19:19 -07:00
Quixos Subtree Publisher b406738249 Publish quixos-protocol from 11d2ad06170609a09118cbabd4245b5828a148d1 2026-10-08 18:19:19 +00:00
Timothy J. Aveni ffd728b061 Keep pin-upgraded workbench paths relative for relocation 2026-10-08 07:59:49 -07:00
Quixos Subtree Publisher e78b7adf28 Publish quixos-protocol from c4319441699b7b8c5af7e70dade6e4ad8cccddea 2026-10-08 14:59:49 +00:00
Timothy J. Aveni a935273913 Use execution workspace review semantics during bottom-up pin upgrades 2026-10-08 07:43:32 -07:00
Quixos Subtree Publisher e162dc3013 Publish quixos-protocol from e4075003e669be0e307ec8c0585cccb1bd08276a 2026-10-08 14:43:32 +00:00
Quixos Subtree Publisher e65ddad798 Publish quixos-protocol from 932fe7714761fb8b5db4bd6401357cdff762a428 2026-10-08 05:08:28 +00:00
Timothy J. Aveni 31a48e746d Admit checked restricted artifacts without individual code approvals 2026-10-07 21:43:44 -07:00
Quixos Subtree Publisher f9a8d64564 Publish quixos-protocol from abc91ab1cbbd61ffd7f0a49dbc5768598ac8745c 2026-10-08 00:03:01 +00:00
Timothy J. Aveni 61534d3fb5 Keep checked browser runtime versions independent of authority upgrades 2026-10-07 17:03:01 -07:00
Timothy J. Aveni 391f02f78a Pool host-approved restricted code with scoped and fair graph execution 2026-10-07 16:47:19 -07:00
Timothy J. Aveni c8c56d8ea7 Bound checked candidate metadata and restricted invocation resources 2026-10-07 15:51:22 -07:00
Quixos Subtree Publisher 0443992dd4 Publish quixos-protocol from 452f3c48aadceaf08e56ae9c226e98a7f9df4900 2026-10-07 13:30:33 +00:00
Timothy J. Aveni 9248332da6 Allow explicitly exported read-only edge dependency ports 2026-10-07 06:30:33 -07:00
Quixos Subtree Publisher b633a91a41 Publish quixos-protocol from dd7527da2714f3b0941ed908357fd82e98f45bc4 2026-10-07 12:07:09 +00:00
Timothy J. Aveni 192a22c936 Handle optional source-binding configuration in structural package upgrades 2026-10-07 05:07:09 -07:00
Quixos Subtree Publisher 3f0ef70ecd Publish quixos-protocol from 6e51f796de7af0da8c053f770b89d243f74c5d61 2026-10-07 05:33:13 +00:00
Timothy J. Aveni 5c618e0e41 Build checked workspace source in a sealed tenant-scoped VM 2026-10-06 21:16:21 -07:00
Timothy J. Aveni be8a19b5c5 Report conservative execution placement from checked dependency closures 2026-10-06 16:28:33 -07:00
Timothy J. Aveni 9d8bc5e2ab Scope Camino storage and database authority to each workspace 2026-10-06 16:22:59 -07:00
40 changed files with 2268 additions and 176 deletions
+1 -1
View File
@@ -1,7 +1,7 @@
{ {
"version": 1, "version": 1,
"sourceRepo": "https://gitea-external.egads.tutti.syntaxblitz.net/quixos/quixos", "sourceRepo": "https://gitea-external.egads.tutti.syntaxblitz.net/quixos/quixos",
"sourceCommit": "37a50c17063a41d23037b39785f7054992d7c708", "sourceCommit": "a61bdda658be4878403b8d60aecb71fe5a614ac0",
"sourcePath": "quixos-protocol", "sourcePath": "quixos-protocol",
"exportName": "quixos-protocol", "exportName": "quixos-protocol",
"mirrorRemote": "https://gitea-external.egads.tutti.syntaxblitz.net/quixos/quixos-protocol.git" "mirrorRemote": "https://gitea-external.egads.tutti.syntaxblitz.net/quixos/quixos-protocol.git"
+2
View File
@@ -65,6 +65,7 @@
esbuild dist/src/bindings/portable-client-cli.js --bundle --platform=node --target=node24 --format=esm --outfile=quixos-codegen-client.mjs esbuild dist/src/bindings/portable-client-cli.js --bundle --platform=node --target=node24 --format=esm --outfile=quixos-codegen-client.mjs
esbuild dist/src/bindings/react-platform.js --bundle --platform=node --target=node24 --format=esm --outfile=react-platform.mjs esbuild dist/src/bindings/react-platform.js --bundle --platform=node --target=node24 --format=esm --outfile=react-platform.mjs
esbuild dist/src/capability-language/tool-cli.js --bundle --platform=node --target=node24 --format=esm --outfile=quixos-qx.mjs esbuild dist/src/capability-language/tool-cli.js --bundle --platform=node --target=node24 --format=esm --outfile=quixos-qx.mjs
esbuild dist/src/capability-language/source-check-driver.js --bundle --platform=node --target=node24 --format=esm --outfile=source-check-driver.mjs
runHook postBuild runHook postBuild
''; '';
doCheck = true; doCheck = true;
@@ -132,6 +133,7 @@
install -m644 client-codegen.mjs "$out/libexec/quixos-protocol/client-codegen.mjs" install -m644 client-codegen.mjs "$out/libexec/quixos-protocol/client-codegen.mjs"
install -m644 react-platform.mjs "$out/libexec/quixos-protocol/react-platform.mjs" install -m644 react-platform.mjs "$out/libexec/quixos-protocol/react-platform.mjs"
install -m644 quixos-codegen-ts.mjs quixos-qx.mjs "$out/libexec/quixos-protocol/" install -m644 quixos-codegen-ts.mjs quixos-qx.mjs "$out/libexec/quixos-protocol/"
install -m644 source-check-driver.mjs "$out/libexec/quixos-protocol/"
install -m644 quixos-codegen-client.mjs "$out/libexec/quixos-protocol/" install -m644 quixos-codegen-client.mjs "$out/libexec/quixos-protocol/"
install -m644 quixos-descriptor-check.mjs "$out/libexec/quixos-protocol/quixos-descriptor-check.mjs" install -m644 quixos-descriptor-check.mjs "$out/libexec/quixos-protocol/quixos-descriptor-check.mjs"
install -m644 quixos-capability-compile.mjs "$out/libexec/quixos-protocol/quixos-capability-compile.mjs" install -m644 quixos-capability-compile.mjs "$out/libexec/quixos-protocol/quixos-capability-compile.mjs"
+8
View File
@@ -3,6 +3,7 @@ import path from "node:path";
import { profile } from "./profile.js"; import { profile } from "./profile.js";
import { loadQxSources, resolveQxSources } from "./source-loader.js"; import { loadQxSources, resolveQxSources } from "./source-loader.js";
import { compileQuery, compileRepositoryQuery } from "../query/compile.js"; import { compileQuery, compileRepositoryQuery } from "../query/compile.js";
import { queryTreeProjections } from "../query/tree.js";
import type { QueryDeclaration } from "../query/types.js"; import type { QueryDeclaration } from "../query/types.js";
import { compileQueryComposition, type QueryComposition } from "../query/composition.js"; import { compileQueryComposition, type QueryComposition } from "../query/composition.js";
import { checkQueryTemplate } from "../query/templates.js"; import { checkQueryTemplate } from "../query/templates.js";
@@ -390,6 +391,13 @@ const createResourceGraphResolver = (
}; };
pkg.checkedQueries = []; pkg.checkedQueries = [];
for (const query of pkg.queries!) pkg.checkedQueries.push(await compile(query.id)); for (const query of pkg.queries!) pkg.checkedQueries.push(await compile(query.id));
const projections = pkg.checkedQueries.flatMap(queryTreeProjections);
for (const projection of projections) {
if (pkg.queries!.some((query) => query.id === projection.declaration.id))
throw new Error(`Generated Query Tree projection conflicts with ${projection.declaration.id}`);
pkg.queries!.push(projection.declaration);
pkg.checkedQueries.push(projection);
}
} }
if (generated?.compositions?.length) { if (generated?.compositions?.length) {
const pkg = compiled.resource.revision; const pkg = compiled.resource.revision;
+11 -1
View File
@@ -128,6 +128,7 @@ export async function buildImmutableCandidate(
log.once("open", () => resolve()); log.once("open", () => resolve());
log.once("error", reject); log.once("error", reject);
}); });
let logBytes = 0;
const run = async (executable: string, args: string[]) => const run = async (executable: string, args: string[]) =>
await new Promise<string>((resolve, reject) => { await new Promise<string>((resolve, reject) => {
let output = "", let output = "",
@@ -140,9 +141,18 @@ export async function buildImmutableCandidate(
}; };
log.on("error", failedLog); log.on("error", failedLog);
child.stdout.on("data", (chunk) => { child.stdout.on("data", (chunk) => {
output += chunk; if (failure) return;
if (Buffer.byteLength(output) + chunk.length > 65536)
failedLog(new Error("Candidate checker output exceeds 64 KiB"));
else output += chunk;
}); });
child.stderr.on("data", (chunk) => { child.stderr.on("data", (chunk) => {
if (failure) return;
logBytes += chunk.length;
if (logBytes > 16 * 1024 * 1024) {
failedLog(new Error("Candidate checker log exceeds 16 MiB"));
return;
}
log.write(chunk); log.write(chunk);
tail = (tail + String(chunk)).slice(-6000); tail = (tail + String(chunk)).slice(-6000);
}); });
+45 -7
View File
@@ -15,7 +15,12 @@ import {
} from "./assembly.js"; } from "./assembly.js";
import { createGitCapabilityResolver } from "./git-resolver.js"; import { createGitCapabilityResolver } from "./git-resolver.js";
import { snapshotCommit, buildImmutableCandidate } from "./checked-build.js"; import { snapshotCommit, buildImmutableCandidate } from "./checked-build.js";
import { planEvolution, type WorkspaceRevision, type EvolutionReview } from "../capability-model/index.js"; import {
planEvolution,
reviewSemanticMajors,
type WorkspaceRevision,
type EvolutionReview,
} from "../capability-model/index.js";
import { withFileLock } from "./file-lock.js"; import { withFileLock } from "./file-lock.js";
const execFile = promisify(callback); const execFile = promisify(callback);
type Source = { repository: string; commit: string }; type Source = { repository: string; commit: string };
@@ -187,6 +192,34 @@ export type UpgradeEffects = {
snapshot(root: string): Promise<string>; snapshot(root: string): Promise<string>;
publish(root: string, commit: string): Promise<void>; publish(root: string, commit: string): Promise<void>;
}; };
/** Review a successfully built immutable candidate using the same boundary as
* ordinary authoring checks. Execution storage compatibility is checked against
* the current graph at activation; the legacy evolution model is not its schema.
*/
export async function reviewUpgradeCandidate({
artifact,
baseline,
candidate,
reviews = [],
}: {
artifact: string;
baseline: WorkspaceRevision | null;
candidate: WorkspaceRevision;
reviews?: EvolutionReview[];
}) {
let execution = false;
try {
await fs.access(path.join(artifact, "execution-plan.json"));
execution = true;
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
}
return execution
? { filename: "semantic-review.json", review: reviewSemanticMajors(baseline, candidate, reviews) }
: { filename: "evolution.json", review: planEvolution(baseline, candidate, { reviews }) };
}
const effects: UpgradeEffects = { const effects: UpgradeEffects = {
async check(node, root, output, spec) { async check(node, root, output, spec) {
if (node.kind === "workspace" && !spec.baseline && !spec.bootstrap) if (node.kind === "workspace" && !spec.baseline && !spec.bootstrap)
@@ -206,10 +239,15 @@ const effects: UpgradeEffects = {
? (JSON.parse(await fs.readFile(spec.baseline, "utf8")) as WorkspaceRevision) ? (JSON.parse(await fs.readFile(spec.baseline, "utf8")) as WorkspaceRevision)
: null; : null;
const reviews = spec.reviews ? (JSON.parse(await fs.readFile(spec.reviews, "utf8")) as EvolutionReview[]) : []; const reviews = spec.reviews ? (JSON.parse(await fs.readFile(spec.reviews, "utf8")) as EvolutionReview[]) : [];
const evolution = planEvolution(baseline, JSON.parse(candidate), { reviews }); const { filename, review } = await reviewUpgradeCandidate({
await fs.writeFile(path.join(output, "evolution.json"), JSON.stringify(evolution, null, 2)); artifact,
if (evolution.blockers.length) baseline,
throw new Error(`Refactor required in ${node.directory}: ${evolution.blockers.join("; ")}`); candidate: JSON.parse(candidate),
reviews,
});
await fs.writeFile(path.join(output, filename), JSON.stringify(review, null, 2));
if (review.blockers.length)
throw new Error(`Refactor required in ${node.directory}: ${review.blockers.join("; ")}`);
} }
}, },
async snapshot(root) { async snapshot(root) {
@@ -443,13 +481,13 @@ export const applyPinUpgrades = async (
quixos: compiled.lock.quixos, quixos: compiled.lock.quixos,
directResources: [...compiled.directResources.entries()].map(([bindingKey, node]) => { directResources: [...compiled.directResources.entries()].map(([bindingKey, node]) => {
const [kind, binding] = bindingKey.split("\0"); const [kind, binding] = bindingKey.split("\0");
return { kind, binding, resourceKey: node.key, directory: node.directory }; return { kind, binding, resourceKey: node.key, directory: path.relative(plan.workbench, node.directory) };
}), }),
resources: [...resources.values()].map((node) => ({ resources: [...resources.values()].map((node) => ({
key: node.key, key: node.key,
kind: node.kind, kind: node.kind,
source: node.source, source: node.source,
directory: node.directory, directory: path.relative(plan.workbench, node.directory),
...(node.resource.kind === "build" ...(node.resource.kind === "build"
? {} ? {}
: { : {
@@ -0,0 +1,8 @@
import { buildImmutableCandidate } from "./checked-build.js";
// Installed platform driver, run only inside the sealed checker's unprivileged
// evaluator. Authored flakes never become the outer evaluator program.
const [repository, commit, log] = process.argv.slice(2);
if (!repository || !commit || !log || process.argv.length !== 5)
throw Error("source-check-driver REPOSITORY COMMIT LOG");
process.stdout.write((await buildImmutableCandidate({ repository, commit }, "workspace", log)) + "\n");
+3 -2
View File
@@ -167,11 +167,12 @@ export const planStructure = async (rootPath: string, request: StructuralRequest
resolveResource, resolveResource,
}); });
if (compiled.resource.kind === "package") { if (compiled.resource.kind === "package") {
const configuration = JSON.parse(await fs.readFile(path.join(resourceRoot, "quixos.check.json"), "utf8")); const configurationSource = await read(resourceRoot, "quixos.check.json");
const configuration = configurationSource === null ? undefined : JSON.parse(configurationSource);
// Execution bindings are immutable build outputs owned by checkedArtifacts, // Execution bindings are immutable build outputs owned by checkedArtifacts,
// not source edits produced by a structural preview. // not source edits produced by a structural preview.
const artifacts = const artifacts =
configuration.backend === "execution" !configuration || configuration.backend === "execution"
? [] ? []
: [ : [
{ {
+3 -1
View File
@@ -118,7 +118,9 @@ const main = async () => {
if (options.executionPlanOut || options.buildContextsOut) { if (options.executionPlanOut || options.buildContextsOut) {
const executionStarted = performance.now(); const executionStarted = performance.now();
const plan = compileExecutionPlan(assembled.workspace); const plan = compileExecutionPlan(assembled.workspace);
if (options.executionPlanOut) await writeFile(options.executionPlanOut, `${JSON.stringify(plan, null, 2)}\n`); // Machine-consumed immutable metadata should not spend its bounded input
// reservation on indentation. Its parsed allocation is charged separately.
if (options.executionPlanOut) await writeFile(options.executionPlanOut, `${JSON.stringify(plan)}\n`);
if (options.buildContextsOut) if (options.buildContextsOut)
await writeFile(options.buildContextsOut, JSON.stringify(packageBuildContexts(plan.definition.bindingSchema))); await writeFile(options.buildContextsOut, JSON.stringify(packageBuildContexts(plan.definition.bindingSchema)));
profile("execution-plan-and-contexts", executionStarted); profile("execution-plan-and-contexts", executionStarted);
+6 -1
View File
@@ -1526,7 +1526,6 @@ const validateBoundDependencies = (
); );
break; break;
} }
validateAttachmentAccess(issues, attachment, params.conformance, `${path}.binding.edgeTypeId`);
const projection = edgeProjection(attachment.attachment, edgeBinding.projectionId); const projection = edgeProjection(attachment.attachment, edgeBinding.projectionId);
if (!projection) { if (!projection) {
issue( issue(
@@ -1537,6 +1536,12 @@ const validateBoundDependencies = (
); );
break; break;
} }
// Exporting traversal never exports writes or subscription ownership.
const publicRead =
projection.endpoint.publicTraversal &&
requirement.primitives.length > 0 &&
requirement.primitives.every((primitive) => primitive === "resolve");
if (!publicRead) validateAttachmentAccess(issues, attachment, params.conformance, `${path}.binding.edgeTypeId`);
if (projection.target.keyType && requirement.primitives.includes("connect")) if (projection.target.keyType && requirement.primitives.includes("connect"))
issue( issue(
issues, issues,
+11 -5
View File
@@ -1,5 +1,11 @@
# Closed execution plans and artifacts # 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 `compileExecutionPlan` validates a workspace, links its checked queries, resolves
public forwarding, and emits one versioned plan with an SHA-256 digest. It retains public forwarding, and emits one versioned plan with an SHA-256 digest. It retains
exact interface/package revisions and generic applications, owner initialization, 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. monorepo `camino-execution-world` check compares the compiler and core implementations.
No machine-local Nix path enters the world descriptor. No machine-local Nix path enters the world descriptor.
The current binding schema is the closed workspace schema. This is conservative: Reusable package compilation now receives a canonical per-package build contract;
an unrelated contract change can require checking/rebuilding several packages. exact source provenance and workspace linking remain separate. See
LF-05 may narrow it to exact checked per-package closures, but must use the same [package build contracts](../../../docs/PACKAGE_BUILD_CONTRACTS.md). Generation,
schema for generation, receipts, and world validation. It must not substitute an receipts and checking must agree on that contract; unchanged source alone does
older package schema just because the source revision did not change. not justify reusing an incompatible binding schema.
## Transaction-port ABI ## Transaction-port ABI
+14 -3
View File
@@ -11,7 +11,7 @@ export interface ArtifactFile {
export interface ArtifactImplementation { export interface ArtifactImplementation {
id: string; id: string;
target: string; target: string;
compatibility: "quixos-service-v1" | "quixos-js-module-v1"; compatibility: "quixos-service-v1" | "quixos-js-module-v1" | "quixos-restricted-module-v1";
path: string; path: string;
ports: "quixos-transaction-ports-v1"; ports: "quixos-transaction-ports-v1";
registryExport?: string; registryExport?: string;
@@ -225,7 +225,11 @@ export function parseArtifactGroup(value: unknown): ArtifactGroup {
["registryExport"], ["registryExport"],
path, path,
); );
if (entry.compatibility !== "quixos-service-v1" && entry.compatibility !== "quixos-js-module-v1") if (
!["quixos-service-v1", "quixos-js-module-v1", "quixos-restricted-module-v1"].includes(
String(entry.compatibility),
)
)
fail(path, "Unsupported artifact ABI"); fail(path, "Unsupported artifact ABI");
if (entry.ports !== "quixos-transaction-ports-v1") fail(path, "Unsupported transaction port ABI"); if (entry.ports !== "quixos-transaction-ports-v1") fail(path, "Unsupported transaction port ABI");
if ( if (
@@ -233,7 +237,9 @@ export function parseArtifactGroup(value: unknown): ArtifactGroup {
(entry.target !== "server" || entry.registryExport !== undefined) (entry.target !== "server" || entry.registryExport !== undefined)
) )
fail(path, "Service must target server and has no JS registry export"); fail(path, "Service must target server and has no JS registry export");
if (entry.compatibility === "quixos-js-module-v1") text(entry.registryExport, `${path}.registryExport`); if (entry.compatibility !== "quixos-service-v1") text(entry.registryExport, `${path}.registryExport`);
if (entry.compatibility === "quixos-restricted-module-v1" && entry.target !== "server")
fail(path, "Restricted modules must target server");
const exports = array(entry.exports, `${path}.exports`).map((value) => text(value, `${path}.exports`)); const exports = array(entry.exports, `${path}.exports`).map((value) => text(value, `${path}.exports`));
unique(exports, `${path}.exports`); unique(exports, `${path}.exports`);
const files = parseArtifactFiles(entry.files, `${path}.files`); const files = parseArtifactFiles(entry.files, `${path}.files`);
@@ -300,6 +306,11 @@ export function checkPackageCoverage(
for (const id of implementation.exports) { for (const id of implementation.exports) {
const entry = expected.exports.find((e) => e.id === id); const entry = expected.exports.find((e) => e.id === id);
if (!entry) fail(implementation.id, `Unknown export ${id}`); if (!entry) fail(implementation.id, `Unknown export ${id}`);
if (
implementation.compatibility === "quixos-restricted-module-v1" &&
(entry!.execution.kind === "remote" || !entry!.execution.targets.includes("server"))
)
fail(implementation.id, `Export ${id} does not promise restricted server computation`);
if ( if (
implementation.target !== "server" && implementation.target !== "server" &&
(!entry?.execution || (!entry?.execution ||
+166 -107
View File
@@ -1,18 +1,34 @@
import { graphExecutionRepresentation } from "./graph-execution.js"; import { graphExecutionRepresentation } from "./graph-execution.js";
import { open, lstat } from "node:fs/promises"; import { lstat } from "node:fs/promises";
import { constants } from "node:fs";
import { join } from "node:path"; import { join } from "node:path";
import { hexDigest, ExecutionPlanError, type ExecutionPlan } from "./plan.js"; 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,
type CandidateMetadataBudget,
type CandidateMetadataScope,
} from "./metadata.js";
const rootPattern = /^\/nix\/store\/[a-z0-9]{32}-[^/\s]+$/; const rootPattern = /^\/nix\/store\/[a-z0-9]{32}-[^/\s]+$/;
async function readJson(root: string, file: string): Promise<any> { async function readJson(root: string, file: string, scope: CandidateMetadataScope) {
const handle = await open(join(root, file), constants.O_RDONLY | constants.O_NOFOLLOW); // Query Trees add checked projections to an already large application plan.
// The Reader now exceeds 32 MiB even without indentation. This file bound
// does not replace the stricter aggregate/owner parse-allocation budgets.
const input = await readCandidateMetadata(join(root, file), scope, 64 * 1024 * 1024);
try { try {
const metadata = await handle.stat(); return {
if (!metadata.isFile() || metadata.size > 32 * 1024 * 1024) throw Error(`Invalid checked candidate file: ${file}`); value: JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(input.bytes)),
return JSON.parse(await handle.readFile("utf8")); releaseTree: input.releaseTree,
};
} catch (error) {
input.releaseTree();
throw error;
} finally { } finally {
await handle.close(); input.releaseInput();
} }
} }
/** Load the checked Nix output, preserving its original compilation and provenance. /** Load the checked Nix output, preserving its original compilation and provenance.
@@ -22,113 +38,156 @@ async function readJson(root: string, file: string): Promise<any> {
export async function loadCheckedInstallationCandidate( export async function loadCheckedInstallationCandidate(
root: string, root: string,
selections: Readonly<Record<string, PackageInstallationSelection>> = {}, selections: Readonly<Record<string, PackageInstallationSelection>> = {},
resources: { budget?: CandidateMetadataBudget; owner?: string } = {},
) { ) {
if (!rootPattern.test(root) || !(await lstat(root)).isDirectory()) if (!rootPattern.test(root) || !(await lstat(root)).isDirectory())
throw Error("Candidate must be an immutable Nix output directory"); throw Error("Candidate must be an immutable Nix output directory");
const [candidate, plan, artifacts, source, entryRequest, kernel, queries, graph] = await Promise.all([ const scope = (resources.budget ?? candidateMetadataBudget).acquire(resources.owner ?? root);
readJson(root, "candidate.json"), try {
readJson(root, "execution-plan.json"), // Validate the duplicated source contract by digest, then discard its tree
readJson(root, "execution-artifacts.json"), // before allocating the substantially larger checked execution plan.
readJson(root, "source.json"), const workspaceDigest = await (async () => {
readJson(root, "entry.json"), const input = await readJson(root, "candidate.json", scope);
readJson(root, "kernel.json"), try {
readJson(root, "queries.json"), const { executionContracts: _legacyContracts, ...workspace } = input.value;
readJson(root, "graph-execution.json"), return hexDigest(workspace);
]); } finally {
const { executionContracts: _legacyContracts, ...workspace } = candidate; input.releaseTree();
if ( }
plan?.definition?.codec !== "camino-execution-plan-v1" || })();
hexDigest(plan.definition) !== plan.digest || // Sequential reads avoid partially rejected Promise.all() work allocating
hexDigest(workspace) !== hexDigest(plan.definition.workspace) // after the failed candidate's reservation has been released.
) const values = [];
throw new ExecutionPlanError( for (const file of [
"CANDIDATE_PLAN_MISMATCH", "execution-plan.json",
root, "execution-artifacts.json",
"Stored plan must match its digest and exact workspace source contract", "source.json",
); "entry.json",
if ( "kernel.json",
source.kind !== "workspace" || "queries.json",
source.commit !== plan.definition.workspace.sourceRootCommit || ]) {
typeof source.repository !== "string" const parsed = await readJson(root, file, scope);
) values.push(parsed.value);
throw new ExecutionPlanError("CANDIDATE_SOURCE_MISMATCH", root, "Expected exact workspace source provenance"); }
const repository = new URL(source.repository); const [plan, artifacts, source, entryRequest, kernel, queries] = values;
if ( if (
!["https:", "ssh:"].includes(repository.protocol) || plan?.definition?.codec !== "camino-execution-plan-v1" ||
repository.username || hexDigest(plan.definition) !== plan.digest ||
repository.password || workspaceDigest !== hexDigest(plan.definition.workspace)
repository.hash || )
repository.search
)
throw new ExecutionPlanError("CANDIDATE_SOURCE_INVALID", root, "Expected a source URL without credentials");
if (
artifacts.codec !== "camino-checked-execution-v2" ||
typeof artifacts.generator !== "string" ||
!/^[0-9a-f]{64}$/.test(artifacts.generator) ||
!artifacts.roots ||
typeof artifacts.roots !== "object" ||
Array.isArray(artifacts.roots)
)
throw new ExecutionPlanError("CANDIDATE_ARTIFACTS_INVALID", root, "Expected checked package roots");
for (const entry of Object.values(artifacts.roots))
if (typeof entry !== "string" || !rootPattern.test(entry))
throw new ExecutionPlanError( throw new ExecutionPlanError(
"CANDIDATE_ARTIFACTS_INVALID", "CANDIDATE_PLAN_MISMATCH",
root, root,
"Package artifacts must be immutable Nix roots", "Stored plan must match its digest and exact workspace source contract",
); );
const installation = await loadExecutionInstallation(plan, artifacts.roots, selections); if (
const entry = compileWorkspaceEntry(plan, entryRequest); source.kind !== "workspace" ||
for (const [name, program, codec] of [ source.commit !== plan.definition.workspace.sourceRootCommit ||
["kernel", kernel, "camino-kernel-program-v1"], typeof source.repository !== "string"
["queries", queries, "camino-query-program-v1"], )
] as const) throw new ExecutionPlanError("CANDIDATE_SOURCE_MISMATCH", root, "Expected exact workspace source provenance");
if (program?.codec !== codec || program.plan !== kernel.plan || hexDigest(program) !== artifacts.programs?.[name]) const repository = new URL(source.repository);
throw new ExecutionPlanError( if (
"CANDIDATE_PROGRAM_MISMATCH", !["https:", "ssh:"].includes(repository.protocol) ||
name, repository.username ||
"Stored interpreter input must match the checked build and plan", repository.password ||
); repository.hash ||
const expectedGraph = graphExecutionRepresentation(plan, installation, kernel, queries); repository.search
if (hexDigest(graph) !== hexDigest(expectedGraph) || artifacts.execution !== hexDigest(graph)) )
throw new ExecutionPlanError( throw new ExecutionPlanError("CANDIDATE_SOURCE_INVALID", root, "Expected a source URL without credentials");
"CANDIDATE_EXECUTION_MISMATCH", if (
artifacts.codec !== "camino-checked-execution-v2" ||
typeof artifacts.generator !== "string" ||
!/^[0-9a-f]{64}$/.test(artifacts.generator) ||
!artifacts.roots ||
typeof artifacts.roots !== "object" ||
Array.isArray(artifacts.roots)
)
throw new ExecutionPlanError("CANDIDATE_ARTIFACTS_INVALID", root, "Expected checked package roots");
for (const entry of Object.values(artifacts.roots))
if (typeof entry !== "string" || !rootPattern.test(entry))
throw new ExecutionPlanError(
"CANDIDATE_ARTIFACTS_INVALID",
root,
"Package artifacts must be immutable Nix roots",
);
const installation = await loadExecutionInstallation(plan, artifacts.roots, selections, scope);
const entry = compileWorkspaceEntry(plan, entryRequest);
for (const [name, program, codec] of [
["kernel", kernel, "camino-kernel-program-v1"],
["queries", queries, "camino-query-program-v1"],
] as const)
if (program?.codec !== codec || program.plan !== kernel.plan || hexDigest(program) !== artifacts.programs?.[name])
throw new ExecutionPlanError(
"CANDIDATE_PROGRAM_MISMATCH",
name,
"Stored interpreter input must match the checked build and plan",
);
const expectedGraph = graphExecutionRepresentation(plan, installation, kernel, queries);
// The stored graph embeds the same kernel/query programs. Validate it in a
// short-lived scope and retain the representation that shares those trees.
await (async () => {
const input = await readJson(root, "graph-execution.json", scope);
try {
const digest = hexDigest(input.value);
if (digest !== hexDigest(expectedGraph) || artifacts.execution !== digest)
throw new ExecutionPlanError(
"CANDIDATE_EXECUTION_MISMATCH",
root,
"Stored graph execution differs from checked inputs",
);
} finally {
input.releaseTree();
}
})();
const provenance = {
workspaceRevision: plan.definition.workspace.id as string,
source: { repository: source.repository as string, commit: source.commit as string },
generator: artifacts.generator as string,
packages: (plan as ExecutionPlan).definition.packages.map((pkg) => ({
revision: pkg.revision,
source: pkg.source,
})),
};
const reference = {
root, root,
"Stored graph execution differs from checked inputs", digest: hexDigest({
); plan: plan.digest,
const provenance = { world: installation.world,
workspaceRevision: workspace.id as string, provenance,
source: { repository: source.repository as string, commit: source.commit as string }, roots: artifacts.roots,
generator: artifacts.generator as string, entry,
packages: (plan as ExecutionPlan).definition.packages.map((pkg) => ({ programs: artifacts.programs,
revision: pkg.revision, }),
source: pkg.source, };
})), const catalog = createClientContractCatalog(plan, installation, scope, kernel);
}; return {
const reference = { reference,
root, workspace: plan.definition.workspace.workspaceId,
digest: hexDigest({ world: hexDigest(expectedGraph),
plan: plan.digest, plan: kernel.plan as string,
world: installation.world, graphExecution: expectedGraph,
provenance, provenance,
roots: artifacts.roots,
entry, entry,
programs: artifacts.programs, kernel,
}), queries,
}; installation,
return { executionPlan: plan as ExecutionPlan,
reference, clientContractCatalog: catalog.select,
workspace: plan.definition.workspace.workspaceId, metadata: {
world: hexDigest(graph), get bytes() {
plan: kernel.plan as string, return scope.bytes;
graphExecution: graph, },
provenance, release: () => {
entry, catalog.close();
kernel, scope.release();
queries, },
installation, },
executionPlan: plan as ExecutionPlan, };
}; } catch (error) {
scope.release();
throw error;
}
} }
export function compileWorkspaceEntry(plan: ExecutionPlan, entryRequest: unknown): { operation: string } | null { export function compileWorkspaceEntry(plan: ExecutionPlan, entryRequest: unknown): { operation: string } | null {
+15 -6
View File
@@ -11,6 +11,7 @@ import type { BindingSchema } from "../bindings/index.js";
import type { PackageBuildContract } from "./build-contract.js"; import type { PackageBuildContract } from "./build-contract.js";
import { preparationArtifact, type ReactPreparationArtifact } from "../react-build/declarations.js"; import { preparationArtifact, type ReactPreparationArtifact } from "../react-build/declarations.js";
import { moduleTypeContext } from "./module-contracts.js"; import { moduleTypeContext } from "./module-contracts.js";
import { queryTreeBlueprint, queryTreeType } from "./query-trees.js";
/** Public shape only: no slot inventory, implementation binding, or workspace identity. */ /** Public shape only: no slot inventory, implementation binding, or workspace identity. */
export interface PublicOperationContract { export interface PublicOperationContract {
@@ -76,6 +77,7 @@ export interface PublicQueryContract {
sourceQuery?: string; sourceQuery?: string;
input: unknown; input: unknown;
output: unknown; output: unknown;
tree?: ReturnType<typeof queryTreeBlueprint>;
} }
export function publicQueryContract(pkg: PackageRevision, queryId: string): PublicQueryContract { export function publicQueryContract(pkg: PackageRevision, queryId: string): PublicQueryContract {
const query = pkg.checkedQueries?.find((q) => q.declaration.id === queryId); const query = pkg.checkedQueries?.find((q) => q.declaration.id === queryId);
@@ -88,9 +90,10 @@ export function publicQueryContract(pkg: PackageRevision, queryId: string): Publ
definitionDigest: query.definitionDigest, definitionDigest: query.definitionDigest,
root: query.declaration.root, root: query.declaration.root,
placement: placement?.kind ?? "server", placement: placement?.kind ?? "server",
...(placement?.kind === "local" ? { sourceQuery: placement.sourceQueryId } : {}), ...(placement?.kind === "local" ? { sourceQuery: query.treeProjection?.tree ?? placement.sourceQueryId } : {}),
input: portableValueSchema(query.variables), input: portableValueSchema(query.variables),
output: portableValueSchema(query.output), output: portableValueSchema(query.output),
...(query.tree ? { tree: queryTreeBlueprint(pkg.revisionId, query) } : {}),
}; };
} }
export function linkPackageQuery(plan: ExecutionPlan, contract: PublicQueryContract) { export function linkPackageQuery(plan: ExecutionPlan, contract: PublicQueryContract) {
@@ -156,10 +159,10 @@ export function generatePackageQueryClientBindings(
checkedQueries: pkg.checkedQueries?.filter((query) => !internal.includes(query.declaration.id)), checkedQueries: pkg.checkedQueries?.filter((query) => !internal.includes(query.declaration.id)),
}; };
const queries = (pkg.checkedQueries ?? []) const queries = (pkg.checkedQueries ?? [])
.filter((query) => !query.declaration.fragment) .filter((query) => !query.declaration.fragment && !query.treeProjection)
.map( .map(
(query) => (query) =>
`${JSON.stringify(query.declaration.displayName)}: definePackageQuery<${tsType(query.variables)}, ${tsType(query.output)}, ${JSON.stringify(publicQueryContract(pkg, query.declaration.id).placement)}>(${JSON.stringify(publicQueryContract(pkg, query.declaration.id))})`, `${JSON.stringify(query.declaration.displayName)}: ${query.tree ? `definePackageQueryTree<${tsType(query.variables)}, ${queryTreeType(query)}, ${JSON.stringify(query.declaration.root.interface)}>` : `definePackageQuery<${tsType(query.variables)}, ${tsType(query.output)}, ${JSON.stringify(publicQueryContract(pkg, query.declaration.id).placement)}>`}(${JSON.stringify(publicQueryContract(pkg, query.declaration.id))})`,
); );
const emitFragment = (provider: PackageRevision, id: string) => { const emitFragment = (provider: PackageRevision, id: string) => {
const query = provider.checkedQueries?.find((query) => query.declaration.id === id); const query = provider.checkedQueries?.find((query) => query.declaration.id === id);
@@ -210,7 +213,7 @@ export function generatePackageQueryClientBindings(
fragments.push( fragments.push(
`${JSON.stringify(alias)}: {${[...entries].map(([name, value]) => `${JSON.stringify(name)}: ${value}`).join(",")}}`, `${JSON.stringify(alias)}: {${[...entries].map(([name, value]) => `${JSON.stringify(name)}: ${value}`).join(",")}}`,
); );
return `// Generated from checked package query contracts. Regenerate; do not edit.\nimport { definePackageQuery, definePackageFragment, type ManagedReference } from ${JSON.stringify(runtimeModule)};\nexport const queries = {${queries.join(",\n")}} as const;\nexport const fragments = {${fragments.join(",\n")}} as const;\n`; return `// Generated from checked package query contracts. Regenerate; do not edit.\nimport { definePackageQuery, definePackageFragment, ${queries.some((query) => query.includes("definePackageQueryTree<")) ? "definePackageQueryTree, type QueryTreeShape, type QueryTreeOccurrence, " : ""}type ManagedReference } from ${JSON.stringify(runtimeModule)};\nexport const queries = {${queries.join(",\n")}} as const;\nexport const fragments = {${fragments.join(",\n")}} as const;\n`;
} }
/** Receipt-covered bindings expose the package's imports, component subjects and /** Receipt-covered bindings expose the package's imports, component subjects and
@@ -279,7 +282,7 @@ export function generatePackageComponentBindings(
.join("\n"); .join("\n");
return ( return (
interfaces + interfaces +
'\nimport {createObjectRenderer,definePackageQuery,definePackageFragment,type ComponentType,type ComponentProps,type PresentationHandle} from "@quixos/camino-react";\n' + '\nimport {createObjectRenderer,definePackageQuery,definePackageFragment,definePackageQueryTree,type QueryTreeShape,type QueryTreeOccurrence,type QueryTreeHandle,type ComponentType,type ComponentProps,type PresentationHandle} from "@quixos/camino-react";\n' +
subjectBindings + subjectBindings +
"\n" + "\n" +
queries + queries +
@@ -319,7 +322,13 @@ export function generatePackageComponentBindings(
const handle = `PresentationHandle<${JSON.stringify(child.subject)}, ${extra}>`; const handle = `PresentationHandle<${JSON.stringify(child.subject)}, ${extra}>`;
return `readonly ${JSON.stringify(child.name)}: ${child.each ? `readonly ${handle}[]` : child.with || child.when ? `${handle} | null` : handle}`; return `readonly ${JSON.stringify(child.name)}: ${child.each ? `readonly ${handle}[]` : child.with || child.when ? `${handle} | null` : handle}`;
}); });
const input = `${tsType(preparation.input ?? composition.output)} & {readonly children: {${children.join(";")}}}`; const trees = (preparation.trees ?? []).map((tree) => {
const query = pkg.checkedQueries?.find((query) => query.declaration.id === tree.query);
if (!query?.tree)
throw new ExecutionPlanError("MISSING_QUERY_TREE", tree.query, "Expected a checked Query Tree");
return `readonly ${JSON.stringify(tree.name)}: QueryTreeHandle<${queryTreeType(query)}>`;
});
const input = `${tsType(preparation.input ?? composition.output)} & {readonly children: {${children.join(";")}}${trees.length ? `;readonly trees:{${trees.join(";")}}` : ""}}`;
return `${JSON.stringify(component.displayName)}: ComponentType<ComponentProps<${JSON.stringify(component.subject)}, ${JSON.stringify(module.contract)}, ${moduleArguments(find(module.interfaceRevisionId))}, ${input}> & ExtraModuleProps<${JSON.stringify(key)}>>;`; return `${JSON.stringify(component.displayName)}: ComponentType<ComponentProps<${JSON.stringify(component.subject)}, ${JSON.stringify(module.contract)}, ${moduleArguments(find(module.interfaceRevisionId))}, ${input}> & ExtraModuleProps<${JSON.stringify(key)}>>;`;
}) })
.join("\n") + .join("\n") +
+25 -11
View File
@@ -13,6 +13,7 @@ import {
type CheckedWorld, type CheckedWorld,
} from "./artifacts.js"; } from "./artifacts.js";
import { type ExecutionPlan, ExecutionPlanError } from "./plan.js"; import { type ExecutionPlan, ExecutionPlanError } from "./plan.js";
import { readCandidateMetadata, type CandidateMetadataScope } from "./metadata.js";
const maxFileBytes = 256 * 1024 * 1024; const maxFileBytes = 256 * 1024 * 1024;
const metadataLimit = 16 * 1024 * 1024; const metadataLimit = 16 * 1024 * 1024;
@@ -21,6 +22,18 @@ const fail = (where: string, message: string): never => {
}; };
/** Roots must be trusted immutable output directories. Refuse symlinks, including /** Roots must be trusted immutable output directories. Refuse symlinks, including
* interior directory links. Hash verification is still required before serving bytes. */ * interior directory links. Hash verification is still required before serving bytes. */
async function artifactFile(root: string, relative: string): Promise<string> {
artifactPath(relative);
const components = relative.split("/");
let resolved = root;
for (let index = 0; index < components.length; index++) {
resolved = path.join(resolved, components[index]!);
const stat = await lstat(resolved);
if (stat.isSymbolicLink() || (index < components.length - 1 ? !stat.isDirectory() : !stat.isFile()))
fail(relative, "Only real directories and regular files are allowed");
}
return resolved;
}
export async function artifactFileReader(roots: Readonly<Record<string, string>>): Promise<ArtifactReader> { export async function artifactFileReader(roots: Readonly<Record<string, string>>): Promise<ArtifactReader> {
const directories = new Map<string, string>(); const directories = new Map<string, string>();
for (const [revision, root] of Object.entries(roots)) { for (const [revision, root] of Object.entries(roots)) {
@@ -33,16 +46,8 @@ export async function artifactFileReader(roots: Readonly<Record<string, string>>
return async (revision, relative, limit) => { return async (revision, relative, limit) => {
const root = directories.get(revision); const root = directories.get(revision);
if (!root) fail(revision, "Unknown package output"); if (!root) fail(revision, "Unknown package output");
artifactPath(relative);
if (!Number.isSafeInteger(limit) || limit < 0 || limit > maxFileBytes) fail(relative, "Invalid file byte limit"); if (!Number.isSafeInteger(limit) || limit < 0 || limit > maxFileBytes) fail(relative, "Invalid file byte limit");
const components = relative.split("/"); const resolved = await artifactFile(root!, relative);
let resolved = root!;
for (let index = 0; index < components.length; index++) {
resolved = path.join(resolved, components[index]!);
const stat = await lstat(resolved);
if (stat.isSymbolicLink() || (index < components.length - 1 ? !stat.isDirectory() : !stat.isFile()))
fail(relative, "Only real directories and regular files are allowed");
}
const handle = await open(resolved, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); const handle = await open(resolved, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
try { try {
const stat = await handle.stat(); const stat = await handle.stat();
@@ -72,6 +77,7 @@ export interface LoadedArtifactWorld {
export async function loadArtifactWorld( export async function loadArtifactWorld(
plan: ExecutionPlan, plan: ExecutionPlan,
roots: Readonly<Record<string, string>>, roots: Readonly<Record<string, string>>,
metadata?: CandidateMetadataScope,
): Promise<LoadedArtifactWorld> { ): Promise<LoadedArtifactWorld> {
const read = await artifactFileReader(roots), const read = await artifactFileReader(roots),
manifests: PackageArtifacts[] = []; manifests: PackageArtifacts[] = [];
@@ -79,8 +85,16 @@ export async function loadArtifactWorld(
if (JSON.stringify(Object.keys(roots).sort()) !== JSON.stringify(expected)) if (JSON.stringify(Object.keys(roots).sort()) !== JSON.stringify(expected))
fail("world", "Output roots must exactly match the installed plan"); fail("world", "Output roots must exactly match the installed plan");
for (const revision of expected) { for (const revision of expected) {
const bytes = await read(revision, "share/quixos/package-artifacts.json", metadataLimit); const file = "share/quixos/package-artifacts.json";
const manifest = parsePackageArtifacts(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes))); const input = metadata
? await readCandidateMetadata(await artifactFile(roots[revision]!, file), metadata, metadataLimit)
: { bytes: await read(revision, file, metadataLimit), releaseInput: () => {} };
let manifest: PackageArtifacts;
try {
manifest = parsePackageArtifacts(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(input.bytes)));
} finally {
input.releaseInput();
}
if (manifest.packageRevisionId !== revision) fail(revision, "Output belongs to another package revision"); if (manifest.packageRevisionId !== revision) fail(revision, "Output belongs to another package revision");
manifests.push(manifest); manifests.push(manifest);
} }
+2
View File
@@ -17,6 +17,7 @@ export * from "./queries.js";
export * from "./query-document.js"; export * from "./query-document.js";
export { generatePortableClientBindings } from "../bindings/portable-client.js"; export { generatePortableClientBindings } from "../bindings/portable-client.js";
export * from "./candidate.js"; export * from "./candidate.js";
export * from "./metadata.js";
export { reviewSemanticMajors } from "../capability-model/evolution.js"; export { reviewSemanticMajors } from "../capability-model/evolution.js";
@@ -25,3 +26,4 @@ export * from "./public-reflection.js";
export * from "./graph-execution.js"; export * from "./graph-execution.js";
export * from "./build-contract.js"; export * from "./build-contract.js";
export * from "./placement.js";
+17 -14
View File
@@ -35,20 +35,23 @@ export interface InspectionTemplate {
} }
/** A finite installed template per interface/lane, not a per-client query compiler. /** A finite installed template per interface/lane, not a per-client query compiler.
* Flags select public cache boundaries; normal scope identity bounds specialization. */ * Flags select public cache boundaries; normal scope identity bounds specialization. */
export function compileInspectionTemplates(plan: ExecutionPlan) { export interface InspectionKernel {
const kernel = compileKernelProgram(plan) as { operations: {
operations: { key: string;
key: string; atom: string;
atom: string; interface: string;
interface: string; operation: string;
operation: string; effect: string;
effect: string; targets: string[];
targets: string[]; unsupported: string | null;
unsupported: string | null; output: unknown;
output: unknown; binding: { kind: string };
binding: { kind: string }; }[];
}[]; }
}; export function compileInspectionTemplates(
plan: ExecutionPlan,
kernel: InspectionKernel = compileKernelProgram(plan) as InspectionKernel,
) {
const queries: unknown[] = [], const queries: unknown[] = [],
contracts: PublicQueryContract[] = [], contracts: PublicQueryContract[] = [],
templates: InspectionTemplate[] = []; templates: InspectionTemplate[] = [];
+90 -4
View File
@@ -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 path from "node:path";
import { loadCheckedArtifactWorld } from "./receipts.js"; import { loadCheckedArtifactWorld } from "./receipts.js";
import { contentArtifactUrl, loadArtifactWorld, type LoadedArtifactWorld } from "./files.js"; import { contentArtifactUrl, loadArtifactWorld, type LoadedArtifactWorld } from "./files.js";
@@ -11,6 +11,7 @@ import {
type PublicQueryContract, type PublicQueryContract,
} from "./client-contracts.js"; } from "./client-contracts.js";
import { resultInterfaces } from "./projections.js"; import { resultInterfaces } from "./projections.js";
import type { CandidateMetadataScope } from "./metadata.js";
/** Activation is assigned by graph authority, never by a package artifact. */ /** Activation is assigned by graph authority, never by a package artifact. */
export interface ActiveExecutionIdentity { export interface ActiveExecutionIdentity {
@@ -44,6 +45,7 @@ export function clientContractCatalog(
plan: ExecutionPlan, plan: ExecutionPlan,
installation: ExecutionInstallation, installation: ExecutionInstallation,
requestedPackages: readonly string[], requestedPackages: readonly string[],
checkedKernel?: InspectionKernel,
): ClientContractCatalog { ): ClientContractCatalog {
if (installation.plan !== plan.digest || hexDigest(plan.definition) !== plan.digest) if (installation.plan !== plan.digest || hexDigest(plan.definition) !== plan.digest)
throw new ExecutionPlanError( throw new ExecutionPlanError(
@@ -68,7 +70,7 @@ export function clientContractCatalog(
.map((operation) => publicOperationContract(iface, operation)), .map((operation) => publicOperationContract(iface, operation)),
), ),
); );
const inspection = compileInspectionTemplates(plan); const inspection = compileInspectionTemplates(plan, checkedKernel);
return { return {
inspections: inspection.templates, inspections: inspection.templates,
resultInterfaces: Object.fromEntries( resultInterfaces: Object.fromEntries(
@@ -97,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 { export interface PackageInstallationSelection {
readonly browser?: { readonly id?: string }; readonly browser?: { readonly id?: string };
readonly service?: { readonly id?: string }; readonly service?: { readonly id?: string };
@@ -112,6 +183,8 @@ export interface ExecutionInstallation {
readonly root: string; readonly root: string;
readonly service?: ArtifactImplementation; readonly service?: ArtifactImplementation;
readonly module?: ArtifactImplementation; readonly module?: ArtifactImplementation;
/** Checked candidate only; the qualified host verifies its import surface and SDK. */
readonly restricted?: ArtifactImplementation;
readonly browserImplementation?: ArtifactImplementation; readonly browserImplementation?: ArtifactImplementation;
readonly browserURL?: string; readonly browserURL?: string;
readonly browserRegistry?: string; readonly browserRegistry?: string;
@@ -159,8 +232,9 @@ export async function loadExecutionInstallation(
plan: ExecutionPlan, plan: ExecutionPlan,
roots: Readonly<Record<string, string>>, roots: Readonly<Record<string, string>>,
selections: Readonly<Record<string, PackageInstallationSelection>> = {}, selections: Readonly<Record<string, PackageInstallationSelection>> = {},
metadata?: CandidateMetadataScope,
): Promise<ExecutionInstallation> { ): Promise<ExecutionInstallation> {
return assembleExecutionInstallation(plan, roots, await loadArtifactWorld(plan, roots), selections); return assembleExecutionInstallation(plan, roots, await loadArtifactWorld(plan, roots, metadata), selections);
} }
function assembleExecutionInstallation( function assembleExecutionInstallation(
plan: ExecutionPlan, plan: ExecutionPlan,
@@ -249,6 +323,11 @@ function assembleExecutionInstallation(
exports: exports.map((entry) => entry.id), exports: exports.map((entry) => entry.id),
}) })
: undefined; : undefined;
const restrictedCandidates = manifest.implementations.filter(
(entry) => entry.compatibility === "quixos-restricted-module-v1",
);
if (restrictedCandidates.length > 1) fail(revision, "Ambiguous restricted module candidates");
const restricted = restrictedCandidates[0];
const browserExports = exports.filter( const browserExports = exports.filter(
(entry) => (entry) =>
entry.execution.kind !== "remote" && entry.execution.kind !== "remote" &&
@@ -256,7 +335,13 @@ function assembleExecutionInstallation(
); );
if (!browserExports.length) { if (!browserExports.length) {
if (selection.browser) fail(revision, "Package has no browser exports to select"); if (selection.browser) fail(revision, "Package has no browser exports to select");
packages.push({ revision, root, ...(service ? { service } : {}), ...(module ? { module } : {}) }); packages.push({
revision,
root,
...(service ? { service } : {}),
...(module ? { module } : {}),
...(restricted ? { restricted } : {}),
});
continue; continue;
} }
const browser = selectArtifactImplementation(manifest, { const browser = selectArtifactImplementation(manifest, {
@@ -287,6 +372,7 @@ function assembleExecutionInstallation(
root, root,
...(service ? { service } : {}), ...(service ? { service } : {}),
...(module ? { module } : {}), ...(module ? { module } : {}),
...(restricted ? { restricted } : {}),
browserImplementation: browser, browserImplementation: browser,
browserURL: contentArtifactUrl(entry), browserURL: contentArtifactUrl(entry),
browserRegistry: browser.registryExport, browserRegistry: browser.registryExport,
+138
View File
@@ -0,0 +1,138 @@
import { constants } from "node:fs";
import { open } from "node:fs/promises";
/** Admission estimates, not a hard V8 heap limit. A process/cgroup ceiling is
* still required. Charge input, parse trees and derived indexes before reading
* or parsing. Each live candidate retains its reservation until explicit close. */
export class CandidateMetadataBudget {
readonly limits: Readonly<{ bytes: number; ownerBytes: number; candidates: number }>;
private bytes = 0;
private scopes = 0;
private readonly owners = new Map<string, number>();
// A cutover holds both the serving and proposed installation plus transient
// parsing space. The Reader with checked Query Trees retains ~176 MiB per
// installation; its replacement also needs transient parse/index space.
// Keep the aggregate ceiling independent and leave room for parsing overlap.
constructor(limits = { bytes: 768 * 1024 * 1024, ownerBytes: 512 * 1024 * 1024, candidates: 128 }) {
for (const value of Object.values(limits))
if (!Number.isSafeInteger(value) || value < 1) throw Error("INVALID_CANDIDATE_METADATA_BUDGET");
if (limits.ownerBytes > limits.bytes) throw Error("INVALID_CANDIDATE_METADATA_BUDGET");
this.limits = Object.freeze({ ...limits });
}
snapshot() {
return { bytes: this.bytes, candidates: this.scopes, owners: this.owners.size, limits: this.limits };
}
acquire(owner: string) {
if (!owner || owner.length > 4096) throw Error("INVALID_CANDIDATE_METADATA_OWNER");
if (this.scopes >= this.limits.candidates) throw Error("CANDIDATE_METADATA_LIMIT");
this.scopes++;
let bytes = 0,
closed = false;
const charge = (amount: number) => {
if (closed) throw Error("CANDIDATE_METADATA_CLOSED");
if (!Number.isSafeInteger(amount) || amount < 0) throw Error("INVALID_CANDIDATE_METADATA_CHARGE");
const owned = this.owners.get(owner) ?? 0;
if (this.bytes + amount > this.limits.bytes || owned + amount > this.limits.ownerBytes)
throw Error("CANDIDATE_METADATA_LIMIT");
bytes += amount;
this.bytes += amount;
this.owners.set(owner, owned + amount);
};
const subtract = (amount: number) => {
bytes -= amount;
this.bytes -= amount;
const remaining = (this.owners.get(owner) ?? 0) - amount;
if (remaining) this.owners.set(owner, remaining);
else this.owners.delete(owner);
};
return {
get bytes() {
return bytes;
},
charge,
/** Opaque, idempotent transient reservation; callers cannot subtract an
* arbitrary amount or release another candidate's charges. */
reserve: (amount: number) => {
charge(amount);
let released = false;
return () => {
if (closed || released) return;
released = true;
subtract(amount);
};
},
release: () => {
if (closed) return;
closed = true;
subtract(bytes);
this.scopes--;
},
};
}
}
export type CandidateMetadataScope = ReturnType<CandidateMetadataBudget["acquire"]>;
export const candidateMetadataBudget = new CandidateMetadataBudget();
// Estimate JSON allocation without constructing its tree. Object/array headers,
// value slots and strings get explicit weights, with a multiplier for checked
// indexes/derived representations. Indentation must not multiply tree charges.
function jsonAllocation(bytes: Uint8Array): number {
let estimate = 0;
for (let i = 0; i < bytes.length; i++) {
const c = bytes[i]!;
if (c === 123) estimate += 64;
else if (c === 91) estimate += 32;
else if (c === 34) {
const start = ++i;
while (i < bytes.length && bytes[i] !== 34) {
if (bytes[i] === 92) i++;
i++;
}
estimate += 32 + 2 * (i - start);
} else if (c === 45 || (c >= 48 && c <= 57) || c === 116 || c === 102 || c === 110) {
estimate += 16;
while (i + 1 < bytes.length) {
const next = bytes[i + 1]!;
if (next === 9 || next === 10 || next === 13 || next === 32 || next === 44 || next === 93 || next === 125)
break;
i++;
}
}
}
return estimate * 2;
}
/** Immutable regular files only. Fixed allocation plus an extra byte catches
* growth; readFile() would allocate before the admission check can intervene. */
export async function readCandidateMetadata(
path: string,
scope: CandidateMetadataScope,
limit: number,
): Promise<{ bytes: Uint8Array; releaseInput: () => void; releaseTree: () => void }> {
const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
let releaseInput: (() => void) | undefined;
try {
const stat = await handle.stat();
if (!stat.isFile() || !Number.isSafeInteger(stat.size) || stat.size > limit)
throw Error("CANDIDATE_METADATA_FILE_LIMIT");
// Reserve the input buffer and UTF-16 decoding before allocating either.
releaseInput = scope.reserve((stat.size + 1) * 3);
const bytes = Buffer.alloc(stat.size + 1);
let offset = 0;
while (offset < bytes.length) {
const read = await handle.read(bytes, offset, bytes.length - offset, offset);
if (!read.bytesRead) break;
offset += read.bytesRead;
}
if (offset !== stat.size) throw Error("CANDIDATE_METADATA_CHANGED");
const content = bytes.subarray(0, offset);
// No JSON.parse/decoded tree exists until its shape-based charge succeeds.
const releaseTree = scope.reserve(jsonAllocation(content));
return { bytes: content, releaseInput, releaseTree };
} catch (error) {
releaseInput?.();
throw error;
} finally {
await handle.close();
}
}
+367
View File
@@ -0,0 +1,367 @@
import { parse } from "@babel/parser";
import { builtinModules } from "node:module";
import { ExecutionPlanError, hexDigest, type ExecutionPlan } from "./plan.js";
import type { ExecutionInstallation } from "./installation.js";
import type { ArtifactImplementation, ArtifactReader } from "./artifacts.js";
export interface PlacementBlocker {
readonly code: string;
readonly path: readonly string[];
readonly detail: string;
}
export interface PlacementEntry {
readonly operation: string;
readonly effect: string;
readonly availableTargets: readonly string[];
readonly requiresVM: boolean;
readonly nativeBindings: readonly string[];
readonly cycles: readonly (readonly string[])[];
readonly blockers: readonly PlacementBlocker[];
}
export interface ImportFinding {
readonly code: string;
readonly detail: string;
readonly line: number | null;
}
export const restrictedSDKSpecifier = "quixos:restricted-sdk/v1";
export const restrictedSDKPath = "share/quixos/restricted/core.mjs";
/** Compare trusted SDK syntax without build-machine paths in source comments.
* Keep literal/directive spelling and every executable AST node. This is SDK
* compatibility only: artifact files and the executed host SDK still have exact
* byte digests, and authored SDK bytes are never loaded by the restricted host.
*/
export function restrictedSDKIdentity(source: string): string {
if (Buffer.byteLength(source) > 2 * 1024 * 1024) throw Error("RESTRICTED_SDK_ANALYSIS_LIMIT");
const syntax = parse(source, { sourceType: "module", attachComment: false });
const metadata = new Set([
"start",
"end",
"loc",
"comments",
"leadingComments",
"innerComments",
"trailingComments",
"parenStart",
]);
let nodes = 0;
const encoded = JSON.stringify(syntax, (key, value) => {
if (metadata.has(key)) return undefined;
if (value && typeof value === "object" && typeof value.type === "string" && ++nodes > 100000)
throw Error("RESTRICTED_SDK_ANALYSIS_LIMIT");
return value;
});
return hexDigest({ codec: "quixos-restricted-sdk-syntax-v1", syntax: JSON.parse(encoded) });
}
/** Mechanical candidate checks, not authorization or an engine-safety proof.
* The caller must first verify the manifest and all declared file digests. */
export async function inspectRestrictedImplementation(
revision: string,
implementation: ArtifactImplementation,
read: ArtifactReader,
qualifiedSDKIdentity?: string,
): Promise<ImportFinding[]> {
const entry = implementation.files.find((file) => file.path === implementation.path);
const sdk = implementation.files.find((file) => file.path === restrictedSDKPath);
if (
implementation.compatibility !== "quixos-restricted-module-v1" ||
implementation.target !== "server" ||
implementation.files.length !== 2 ||
!entry ||
!sdk ||
entry === sdk ||
entry.mediaType !== "text/javascript" ||
sdk.mediaType !== "text/javascript" ||
!/^[$A-Z_a-z][$\w]*$/.test(implementation.registryExport ?? "")
)
return [{ code: "RESTRICTED_CLOSURE", detail: "Expected one closed module and the restricted SDK", line: null }];
if (entry.bytes > 1024 * 1024 || sdk.bytes > 2 * 1024 * 1024)
return [{ code: "ANALYSIS_LIMIT", detail: "Restricted closure exceeds the source budget", line: null }];
if (qualifiedSDKIdentity) {
const source = Buffer.from(await read(revision, sdk.path, sdk.bytes)).toString("utf8");
try {
if (restrictedSDKIdentity(source) !== qualifiedSDKIdentity) throw Error("SDK syntax differs");
} catch {
return [
{ code: "RESTRICTED_SDK_UNSUPPORTED", detail: "SDK differs from the qualified host profile", line: null },
];
}
}
return inspectJavaScriptSurface(Buffer.from(await read(revision, entry.path, entry.bytes)).toString("utf8"), [
restrictedSDKSpecifier,
]);
}
const nativeImports = new Set(builtinModules.flatMap((name) => [name, name.replace(/^node:/, "")]));
const ambient = new Set([
"process",
"global",
"globalThis",
"fetch",
"WebSocket",
"XMLHttpRequest",
"Deno",
"Bun",
"eval",
"Function",
"SharedArrayBuffer",
"Atomics",
]);
/** Diagnostic scan of compiled JavaScript, never a certificate of purity. A
* shadowed name can conservatively produce a finding; computed access/aliases
* cannot be proven safe here. No findings still require a qualified loader and
* runtime before this artifact can enter restricted execution. */
export function inspectJavaScriptSurface(source: string, checkedSDKImports: readonly string[] = []): ImportFinding[] {
if (Buffer.byteLength(source) > 1024 * 1024)
return [{ code: "ANALYSIS_LIMIT", detail: "JavaScript exceeds the 1 MiB inspection budget", line: null }];
let ast;
try {
ast = parse(source, { sourceType: "module", createImportExpressions: true });
} catch {
return [
{
code: "UNCLASSIFIED_SYNTAX",
detail: "Compiled source cannot be classified by the selected parser",
line: null,
},
];
}
const findings: ImportFinding[] = [],
seen = new Set<string>(),
sdk = new Set(checkedSDKImports);
const add = (code: string, detail: string, node: any) => {
const key = JSON.stringify([code, detail]);
if (seen.has(key)) return;
seen.add(key);
if (findings.length < 63) findings.push({ code, detail, line: node?.loc?.start.line ?? null });
};
const imported = (node: any, at: any) => {
if (node?.type !== "StringLiteral") {
add("COMPUTED_MODULE_LOADING", "Module name is computed", at);
return;
}
const name: string = node.value;
if (sdk.has(name)) return;
add(
name.startsWith("node:") || nativeImports.has(name) ? "NATIVE_IMPORT" : "UNCLASSIFIED_IMPORT",
name.slice(0, 256),
at,
);
};
const pending: { node: any; parent?: any; key?: string }[] = [{ node: ast }];
let visited = 0;
while (pending.length) {
if (++visited > 100000) {
add("ANALYSIS_LIMIT", "JavaScript exceeds the syntax-node inspection budget", null);
break;
}
const { node, parent, key } = pending.pop()!;
if (!node || typeof node !== "object") continue;
if (["ImportDeclaration", "ExportAllDeclaration", "ExportNamedDeclaration"].includes(node.type) && node.source)
imported(node.source, node);
if (node.type === "ImportExpression") imported(node.source, node);
if (node.type === "CallExpression" && node.callee?.type === "Identifier" && node.callee.name === "require")
imported(node.arguments[0], node);
const propertyName = key === "property" && parent?.type === "MemberExpression" && !parent.computed;
const recordKey =
key === "key" &&
["ObjectProperty", "ObjectMethod"].includes(parent?.type) &&
!parent.computed &&
!parent.shorthand;
if (node.type === "Identifier" && ambient.has(node.name) && !propertyName && !recordKey)
add("AMBIENT_HOST_ACCESS", node.name, node);
if (
node.type === "MemberExpression" &&
node.object?.type === "Identifier" &&
node.object.name === "Math" &&
(node.computed || node.property?.name === "random")
)
add("AMBIENT_RANDOMNESS", "Use captured input or a frame-scoped seed", node);
if (
(node.type === "CallExpression" || node.type === "NewExpression") &&
node.callee?.type === "Identifier" &&
node.callee.name === "Date" &&
node.arguments.length === 0
)
add("AMBIENT_CLOCK", "Use captured time; date parsing is allowed", node);
if (
node.type === "MemberExpression" &&
node.object?.type === "Identifier" &&
node.object.name === "Date" &&
(node.computed || node.property?.name === "now")
)
add("AMBIENT_CLOCK", "Use captured time; date parsing is allowed", node);
for (const [childKey, child] of Object.entries(node)) {
if (["loc", "start", "end", "extra", "comments", "tokens"].includes(childKey)) continue;
if (Array.isArray(child)) {
for (const value of child)
if (value && typeof value === "object") pending.push({ node: value, parent: node, key: childKey });
} else if (child && typeof child === "object") pending.push({ node: child, parent: node, key: childKey });
}
}
if (seen.size > findings.length)
findings.push({ code: "ANALYSIS_LIMIT", detail: "Additional findings omitted", line: null });
return findings;
}
/** Derived metadata only. A build report can describe a closed candidate but
* cannot qualify the host's engine, SDK, OS sandbox or resource controller. */
export async function reportExecutionPlacement(
plan: ExecutionPlan,
installation: ExecutionInstallation,
read: ArtifactReader,
) {
if (installation.plan !== plan.digest || hexDigest(plan.definition) !== plan.digest)
throw new ExecutionPlanError(
"PLACEMENT_PLAN_MISMATCH",
plan.digest,
"Expected the selected checked plan and installation",
);
const operations = new Map(plan.definition.operations.map((entry) => [entry.key, entry]));
const queries = new Map(plan.definition.queries.map((entry) => [entry.id, entry]));
const packages = await Promise.all(
installation.packages.map(async (pkg) => {
const implementations: { id: string; digest: string; compatibility: string; findings: ImportFinding[] }[] = [];
for (const implementation of [pkg.service, pkg.module, pkg.restricted].filter(
(entry): entry is ArtifactImplementation => !!entry,
)) {
let findings: ImportFinding[];
if (implementation.compatibility === "quixos-restricted-module-v1")
findings = await inspectRestrictedImplementation(pkg.revision, implementation, read);
else if (implementation.compatibility === "quixos-js-module-v1") {
const file = implementation.files.find((file) => file.path === implementation.path)!;
if (!file || file.bytes > 1024 * 1024)
findings = [
{ code: "ANALYSIS_LIMIT", detail: "Entry source unavailable within the inspection budget", line: null },
];
else {
const sdk = implementation.files.filter((file) => file.path.endsWith("/core.mjs"));
const allowed = sdk.flatMap((file) => [
`${pkg.root}/${file.path}`,
`/__quixos/artifacts/content/${file.digest}/core.mjs`,
]);
findings = inspectJavaScriptSurface(
Buffer.from(await read(pkg.revision, file.path, file.bytes)).toString("utf8"),
allowed,
);
}
} else
findings = [
{ code: "NATIVE_SERVICE", detail: "Native/persistent service stays in VM execution", line: null },
];
implementations.push({
id: implementation.id,
digest: implementation.contentDigest,
compatibility: implementation.compatibility,
findings,
});
}
return {
revision: pkg.revision,
requiresVM: implementations.length > 0,
restrictedEligible: false as const,
reason: pkg.restricted ? "HOST_PROFILE_QUALIFICATION_REQUIRED" : "NO_RESTRICTED_IMPLEMENTATION",
restrictedCandidate: pkg.restricted
? {
digest: pkg.restricted.contentDigest,
exports: pkg.restricted.exports,
compatible: implementations.find((entry) => entry.id === pkg.restricted!.id)!.findings.length === 0,
}
: null,
implementations,
};
}),
);
const entries: PlacementEntry[] = plan.definition.operations.map((root) => {
const native = new Set<string>(),
visited = new Set<string>(),
cycles: string[][] = [],
blockers: PlacementBlocker[] = [];
const pending = [{ key: root.key, path: [root.key] }];
let limited = false;
const block = (code: string, path: string[], detail: string) => {
if (blockers.length < 63) blockers.push({ code, path, detail });
else limited = true;
};
while (pending.length) {
if (visited.size >= 512) {
limited = true;
break;
}
const { key, path } = pending.pop()!;
const repeated = path.slice(0, -1).indexOf(key);
if (repeated >= 0) {
if (cycles.length < 16) cycles.push(path.slice(repeated));
else limited = true;
continue;
}
if (visited.has(key)) continue;
if (path.length > 128) {
limited = true;
continue;
}
visited.add(key);
const node = operations.get(key);
if (!node) {
block("UNCLASSIFIED_DEPENDENCY", path, "Operation is absent from the checked closure");
continue;
}
if (node.execution.kind === "remote")
block("REMOTE_EFFECT", path, "Remote effects require VM or separately approved effect authority");
if (node.binding.kind === "package")
block(
"UNQUALIFIED_PACKAGE",
path,
`${node.binding.packageRevisionId}/${node.binding.exportId}: no qualified restricted implementation`,
);
else if (["state", "edge", "journal", "subscription", "lifecycle"].includes(node.binding.kind))
native.add(node.binding.kind);
else block("UNCLASSIFIED_NATIVE", path, node.binding.kind);
for (const dependency of node.dependencies) {
if (dependency.kind === "operation")
pending.push({ key: dependency.operation, path: [...path, dependency.port, dependency.operation] });
if (dependency.kind === "query") {
const query = queries.get(dependency.query);
if (!query) block("UNCLASSIFIED_QUERY", [...path, dependency.port], dependency.query);
else
for (const operation of new Set([...query.operations, ...query.admittedOperations]))
pending.push({ key: operation, path: [...path, dependency.port, dependency.query, operation] });
}
}
}
if (limited)
blockers.push({
code: "ANALYSIS_LIMIT",
path: [root.key],
detail: "Dependency closure exceeds the bounded report; keep VM placement",
});
return {
operation: root.key,
effect: root.execution.kind,
availableTargets: [...root.availableTargets],
requiresVM: blockers.length > 0,
nativeBindings: [...native].sort(),
cycles,
blockers,
};
});
const background = plan.definition.packages.flatMap((pkg) =>
(pkg.controllers ?? []).map((controller) => ({
package: pkg.revision,
id: controller.id,
requiresVM: true,
reason: "PERSISTENT_CONTROLLER_EXECUTION",
})),
);
return {
codec: "quixos-execution-placement-v1" as const,
workspace: plan.definition.workspace.workspaceId,
plan: plan.digest,
requiresVM:
packages.some((pkg) => pkg.requiresVM) || entries.some((entry) => entry.requiresVM) || background.length > 0,
operations: entries,
packages,
background,
};
}
+2
View File
@@ -29,6 +29,8 @@ export interface PackageInvocation {
/** Capability arguments/receiver use the versioned managed-reference codec. */ /** Capability arguments/receiver use the versioned managed-reference codec. */
input: unknown; input: unknown;
receiver: unknown | null; receiver: unknown | null;
/** Host-owned remaining root resources, separate from authored input. */
budget?: { root: string; depth: number; calls: number; deadlineMs: number };
} }
export type InvocationReply = export type InvocationReply =
| { abi: typeof transactionPortAbi; invocation: string; status: "returned"; output: unknown } | { abi: typeof transactionPortAbi; invocation: string; status: "returned"; output: unknown }
+25 -2
View File
@@ -4,6 +4,7 @@ import { portableValueSchema } from "../bindings/portable.js";
import { ExecutionPlanError, hexDigest, type ExecutionPlan } from "./plan.js"; import { ExecutionPlanError, hexDigest, type ExecutionPlan } from "./plan.js";
import type { ValueType } from "../capability-model/types.js"; import type { ValueType } from "../capability-model/types.js";
import { compileQueryComposition } from "../query/composition.js"; import { compileQueryComposition } from "../query/composition.js";
import { queryTreeBlueprint } from "./query-trees.js";
const lowerTypes = (value: unknown): unknown => const lowerTypes = (value: unknown): unknown =>
JSON.parse( JSON.parse(
@@ -59,6 +60,12 @@ export function compileQueryProgram(plan: ExecutionPlan): unknown {
codec: "camino-query-program-v1", codec: "camino-query-program-v1",
plan: (compileKernelProgram(plan) as { plan: string }).plan, plan: (compileKernelProgram(plan) as { plan: string }).plan,
...(compositions.length ? { compositions } : {}), ...(compositions.length ? { compositions } : {}),
trees: plan.definition.queries
.filter((entry) => entry.query.checked.tree)
.map((entry) => ({
id: entry.id,
...queryTreeBlueprint(entry.query.packageRevisionId, entry.query.checked),
})),
queries: [ queries: [
...compileInspectionTemplates(plan).queries, ...compileInspectionTemplates(plan).queries,
...plan.definition.queries.map((entry) => queryProgramEntry(plan, entry)), ...plan.definition.queries.map((entry) => queryProgramEntry(plan, entry)),
@@ -85,7 +92,10 @@ export function queryProgramEntry(plan: ExecutionPlan, entry: import("./plan.js"
placement: checked.declaration.placement?.kind ?? "remote", placement: checked.declaration.placement?.kind ?? "remote",
source: source:
checked.declaration.placement?.kind === "local" checked.declaration.placement?.kind === "local"
? JSON.stringify([query.packageRevisionId, checked.declaration.placement.sourceQueryId]) ? JSON.stringify([
query.packageRevisionId,
checked.treeProjection?.tree ?? checked.declaration.placement.sourceQueryId,
])
: null, : null,
root: checked.declaration.root, root: checked.declaration.root,
atoms: query.rootAtoms, atoms: query.rootAtoms,
@@ -105,6 +115,19 @@ export function queryProgramEntry(plan: ExecutionPlan, entry: import("./plan.js"
operation: JSON.stringify([field.atomId, field.interfaceRevisionId, field.getter]), operation: JSON.stringify([field.atomId, field.interfaceRevisionId, field.getter]),
}; };
}), }),
admittedOperations, admittedOperations: checked.tree
? [
...new Set([
...admittedOperations,
...plan.definition.queries
.filter(
(entry) =>
entry.query.packageRevisionId === query.packageRevisionId &&
entry.query.checked.treeProjection?.tree === checked.declaration.id,
)
.flatMap((entry) => entry.operations),
]),
].sort()
: admittedOperations,
}; };
} }
+94
View File
@@ -0,0 +1,94 @@
import type { CheckedQuery, QueryTreeNode } from "../query/types.js";
import type { ValueType } from "../capability-model/types.js";
import { treeProjectionQuery } from "../query/tree.js";
import { tsType } from "../bindings/portable.js";
export function queryTreeBlueprint(packageId: string, query: CheckedQuery) {
const tree = query.tree!;
const projection = (id: string) =>
JSON.stringify([packageId, treeProjectionQuery(query.declaration.id, id, "local")]);
const admission = (id: string) =>
JSON.stringify([packageId, treeProjectionQuery(query.declaration.id, id, "replica")]);
return {
root: tree.root,
maxOccurrences: tree.maxOccurrences,
nodes: tree.nodes.map((node) => ({
...node,
projection: projection(node.projection),
admission: admission(node.projection),
bindings: node.bindings.map((binding) => ({
...binding,
projection: projection(binding.projection),
admission: admission(binding.projection),
})),
})),
};
}
/** Emit the shape of owned handles separately from graph result codecs. */
export function queryTreeType(query: CheckedQuery): string {
const tree = query.tree!;
const nodes = new Map(tree.nodes.map((node) => [node.id, node]));
const projections = new Map(tree.projections.map((projection) => [projection.id, projection]));
const rootOutput = (id: string) => {
const shape = projections.get(id)!.output;
if (shape.kind !== "record" || !shape.fields.root) throw Error("Unchecked Query Tree projection");
return shape.fields.root;
};
const shape = (id: string): string => {
const node = nodes.get(id)!;
return `QueryTreeShape<${tsType(rootOutput(node.projection))}, {${node.boundaries
.map(
(boundary) =>
`readonly ${JSON.stringify(boundary.name)}${boundary.conditions.length ? "?" : ""}: ${shape(boundary.node)}`,
)
.join(";")}}, {readonly root: {${node.bindings
.map(
(binding) =>
`readonly ${JSON.stringify(binding.name)}: ${bindingType(rootOutput(binding.projection), binding.targets, [binding.name])}`,
)
.join(";")}}}>`;
};
const bindingType = (
type: ValueType,
targets: QueryTreeNode["bindings"][number]["targets"],
prefix: string[],
): string => {
const at = (type: ValueType, targets: QueryTreeNode["bindings"][number]["targets"]): string => {
if (type.kind === "optional") return `(${at(type.value, targets)} | null)`;
if (type.kind === "list")
return `ReadonlyArray<${at(
type.value,
targets.map((target) => ({ ...target, path: target.path.slice(1) })),
)}>`;
const target = targets.find((target) => !target.path.length);
if (target) {
if (type.kind !== "record" || type.fields._camino?.kind !== "record" || !type.fields._camino.fields.ref)
throw Error("Unchecked binding identity");
return `QueryTreeOccurrence<${tsType(type.fields._camino.fields.ref)}, ${shape(target.node)}>`;
}
if (type.kind !== "record") return tsType(type);
return `{${Object.entries(type.fields)
.map(
([key, value]) =>
`readonly ${JSON.stringify(key)}: ${at(
value,
targets
.filter((target) => target.path[0] === key)
.map((target) => ({ ...target, path: target.path.slice(1) })),
)}`,
)
.join(";")}}`;
};
let selected = type;
for (const key of prefix) {
if (selected.kind !== "record" || !selected.fields[key]) throw Error("Unchecked binding field");
selected = selected.fields[key];
}
return at(
selected,
targets.map((target) => ({ ...target, path: target.path.slice(prefix.length) })),
);
};
return shape(tree.root);
}
+61 -4
View File
@@ -41,6 +41,7 @@ import { objectRow } from "./relational-schema.js";
import { workspaceQueryRootId } from "./root.js"; import { workspaceQueryRootId } from "./root.js";
import { relationalCompiler } from "./relational-compile.js"; import { relationalCompiler } from "./relational-compile.js";
import { fragmentSources, type FragmentResolver } from "./fragments.js"; import { fragmentSources, type FragmentResolver } from "./fragments.js";
import { lowerQueryTree, stripQueryBoundaries } from "./tree.js";
import { import {
QueryCompileError, QueryCompileError,
type QueryDeclaration, type QueryDeclaration,
@@ -158,7 +159,7 @@ export async function compileQuery(
if (node.name.value.startsWith("__")) fail("QUERY_UNSUPPORTED_FEATURE", "Introspection is not supported", node); if (node.name.value.startsWith("__")) fail("QUERY_UNSUPPORTED_FEATURE", "Introspection is not supported", node);
}, },
Directive(node) { Directive(node) {
if (!["include", "skip"].includes(node.name.value)) if (!["include", "skip", "boundary"].includes(node.name.value))
fail("QUERY_UNSUPPORTED_FEATURE", `Unsupported directive ${node.name.value}`, node); fail("QUERY_UNSUPPORTED_FEATURE", `Unsupported directive ${node.name.value}`, node);
}, },
}); });
@@ -421,6 +422,7 @@ export async function compileQuery(
for (const selection of set.selections) { for (const selection of set.selections) {
if (++expandedFields > 10000) fail("QUERY_WORK_LIMIT", "Expanded query exceeds 10000 fields", selection); if (++expandedFields > 10000) fail("QUERY_WORK_LIMIT", "Expanded query exceeds 10000 fields", selection);
if (selection.kind === "FragmentSpread") { if (selection.kind === "FragmentSpread") {
if (selection.directives?.some((directive) => directive.name.value === "boundary")) continue;
if (fragmentContracts.get(selection.name.value)?.mode === "reference") continue; if (fragmentContracts.get(selection.name.value)?.mode === "reference") continue;
add( add(
fragments.get(selection.name.value)!.selectionSet, fragments.get(selection.name.value)!.selectionSet,
@@ -519,7 +521,7 @@ export async function compileQuery(
}; };
const conditions = (directives: readonly DirectiveNode[] = []) => const conditions = (directives: readonly DirectiveNode[] = []) =>
directives directives
.filter((directive) => directive.name.value !== "live") .filter((directive) => ["include", "skip"].includes(directive.name.value))
.map((directive) => ({ .map((directive) => ({
include: directive.name.value === "include", include: directive.name.value === "include",
value: argument(directive.arguments!.find((entry) => entry.name.value === "if")!.value), value: argument(directive.arguments!.find((entry) => entry.name.value === "if")!.value),
@@ -540,6 +542,52 @@ export async function compileQuery(
const contract = fragmentContracts.get(node.name.value); const contract = fragmentContracts.get(node.name.value);
if (contract && generated.byName.get(parent.name)?.revisionId !== contract.root) if (contract && generated.byName.get(parent.name)?.revisionId !== contract.root)
fail("FRAGMENT_ROOT_MISMATCH", "Imported fragment requires its exact nominal root interface", node); fail("FRAGMENT_ROOT_MISMATCH", "Imported fragment requires its exact nominal root interface", node);
const directive = node.directives?.find((directive) => directive.name.value === "boundary");
if (directive) {
const name = directive.arguments?.find((argument) => argument.name.value === "name")?.value;
if (name?.kind !== "StringValue" || !/^[A-Za-z_][A-Za-z0-9_]{0,63}$/.test(name.value))
return fail(
"QUERY_BOUNDARY_NAME",
"A boundary needs a literal identifier of at most 64 characters",
directive,
);
const root = generated.byName.get(parent.name)?.revisionId;
if (!root || root === workspaceQueryRootId)
return fail("QUERY_BOUNDARY_ROOT", "A boundary must select a nominal Graph Object", node);
if (contract?.mode === "reference")
fail("QUERY_BOUNDARY_REFERENCE", "Use an ordinary checked Fragment spread for a boundary", node);
const fragment = fragments.get(node.name.value)!;
const token = node.loc?.startToken;
return [
{
name: "$boundary",
key: "",
arguments: {},
conditions: inheritedConditions,
boundary: {
name: name.value,
root,
output: required(parent, fragment.selectionSet),
...(token ? { location: { file: node.loc!.source.name, line: token.line, column: token.column } } : {}),
},
selection: [
...(contract
? [
{
name: "$fragment",
key: "",
selection: [],
arguments: {},
conditions: [],
fragmentSpread: contract,
},
]
: []),
...selection(fragment.selectionSet, parent),
],
},
];
}
return [ return [
...(contract ...(contract
? [ ? [
@@ -598,6 +646,13 @@ export async function compileQuery(
]; ];
}); });
const contract = generated.byName.get(parent.name); const contract = generated.byName.get(parent.name);
const names = new Set<string>();
for (const field of selections)
if (field.boundary) {
if (names.has(field.boundary.name))
fail("QUERY_BOUNDARY_DUPLICATE", `Duplicate boundary ${field.boundary.name}`);
names.add(field.boundary.name);
}
if (!contract || contract.revisionId === workspaceQueryRootId) return selections; if (!contract || contract.revisionId === workspaceQueryRootId) return selections;
// Fragment expansion may repeat metadata. Combine its children so a later // Fragment expansion may repeat metadata. Combine its children so a later
// implicit reference cannot overwrite an explicitly selected aggregate. // implicit reference cannot overwrite an explicitly selected aggregate.
@@ -632,10 +687,11 @@ export async function compileQuery(
const normalized = print(document), const normalized = print(document),
schema = printSchema(generated.schema); schema = printSchema(generated.schema);
const selections = selection(operations[0]!.selectionSet, generated.schema.getQueryType()!); const selections = selection(operations[0]!.selectionSet, generated.schema.getQueryType()!);
const tree = lowerQueryTree(declaration, selections, result);
const definitionDigest = createHash("sha256") const definitionDigest = createHash("sha256")
.update( .update(
canonicalJson({ canonicalJson({
semantics: 6, semantics: tree ? 7 : 6,
declaration, declaration,
normalized, normalized,
fragmentContracts: Object.fromEntries(fragmentContracts), fragmentContracts: Object.fromEntries(fragmentContracts),
@@ -667,7 +723,8 @@ export async function compileQuery(
variables: { kind: "record", fields: variables }, variables: { kind: "record", fields: variables },
output: result, output: result,
effects: [...effects.values()], effects: [...effects.values()],
selection: selections, selection: tree ? stripQueryBoundaries(selections) : selections,
...(tree ? { tree } : {}),
variableDefaults: Object.fromEntries( variableDefaults: Object.fromEntries(
(operations[0]!.variableDefinitions ?? []) (operations[0]!.variableDefinitions ?? [])
.filter((entry) => entry.defaultValue) .filter((entry) => entry.defaultValue)
+10 -1
View File
@@ -11,6 +11,8 @@ import {
GraphQLList, GraphQLList,
GraphQLNonNull, GraphQLNonNull,
GraphQLSchema, GraphQLSchema,
GraphQLDirective,
DirectiveLocation,
specifiedDirectives, specifiedDirectives,
visit, visit,
type GraphQLOutputType, type GraphQLOutputType,
@@ -294,7 +296,14 @@ export function querySchema(
return result; return result;
}; };
const schema = new GraphQLSchema({ const schema = new GraphQLSchema({
directives: specifiedDirectives, directives: [
...specifiedDirectives,
new GraphQLDirective({
name: "boundary",
locations: [DirectiveLocation.FRAGMENT_SPREAD],
args: { name: { type: new GraphQLNonNull(GraphQLString) } },
}),
],
// Nominal projections can mention an interface not reached by a relation. // Nominal projections can mention an interface not reached by a relation.
types: (() => { types: (() => {
const requested = new Set<string>(); const requested = new Set<string>();
+260
View File
@@ -0,0 +1,260 @@
import { valueType, type InterfaceRevisionId, type ValueType } from "../capability-model/types.js";
import {
QueryCompileError,
type QueryDeclaration,
type QuerySelection,
type QueryTreePlan,
type QueryTreeNode,
} from "./types.js";
import type { CheckedQuery } from "./types.js";
import { createHash } from "node:crypto";
import { canonicalJson } from "../capability-model/evolution.js";
export const stripQueryBoundaries = (fields: readonly QuerySelection[]): QuerySelection[] =>
fields
.filter((field) => !field.boundary)
.map((field) => ({ ...field, selection: stripQueryBoundaries(field.selection) }));
const containsBoundary = (fields: readonly QuerySelection[]): boolean =>
fields.some((field) => !!field.boundary || containsBoundary(field.selection));
/** GraphQL repeated paths form one projection. Equivalent checked selections
* reuse their binding; differing windows/guards never silently share it. */
function mergeTreeFields(fields: readonly QuerySelection[]): QuerySelection[] {
const result: QuerySelection[] = [];
for (const input of fields) {
const field = { ...input, selection: mergeTreeFields(input.selection) };
const previous = result.find(
(candidate) =>
!candidate.boundary &&
!field.boundary &&
!candidate.fragmentSpread &&
!field.fragmentSpread &&
candidate.key === field.key,
);
if (!previous) {
result.push(field);
continue;
}
const { selection: _left, ...left } = previous;
const { selection: _right, ...right } = field;
if (canonicalJson(left) !== canonicalJson(right)) {
if (containsBoundary(previous.selection) || containsBoundary(field.selection))
throw new QueryCompileError(
"QUERY_TREE_BINDING_CONFLICT",
`Alias differently guarded or parameterized paths selected as ${field.key}`,
);
result.push(field);
continue;
}
previous.selection = mergeTreeFields([...previous.selection, ...field.selection]);
}
const names = new Set<string>();
for (const field of result)
if (field.boundary) {
if (names.has(field.boundary.name))
throw new QueryCompileError("QUERY_BOUNDARY_DUPLICATE", `Duplicate boundary ${field.boundary.name}`);
names.add(field.boundary.name);
}
return result;
}
const required = (type: ValueType): ValueType =>
type.kind === "optional" || type.kind === "list" ? required(type.value) : type;
const fieldType = (type: ValueType, key: string): ValueType => {
const shape = required(type);
if (shape.kind !== "record" || !shape.fields[key])
throw new QueryCompileError("QUERY_TREE_SHAPE", `Missing checked field ${key}`);
return shape.fields[key];
};
const objectInterface = (fields: readonly QuerySelection[]): InterfaceRevisionId | undefined =>
fields
.find((field) => field.name === "_camino" && field.key === "_camino")
?.selection.find((field) => field.name === "ref")?.targetInterfaceRevisionId;
const identity = (fields: readonly QuerySelection[]): QuerySelection[] =>
fields
.filter((field) => field.name === "_camino" && field.key === "_camino")
.map((field) => ({ ...field, conditions: [], selection: field.selection.filter((child) => child.name === "ref") }));
function projectionType(type: ValueType, fields: readonly QuerySelection[]): ValueType {
if (type.kind === "optional") return valueType.optional(projectionType(type.value, fields));
if (type.kind === "list") return valueType.list(projectionType(type.value, fields));
if (type.kind !== "record") return type;
return {
kind: "record",
fields: Object.fromEntries(
fields
.filter((field) => !field.fragmentSpread)
.map((field) => {
const source = type.fields[field.key] ?? (field.key === "key" ? valueType.string : undefined);
if (!source) throw new QueryCompileError("QUERY_TREE_SHAPE", `Missing checked projection ${field.key}`);
return [field.key, projectionType(source, field.selection)];
}),
),
};
}
const keyField = (): QuerySelection => ({ name: "key", key: "key", conditions: [], arguments: {}, selection: [] });
/** Lower into complete projections and minimal binding projections. No runtime
* component inspection, executable client source, or graph handle value is involved.
* Each projection is rooted at its own nominal subject; lists retain entry keys.
*/
export function lowerQueryTree(
declaration: QueryDeclaration,
selection: QuerySelection[],
output: ValueType,
): QueryTreePlan | undefined {
if (!containsBoundary(selection)) return;
selection = mergeTreeFields(selection);
if (declaration.placement?.kind !== "replica" || declaration.fragment)
throw new QueryCompileError(
"QUERY_TREE_PLACEMENT",
"Declare a Query Tree as a replica query; its checked projections supply local views",
);
const root = selection.find((field) => field.name === "root" && field.key === "root");
if (!root || selection.some((field) => field !== root))
throw new QueryCompileError("QUERY_TREE_ROOT", "A Query Tree requires one unaliased root selection");
const plan: QueryTreePlan = { root: "root", nodes: [], projections: [], maxOccurrences: 0 };
const project = (id: string, subject: InterfaceRevisionId, fields: QuerySelection[], shape: ValueType) => {
if (plan.projections.length >= 256)
throw new QueryCompileError("QUERY_TREE_LIMIT", "Query Tree exceeds 256 projections");
plan.projections.push({
id,
root: id === "root/value" ? declaration.root : { kind: "object", interface: subject },
selection: [{ name: "root", key: "root", arguments: {}, conditions: [], selection: fields }],
output: { kind: "record", fields: { root: shape } },
});
return id;
};
const node = (
id: string,
subject: InterfaceRevisionId,
fields: QuerySelection[],
shape: ValueType,
occurrences: number,
): string => {
plan.maxOccurrences += occurrences;
if (!Number.isSafeInteger(plan.maxOccurrences) || plan.maxOccurrences > 256)
throw new QueryCompileError("QUERY_TREE_LIMIT", "Query Tree exceeds 256 bounded node occurrences");
const current: QueryTreeNode = {
id,
projection: project(id + "/value", subject, stripQueryBoundaries(fields), shape),
boundaries: [],
bindings: [],
};
plan.nodes.push(current);
for (const field of fields)
if (field.boundary) {
const child = field.boundary;
current.boundaries.push({
name: child.name,
conditions: field.conditions,
node: node(id + "/boundary/" + child.name, child.root, field.selection, child.output, occurrences),
});
}
for (const field of fields) {
if (field.boundary || !containsBoundary(field.selection)) continue;
const targets: { path: string[]; node: string }[] = [];
const prune = (fields: QuerySelection[], shape: ValueType, path: string[], bound: number): QuerySelection[] => {
if (shape.kind === "optional") return prune(fields, shape.value, path, bound);
if (shape.kind === "list") return prune(fields, shape.value, [...path, "[]"], bound * declaration.budgets.rows);
const target = objectInterface(fields);
if (target) {
targets.push({
path,
node: node(id + "/binding/" + path.map(encodeURIComponent).join("/"), target, fields, shape, bound),
});
return identity(fields);
}
const minimal = fields
.filter((field) => containsBoundary(field.selection))
.map((field) => ({
...field,
selection: prune(field.selection, fieldType(shape, field.key), [...path, field.key], bound),
}));
// Relationship occurrence identity is its entry key, including duplicate
// target Objects. Never substitute list position or Object identity.
if (minimal.some((field) => field.name === "node") && !minimal.some((field) => field.name === "key"))
minimal.unshift(fields.find((field) => field.name === "key" && field.key === "key") ?? keyField());
return minimal;
};
const type = fieldType(shape, field.key);
const minimal = { ...field, selection: prune(field.selection, type, [field.key], occurrences) };
const selected = [...identity(fields), minimal];
current.bindings.push({
name: field.key,
targets,
projection: project(
id + "/bindings/" + encodeURIComponent(field.key),
subject,
selected,
projectionType(shape, selected),
),
});
}
return id;
};
node("root", declaration.root.interface, root.selection, fieldType(output, "root"), 1);
return plan;
}
export const treeProjectionQuery = (tree: string, projection: string, role: "replica" | "local") =>
`${tree}/@tree/${projection}/${role}`;
/** Checked synthetic queries remain ordinary nominal queries for linking,
* authority, native input acquisition and execution. Public trees own the plan;
* applications do not copy these projections into their source declarations. */
export function queryTreeProjections(query: CheckedQuery): CheckedQuery[] {
if (!query.tree) return [];
const { tree: _tree, ...base } = query;
return query.tree.projections.flatMap((projection) => {
const selected = new Set<string>();
const walk = (fields: readonly QuerySelection[]) => {
for (const field of fields) {
if (field.interfaceRevisionId && field.memberId)
selected.add(JSON.stringify([field.interfaceRevisionId, field.memberId]));
walk(field.selection);
}
};
walk(projection.selection);
const effects = query.effects.filter(
(effect) =>
selected.has(JSON.stringify([effect.interfaceRevisionId, effect.memberId])) ||
effect.uses.some((use) => use !== "select"),
);
if (effects.some((effect) => effect.execution === "rpc-permitted"))
throw new QueryCompileError(
"QUERY_TREE_LOCAL_DEPENDENCY",
"A replica Query Tree requires locally executable snapshot projections",
);
return (["replica", "local"] as const).map((role): CheckedQuery => {
const id = treeProjectionQuery(query.declaration.id, projection.id, role);
const declaration: QueryDeclaration = {
...query.declaration,
id,
displayName: id,
root: projection.root,
placement:
role === "replica"
? { kind: "replica" }
: { kind: "local", sourceQueryId: treeProjectionQuery(query.declaration.id, projection.id, "replica") },
};
return {
...base,
declaration,
effects,
selection: projection.selection,
output: projection.output,
treeProjection: { tree: query.declaration.id, projection: projection.id, role },
definitionDigest: createHash("sha256")
.update(
canonicalJson({
parent: query.definitionDigest,
declaration,
selection: projection.selection,
output: projection.output,
}),
)
.digest("hex"),
};
});
});
}
+33
View File
@@ -94,6 +94,9 @@ export class QueryCompileError extends Error {
} }
} }
export interface CheckedQuery { export interface CheckedQuery {
/** Checked decomposition; handles belong to a Client Session, never graph values. */
tree?: QueryTreePlan;
treeProjection?: { tree: string; projection: string; role: "replica" | "local" };
fragmentContracts?: Record<string, NonNullable<QuerySelection["fragmentSpread"]>>; fragmentContracts?: Record<string, NonNullable<QuerySelection["fragmentSpread"]>>;
declaration: QueryDeclaration; declaration: QueryDeclaration;
definitionDigest: string; definitionDigest: string;
@@ -115,6 +118,12 @@ export type QueryArgument =
| { kind: "list"; values: QueryArgument[] } | { kind: "list"; values: QueryArgument[] }
| { kind: "object"; fields: Record<string, QueryArgument> }; | { kind: "object"; fields: Record<string, QueryArgument> };
export interface QuerySelection { export interface QuerySelection {
boundary?: {
name: string;
root: InterfaceRevisionId;
output: ValueType;
location?: QuerySourceLocation;
};
/** A checked occurrence marker, not an output field or storage capability. */ /** A checked occurrence marker, not an output field or storage capability. */
fragmentSpread?: { fragmentSpread?: {
mode?: "reference"; mode?: "reference";
@@ -135,3 +144,27 @@ export interface QuerySelection {
relational?: import("./relational.js").QueryRelationalPlan; relational?: import("./relational.js").QueryRelationalPlan;
predicate?: import("./relational.js").QueryPredicate; predicate?: import("./relational.js").QueryPredicate;
} }
export interface QueryTreeProjection {
id: string;
root: QueryRoot;
selection: QuerySelection[];
output: ValueType;
}
export interface QueryTreeNode {
id: string;
projection: string;
boundaries: { name: string; conditions: QuerySelection["conditions"]; node: string }[];
bindings: {
name: string;
projection: string;
/** [] denotes an occurrence in a bounded list; its entry key owns identity. */
targets: { path: string[]; node: string }[];
}[];
}
export interface QueryTreePlan {
root: string;
nodes: QueryTreeNode[];
projections: QueryTreeProjection[];
maxOccurrences: number;
}
+27 -2
View File
@@ -20,6 +20,9 @@ export interface ReactModulePreparation {
/** Public input type before workspace query lowering adds private projections. */ /** Public input type before workspace query lowering adds private projections. */
input?: ValueType; input?: ValueType;
children: ReactChildDeclaration[]; children: ReactChildDeclaration[];
/** Binds roots/arguments only. The ordinary checked Query Tree owns every
* acquisition path; the React declaration does not repeat its descendants. */
trees?: Pick<QueryCompositionStep, "name" | "query" | "root" | "arguments">[];
} }
export interface ReactPreparationArtifact { export interface ReactPreparationArtifact {
/** Frontend queries belong to installed preparation, not the authored client API. */ /** Frontend queries belong to installed preparation, not the authored client API. */
@@ -51,7 +54,7 @@ export function presentationDeclarations(
}; };
for (const [name, value] of Object.entries(modules)) { for (const [name, value] of Object.entries(modules)) {
const declaration = object(value, `module ${name}`); const declaration = object(value, `module ${name}`);
if (Object.keys(declaration).some((key) => !["inputs", "children"].includes(key))) if (Object.keys(declaration).some((key) => !["inputs", "children", "trees"].includes(key)))
throw Error(`${name}: unknown preparation field`); throw Error(`${name}: unknown preparation field`);
const module = pkg.modules?.find((entry) => entry.displayName === name); const module = pkg.modules?.find((entry) => entry.displayName === name);
if (!module) throw Error(`React declaration: unknown module ${name}`); if (!module) throw Error(`React declaration: unknown module ${name}`);
@@ -129,7 +132,29 @@ export function presentationDeclarations(
...(role ? { role } : {}), ...(role ? { role } : {}),
}; };
}); });
artifact.modules.push({ module: module.id, composition, children: parsed }); const trees = declaration.trees ?? [];
if (!Array.isArray(trees) || trees.length > 16) throw Error(`${name}: trees must be a bounded array`);
const treeNames = new Set<string>();
const preparedTrees = trees.map((value) => {
const tree = object(value, `${name} tree`) as unknown as NonNullable<ReactModulePreparation["trees"]>[number];
if (
Object.keys(tree).some((key) => !["name", "query", "root", "arguments"].includes(key)) ||
!/^[A-Za-z_][A-Za-z0-9_]*$/.test(tree.name) ||
treeNames.has(tree.name)
)
throw Error(`${name}: tree requires a unique name and checked root/arguments`);
treeNames.add(tree.name);
const query = pkg.queries?.find((entry) => entry.displayName === tree.query);
if (!query || query.placement?.kind !== "replica")
throw Error(`${name}.${tree.name}: requires a replica Query Tree`);
return { ...tree, query: query.id };
});
artifact.modules.push({
module: module.id,
composition,
children: parsed,
...(preparedTrees.length ? { trees: preparedTrees } : {}),
});
} }
for (const module of pkg.modules ?? []) { for (const module of pkg.modules ?? []) {
const contract = interfaces.find((entry) => entry.revisionId === module.interfaceRevisionId); const contract = interfaces.find((entry) => entry.revisionId === module.interfaceRevisionId);
+12 -1
View File
@@ -1,7 +1,7 @@
import type { WorkspaceRevision, ValueType } from "../capability-model/types.js"; import type { WorkspaceRevision, ValueType } from "../capability-model/types.js";
import { moduleContract } from "../capability-model/modules.js"; import { moduleContract } from "../capability-model/modules.js";
import { canonicalJson } from "../capability-model/evolution.js"; import { canonicalJson } from "../capability-model/evolution.js";
import { queryBindingType } from "../query/composition.js"; import { queryBindingType, compileQueryComposition } from "../query/composition.js";
import { moduleTypeContext } from "../execution-world/module-contracts.js"; import { moduleTypeContext } from "../execution-world/module-contracts.js";
import { preparationArtifact, type ReactPreparationArtifact } from "./declarations.js"; import { preparationArtifact, type ReactPreparationArtifact } from "./declarations.js";
import { expandPresentationQueries } from "./expansion.js"; import { expandPresentationQueries } from "./expansion.js";
@@ -25,6 +25,17 @@ export async function completeWorkspace(workspace: WorkspaceRevision): Promise<v
if (!composition || composition.output.kind !== "record") if (!composition || composition.output.kind !== "record")
throw Error(`Missing checked inputs for ${parent.module.displayName}`); throw Error(`Missing checked inputs for ${parent.module.displayName}`);
parent.preparation.input = structuredClone(composition.output); parent.preparation.input = structuredClone(composition.output);
const treeQueries = new Map((parent.pkg.checkedQueries ?? []).map((query) => [query.declaration.id, query]));
for (const tree of parent.preparation.trees ?? []) {
if (!treeQueries.get(tree.query)?.tree)
throw Error(`${parent.module.displayName}.${tree.name}: expected a checked Query Tree`);
// Reuse Camino's ordinary nominal/argument binder. Only input parameters
// are available; a tree cannot wait on a whole presentation result.
compileQueryComposition(
{ id: `react:tree:${parent.module.id}:${tree.name}`, input: composition.input, steps: [tree], maxQueries: 1 },
treeQueries,
);
}
const outputs = new Map(Object.entries(composition.output.fields)); const outputs = new Map(Object.entries(composition.output.fields));
const dependencies: string[] = []; const dependencies: string[] = [];
const children = parent.preparation.children.map((child) => { const children = parent.preparation.children.map((child) => {
+160
View File
@@ -0,0 +1,160 @@
import test from "node:test";
import assert from "node:assert/strict";
import { mkdtemp, writeFile, symlink, rm } from "node:fs/promises";
import { join } from "node:path";
import { tmpdir } from "node:os";
import { CandidateMetadataBudget, readCandidateMetadata } from "../src/execution-world/metadata.js";
import { loadCheckedInstallationCandidate } from "../src/execution-world/candidate.js";
test(
"a real checked application can stage its replacement within the default metadata budget",
{
skip: !process.env.QX_CHECKED_CANDIDATE,
},
async () => {
const root = process.env.QX_CHECKED_CANDIDATE!;
const budget = new CandidateMetadataBudget();
const first = await loadCheckedInstallationCandidate(root, {}, { budget, owner: "reader" });
try {
const retained = budget.snapshot().bytes;
const second = await loadCheckedInstallationCandidate(root, {}, { budget, owner: "reader" });
try {
assert.equal(budget.snapshot().bytes, retained * 2);
assert.deepEqual(second.reference, first.reference, "Compaction preserves exact checked identity");
assert.equal(second.graphExecution.kernel, second.kernel, "Graph representation shares the validated program");
assert.equal(second.graphExecution.queries, second.queries);
// A deliberately tighter pool admits the serving installation but must
// reject replacement parsing without leaking a candidate or tree lease.
const tight = new CandidateMetadataBudget({
bytes: retained + 1,
ownerBytes: retained + 1,
candidates: 2,
});
const blocker = tight.acquire("reader");
blocker.charge(retained);
try {
await assert.rejects(
loadCheckedInstallationCandidate(root, {}, { budget: tight, owner: "reader" }),
/CANDIDATE_METADATA_LIMIT/,
);
assert.equal(tight.snapshot().bytes, retained);
assert.equal(tight.snapshot().candidates, 1);
} finally {
blocker.release();
}
const other = budget.acquire("other");
try {
assert.throws(() => other.charge(budget.limits.bytes), /CANDIDATE_METADATA_LIMIT/);
assert.equal(budget.snapshot().bytes, retained * 2, "Rejected admission must not leak charges");
} finally {
other.release();
}
} finally {
second.metadata.release();
}
assert.equal(budget.snapshot().bytes, retained, "The serving candidate survives failed or completed staging");
} finally {
first.metadata.release();
}
assert.equal(budget.snapshot().bytes, 0);
assert.equal(budget.snapshot().candidates, 0);
},
);
test("concurrent candidate reservations enforce aggregate and owner limits and release exactly once", () => {
const budget = new CandidateMetadataBudget({ bytes: 1000, ownerBytes: 600, candidates: 3 });
const first = budget.acquire("a"),
second = budget.acquire("a"),
third = budget.acquire("b");
assert.throws(() => budget.acquire("c"), /CANDIDATE_METADATA_LIMIT/);
first.charge(400);
second.charge(200);
third.charge(400);
assert.throws(() => second.charge(1), /CANDIDATE_METADATA_LIMIT/);
assert.throws(() => third.charge(1), /CANDIDATE_METADATA_LIMIT/);
assert.equal(budget.snapshot().bytes, 1000);
second.release();
second.release();
assert.equal(budget.snapshot().bytes, 800);
assert.throws(() => second.charge(1), /CANDIDATE_METADATA_CLOSED/);
first.release();
third.release();
assert.deepEqual(budget.snapshot(), { bytes: 0, candidates: 0, owners: 0, limits: budget.limits });
});
test("metadata files reserve parse/index space before allocation and refuse oversized or linked inputs", async () => {
const root = await mkdtemp(join(tmpdir(), "qx-metadata-budget-"));
const budget = new CandidateMetadataBudget({ bytes: 450, ownerBytes: 450, candidates: 2 });
const scope = budget.acquire("workspace");
try {
const file = join(root, "metadata.json");
await writeFile(file, '{"ok":true}');
const input = await readCandidateMetadata(file, scope, 100);
assert.equal(new TextDecoder().decode(input.bytes), '{"ok":true}');
const withInput = scope.bytes;
input.releaseInput();
input.releaseInput();
const first = scope.bytes;
assert.equal(withInput - first, (Buffer.byteLength('{"ok":true}') + 1) * 3);
assert.ok(first > 12 * 3, "Decoded tree and derived metadata are reserved before parsing");
await assert.rejects(readCandidateMetadata(file, scope, 100), /CANDIDATE_METADATA_LIMIT/);
assert.equal(scope.bytes, first, "Rejected tree allocation releases its transient input buffer");
await assert.rejects(readCandidateMetadata(file, scope, 5), /CANDIDATE_METADATA_FILE_LIMIT/);
await symlink(file, join(root, "linked"));
await assert.rejects(readCandidateMetadata(join(root, "linked"), scope, 100), { code: "ELOOP" });
await assert.rejects(readCandidateMetadata(root, scope, 100), /CANDIDATE_METADATA_FILE_LIMIT/);
assert.equal(scope.bytes, first);
input.releaseTree();
input.releaseTree();
assert.equal(scope.bytes, 0, "Discarded validation trees can release independently of the candidate");
} finally {
scope.release();
await rm(root, { recursive: true, force: true });
}
assert.equal(budget.snapshot().bytes, 0);
});
test("JSON structure accounting is independent of indentation and covers strings, values and dense nodes", async () => {
const root = await mkdtemp(join(tmpdir(), "qx-metadata-shape-"));
const budget = new CandidateMetadataBudget();
try {
for (const value of [{}, [null, true, false, 1, -3.5e8], { 'a"b': '雪\\"', nodes: [{}, {}, {}] }]) {
const measured = [];
for (const spaces of [0, 4]) {
const file = join(root, "metadata.json"),
text = JSON.stringify(value, null, spaces);
await writeFile(file, text);
const scope = budget.acquire("test");
try {
const input = await readCandidateMetadata(file, scope, 10000);
assert.deepEqual(JSON.parse(new TextDecoder().decode(input.bytes)), value);
input.releaseInput();
measured.push(scope.bytes);
} finally {
scope.release();
}
}
assert.equal(measured[0], measured[1], "Whitespace changes input storage, not the allocated JSON shape");
assert.ok(measured[0] >= 128);
}
} finally {
await rm(root, { recursive: true, force: true });
}
assert.equal(budget.snapshot().bytes, 0);
});
test("transient leases release exactly once, including after their parent closes", () => {
const budget = new CandidateMetadataBudget({ bytes: 1000, ownerBytes: 600, candidates: 3 });
const scope = budget.acquire("a");
scope.charge(200);
const release = scope.reserve(300);
assert.throws(() => scope.reserve(101), /CANDIDATE_METADATA_LIMIT/);
release();
release();
assert.equal(scope.bytes, 200);
const afterClose = scope.reserve(100);
scope.release();
afterClose();
assert.equal(scope.bytes, 0);
assert.equal(budget.snapshot().bytes, 0);
});
+57
View File
@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
import { test } from "node:test"; import { test } from "node:test";
import { import {
compileWorkspaceRevision, compileWorkspaceRevision,
capabilityId,
computeCapabilityClosure, computeCapabilityClosure,
resolveOperationPlan, resolveOperationPlan,
validateWorkspaceRevision, validateWorkspaceRevision,
@@ -197,6 +198,62 @@ test("public traversal permits a native inverse read without exporting mutation
expectIssue(workspace, "private-attachment-access"); expectIssue(workspace, "private-attachment-access");
}); });
test("public traversal exports only the selected read-only package edge port", () => {
const workspace = makeValidCapabilityWorkspace();
const exportDefinition = workspace.packageImports
.flatMap((pkg) => pkg.exports)
.find((entry) => entry.id === fixtureId.summaryGetExport)!;
const port = {
id: capabilityId.dependencyPort("port:summary:owner"),
displayName: "owner",
requirement: {
kind: "edge" as const,
target: { kind: "interface" as const, interfaceRevisionId: fixtureId.namedV1 },
cardinality: "exactly-one" as const,
primitives: ["resolve" as const],
},
};
exportDefinition.dependencyPorts.push(port);
const binding = conformance(workspace, fixtureId.projectSummaryConformance).operationBindings[0].binding;
assert.ok(binding.kind === "package");
binding.dependencies.push({
portId: port.id,
binding: {
kind: "edge",
edgeTypeId: fixtureId.projectOwner,
projectionId: fixtureId.projectOwnerProjection,
},
});
const edge = conformance(workspace, fixtureId.projectOwnedConformance).privateAttachments.find(
(entry) => entry.id === fixtureId.projectOwner,
);
assert.ok(edge?.kind === "edge");
const endpoint = edge.endpoints.find((entry) => entry.projectionId === fixtureId.projectOwnerProjection)!;
expectIssue(workspace, "private-attachment-access");
// Publicity of the opposite projection does not grant this receiver access.
edge.endpoints.find((entry) => entry !== endpoint)!.publicTraversal = true;
expectIssue(workspace, "private-attachment-access");
endpoint.publicTraversal = true;
assert.deepEqual(validateWorkspaceRevision(workspace), []);
const compiled = compileWorkspaceRevision(workspace);
assert.ok(compiled.ok);
const plan = resolveOperationPlan(compiled.plan, fixtureId.project, fixtureId.summaryV1, fixtureId.summaryGet);
assert.ok(plan?.kind === "package");
assert.deepEqual(plan.dependencies.find((entry) => entry.port.id === port.id)?.port.requirement, port.requirement);
for (const primitive of ["connect", "disconnect", "watch-start", "watch-stop"] as const) {
const mutated = structuredClone(workspace);
const requirement = mutated.packageImports
.flatMap((pkg) => pkg.exports)
.find((entry) => entry.id === fixtureId.summaryGetExport)!
.dependencyPorts.find((entry) => entry.id === port.id)!.requirement;
assert.ok(requirement.kind === "edge");
requirement.primitives.push(primitive);
expectIssue(mutated, "private-attachment-access");
}
});
test("native state and edge providers must match operation shape", () => { test("native state and edge providers must match operation shape", () => {
const stateWorkspace = makeValidCapabilityWorkspace(); const stateWorkspace = makeValidCapabilityWorkspace();
const state = conformance(stateWorkspace, fixtureId.projectNamedConformance).operationBindings[0]!.binding; const state = conformance(stateWorkspace, fixtureId.projectNamedConformance).operationBindings[0]!.binding;
+11
View File
@@ -3,6 +3,8 @@ import { readFile, mkdir, writeFile } from "node:fs/promises";
import { compileCapabilityResourceSource, compileCapabilitySource } from "../src/capability-language/index.js"; import { compileCapabilityResourceSource, compileCapabilitySource } from "../src/capability-language/index.js";
import { compileQuery } from "../src/query/compile.js"; import { compileQuery } from "../src/query/compile.js";
import { parseControllerCatalog } from "../src/capability-model/controllers.js"; import { parseControllerCatalog } from "../src/capability-model/controllers.js";
import { presentationDeclarations, preparationArtifact } from "../src/react-build/declarations.js";
import { compileQueryComposition } from "../src/query/composition.js";
import { import {
compileExecutionPlan, compileExecutionPlan,
generateInterfaceClientBindings, generateInterfaceClientBindings,
@@ -59,6 +61,15 @@ const viewerPackage = viewer.resource.revision;
viewerPackage.checkedQueries = await Promise.all( viewerPackage.checkedQueries = await Promise.all(
viewerPackage.queries!.map((query) => compileQuery(query, [iface], read)), viewerPackage.queries!.map((query) => compileQuery(query, [iface], read)),
); );
const preparation = presentationDeclarations(
await read("quixos.react.json"),
viewerPackage,
environment.interfaceClosure,
);
viewerPackage.buildArtifacts = { [preparationArtifact]: preparation.artifact };
viewerPackage.queryCompositions = preparation.compositions.map((entry) =>
compileQueryComposition(entry, new Map(viewerPackage.checkedQueries!.map((query) => [query.declaration.id, query]))),
);
for (const variant of ["controller", "controller-next"]) { for (const variant of ["controller", "controller-next"]) {
const extra = variant.endsWith("next") const extra = variant.endsWith("next")
? 'atom Dashboard id "dashboard"; import package DeviceViewer; presentation DeviceStatus id "device:status" for Device using DeviceViewer.Status;' ? 'atom Dashboard id "dashboard"; import package DeviceViewer; presentation DeviceStatus id "device:status" for Device using DeviceViewer.Status;'
+8
View File
@@ -179,3 +179,11 @@ await writeFile(
"dist/portable-reader/variants/entries.ts", "dist/portable-reader/variants/entries.ts",
"export type Entries = " + tsType(entries.valueType) + ";\n", "export type Entries = " + tsType(entries.valueType) + ";\n",
); );
const { queryTreeFixture } = await import("./query-tree-fixture.js");
const { generatePackageQueryClientBindings } = await import("../src/execution-world/client-contracts.js");
const treeFixture = await queryTreeFixture();
await mkdir("dist/portable-reader/query-tree", { recursive: true });
await writeFile("dist/portable-reader/query-tree/queries.ts", generatePackageQueryClientBindings(treeFixture.pkg));
await writeFile("dist/portable-reader/query-tree/queries.json", JSON.stringify(compileQueryProgram(treeFixture.plan)));
await writeFile("dist/portable-reader/query-tree/kernel.json", JSON.stringify(compileKernelProgram(treeFixture.plan)));
+14
View File
@@ -0,0 +1,14 @@
{
"modules": {
"Status": {
"inputs": [
{
"name": "view",
"query": "View",
"root": { "from": "input", "path": ["subject"] },
"arguments": { "record": {} }
}
]
}
}
}
+10 -2
View File
@@ -8,10 +8,18 @@ export const queryFixtureSource = {
repository: "https://query-fixture.example.test/source.git", repository: "https://query-fixture.example.test/source.git",
commit: "1".repeat(40), commit: "1".repeat(40),
}; };
export async function queryWorkspaceFixture(options: { live?: boolean } = {}) { export async function queryWorkspaceFixture(options: { live?: boolean; snapshot?: boolean } = {}) {
const interfaces = new Map<string, InterfaceRevision>(); const interfaces = new Map<string, InterfaceRevision>();
const sources: Record<string, string> = {}; const sources: Record<string, string> = {};
function iface(name: string, members: string, parameters = "") { function iface(name: string, members: string, parameters = "") {
if (options.snapshot) members = members.replaceAll(" ordered", "");
if (options.snapshot)
for (const member of ["name", "title", "done", "rank", "assignee", "items"])
for (const operation of ["get", "resolve"])
members = members.replace(
`${operation} id "${member}:${operation}";`,
`${operation} id "${member}:${operation}" execution snapshot;`,
);
const text = `${[...interfaces.keys()].map((name) => `import interface ${name};`).join("\n")} const text = `${[...interfaces.keys()].map((name) => `import interface ${name};`).join("\n")}
interface ${name}${parameters} id "${name}" revision "${name}@1" {${members}}`; interface ${name}${parameters} id "${name}" revision "${name}@1" {${members}}`;
sources[name] = text; sources[name] = text;
@@ -117,7 +125,7 @@ export async function queryWorkspaceFixture(options: { live?: boolean } = {}) {
${implementation("Task")} ${implementation("Reminder")} ${implementation("Task")} ${implementation("Reminder")}
conform Tasks as Collection<interface TaskFacts> id "tasks-collection" { conform Tasks as Collection<interface TaskFacts> id "tasks-collection" {
private edge Items id "items" { private edge Items id "items" {
atom Tasks projection items id "items:forward" many ordered; atom Tasks projection items id "items:forward" many${options.snapshot ? "" : " ordered"};
interface TaskFacts projection collections id "items:inverse" many; interface TaskFacts projection collections id "items:inverse" many;
} }
bind items.resolve to edge Items.items.resolve; bind items.resolve to edge Items.items.resolve;
+97 -1
View File
@@ -5,9 +5,90 @@ import os from "node:os";
import path from "node:path"; import path from "node:path";
import { promisify } from "node:util"; import { promisify } from "node:util";
import { execFile as callback } from "node:child_process"; import { execFile as callback } from "node:child_process";
import { planPinUpgrades, applyPinUpgrades, type UpgradeEffects } from "../src/capability-language/pin-upgrades.js"; import {
planPinUpgrades,
applyPinUpgrades,
discoverUpgradeSpec,
reviewUpgradeCandidate,
type UpgradeEffects,
} from "../src/capability-language/pin-upgrades.js";
import { capabilityId } from "../src/capability-model/index.js";
import { makeValidCapabilityWorkspace } from "./fixtures/capability-model.js";
const execFile = promisify(callback); const execFile = promisify(callback);
test("execution pin upgrades accept unchanged shared attachments without legacy migration planning", async (context) => {
const artifact = await fs.mkdtemp(path.join(os.tmpdir(), "qx-upgrade-execution-review-"));
context.after(() => fs.rm(artifact, { recursive: true, force: true }));
await fs.writeFile(path.join(artifact, "execution-plan.json"), "{}");
const baseline = makeValidCapabilityWorkspace();
assert.ok(baseline.sharedAttachments.length);
const candidate = structuredClone(baseline);
candidate.sourceRootCommit = "f".repeat(40);
const { filename, review } = await reviewUpgradeCandidate({ artifact, baseline, candidate });
assert.equal(filename, "semantic-review.json");
assert.equal(review.checkerVersion, "quixos-semantic-review-v1");
assert.deepEqual(review.blockers, []);
assert.equal("migrationRequired" in review, false);
assert.equal("runtimeActions" in review, false);
});
test("execution pin upgrades require exact semantic-major receipts and reject foreign workspaces", async (context) => {
const artifact = await fs.mkdtemp(path.join(os.tmpdir(), "qx-upgrade-semantic-review-"));
context.after(() => fs.rm(artifact, { recursive: true, force: true }));
await fs.writeFile(path.join(artifact, "execution-plan.json"), "{}");
const baseline = makeValidCapabilityWorkspace();
baseline.conformances[0]!.id = capabilityId.conformance("conformance:project:named");
const candidate = structuredClone(baseline);
candidate.conformances[0]!.semanticMajor = 2;
const { review } = await reviewUpgradeCandidate({ artifact, baseline, candidate });
assert.equal(review.reviews.length, 1);
assert.equal(review.reviews[0]!.accepted, false);
assert.match(review.blockers[0]!, /Semantic-major review required/);
const receipt = {
requirementDigest: review.reviews[0]!.requirementDigest,
decision: "accepted-unchanged" as const,
rationale: "Reviewed the consumer against the provider's unchanged label behavior",
agentId: "upgrade-fixture-agent",
};
assert.deepEqual(
(await reviewUpgradeCandidate({ artifact, baseline, candidate, reviews: [receipt] })).review.blockers,
[],
);
candidate.packageImports[0]!.source.commit = "f".repeat(40);
assert.equal(
(await reviewUpgradeCandidate({ artifact, baseline, candidate, reviews: [receipt] })).review.reviews[0]!.accepted,
false,
);
candidate.workspaceId = capabilityId.workspace("workspace:foreign");
await assert.rejects(() => reviewUpgradeCandidate({ artifact, baseline, candidate }), /different workspace/);
});
test("nonexecution pin upgrades retain their evolution checks", async (context) => {
const artifact = await fs.mkdtemp(path.join(os.tmpdir(), "qx-upgrade-evolution-review-"));
context.after(() => fs.rm(artifact, { recursive: true, force: true }));
const baseline = makeValidCapabilityWorkspace();
const { filename, review } = await reviewUpgradeCandidate({
artifact,
baseline,
candidate: structuredClone(baseline),
});
assert.equal(filename, "evolution.json");
assert.equal(review.checkerVersion, "quixos-evolution-v1");
assert.ok(review.blockers.some((message) => message.includes("legacy workspace-shared attachments")));
assert.equal("migrationRequired" in review, true);
});
test("unexpected artifact access failures do not select nonexecution checks", async (context) => {
const directory = await fs.mkdtemp(path.join(os.tmpdir(), "qx-upgrade-review-failure-"));
context.after(() => fs.rm(directory, { recursive: true, force: true }));
const artifact = path.join(directory, "not-a-directory");
await fs.writeFile(artifact, "not an artifact");
const candidate = makeValidCapabilityWorkspace();
await assert.rejects(() => reviewUpgradeCandidate({ artifact, baseline: candidate, candidate }), {
code: "ENOTDIR",
});
});
test( test(
"real jj snapshots and immutable Git publication propagate a changed interface into the root", "real jj snapshots and immutable Git publication propagate a changed interface into the root",
{ skip: !process.env.QX_CHECK_GENERATOR }, { skip: !process.env.QX_CHECK_GENERATOR },
@@ -73,6 +154,21 @@ test(
await run(workbench, "git", ["--git-dir", path.join(workbench, "remotes/named.git"), "show-ref"]), await run(workbench, "git", ["--git-dir", path.join(workbench, "remotes/named.git"), "show-ref"]),
new RegExp(commit), new RegExp(commit),
); );
assert.equal(graph.resources[0].directory, "resources/Named");
assert.equal(graph.directResources[0].directory, "resources/Named");
// A retained workbench can move without keeping its original absolute path
// alive. Recovery journals remain bound to their original writer/root.
const relocated = `${workbench}-relocated`;
context.after(() => fs.rm(relocated, { recursive: true, force: true }));
await fs.cp(workbench, relocated, { recursive: true });
const discovered = await discoverUpgradeSpec(relocated);
assert.equal(discovered.nodes[1]!.directory, "resources/Named");
const relocatedPlan = await planPinUpgrades(relocated, { ...discovered, bootstrap: true });
assert.equal(relocatedPlan.workbench, relocated);
assert.deepEqual(
relocatedPlan.nodes.map((node) => node.directory),
["resources/Named", "root"],
);
}, },
); );
+168
View File
@@ -0,0 +1,168 @@
import assert from "node:assert/strict";
import { test } from "node:test";
import { loadReaderWorkspace } from "./reader-fixture.js";
import { buildArtifactFixture } from "./artifact-fixture.js";
import {
compileExecutionPlan,
hexDigest,
inspectJavaScriptSurface,
inspectRestrictedImplementation,
restrictedSDKIdentity,
restrictedSDKPath,
type ArtifactImplementation,
reportExecutionPlacement,
type ExecutionInstallation,
} from "../src/execution-world/index.js";
test("restricted SDK identity ignores build comments and positions, preserving executable syntax", () => {
const source = 'export function value() { return ("hello"); }';
const x86 = "// /nix/store/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-core/dist/portable.js\n" + source;
const arm = "// /nix/store/bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb-core/dist/portable.js\n\n" + source;
assert.equal(restrictedSDKIdentity(x86), restrictedSDKIdentity(arm));
for (const changed of [
'export function value() { return ("goodbye"); }',
'export function value() { return\n("hello"); }',
'export function value() { fetch("hello"); }',
'import x from "node:fs"; ' + source,
'export function value() { return "/nix/store/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-core"; }',
])
assert.notEqual(restrictedSDKIdentity(source), restrictedSDKIdentity(changed));
assert.notEqual(restrictedSDKIdentity('"use strict";'), restrictedSDKIdentity('"use\\x20strict";'));
assert.notEqual(restrictedSDKIdentity('const value="// comment";'), restrictedSDKIdentity('const value="";'));
assert.throws(() => restrictedSDKIdentity("const ???"));
assert.throws(() => restrictedSDKIdentity(" ".repeat(2 * 1024 * 1024 + 1)), /ANALYSIS_LIMIT/);
});
test("restricted admission accepts the same SDK syntax and rejects changed SDK behavior", async () => {
const source = "export const registry = {};";
const sdk = 'export const value = "trusted";';
const implementation: ArtifactImplementation = {
id: "restricted",
target: "server",
compatibility: "quixos-restricted-module-v1",
path: "module.mjs",
ports: "quixos-transaction-ports-v1",
registryExport: "registry",
exports: ["value"],
contentDigest: "a".repeat(64),
files: [
{ path: "module.mjs", digest: "b".repeat(64), bytes: source.length, mediaType: "text/javascript" },
{ path: restrictedSDKPath, digest: "c".repeat(64), bytes: sdk.length, mediaType: "text/javascript" },
],
};
const check = (candidateSDK: string) => {
implementation.files[1]!.bytes = Buffer.byteLength(candidateSDK);
return inspectRestrictedImplementation(
"package:test@1",
implementation,
async (_revision, path) => Buffer.from(path === restrictedSDKPath ? candidateSDK : source),
restrictedSDKIdentity(sdk),
);
};
assert.deepEqual(await check("// a different build path\n" + sdk), []);
assert.equal((await check('export const value = "untrusted";'))[0]?.code, "RESTRICTED_SDK_UNSUPPORTED");
assert.equal((await check("export const ???"))[0]?.code, "RESTRICTED_SDK_UNSUPPORTED");
});
test("compiled-source inspection finds authority imports and ambient facilities without executing code", () => {
const surface = inspectJavaScriptSurface(
`
import sdk from "/checked/core.mjs";
export * from "node:fs";
import path from "path";
import unknown from "./another.mjs";
const load = () => import(moduleName);
const req = () => require("node:net");
const n = Math.random(); const t = Date.now(); const next = new Date();
const call = () => fetch("https://example.test/");
const globalValue = globalThis["hidden"];
throw Error("INSPECTION_MUST_NOT_EXECUTE");
`,
["/checked/core.mjs"],
);
assert.equal(
surface.some((f) => f.detail === "/checked/core.mjs"),
false,
);
for (const name of ["node:fs", "path", "node:net"])
assert.ok(surface.some((f) => f.code === "NATIVE_IMPORT" && f.detail === name));
for (const code of [
"UNCLASSIFIED_IMPORT",
"COMPUTED_MODULE_LOADING",
"AMBIENT_CLOCK",
"AMBIENT_RANDOMNESS",
"AMBIENT_HOST_ACCESS",
])
assert.ok(
surface.some((f) => f.code === code),
code,
);
assert.ok(surface.some((f) => f.detail === "fetch"));
assert.ok(surface.some((f) => f.detail === "globalThis"));
assert.ok(surface.every((f) => typeof f.line === "number"));
assert.deepEqual(
inspectJavaScriptSurface(
'const d = new Date("2026-01-01"); const properties = { fetch: 1 }; properties.fetch; Math.floor(3.1);',
),
[],
);
assert.equal(inspectJavaScriptSurface("const ???")[0]!.code, "UNCLASSIFIED_SYNTAX");
assert.equal(inspectJavaScriptSurface(" ".repeat(1024 * 1024 + 1))[0]!.code, "ANALYSIS_LIMIT");
const many = Array.from({ length: 100 }, (_, i) => `import x${i} from "unknown-${i}";`).join("\n");
const bounded = inspectJavaScriptSurface(many);
assert.equal(bounded.length, 64);
assert.equal(bounded.at(-1)!.code, "ANALYSIS_LIMIT");
});
const fixture = async () => {
const plan = compileExecutionPlan(await loadReaderWorkspace());
const artifacts = plan.definition.packages.map((pkg) => buildArtifactFixture(plan, pkg.revision));
const installation: ExecutionInstallation = {
codec: "camino-execution-installation-v1",
plan: plan.digest,
world: "a".repeat(64),
routes: {},
components: [],
packages: artifacts.map((f) => ({
revision: f.manifest.packageRevisionId,
root: "/fixture",
service: f.manifest.implementations[0]!,
module: f.manifest.implementations[1]!,
})),
};
return { plan, installation, read: artifacts[0]!.read };
};
test("placement separates native bindings, target portability, package eligibility and transitive blockers", async () => {
const { plan, installation, read } = await fixture();
const report = await reportExecutionPlacement(plan, installation, read);
const native = plan.definition.operations.find((op) => op.binding.kind === "state")!;
assert.equal(report.operations.find((op) => op.operation === native.key)!.requiresVM, false);
const consumer = plan.definition.operations.find(
(op) => op.binding.kind === "package" && op.dependencies.some((dep) => dep.kind === "operation"),
)!;
const before = structuredClone(consumer);
const entry = report.operations.find((op) => op.operation === consumer.key)!;
assert.equal(entry.requiresVM, true);
assert.deepEqual(entry.availableTargets, consumer.availableTargets);
assert.ok(entry.blockers.some((blocker) => blocker.code === "UNQUALIFIED_PACKAGE"));
assert.ok(entry.nativeBindings.includes("state"));
assert.ok(report.packages.every((pkg) => pkg.restrictedEligible === false));
assert.deepEqual(consumer, before, "Analysis cannot alter public contracts or placement");
// Add a dependency that disqualifies the consumer while preserving its interface.
const target = plan.definition.operations.find((op) => op.key !== consumer.key && op.binding.kind === "package")!;
consumer.dependencies.push({ kind: "operation", port: "unsafe-provider", operation: target.key });
target.execution = { kind: "remote" };
target.dependencies.push({ kind: "operation", port: "return-to-caller", operation: consumer.key });
plan.digest = hexDigest(plan.definition);
const after = await reportExecutionPlacement(plan, { ...installation, plan: plan.digest }, read);
const changed = after.operations.find((op) => op.operation === consumer.key)!;
assert.ok(
changed.blockers.some((blocker) => blocker.code === "REMOTE_EFFECT" && blocker.path.includes("unsafe-provider")),
);
assert.ok(changed.cycles.some((cycle) => cycle[0] === consumer.key && cycle.at(-1) === consumer.key));
assert.deepEqual(consumer.input, before.input);
assert.deepEqual(consumer.output, before.output);
await assert.rejects(reportExecutionPlacement(plan, installation, read), { code: "PLACEMENT_PLAN_MISMATCH" });
});
+54
View File
@@ -19,12 +19,16 @@ import {
expectedArtifactReceipt, expectedArtifactReceipt,
checkExecutionInstallation, checkExecutionInstallation,
clientContractCatalog, clientContractCatalog,
createClientContractCatalog,
CandidateMetadataBudget,
compileKernelProgram,
type ComponentArtifact, type ComponentArtifact,
type PackageArtifacts, type PackageArtifacts,
} from "../src/execution-world/index.js"; } from "../src/execution-world/index.js";
import { validateWorkspaceRevision } from "../src/capability-model/index.js"; import { validateWorkspaceRevision } from "../src/capability-model/index.js";
import { presentationDeclarations, preparationArtifact } from "../src/react-build/declarations.js"; import { presentationDeclarations, preparationArtifact } from "../src/react-build/declarations.js";
import { compileQueryComposition } from "../src/query/composition.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 source = { repository: "https://example.test/components.git", commit: "a".repeat(40) };
const contract = (name: string) => { 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]), () => clientContractCatalog(plan, { ...installation, plan: "bad" }, [pkg.revision]),
/CATALOG_PLAN_MISMATCH/, /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 { } finally {
await rm(root, { recursive: true, force: true }); await rm(root, { recursive: true, force: true });
} }
+37
View File
@@ -0,0 +1,37 @@
import { queryWorkspaceFixture } from "./fixtures/query-workspace.js";
import { compileQuery } from "../src/query/compile.js";
import { queryTreeProjections } from "../src/query/tree.js";
import { linkQueries } from "../src/query/link.js";
import { compileExecutionPlan } from "../src/execution-world/plan.js";
export async function queryTreeFixture() {
const fixture = await queryWorkspaceFixture({ live: true, snapshot: true });
const declaration = {
...fixture.pkg.queries!.find((query) => query.id === "upcoming")!,
id: "tree",
displayName: "Tree",
operation: "Tree",
placement: { kind: "replica" as const },
fragments: [],
};
const checked = await compileQuery(
declaration,
fixture.interfaces,
async () => `query Tree($first:Int!, $details:Boolean!) {
root {items(first:$first) {entries {node {
...Heading @boundary(name:"basic") ...Details @boundary(name:"details") @include(if:$details)
assignee {...Person @boundary(name:"person")}
}}}}
} fragment Heading on TaskFacts {title} fragment Details on TaskFacts {rank done}
fragment Person on PersonFacts {name}`,
);
const projections = queryTreeProjections(checked);
fixture.pkg.queries = [declaration, ...projections.map((query) => query.declaration)];
fixture.pkg.checkedQueries = [checked, ...projections];
// Workspace imports retain the checked Package by value in the assembler.
const imported = fixture.workspace.packageImports.find((pkg) => pkg.revisionId === fixture.pkg.revisionId)!;
imported.queries = fixture.pkg.queries;
imported.checkedQueries = fixture.pkg.checkedQueries;
fixture.workspace.linkedQueries = linkQueries(fixture.workspace);
return { ...fixture, plan: compileExecutionPlan(fixture.workspace) };
}
+165
View File
@@ -0,0 +1,165 @@
import assert from "node:assert/strict";
import test from "node:test";
import { compileCapabilityResourceSource } from "../src/capability-language/index.js";
import { compileQuery } from "../src/query/compile.js";
import type { InterfaceRevision } from "../src/capability-model/types.js";
const source = { repository: "https://example.test/tree", commit: "a".repeat(40) };
function iface(text: string, dependencies: InterfaceRevision[] = []) {
const result = compileCapabilityResourceSource(text, {
source,
environment: {
interfaces: new Map(dependencies.map((value) => [value.displayName, value])),
interfaceClosure: dependencies,
},
});
assert.ok(result.ok, JSON.stringify(result.diagnostics));
if (result.resource.kind !== "interface") throw Error("Expected Interface");
return result.resource.revision;
}
const item = iface(`interface Item id "item" revision "item@1" {
queryable value title id "title" : string {get id "title:get" execution snapshot;}
queryable value body id "body" : string {get id "body:get" execution snapshot;}
}`);
const navigation = iface(
`import interface Item; interface Navigation id "nav" revision "nav@1" {
queryable value chrome id "chrome" : string {get id "chrome:get" execution snapshot;}
queryable relation document id "document" : optional-one interface Item {resolve id "document:resolve" execution snapshot;}
queryable relation items id "items" : many interface Item ordered {resolve id "items:resolve" execution snapshot;}
}`,
[item],
);
function declaration(root: InterfaceRevision = item) {
const result = compileCapabilityResourceSource(
`import interface ${root.displayName}; package Views id "views" revision "views@1" {
query Open id "open" root ${root.displayName} document "open.graphql" operation "Open" {replica; max rows 10;}
}`,
{ source, environment: { interfaces: new Map([[root.displayName, root]]), interfaceClosure: [root, item] } },
);
assert.ok(result.ok, JSON.stringify(result.diagnostics));
if (result.resource.kind !== "package") throw Error("Expected Package");
return result.resource.revision.queries![0]!;
}
const fragments = `fragment Heading on Item {title} fragment Body on Item {body}`;
test("boundaries remain complete typed projections; ordinary spreads stay inline", async () => {
const checked = await compileQuery(
declaration(),
[item],
async () => `query Open {root {...Heading ...Body @boundary(name:"body")}} ${fragments}`,
);
assert(checked.tree);
assert(!JSON.stringify(checked.output).includes('"body"'));
assert(!JSON.stringify(checked.selection).includes('"body"'));
const body = checked.tree.nodes.find((node) => node.id === "root/boundary/body")!;
assert(body);
assert(
JSON.stringify(checked.tree.projections.find((projection) => projection.id === body.projection)!.output).includes(
'"body"',
),
);
assert.equal(checked.tree.nodes[0]!.boundaries[0]!.name, "body");
const ordinary = await compileQuery(
declaration(),
[item],
async () => `query Open {root {...Heading ...Body}} ${fragments}`,
);
assert.equal(ordinary.tree, undefined);
assert(JSON.stringify(ordinary.output).includes('"body"'));
});
test("minimal nullable-root bindings exclude slow siblings and carry child handles", async () => {
const checked = await compileQuery(
declaration(navigation),
[item, navigation],
async () => `query Open {root {
...Chrome @boundary(name:"chrome") document {...Heading @boundary(name:"basic") ...Body @boundary(name:"body")}
}} fragment Chrome on Navigation {chrome} ${fragments}`,
);
const tree = checked.tree!;
const binding = tree.nodes[0]!.bindings[0]!;
assert.equal(binding.name, "document");
const projection = tree.projections.find((projection) => projection.id === binding.projection)!;
assert(!JSON.stringify(projection.selection).includes('"chrome"'));
assert(!JSON.stringify(projection.selection).includes('"title"'));
assert(!JSON.stringify(projection.selection).includes('"body"'));
assert.deepEqual(binding.targets[0]!.path, ["document"]);
assert.deepEqual(
tree.nodes.find((node) => node.id === binding.targets[0]!.node)!.boundaries.map((boundary) => boundary.name),
["basic", "body"],
);
});
test("bounded list bindings preserve entry identity without requesting details", async () => {
const checked = await compileQuery(
declaration(navigation),
[item, navigation],
async () => `query Open {root {
items(first: 3) {entries {node {...Body @boundary(name:"body")}}}
}} fragment Body on Item {body}`,
);
const tree = checked.tree!,
binding = tree.nodes[0]!.bindings[0]!;
assert.deepEqual(binding.targets[0]!.path, ["items", "entries", "[]", "node"]);
const projection = tree.projections.find((projection) => projection.id === binding.projection)!;
assert(JSON.stringify(projection.selection).includes('"name":"key"'));
assert(!JSON.stringify(projection.selection).includes('"name":"body"'));
assert(tree.maxOccurrences <= 256);
});
test("guards control boundary participation and invalid syntax fails checking", async () => {
const checked = await compileQuery(
declaration(),
[item],
async () => `query Open($show:Boolean!) {root {
...Body @boundary(name:"body") @include(if:$show)
}} fragment Body on Item {body}`,
);
assert.deepEqual(checked.tree!.nodes[0]!.boundaries[0]!.conditions, [
{ include: true, value: { kind: "variable", name: "show" } },
]);
for (const [text, error] of [
[`query Open {root {...Body @boundary(name:"")}} fragment Body on Item {body}`, /QUERY_BOUNDARY_NAME/],
[
`query Open($name:String!) {root {...Body @boundary(name:$name)}} fragment Body on Item {body}`,
/QUERY_BOUNDARY_NAME/,
],
[
`query Open {root {...Body @boundary(name:"x") ...Heading @boundary(name:"x")}} ${fragments}`,
/QUERY_BOUNDARY_DUPLICATE/,
],
[`query Open {root {body @boundary(name:"x")}}`, /QUERY_VALIDATION/],
[`query Open {root {...Cycle @boundary(name:"x")}} fragment Cycle on Item {...Cycle}`, /QUERY_VALIDATION/],
] as const)
await assert.rejects(
compileQuery(declaration(), [item], async () => text),
error,
);
});
test("equivalent repeated paths share bindings; aliases preserve different windows", async () => {
const checked = await compileQuery(
declaration(navigation),
[item, navigation],
async () => `query Open {root {
document {...Heading @boundary(name:"basic")} document {...Body @boundary(name:"body")}
recent:items(first:2) {entries {node {...Body @boundary(name:"body")}}}
earlier:items(first:3) {entries {node {...Body @boundary(name:"body")}}}
}} ${fragments}`,
);
assert.deepEqual(
checked.tree!.nodes[0]!.bindings.map((binding) => binding.name),
["document", "recent", "earlier"],
);
assert.deepEqual(
checked
.tree!.nodes.find((node) => node.id === "root/binding/document")!
.boundaries.map((boundary) => boundary.name),
["basic", "body"],
);
await assert.rejects(
compileQuery(
declaration(navigation),
[item, navigation],
async () => `query Open($show:Boolean!) {root {
document @include(if:$show) {...Heading @boundary(name:"basic")} document {...Body @boundary(name:"body")}
}} ${fragments}`,
),
/QUERY_TREE_BINDING_CONFLICT/,
);
});
+31
View File
@@ -13,6 +13,37 @@ import {
} from "../src/capability-language/structural-plan.js"; } from "../src/capability-language/structural-plan.js";
const execFile = promisify(callback); const execFile = promisify(callback);
test("package structural validation does not require source-generated bindings", async (context) => {
const root = await fs.mkdtemp(path.join(os.tmpdir(), "qx-structural-package-test-"));
context.after(() => fs.rm(root, { recursive: true, force: true }));
await execFile("git", ["-C", root, "init"]);
await fs.writeFile(path.join(root, ".gitignore"), ".quixos/\n");
await fs.writeFile(
path.join(root, "quixos.lock"),
`quixos-lock version 1 { quixos source { repository "https://example.test/quixos.git"; commit "${"a".repeat(40)}"; } }`,
);
const before = 'package Test id "package:test" revision "package:test@1" {}';
await fs.writeFile(path.join(root, "package.qx"), before);
const request: StructuralRequest = {
kind: "package",
source: { repository: "https://example.test/package.git", commit: "b".repeat(40) },
files: [{ file: "package.qx", expected: before, replace: `${before}\n// updated` }],
};
const plan = await planStructure(root, request);
assert.deepEqual(
plan.changes.map((change) => change.file),
["package.qx"],
);
assert.equal(plan.validation, "resource-graph");
await fs.writeFile(path.join(root, "quixos.check.json"), "not valid json");
await assert.rejects(() => planStructure(root, request), SyntaxError);
await fs.writeFile(path.join(root, "quixos.check.json"), '{"backend":"execution"}');
assert.deepEqual(
(await planStructure(root, request)).changes.map((change) => change.file),
["package.qx"],
);
});
test("structural plans validate the graph, journal originals, and reject stale edits", async (context) => { test("structural plans validate the graph, journal originals, and reject stale edits", async (context) => {
const root = await fs.mkdtemp(path.join(os.tmpdir(), "qx-structural-test-")); const root = await fs.mkdtemp(path.join(os.tmpdir(), "qx-structural-test-"));
context.after(() => fs.rm(root, { recursive: true, force: true })); context.after(() => fs.rm(root, { recursive: true, force: true }));