Files
quixos-protocol/src/execution-world/placement.ts
T
Timothy J. Aveni 62a09605cf Reuse verified immutable plans and streamline cooperative hashing
Continue final hosted development reliability qualification.
2026-10-12 20:16:56 -07:00

369 lines
15 KiB
TypeScript

import { executionPlanDigest, ExecutionPlanError, hexDigest, type ExecutionPlan } from "./plan.js";
import { parse } from "@babel/parser";
import { builtinModules } from "node:module";
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 || executionPlanDigest(plan) !== 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,
};
}