@spine-event-engine/proto-tools 2.0.0-snapshot.10

package/dist/src/index.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Published manifest JSON revision.
+ */
+export declare const manifestFormatVersion = 2;
+/**
+ * Configures an independently published Proto model package.
+ */
+export interface ModelConfig {
+    /**
+     * Declares the version of this configuration contract.
+     */
+    readonly formatVersion: 1;
+    /**
+     * Selects an independently published model package.
+     */
+    readonly mode: "model";
+    /**
+     * Names the owning npm package.
+     */
+    readonly packageName: string;
+    /**
+     * Locates the package-contained canonical Proto sources.
+     */
+    readonly protoRoot: string;
+    /**
+     * Locates the package-contained generated TypeScript files.
+     */
+    readonly generatedRoot: string;
+    /**
+     * Names the generated import subpath root.
+     */
+    readonly exportRoot: string;
+    /**
+     * Lists direct model packages from the npm registry.
+     */
+    readonly dependencies: readonly string[];
+    /**
+     * Names the generated model-module export.
+     */
+    readonly moduleExport: string;
+}
+/**
+ * Configures an application that composes published Proto model packages.
+ */
+export interface ApplicationConfig {
+    /**
+     * Declares the version of this configuration contract.
+     */
+    readonly formatVersion: 1;
+    /**
+     * Selects application model composition.
+     */
+    readonly mode: "application";
+    /**
+     * Lists direct model packages from the npm registry.
+     */
+    readonly modelPackages: readonly string[];
+    /**
+     * Locates the generated package registry source file.
+     */
+    readonly registryOutput: string;
+}
+/**
+ * Version-one model or application configuration selected by mode.
+ */
+export type SpineProtoConfig = ModelConfig | ApplicationConfig;
+/**
+ * Describes the Proto sources and generated exports owned by a model package.
+ */
+export interface ProtoManifest {
+    /**
+     * Declares the version of this manifest contract.
+     */
+    readonly formatVersion: 2;
+    /**
+     * Stores the opaque identifier shared with the generated-root marker.
+     */
+    readonly generationId: string;
+    /**
+     * Names the package that owns every listed Proto source.
+     */
+    readonly packageName: string;
+    /**
+     * States the declared version from the owning package.json file.
+     */
+    readonly packageVersion: string;
+    /**
+     * Lists canonical package-relative Proto paths owned by the package.
+     */
+    readonly protoFiles: readonly string[];
+    /**
+     * Maps each Proto path to its generated package-relative import subpath.
+     */
+    readonly generatedExports: Readonly<Record<string, string>>;
+    /**
+     * Lists direct model-package dependencies.
+     */
+    readonly dependencies: readonly string[];
+    /**
+     * Names the generated ProtoModule export.
+     */
+    readonly moduleExport: string;
+}
+/**
+ * Provides access to the versioned Proto package configuration.
+ */
+export declare const ProtoConfig: Readonly<{
+    /**
+     * Reads and validates `spine-proto.json` at a package root.
+     *
+     * @param packageRoot The package root that contains the configuration.
+     * @returns The validated model or application configuration.
+     */
+    read(packageRoot: string): SpineProtoConfig;
+}>;
+/**
+ * Provides access to deterministic Proto package manifests.
+ */
+export declare const ProtoManifest: Readonly<{
+    /**
+     * Reads and validates a package manifest.
+     *
+     * @param packageRoot The package root that owns the manifest.
+     * @param manifestPath The optional manifest path within the package root.
+     * @returns The validated manifest.
+     */
+    read(packageRoot: string, manifestPath?: string): ProtoManifest;
+    /**
+     * Creates a manifest from package-owned Proto paths. Without a supplied generation ID,
+     * a fresh random ID is assigned for a new generated-root marker lifecycle.
+     *
+     * @param packageRoot The model package root.
+     * @param ownedProtoFiles Optional explicit package-relative Proto paths.
+     * @param generationId Optional generation ID; a random ID is used when omitted.
+     * @returns The created manifest.
+     */
+    create(packageRoot: string, ownedProtoFiles?: readonly string[], generationId?: string): ProtoManifest;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AA8BA;;GAEG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAiEvC;;GAEG;AACH,MAAM,WAAW,WAAW;IAG1B;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAEzC;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAGhC;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAE1C;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,iBAAiB,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,aAAa;IAG5B;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAEvC;;OAEG;IACH,QAAQ,CAAC,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAE5D;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAEzC;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAumBD;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC;IAGjC;;;;;OAKG;IACH,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAAC;CAC7C,CAYC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC;IAGnC;;;;;;OAMG;IACH,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC;IAEhE;;;;;;;;OAQG;IACH,MAAM,CACJ,WAAW,EAAE,MAAM,EACnB,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,EACnC,YAAY,CAAC,EAAE,MAAM,GACpB,aAAa,CAAC;CAClB,CA2CC,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,546 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { closeSync, constants, fstatSync, lstatSync, openSync, opendirSync, readFileSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { isAbsolute, join, normalize, sep } from "node:path";
+import { generationMarkerFile } from "./generation/generation-reuse.mjs";
+import { RegistryDependency } from "./model/registry-dependency.js";
+import { NpmPackageName } from "./model/npm-package-name.js";
+/**
+ * Published manifest JSON revision.
+ */
+export const manifestFormatVersion = 2;
+const configFormatVersion = 1;
+const manifestReadAttempts = 3;
+const manifestCommitDelayMs = 25;
+const generationClaimScanLimit = 1_000;
+function waitForManifestCommit() {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT)), 0, 0, manifestCommitDelayMs);
+}
+function hasLiveGenerationClaim(packageRoot) {
+    try {
+        const directory = opendirSync(packageRoot, { encoding: "utf8" });
+        try {
+            let entry;
+            const claimPaths = [];
+            while ((entry = directory.readSync()) !== null) {
+                if (!entry.name.startsWith(".spine-proto-generate.lock."))
+                    continue;
+                claimPaths.push(join(packageRoot, entry.name));
+                if (claimPaths.length > generationClaimScanLimit)
+                    throw new Error("generation claim count exceeds 1000");
+            }
+            for (const path of claimPaths) {
+                let descriptor;
+                let owner;
+                try {
+                    descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+                    if (!fstatSync(descriptor).isFile())
+                        throw new Error("generation claim is unsafe");
+                    owner = JSON.parse(readFileSync(descriptor, "utf8"));
+                }
+                catch (error) {
+                    if (error instanceof Error && error.message === "generation claim is unsafe")
+                        throw error;
+                    throw new Error("generation claim is unsafe", { cause: error });
+                }
+                finally {
+                    if (descriptor !== undefined)
+                        closeSync(descriptor);
+                }
+                if (typeof owner.pid !== "number" || owner.pid <= 0)
+                    continue;
+                try {
+                    process.kill(owner.pid, 0);
+                    return true;
+                }
+                catch (error) {
+                    if (error.code !== "ESRCH")
+                        return true;
+                }
+            }
+        }
+        finally {
+            directory.closeSync();
+        }
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            ["generation claim count exceeds 1000", "generation claim is unsafe"].includes(error.message))
+            throw error;
+        return false;
+    }
+    return false;
+}
+const reservedBindings = new Set([
+    "await",
+    "break",
+    "case",
+    "catch",
+    "class",
+    "const",
+    "continue",
+    "default",
+    "delete",
+    "do",
+    "else",
+    "enum",
+    "export",
+    "extends",
+    "false",
+    "finally",
+    "for",
+    "function",
+    "if",
+    "import",
+    "in",
+    "instanceof",
+    "let",
+    "new",
+    "null",
+    "return",
+    "super",
+    "switch",
+    "this",
+    "throw",
+    "true",
+    "try",
+    "typeof",
+    "var",
+    "void",
+    "while",
+    "with",
+    "yield",
+]);
+/**
+ * Reports invalid contained Proto package contracts.
+ */
+const ProtoPackageErrors = Object.freeze({
+    fail(name, message) {
+        throw new Error(`spine-proto: ${name}: ${message}`);
+    },
+});
+/**
+ * Reads, validates, and creates contained Proto package contracts.
+ */
+const ProtoPackage = Object.freeze({
+    // prettier-ignore
+    /**
+     * Reads and validates versioned `spine-proto.json` package configuration.
+     */
+    configFromPackage(packageRoot) {
+        const packageJson = ProtoPackage.readPackage(packageRoot);
+        const config = ProtoPackage.objectValue(packageJson.name, ProtoPackage.readJson(join(packageRoot, "spine-proto.json"), packageJson.name), "configuration");
+        if (config.formatVersion !== configFormatVersion)
+            ProtoPackageErrors.fail(packageJson.name, "formatVersion must be 1");
+        if (config.mode !== "model" && config.mode !== "application")
+            ProtoPackageErrors.fail(packageJson.name, "mode must be model or application");
+        if (config.mode === "application") {
+            ProtoPackage.rejectKeys(packageJson.name, config, ["formatVersion", "mode", "modelPackages", "registryOutput"], "application mode");
+            const modelPackages = ProtoPackage.packageNameList(packageJson.name, config.modelPackages, "modelPackages");
+            ProtoPackage.validateRegistryDependencies(packageJson, modelPackages, "model package");
+            const registryOutput = ProtoPackage.packagePath(packageRoot, packageJson.name, config.registryOutput, "registryOutput");
+            if (ProtoPackage.isReservedOutput(registryOutput))
+                ProtoPackageErrors.fail(packageJson.name, "registryOutput must name a safe source file");
+            return {
+                formatVersion: 1,
+                mode: "application",
+                modelPackages,
+                registryOutput,
+            };
+        }
+        ProtoPackage.rejectKeys(packageJson.name, config, [
+            "formatVersion",
+            "mode",
+            "packageName",
+            "protoRoot",
+            "generatedRoot",
+            "exportRoot",
+            "dependencies",
+            "moduleExport",
+        ], "model mode");
+        const packageName = ProtoPackage.packageNameValue(packageJson.name, config.packageName, "packageName");
+        if (packageName !== packageJson.name)
+            ProtoPackageErrors.fail(packageJson.name, "packageName must match package.json name");
+        const dependencies = ProtoPackage.packageNameList(packageJson.name, config.dependencies, "dependencies");
+        ProtoPackage.validateRegistryDependencies(packageJson, dependencies, "dependency");
+        const protoRoot = ProtoPackage.packagePath(packageRoot, packageJson.name, config.protoRoot, "protoRoot");
+        const generatedRoot = ProtoPackage.packagePath(packageRoot, packageJson.name, config.generatedRoot, "generatedRoot");
+        if (generatedRoot === "." ||
+            ["package.json", "spine-proto.json", "spine-proto-manifest.json"].includes(generatedRoot) ||
+            ProtoPackage.pathsOverlap(protoRoot, generatedRoot))
+            ProtoPackageErrors.fail(packageJson.name, "generatedRoot must not overlap protoRoot or package root");
+        const exportRoot = ProtoPackage.packagePath(packageRoot, packageJson.name, config.exportRoot, "exportRoot");
+        ProtoPackage.validateGeneratedExports(packageJson, exportRoot);
+        return {
+            formatVersion: 1,
+            mode: "model",
+            packageName,
+            protoRoot,
+            generatedRoot,
+            exportRoot,
+            dependencies,
+            moduleExport: ProtoPackage.bindingIdentifier(packageJson.name, config.moduleExport, "moduleExport"),
+        };
+    },
+    /**
+     * Validates a deterministic manifest shipped by a model package.
+     */
+    manifestFromPackage(packageRoot, manifestPath = join(packageRoot, "spine-proto-manifest.json")) {
+        const packageJson = ProtoPackage.readPackage(packageRoot);
+        const manifest = ProtoPackage.manifestFromValue(ProtoPackage.readJson(manifestPath, packageJson.name), packageJson.name);
+        if (manifest.packageName !== packageJson.name)
+            ProtoPackageErrors.fail(packageJson.name, "manifest packageName must match package.json name");
+        if (manifest.packageVersion !== packageJson.version)
+            ProtoPackageErrors.fail(packageJson.name, "manifest packageVersion must match package.json version");
+        const config = ProtoPackage.configFromPackage(packageRoot);
+        if (config.mode !== "model")
+            ProtoPackageErrors.fail(packageJson.name, "manifest requires model mode");
+        const marker = ProtoPackage.objectValue(packageJson.name, ProtoPackage.readJson(join(packageRoot, config.generatedRoot, generationMarkerFile), packageJson.name), "generated-root marker");
+        ProtoPackage.rejectKeys(packageJson.name, marker, ["generationId"], "generated-root marker");
+        if (ProtoPackage.stringValue(packageJson.name, marker.generationId, "generated-root marker generationId") !== manifest.generationId)
+            ProtoPackageErrors.fail(packageJson.name, "manifest generationId must match generated-root marker");
+        for (const protoFile of manifest.protoFiles) {
+            ProtoPackage.assertNoSymlinkAncestor(packageRoot, packageJson.name, protoFile, "manifest protoFiles");
+            ProtoPackage.assertNoSymlinkAncestor(packageRoot, packageJson.name, manifest.generatedExports[protoFile] ?? "", `manifest generated export for ${protoFile}`);
+        }
+        return manifest;
+    },
+    /**
+     * Builds a deterministic manifest from a model package's owned Proto paths.
+     */
+    manifestForPackage(packageRoot, ownedProtoFiles, generationId = randomUUID()) {
+        const config = ProtoPackage.configFromPackage(packageRoot);
+        if (config.mode !== "model")
+            ProtoPackageErrors.fail(ProtoPackage.readPackage(packageRoot).name, "manifest requires model mode");
+        const packageJson = ProtoPackage.readPackage(packageRoot);
+        if (ownedProtoFiles !== undefined && ownedProtoFiles.length > 10000)
+            ProtoPackageErrors.fail(packageJson.name, "owned Proto paths exceeds 10000 entries");
+        const protoFiles = (ownedProtoFiles ??
+            ProtoPackage.discoverProtoFiles(join(packageRoot, config.protoRoot), packageJson.name))
+            .map((file) => ProtoPackage.protoPath(packageRoot, packageJson.name, config.protoRoot, file))
+            .sort();
+        if (new Set(protoFiles).size !== protoFiles.length)
+            ProtoPackageErrors.fail(packageJson.name, "duplicate proto path");
+        return {
+            formatVersion: manifestFormatVersion,
+            generationId: ProtoPackage.stringValue(packageJson.name, generationId, "manifest generationId"),
+            packageName: packageJson.name,
+            packageVersion: packageJson.version,
+            protoFiles,
+            generatedExports: Object.fromEntries(protoFiles.map((file) => [
+                file,
+                ProtoPackage.exportPath(packageJson.name, config.exportRoot, file),
+            ])),
+            dependencies: [...config.dependencies].sort(),
+            moduleExport: config.moduleExport,
+        };
+    },
+    manifestFromValue(value, requester) {
+        const manifest = ProtoPackage.objectValue(requester, value, "manifest");
+        ProtoPackage.rejectKeys(requester, manifest, [
+            "formatVersion",
+            "generationId",
+            "packageName",
+            "packageVersion",
+            "protoFiles",
+            "generatedExports",
+            "dependencies",
+            "moduleExport",
+        ], "manifest");
+        if (manifest.formatVersion !== manifestFormatVersion)
+            ProtoPackageErrors.fail(requester, "manifest formatVersion must be 2");
+        const generationId = ProtoPackage.stringValue(requester, manifest.generationId, "manifest generationId");
+        const protoFiles = ProtoPackage.stringList(requester, manifest.protoFiles, "manifest protoFiles")
+            .map((file) => ProtoPackage.manifestPath(requester, file, "manifest protoFiles"))
+            .sort();
+        const generatedExports = ProtoPackage.objectValue(requester, manifest.generatedExports, "manifest generatedExports");
+        ProtoPackage.assertRecordBound(requester, generatedExports, "manifest generatedExports");
+        const keys = Object.keys(generatedExports).sort();
+        if (keys.length !== protoFiles.length || keys.some((key, index) => key !== protoFiles[index])) {
+            ProtoPackageErrors.fail(requester, "manifest generatedExports must map every proto file exactly once");
+        }
+        return {
+            formatVersion: manifestFormatVersion,
+            generationId,
+            packageName: ProtoPackage.packageNameValue(requester, manifest.packageName, "manifest packageName"),
+            packageVersion: ProtoPackage.stringValue(requester, manifest.packageVersion, "manifest packageVersion"),
+            protoFiles,
+            generatedExports: Object.fromEntries(protoFiles.map((file) => [
+                file,
+                ProtoPackage.manifestPath(requester, generatedExports[file], `manifest generated export for ${file}`),
+            ])),
+            dependencies: [
+                ...ProtoPackage.packageNameList(requester, manifest.dependencies, "manifest dependencies"),
+            ].sort(),
+            moduleExport: ProtoPackage.bindingIdentifier(requester, manifest.moduleExport, "manifest moduleExport"),
+        };
+    },
+    discoverProtoFiles(root, name) {
+        const files = [];
+        const pending = [{ path: root, relativePath: "", depth: 0 }];
+        let encountered = 0;
+        while (pending.length > 0) {
+            const directory = pending.pop();
+            if (directory === undefined)
+                break;
+            let directoryHandle;
+            try {
+                directoryHandle = opendirSync(directory.path, { encoding: "utf8" });
+            }
+            catch {
+                ProtoPackageErrors.fail(name, "proto root is missing or inaccessible");
+            }
+            try {
+                for (let entry = directoryHandle.readSync(); entry !== null; entry = directoryHandle.readSync()) {
+                    encountered += 1;
+                    if (encountered > 10000)
+                        ProtoPackageErrors.fail(name, "proto source exceeds 10000 entries");
+                    const relativePath = directory.relativePath === "" ? entry.name : `${directory.relativePath}/${entry.name}`;
+                    if (entry.isDirectory()) {
+                        if (directory.depth >= 100)
+                            ProtoPackageErrors.fail(name, "proto source exceeds 100 directory levels");
+                        pending.push({
+                            path: join(directory.path, entry.name),
+                            relativePath,
+                            depth: directory.depth + 1,
+                        });
+                    }
+                    else if (entry.isFile() && entry.name.endsWith(".proto")) {
+                        files.push(relativePath);
+                    }
+                }
+            }
+            finally {
+                directoryHandle.closeSync();
+            }
+        }
+        return files;
+    },
+    protoPath(packageRoot, name, protoRoot, value) {
+        const path = ProtoPackage.manifestPath(name, value, "proto path");
+        ProtoPackage.assertNoSymlinkAncestor(packageRoot, name, join(protoRoot, path), "proto path");
+        return path;
+    },
+    exportPath(name, exportRoot, protoPath) {
+        return ProtoPackage.manifestPath(name, `${exportRoot}/${protoPath.replace(/\.proto$/, "_pb.js")}`, "generated export");
+    },
+    packagePath(packageRoot, name, value, label) {
+        const path = ProtoPackage.manifestPath(name, value, label);
+        ProtoPackage.assertNoSymlinkAncestor(packageRoot, name, path, label);
+        return path;
+    },
+    pathsOverlap(left, right) {
+        return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+    },
+    isReservedOutput(path) {
+        return (path === "." ||
+            ["package.json", "spine-proto.json", "spine-proto-manifest.json"].includes(path) ||
+            !path.includes("."));
+    },
+    bindingIdentifier(name, value, label) {
+        const identifier = ProtoPackage.stringValue(name, value, label);
+        if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(identifier) || reservedBindings.has(identifier))
+            ProtoPackageErrors.fail(name, `${label} must be a legal ESM binding identifier`);
+        return identifier;
+    },
+    manifestPath(name, value, label) {
+        const path = ProtoPackage.stringValue(name, value, label).replaceAll("\\", "/");
+        if (isAbsolute(path))
+            ProtoPackageErrors.fail(name, `${label} must be relative`);
+        if (path.split("/").includes(".."))
+            ProtoPackageErrors.fail(name, `${label} must not contain traversal`);
+        if (path.endsWith("/") || normalize(path).replaceAll("\\", "/") !== path) {
+            ProtoPackageErrors.fail(name, `${label} must be a normalized contained relative path`);
+        }
+        return path;
+    },
+    assertNoSymlinkAncestor(packageRoot, name, path, label) {
+        let current = packageRoot;
+        for (const segment of path.split("/")) {
+            current = join(current, segment);
+            try {
+                if (lstatSync(current).isSymbolicLink())
+                    ProtoPackageErrors.fail(name, `${label} must not pass through a symlink`);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+    },
+    validateRegistryDependencies(packageJson, names, label) {
+        for (const name of names) {
+            const specifier = packageJson.dependencies[name];
+            if (specifier === undefined) {
+                ProtoPackageErrors.fail(packageJson.name, `${label} ${name} must be declared in package.json dependencies`);
+            }
+            if (!RegistryDependency.is(specifier)) {
+                ProtoPackageErrors.fail(packageJson.name, `${label} ${name} must use a registry version`);
+            }
+        }
+    },
+    validateGeneratedExports(packageJson, exportRoot) {
+        const key = `./${exportRoot}/*.js`;
+        const entry = packageJson.exports[key];
+        const expectedRuntime = `./dist/${exportRoot}/*.js`;
+        const expectedTypes = `./dist/${exportRoot}/*.d.ts`;
+        if (typeof entry !== "object" ||
+            entry === null ||
+            Array.isArray(entry) ||
+            entry.default !== expectedRuntime ||
+            entry.types !== expectedTypes) {
+            ProtoPackageErrors.fail(packageJson.name, `package.json exports must expose ${key} with default ${expectedRuntime} and types ${expectedTypes}`);
+        }
+    },
+    readPackage(packageRoot) {
+        const value = ProtoPackage.objectValue(packageRoot, ProtoPackage.readJson(join(packageRoot, "package.json"), packageRoot), "package.json");
+        const name = ProtoPackage.packageNameValue(packageRoot, value.name, "package.json name");
+        return {
+            name,
+            version: ProtoPackage.stringValue(name, value.version, "package.json version"),
+            dependencies: ProtoPackage.stringRecord(value.dependencies, name, "package.json dependencies"),
+            exports: value.exports === undefined
+                ? {}
+                : ProtoPackage.objectValue(name, value.exports, "package.json exports"),
+        };
+    },
+    readJson(path, name) {
+        let descriptor;
+        try {
+            descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            if (!fstatSync(descriptor).isFile())
+                throw new Error("unsafe JSON input");
+            return JSON.parse(readFileSync(descriptor, "utf8"));
+        }
+        catch {
+            return ProtoPackageErrors.fail(name, `cannot read ${path.split(sep).at(-1) ?? path}`);
+        }
+        finally {
+            if (descriptor !== undefined)
+                closeSync(descriptor);
+        }
+    },
+    objectValue(name, value, label) {
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            return ProtoPackageErrors.fail(name, `${label} must be an object`);
+        return value;
+    },
+    stringValue(name, value, label) {
+        if (typeof value !== "string" || value.length === 0)
+            return ProtoPackageErrors.fail(name, `${label} must be a non-empty string`);
+        return value;
+    },
+    stringList(name, value, label) {
+        if (!Array.isArray(value))
+            ProtoPackageErrors.fail(name, `${label} must be an array of non-empty strings`);
+        if (value.length > 10000)
+            ProtoPackageErrors.fail(name, `${label} exceeds 10000 entries`);
+        const strings = value.filter((item) => typeof item === "string" && item.length > 0);
+        if (strings.length !== value.length)
+            ProtoPackageErrors.fail(name, `${label} must be an array of non-empty strings`);
+        if (new Set(strings).size !== strings.length)
+            ProtoPackageErrors.fail(name, `${label} must not contain duplicates`);
+        return strings;
+    },
+    packageNameValue(name, value, label) {
+        const packageName = ProtoPackage.stringValue(name, value, label);
+        if (!NpmPackageName.is(packageName))
+            ProtoPackageErrors.fail(name, `${label} must be a valid npm package name`);
+        return packageName;
+    },
+    packageNameList(name, value, label) {
+        return ProtoPackage.stringList(name, value, label).map((packageName) => ProtoPackage.packageNameValue(name, packageName, label));
+    },
+    assertRecordBound(name, record, label) {
+        let count = 0;
+        for (const key in record) {
+            if (!Object.hasOwn(record, key))
+                continue;
+            count += 1;
+            if (count > 10000)
+                ProtoPackageErrors.fail(name, `${label} exceeds 10000 entries`);
+        }
+    },
+    stringRecord(value, name, label) {
+        if (value === undefined)
+            return {};
+        const record = ProtoPackage.objectValue(name, value, label);
+        if (!Object.values(record).every((item) => typeof item === "string"))
+            ProtoPackageErrors.fail(name, `${label} must contain string versions`);
+        return record;
+    },
+    rejectKeys(name, value, allowed, label) {
+        const unexpected = Object.keys(value).find((key) => !allowed.includes(key));
+        if (unexpected !== undefined)
+            ProtoPackageErrors.fail(name, `${label} must not declare ${unexpected}`);
+    },
+});
+/**
+ * Provides access to the versioned Proto package configuration.
+ */
+export const ProtoConfig = Object.freeze({
+    // prettier-ignore
+    /**
+     * Reads and validates `spine-proto.json` at a package root.
+     *
+     * @param packageRoot The package root that contains the configuration.
+     * @returns The validated model or application configuration.
+     */
+    read(packageRoot) {
+        return ProtoPackage.configFromPackage(packageRoot);
+    },
+});
+/**
+ * Provides access to deterministic Proto package manifests.
+ */
+export const ProtoManifest = Object.freeze({
+    // prettier-ignore
+    /**
+     * Reads and validates a package manifest.
+     *
+     * @param packageRoot The package root that owns the manifest.
+     * @param manifestPath The optional manifest path within the package root.
+     * @returns The validated manifest.
+     */
+    read(packageRoot, manifestPath = join(packageRoot, "spine-proto-manifest.json")) {
+        let failure;
+        for (let attempt = 0; attempt < manifestReadAttempts; attempt += 1) {
+            try {
+                return ProtoPackage.manifestFromPackage(packageRoot, manifestPath);
+            }
+            catch (error) {
+                failure = error;
+                if (!hasLiveGenerationClaim(packageRoot))
+                    throw error;
+                if (attempt + 1 < manifestReadAttempts)
+                    waitForManifestCommit();
+            }
+        }
+        throw failure;
+    },
+    /**
+     * Creates a manifest from package-owned Proto paths. Without a supplied generation ID,
+     * a fresh random ID is assigned for a new generated-root marker lifecycle.
+     *
+     * @param packageRoot The model package root.
+     * @param ownedProtoFiles Optional explicit package-relative Proto paths.
+     * @param generationId Optional generation ID; a random ID is used when omitted.
+     * @returns The created manifest.
+     */
+    create(packageRoot, ownedProtoFiles, generationId) {
+        return ProtoPackage.manifestForPackage(packageRoot, ownedProtoFiles, generationId);
+    },
+});
+//# sourceMappingURL=index.js.map