@hops-ops/distributed 4.9.0 → 4.10.0

package/dist/sveltekit/islands/boundaries.js

@@ -0,0 +1,734 @@
+import { lstat, readFile, readdir } from 'node:fs/promises';
+import { dirname, extname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
+import { parse } from 'svelte/compiler';
+const BOUNDARY_PLAN_VERSION = 1;
+const MAX_COMPONENTS = 4_096;
+const MAX_ISLANDS = 4_096;
+const MAX_COMPONENT_BYTES = 2 * 1024 * 1024;
+const MAX_GRAPH_EDGES = 32_768;
+/** Validate a persisted adapter plan before check/dev treats it as coherent. */
+export function validateDistributedSvelteKitBoundaryPlan(value, module) {
+    if (value === null ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        value.version !== BOUNDARY_PLAN_VERSION ||
+        typeof value.module !== 'string' ||
+        (module !== undefined && value.module !== module) ||
+        !Array.isArray(value.boundaries) ||
+        !Array.isArray(value.unplaced)) {
+        throw new Error(`[distributed.island.boundary_plan_invalid] ${module ?? '<unknown>'} boundaries.json is not version ${BOUNDARY_PLAN_VERSION}`);
+    }
+    return value;
+}
+/**
+ * Analyze Svelte component reachability without evaluating application code.
+ * The returned plan is deterministic and contains project-relative paths only.
+ */
+export async function analyzeDistributedSvelteKitBoundaries(options) {
+    const cwd = resolve(options.cwd);
+    const routesDir = contained(cwd, options.routesDir ?? 'src/routes', 'routesDir');
+    const libDir = contained(cwd, options.libDir ?? 'src/lib', 'libDir');
+    const aliases = new Map([
+        ['$lib', libDir],
+        ...Object.entries(options.aliases ?? {}).map(([key, value]) => [
+            aliasKey(key),
+            contained(cwd, value, `alias ${key}`)
+        ])
+    ]);
+    const components = await loadComponents(cwd, [
+        ...new Set([routesDir, libDir, ...aliases.values()])
+    ]);
+    const roots = boundaryRoots(cwd, routesDir, components);
+    const sourceOwners = new Map();
+    for (const client of options.clients) {
+        validateInventory(client.module, client.inventory);
+        for (const island of client.inventory.islands.filter((candidate) => candidate.directives.load)) {
+            const source = portableSource(island.source.path);
+            const previous = sourceOwners.get(source);
+            if (previous !== undefined && previous !== client.module) {
+                throw diagnostic('distributed.island.cross_surface', source, island.source.line, island.source.column, `operation ${island.operation} is owned by both ${previous} and ${client.module}; split the GraphQL source by authorization surface`);
+            }
+            sourceOwners.set(source, client.module);
+        }
+    }
+    const plans = [];
+    for (const client of [...options.clients].sort((left, right) => left.module.localeCompare(right.module))) {
+        const loadIslands = client.inventory.islands
+            .filter((island) => island.directives.load)
+            .map((island) => ({ island, source: portableSource(island.source.path) }))
+            .sort((left, right) => left.source.localeCompare(right.source) ||
+            left.island.operation.localeCompare(right.island.operation));
+        const componentIslands = new Map();
+        const routeIslands = new Map();
+        const islandByOperation = new Map(loadIslands.map((entry) => [entry.island.operation, entry]));
+        const explicitByBoundary = new Map();
+        const explicitByIdentity = new Map();
+        const explicitlyPlaced = new Set();
+        for (const registration of client.explicitBoundaries ?? []) {
+            const entry = islandByOperation.get(registration.operation);
+            if (entry === undefined) {
+                throw new Error(`[distributed.island.explicit_operation_missing] ${client.module} explicit boundary references unknown @load operation ${registration.operation}`);
+            }
+            const id = `${registration.kind}:${normalizeRoute(registration.route)}`;
+            const bucket = explicitByBoundary.get(id) ?? [];
+            const identity = `${id}\u0000${registration.operation}`;
+            if (explicitByIdentity.has(identity)) {
+                throw new Error(`[distributed.island.explicit_duplicate] ${client.module} repeats ${registration.operation} at ${registration.route}`);
+            }
+            bucket.push(Object.freeze({ entry, registration }));
+            explicitByBoundary.set(id, bucket);
+            explicitByIdentity.set(identity, registration);
+            explicitlyPlaced.add(entry.island.id);
+        }
+        for (const entry of loadIslands) {
+            const target = islandOwnerComponent(cwd, entry.source);
+            if (target.kind === 'component') {
+                const bucket = componentIslands.get(target.path) ?? [];
+                const conflicting = bucket.find((candidate) => candidate.source !== entry.source);
+                if (conflicting !== undefined) {
+                    throw diagnostic('distributed.island.sibling_conflict', entry.source, entry.island.source.line, entry.island.source.column, `operation ${entry.island.operation} conflicts with sibling source ${conflicting.source}; keep one GraphQL sibling or register an explicit boundary`);
+                }
+                bucket.push(entry);
+                componentIslands.set(target.path, bucket);
+            }
+            else {
+                const bucket = routeIslands.get(target.key) ?? [];
+                bucket.push(entry);
+                routeIslands.set(target.key, bucket);
+            }
+        }
+        for (const component of componentIslands.keys()) {
+            const needsComponent = componentIslands
+                .get(component)
+                .some(({ island }) => !explicitlyPlaced.has(island.id));
+            if (!needsComponent)
+                continue;
+            if (!components.has(component)) {
+                const entry = componentIslands.get(component)[0];
+                throw diagnostic('distributed.island.component_missing', entry.source, entry.island.source.line, entry.island.source.column, `operation ${entry.island.operation} requires sibling ${projectPath(cwd, component)}; add the component, register an explicit boundary, or mark it client-only`);
+            }
+        }
+        const boundaries = [];
+        const placed = new Set();
+        for (const root of roots) {
+            const occurrences = [];
+            const explicitEntries = explicitByBoundary.get(root.id) ?? [];
+            const explicitAtBoundary = new Set(explicitEntries.map(({ entry }) => entry.island.id));
+            for (const { entry, registration } of explicitEntries) {
+                occurrences.push(occurrence(cwd, entry, root, root.path, 'explicit', false, registration.variables));
+                placed.add(entry.island.id);
+            }
+            for (const entry of routeIslands.get(routeBoundaryKey(root.kind, dirname(root.path))) ?? []) {
+                occurrences.push(occurrence(cwd, entry, root, root.path, 'route_document', false, explicitByIdentity.get(`${root.id}\u0000${entry.island.operation}`)?.variables));
+                placed.add(entry.island.id);
+            }
+            const dynamicComponentIslands = new Map([...componentIslands.entries()]
+                .map(([path, entries]) => [
+                path,
+                entries.filter(({ island }) => !explicitAtBoundary.has(island.id))
+            ])
+                .filter(([, entries]) => entries.length > 0));
+            const reachable = traverse(root, components, aliases, dynamicComponentIslands, cwd);
+            for (const component of reachable) {
+                for (const entry of componentIslands.get(component) ?? []) {
+                    occurrences.push(occurrence(cwd, entry, root, component, 'static_component_import', true, explicitByIdentity.get(`${root.id}\u0000${entry.island.operation}`)?.variables));
+                    placed.add(entry.island.id);
+                }
+            }
+            const deduplicated = [...new Map(occurrences.map((entry) => [entry.islandId, entry])).values()].sort(compareOccurrences);
+            if (deduplicated.length > 0) {
+                boundaries.push(Object.freeze({
+                    id: root.id,
+                    route: root.route,
+                    kind: root.kind,
+                    source: projectPath(cwd, root.path),
+                    islands: Object.freeze(deduplicated)
+                }));
+            }
+        }
+        const unplaced = loadIslands
+            .filter(({ island }) => !placed.has(island.id))
+            .map(({ island, source }) => Object.freeze({
+            islandId: island.id,
+            operation: island.operation,
+            graphqlSource: source
+        }));
+        plans.push(Object.freeze({
+            version: BOUNDARY_PLAN_VERSION,
+            module: client.module,
+            schemaFingerprint: client.inventory.schemaFingerprint,
+            protocolFingerprint: client.inventory.protocolFingerprint,
+            boundaries: Object.freeze(boundaries),
+            unplaced: Object.freeze(unplaced)
+        }));
+    }
+    return Object.freeze(plans);
+}
+function occurrence(cwd, entry, root, component, reason, conservative, explicitSources) {
+    if (root.kind === 'layout' &&
+        entry.island.directives.live &&
+        !entry.island.liveCoverage.finite) {
+        throw diagnostic('distributed.island.layout_live_unbounded', entry.source, entry.island.source.line, entry.island.source.column, `operation ${entry.island.operation} is live for layout ${root.route} without finite coverage; add a compiler-proved limit, move it to a page, register a bounded boundary-owned query, or mark it client-only`);
+    }
+    const binding = boundaryBinding(entry, root, explicitSources);
+    return Object.freeze({
+        islandId: entry.island.id,
+        operation: entry.island.operation,
+        modulePath: entry.island.modulePath,
+        exportName: entry.island.exportName,
+        component: projectPath(cwd, component),
+        graphqlSource: entry.source,
+        reason,
+        conservative,
+        directives: entry.island.directives,
+        liveCoverage: entry.island.liveCoverage,
+        binding
+    });
+}
+function boundaryBinding(entry, root, explicitSources) {
+    if (typeof entry.island.operationHash !== 'string' ||
+        entry.island.operationHash.length === 0 ||
+        !Array.isArray(entry.island.variableSchema?.variables)) {
+        throw diagnostic('distributed.island.binding_inventory_invalid', entry.source, entry.island.source.line, entry.island.source.column, `operation ${entry.island.operation} has invalid variable-binding inventory; regenerate the framework-neutral client`);
+    }
+    const variables = [...entry.island.variableSchema.variables].sort((left, right) => left.name.localeCompare(right.name));
+    const allowed = new Set(variables.map(({ name }) => name));
+    for (const name of Object.keys(explicitSources ?? {})) {
+        if (!allowed.has(name)) {
+            throw diagnostic('distributed.island.variable_unknown', entry.source, entry.island.source.line, entry.island.source.column, `operation ${entry.island.operation} binding names unknown variable ${name}; use an explicit binding, parent/boundary query, client-only execution, or a better read root`);
+        }
+    }
+    const routeParams = new Set(routeParameterNames(root.route));
+    const sources = [];
+    let hasExplicit = false;
+    let hasRoute = false;
+    for (const variable of variables) {
+        const explicit = ownDataValue(explicitSources, variable.name);
+        if (explicit !== undefined) {
+            let normalized;
+            try {
+                normalized = normalizeBindingSource(explicit, variable.name);
+            }
+            catch {
+                throw diagnostic('distributed.island.variable_source_invalid', entry.source, entry.island.source.line, entry.island.source.column, `operation ${entry.island.operation} variable ${variable.name} has an unsupported or unsafe explicit variable source at boundary ${root.route}; use a route/search parameter, trusted-session path, constant, forwarded prop, omission, parent/boundary query, client-only execution, or a better read root`);
+            }
+            sources.push([variable.name, normalized]);
+            hasExplicit = true;
+        }
+        else if (routeParams.has(variable.name)) {
+            sources.push([
+                variable.name,
+                Object.freeze({ kind: 'route_param', name: variable.name })
+            ]);
+            hasRoute = true;
+        }
+        else if (!variable.graphqlType.endsWith('!')) {
+            sources.push([variable.name, Object.freeze({ kind: 'omit' })]);
+        }
+        else {
+            throw diagnostic('distributed.island.variable_unprovable', entry.source, entry.island.source.line, entry.island.source.column, `operation ${entry.island.operation} variable ${variable.name} is not boundary-visible at ${root.route}; use an explicit binding, parent/boundary query, client-only execution, or a better read root`);
+        }
+    }
+    const sourceRecord = Object.freeze(Object.fromEntries(sources));
+    return Object.freeze({
+        version: 1,
+        id: `boundary-v1:${fnv1a64(`${entry.island.operationHash}\n${stableJson(sourceRecord)}`)}`,
+        discovery: hasExplicit ? 'explicit' : hasRoute ? 'route_param' : 'empty',
+        sources: sourceRecord
+    });
+}
+function routeParameterNames(route) {
+    const names = [];
+    for (const segment of route.split('/')) {
+        const match = /^\[\[?(?:\.\.\.)?([_A-Za-z][_0-9A-Za-z]*)(?:=[^\]]+)?\]?\]$/.exec(segment);
+        if (match?.[1] !== undefined)
+            names.push(match[1]);
+    }
+    return names;
+}
+function normalizeBindingSource(value, variable) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new TypeError(`Distributed boundary variable ${variable} source must be an object`);
+    }
+    const record = value;
+    const kind = ownDataValue(record, 'kind');
+    switch (kind) {
+        case 'omit':
+            return Object.freeze({ kind: 'omit' });
+        case 'route_param': {
+            const name = ownDataValue(record, 'name');
+            if (typeof name !== 'string' || name.length === 0) {
+                throw new TypeError(`Distributed boundary variable ${variable} source name is invalid`);
+            }
+            return Object.freeze({ kind: 'route_param', name });
+        }
+        case 'search_param': {
+            const name = ownDataValue(record, 'name');
+            if (typeof name !== 'string' || name.length === 0) {
+                throw new TypeError(`Distributed boundary variable ${variable} source name is invalid`);
+            }
+            const mode = ownDataValue(record, 'mode');
+            if (mode !== undefined && mode !== 'first' && mode !== 'all') {
+                throw new TypeError(`Distributed boundary variable ${variable} search mode is invalid`);
+            }
+            return Object.freeze({
+                kind: 'search_param',
+                name,
+                ...(mode === undefined ? {} : { mode })
+            });
+        }
+        case 'trusted_session':
+        case 'forwarded_prop': {
+            const path = ownDataValue(record, 'path');
+            if (!Array.isArray(path) ||
+                path.length === 0 ||
+                path.length > 16 ||
+                path.some((part) => typeof part !== 'string' ||
+                    !/^[_A-Za-z][_0-9A-Za-z]*$/.test(part) ||
+                    ['__proto__', 'prototype', 'constructor'].includes(part))) {
+                throw new TypeError(`Distributed boundary variable ${variable} source path is invalid`);
+            }
+            return Object.freeze({ kind, path: Object.freeze([...path]) });
+        }
+        case 'constant':
+            return Object.freeze({
+                kind: 'constant',
+                value: freezeStable(stableValue(ownDataValue(record, 'value')))
+            });
+        default:
+            throw new TypeError(`Distributed boundary variable ${variable} source is unsupported; use an explicit binding, parent/boundary query, client-only execution, or a better read root`);
+    }
+}
+function traverse(root, components, aliases, componentIslands, cwd) {
+    const reached = new Set();
+    const active = new Set();
+    const parent = new Map();
+    const visiting = [
+        { path: root.path, exit: false }
+    ];
+    let edges = 0;
+    while (visiting.length > 0) {
+        const frame = visiting.pop();
+        const path = frame.path;
+        if (frame.exit) {
+            active.delete(path);
+            continue;
+        }
+        if (reached.has(path))
+            continue;
+        reached.add(path);
+        active.add(path);
+        visiting.push({ path, exit: true });
+        const component = components.get(path);
+        if (component === undefined)
+            continue;
+        const targets = [];
+        for (const imported of component.imports) {
+            edges += 1;
+            if (edges > MAX_GRAPH_EDGES) {
+                throw diagnostic('distributed.island.graph_unbounded', projectPath(cwd, path), imported.line, imported.column, `boundary ${root.route} exceeds ${MAX_GRAPH_EDGES} static component edges; split the boundary or register a bounded explicit boundary`);
+            }
+            const target = resolveComponentImport(path, imported, aliases, components, cwd);
+            if (target === undefined)
+                continue;
+            if (active.has(target)) {
+                const cycle = [target];
+                let cursor = path;
+                while (cursor !== target) {
+                    cycle.push(cursor);
+                    const previous = parent.get(cursor);
+                    if (previous === undefined)
+                        break;
+                    cursor = previous;
+                }
+                if (cycle.some((candidate) => componentIslands.has(candidate))) {
+                    throw diagnostic('distributed.island.component_cycle', projectPath(cwd, path), imported.line, imported.column, `boundary ${root.route} reaches an @load island through a cyclic component graph; break the cycle, register an explicit boundary-owned query, or mark it client-only`);
+                }
+                continue;
+            }
+            if (!reached.has(target)) {
+                parent.set(target, path);
+                targets.push(target);
+            }
+        }
+        for (const target of targets.reverse()) {
+            visiting.push({ path: target, exit: false });
+        }
+        for (const imported of component.dynamicImports) {
+            if (imported.opaque) {
+                if (componentIslands.size > 0) {
+                    throw diagnostic('distributed.island.dynamic_opaque', projectPath(cwd, path), imported.line, imported.column, `boundary ${root.route} has opaque dynamic component reachability while @load islands remain unplaced; use a static import, explicit boundary registration, or client-only execution`);
+                }
+                continue;
+            }
+            const target = resolveComponentImport(path, imported, aliases, components, cwd);
+            if (target !== undefined && componentIslands.has(target)) {
+                throw diagnostic('distributed.island.dynamic_load', projectPath(cwd, path), imported.line, imported.column, `boundary ${root.route} dynamically reaches an @load island; use a static import, explicit boundary registration, or client-only execution`);
+            }
+        }
+    }
+    return [...reached].sort();
+}
+function resolveComponentImport(from, imported, aliases, components, cwd) {
+    const specifier = imported.specifier;
+    let candidate;
+    if (specifier.startsWith('.')) {
+        candidate = resolve(dirname(from), specifier);
+    }
+    else {
+        const alias = [...aliases.entries()]
+            .sort((left, right) => right[0].length - left[0].length)
+            .find(([key]) => specifier === key || specifier.startsWith(`${key}/`));
+        if (alias !== undefined) {
+            candidate = resolve(alias[1], specifier.slice(alias[0].length).replace(/^\//, ''));
+        }
+        else if (specifier.startsWith('$') && looksLikeComponent(specifier)) {
+            throw diagnostic('distributed.island.alias_unresolved', projectPath(cwd, from), imported.line, imported.column, `component alias ${specifier.split('/')[0]} is unresolved; add it to distributedSvelteKit aliases or use a resolvable static import`);
+        }
+    }
+    if (candidate === undefined)
+        return undefined;
+    if (!isWithin(cwd, candidate)) {
+        throw diagnostic('distributed.island.import_escape', projectPath(cwd, from), imported.line, imported.column, 'component import escapes the project root; use a project-local component or client-only execution');
+    }
+    const attempts = extname(candidate) === '.svelte'
+        ? [candidate]
+        : [`${candidate}.svelte`, join(candidate, 'index.svelte')];
+    for (const attempt of attempts) {
+        if (components.has(attempt))
+            return attempt;
+    }
+    if (looksLikeComponent(specifier)) {
+        throw diagnostic('distributed.island.import_unresolved', projectPath(cwd, from), imported.line, imported.column, `component import ${specifier} is unresolved; fix the static import, register an explicit boundary, or mark it client-only`);
+    }
+    return undefined;
+}
+function looksLikeComponent(specifier) {
+    return specifier.endsWith('.svelte') || /\/[A-Z][^/]*$/.test(specifier);
+}
+async function loadComponents(cwd, roots) {
+    const paths = new Set();
+    for (const root of roots)
+        await collectSvelteFiles(root, cwd, paths);
+    if (paths.size > MAX_COMPONENTS) {
+        throw new Error(`[distributed.island.graph_unbounded] Svelte project exceeds ${MAX_COMPONENTS} components; narrow routesDir/libDir`);
+    }
+    const components = new Map();
+    for (const path of [...paths].sort()) {
+        const metadata = await lstat(path);
+        if (!metadata.isFile() || metadata.isSymbolicLink())
+            continue;
+        if (metadata.size > MAX_COMPONENT_BYTES) {
+            throw diagnostic('distributed.island.component_too_large', projectPath(cwd, path), 1, 1, `component exceeds ${MAX_COMPONENT_BYTES} bytes; split it or use client-only execution`);
+        }
+        const source = await readFile(path, 'utf8');
+        components.set(path, parseComponent(path, source, cwd));
+    }
+    return components;
+}
+async function collectSvelteFiles(root, cwd, paths) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isMissing(error))
+            return;
+        throw error;
+    }
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        const path = join(root, entry.name);
+        if (!isWithin(cwd, path) || entry.isSymbolicLink())
+            continue;
+        if (entry.isDirectory())
+            await collectSvelteFiles(path, cwd, paths);
+        else if (entry.isFile() && entry.name.endsWith('.svelte'))
+            paths.add(path);
+    }
+}
+function parseComponent(path, source, cwd) {
+    let ast;
+    try {
+        ast = parse(source, { filename: projectPath(cwd, path), modern: true });
+    }
+    catch (error) {
+        throw new Error(`[distributed.island.svelte_parse] ${projectPath(cwd, path)}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const imports = [];
+    const dynamicImports = [];
+    walkAst(ast, (node) => {
+        if (node.type === 'ImportDeclaration') {
+            const value = literalValue(node.source);
+            if (value !== undefined)
+                imports.push(located(value, node));
+        }
+        else if (node.type === 'ImportExpression') {
+            const value = literalValue(node.source);
+            dynamicImports.push({
+                ...located(value ?? '<dynamic>', node),
+                opaque: value === undefined
+            });
+        }
+    });
+    return Object.freeze({
+        path,
+        imports: Object.freeze(imports),
+        dynamicImports: Object.freeze(dynamicImports)
+    });
+}
+function walkAst(value, visit) {
+    const stack = [value];
+    const seen = new WeakSet();
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (current === null || typeof current !== 'object')
+            continue;
+        if (seen.has(current))
+            continue;
+        seen.add(current);
+        if (!Array.isArray(current))
+            visit(current);
+        for (const child of Array.isArray(current)
+            ? current
+            : Object.values(current)) {
+            if (child !== null && typeof child === 'object')
+                stack.push(child);
+        }
+    }
+}
+function literalValue(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const candidate = value;
+    return candidate.type === 'Literal' && typeof candidate.value === 'string'
+        ? candidate.value
+        : undefined;
+}
+function located(specifier, node) {
+    return Object.freeze({
+        specifier,
+        line: node.loc?.start?.line ?? 1,
+        column: (node.loc?.start?.column ?? 0) + 1
+    });
+}
+function boundaryRoots(cwd, routesDir, components) {
+    return [...components.keys()]
+        .filter((path) => path.startsWith(`${routesDir}${sep}`) || path === routesDir)
+        .flatMap((path) => {
+        const name = posix.basename(portable(path));
+        const kind = boundaryComponentKind(name);
+        if (kind === undefined)
+            return [];
+        const routeDirectory = portable(relative(routesDir, dirname(path)));
+        const route = routeDirectory === '' ? '/' : `/${routeDirectory}`;
+        return [{
+                id: `${kind}:${route}`,
+                route,
+                kind,
+                path
+            }];
+    })
+        .sort((left, right) => left.route.localeCompare(right.route) ||
+        left.kind.localeCompare(right.kind) ||
+        projectPath(cwd, left.path).localeCompare(projectPath(cwd, right.path)));
+}
+function boundaryComponentKind(name) {
+    const match = /^\+(page|layout)(?:@[^/]*)?\.svelte$/.exec(name);
+    return match?.[1] === 'page' || match?.[1] === 'layout'
+        ? match[1]
+        : undefined;
+}
+function routeBoundaryKey(kind, directory) {
+    return `${kind}\u0000${directory}`;
+}
+function islandOwnerComponent(cwd, source) {
+    const absolute = contained(cwd, source, 'island source');
+    const suffix = extname(absolute);
+    const base = absolute.slice(0, -suffix.length);
+    const name = posix.basename(portable(base));
+    if (name === '+page' || name === '+layout') {
+        return {
+            kind: 'route',
+            key: routeBoundaryKey(name === '+page' ? 'page' : 'layout', dirname(base))
+        };
+    }
+    return { kind: 'component', path: `${base}.svelte` };
+}
+function validateInventory(module, inventory) {
+    if (inventory === null ||
+        typeof inventory !== 'object' ||
+        inventory.version !== 1 ||
+        !Array.isArray(inventory.islands) ||
+        inventory.islands.length > MAX_ISLANDS ||
+        typeof inventory.schemaFingerprint !== 'string' ||
+        typeof inventory.protocolFingerprint !== 'string') {
+        throw new Error(`[distributed.island.inventory_invalid] ${module} islands.json is not version 1`);
+    }
+    for (const island of inventory.islands) {
+        const source = island?.source;
+        const variableSchema = island?.variableSchema;
+        if (island?.version !== 1 ||
+            typeof island.id !== 'string' ||
+            typeof island.operation !== 'string' ||
+            typeof island.modulePath !== 'string' ||
+            !island.modulePath.startsWith('operations/') ||
+            !island.modulePath.endsWith('.ts') ||
+            typeof island.exportName !== 'string' ||
+            typeof source?.path !== 'string' ||
+            !Number.isSafeInteger(source.line) ||
+            source.line < 1 ||
+            !Number.isSafeInteger(source.column) ||
+            source.column < 1 ||
+            island.directives === null ||
+            typeof island.directives !== 'object' ||
+            typeof island.directives.load !== 'boolean' ||
+            typeof island.directives.live !== 'boolean' ||
+            island.liveCoverage === null ||
+            typeof island.liveCoverage !== 'object' ||
+            variableSchema === null ||
+            typeof variableSchema !== 'object' ||
+            Array.isArray(variableSchema) ||
+            typeof variableSchema.reference !== 'string' ||
+            !Number.isSafeInteger(variableSchema.codecVersion) ||
+            !Array.isArray(variableSchema.variables) ||
+            variableSchema.variables.some((variable) => variable === null ||
+                typeof variable !== 'object' ||
+                Array.isArray(variable) ||
+                typeof variable.name !== 'string' ||
+                typeof variable.graphqlType !== 'string') ||
+            typeof island.liveCoverage.requested !== 'boolean' ||
+            typeof island.liveCoverage.finite !== 'boolean' ||
+            typeof island.liveCoverage.kind !== 'string' ||
+            (island.liveCoverage.maxItems !== undefined &&
+                (!Number.isSafeInteger(island.liveCoverage.maxItems) ||
+                    island.liveCoverage.maxItems < 0))) {
+            throw new Error(`[distributed.island.version_unsupported] ${typeof source?.path === 'string' ? source.path : module}:${Number.isSafeInteger(source?.line) ? source.line : 1}:${Number.isSafeInteger(source?.column) ? source.column : 1}: island metadata is not version 1; regenerate the framework-neutral client and boundary plan`);
+        }
+    }
+}
+function portableSource(path) {
+    if (typeof path !== 'string' ||
+        path.length === 0 ||
+        isAbsolute(path) ||
+        path.includes('\\') ||
+        path.split('/').some((part) => part === '' || part === '.' || part === '..')) {
+        throw new Error('[distributed.island.source_invalid] island source path is not portable');
+    }
+    return path;
+}
+function compareOccurrences(left, right) {
+    return (left.operation.localeCompare(right.operation) ||
+        left.component.localeCompare(right.component) ||
+        left.graphqlSource.localeCompare(right.graphqlSource));
+}
+function aliasKey(value) {
+    if (!/^\$[A-Za-z0-9_-]+$/.test(value)) {
+        throw new TypeError(`Distributed SvelteKit alias ${value} must be a single $name segment`);
+    }
+    return value;
+}
+function normalizeRoute(value) {
+    if (typeof value !== 'string' ||
+        !value.startsWith('/') ||
+        value.includes('\\') ||
+        value.includes('?') ||
+        value.includes('#') ||
+        value.split('/').some((part) => part === '.' || part === '..')) {
+        throw new TypeError('Distributed explicit boundary route must be a normalized SvelteKit route id');
+    }
+    return value.length > 1 && value.endsWith('/') ? value.slice(0, -1) : value;
+}
+function contained(root, value, label) {
+    const path = resolve(root, value);
+    if (!isWithin(root, path))
+        throw new TypeError(`${label} must stay within project root`);
+    return path;
+}
+function isWithin(root, target) {
+    const path = relative(root, target);
+    return path === '' || (!path.startsWith(`..${sep}`) && path !== '..' && !isAbsolute(path));
+}
+function projectPath(cwd, path) {
+    return portable(relative(cwd, path));
+}
+function portable(path) {
+    return path.split(sep).join('/');
+}
+function diagnostic(code, path, line, column, message) {
+    return new Error(`[${code}] ${path}:${line}:${column}: ${message}`);
+}
+function ownDataValue(value, key) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor === undefined)
+        return undefined;
+    if (!('value' in descriptor)) {
+        throw new TypeError('Distributed boundary binding contains an accessor');
+    }
+    return descriptor.value;
+}
+function stableJson(value) {
+    return JSON.stringify(stableValue(value));
+}
+function stableValue(value) {
+    const active = new Set();
+    let visited = 0;
+    const visit = (current, depth) => {
+        visited += 1;
+        if (visited > 4_096 || depth > 32) {
+            throw new TypeError('Distributed boundary binding exceeds structural limits');
+        }
+        if (current === null ||
+            typeof current === 'string' ||
+            typeof current === 'boolean')
+            return current;
+        if (typeof current === 'number' && Number.isFinite(current))
+            return current;
+        if (typeof current !== 'object') {
+            throw new TypeError('Distributed boundary binding is not JSON-compatible');
+        }
+        if (active.has(current))
+            throw new TypeError('Distributed boundary binding is cyclic');
+        active.add(current);
+        try {
+            if (Array.isArray(current))
+                return current.map((entry) => visit(entry, depth + 1));
+            if (Object.getPrototypeOf(current) !== Object.prototype &&
+                Object.getPrototypeOf(current) !== null) {
+                throw new TypeError('Distributed boundary binding must contain plain objects');
+            }
+            return Object.fromEntries(Object.keys(current).sort().map((key) => {
+                if (['__proto__', 'prototype', 'constructor'].includes(key)) {
+                    throw new TypeError('Distributed boundary binding contains a hostile object key');
+                }
+                return [key, visit(ownDataValue(current, key), depth + 1)];
+            }));
+        }
+        finally {
+            active.delete(current);
+        }
+    };
+    return visit(value, 0);
+}
+function freezeStable(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    for (const entry of Array.isArray(value)
+        ? value
+        : Object.values(value)) {
+        freezeStable(entry);
+    }
+    return Object.freeze(value);
+}
+function fnv1a64(value) {
+    let hash = 0xcbf29ce484222325n;
+    for (const byte of new TextEncoder().encode(value)) {
+        hash ^= BigInt(byte);
+        hash = BigInt.asUintN(64, hash * 0x100000001b3n);
+    }
+    return hash.toString(16).padStart(16, '0');
+}
+function isMissing(error) {
+    return error !== null && typeof error === 'object' && 'code' in error && error.code === 'ENOENT';
+}