@wasm-oj/contracts 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JacobLinCool
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,4 @@
+# `@wasm-oj/contracts`
+
+Environment-neutral WASM-OJ SDK contracts, wire models, errors, and toolchain source types.
+This package has no runtime dependencies and is safe to import from Node.js, browsers, and Workers.

package/dist/index.d.ts

@@ -0,0 +1,468 @@
+/**
+ * The single compatibility boundary shared by WASM-OJ compilers, runners,
+ * artifacts, judge specifications, caches, and conformance evidence.
+ *
+ * Package and upstream toolchain versions remain independent release metadata;
+ * they do not define WASM-OJ protocol compatibility.
+ */
+declare const WASM_OJ_CONTRACT_VERSION: 2;
+declare const WASM_OJ_CONTRACT_ID: "wasm-oj-v2";
+declare const WASM_OJ_SCHEMAS: Readonly<{
+    readonly clangPins: "wasm-oj-v2/clang-pins";
+    readonly clangLibcxxPch: "wasm-oj-v2/clang-libcxx-pch";
+    readonly clangToolchain: "wasm-oj-v2/clang-toolchain";
+    readonly compileBatch: "wasm-oj-v2/compile-batch";
+    readonly compileTrace: "wasm-oj-v2/compile-trace";
+    readonly conformance: "wasm-oj-v2/conformance";
+    readonly conformanceEvidence: "wasm-oj-v2/conformance-evidence";
+    readonly conformanceMatrix: "wasm-oj-v2/conformance-matrix";
+    readonly cppDependencyLock: "wasm-oj-v2/cpp-dependency-lock";
+    readonly dependencyLock: "wasm-oj-v2/dependency-lock";
+    readonly dependencyOfflineBundle: "wasm-oj-v2/dependency-offline-bundle";
+    readonly incrementalBuildGraph: "wasm-oj-v2/incremental-build-graph";
+    readonly interactiveRequest: "wasm-oj-v2/interactive-request";
+    readonly goToolchain: "wasm-oj-v2/go-toolchain";
+    readonly objectCache: "wasm-oj-v2/object-cache";
+    readonly pythonToolchain: "wasm-oj-v2/python-toolchain";
+    readonly replayBundle: "wasm-oj-v2/replay-bundle";
+    readonly releaseManifest: "wasm-oj-v2/release-manifest";
+    readonly rustToolchain: "wasm-oj-v2/rust-toolchain";
+    readonly runRequest: "wasm-oj-v2/run-request";
+    readonly runtimeBundle: "wasm-oj-v2/runtime-bundle";
+    readonly runtimeCoreLicenses: "wasm-oj-v2/runtime-core-licenses";
+    readonly thirdPartyComponents: "wasm-oj-v2/third-party-components";
+    readonly wasmerSdkLicenses: "wasm-oj-v2/wasmer-sdk-licenses";
+    readonly toolchainPackage: "wasm-oj-v2/toolchain-package";
+}>;
+declare const WASM_OJ_STORAGE: Readonly<{
+    readonly database: "wasm-oj-v2:storage";
+    readonly databaseVersion: 2;
+    readonly dependencyCache: "wasm-oj-v2:dependencies";
+    readonly incrementalBuildCache: "wasm-oj-v2:incremental-build-cache";
+    readonly runtimeFilesCache: "wasm-oj-v2:runtime-files";
+    readonly toolchainCache: "wasm-oj-v2:toolchains";
+}>;
+
+declare const LANGUAGES: readonly ["c", "cpp", "rust", "python", "javascript", "typescript", "go"];
+type BuiltinLanguage = (typeof LANGUAGES)[number];
+/**
+ * Stable language identity carried by projects and artifacts.
+ *
+ * WASM-OJ ships the values in `LANGUAGES`; downstream compiler implementations
+ * may use their own non-empty identifier without forking the contract.
+ */
+type Language = BuiltinLanguage | (string & {});
+declare function assertLanguageIdentifier(language: unknown): asserts language is Language;
+declare function isBuiltinLanguage(language: string): language is BuiltinLanguage;
+type TargetAbi = "wasip1" | "wasix";
+type OptimizationLevel = "debug" | "release";
+declare const DEPENDENCY_ECOSYSTEMS: readonly ["cargo", "npm", "pypi", "go", "cpp"];
+type DependencyEcosystem = (typeof DEPENDENCY_ECOSYSTEMS)[number];
+interface DependencyRequirement {
+    ecosystem: DependencyEcosystem;
+    name: string;
+    requirement: string;
+    features?: readonly string[];
+}
+interface DependencySourceFile {
+    ecosystem: DependencyEcosystem;
+    role: "manifest" | "lockfile" | "source";
+    path: string;
+    contents: string;
+}
+interface DependencyManifest {
+    requirements: readonly DependencyRequirement[];
+    sourceFiles?: readonly DependencySourceFile[];
+}
+interface LockedDependencyPackage {
+    id: string;
+    ecosystem: DependencyEcosystem;
+    name: string;
+    version: string;
+    source: string;
+    integritySha256: string;
+    dependencies: readonly string[];
+    features?: readonly string[];
+}
+interface DependencyLock {
+    schema: typeof WASM_OJ_SCHEMAS.dependencyLock;
+    wasmOjContract: typeof WASM_OJ_CONTRACT_VERSION;
+    manifestSha256: string;
+    roots: readonly string[];
+    packages: readonly LockedDependencyPackage[];
+}
+interface MaterializedDependencyPackage {
+    package: LockedDependencyPackage;
+    filesSha256: string;
+    files: Readonly<Record<string, Uint8Array>>;
+}
+/** Archive-independent, fully verified dependency input admitted by compilers. */
+interface DependencyBuildBundle {
+    lock: DependencyLock;
+    lockSha256: string;
+    packages: readonly MaterializedDependencyPackage[];
+}
+interface ProjectFile {
+    path: string;
+    language: Language;
+    content: string;
+}
+interface BuildConfig {
+    language: Language;
+    target: TargetAbi;
+    optimization: OptimizationLevel;
+    entry: string;
+}
+interface DeterminismConfig {
+    /** Unsigned 32-bit seed used by every guest entropy source. */
+    randomSeed: number;
+    /** Unix epoch exposed by the first realtime-clock observation. */
+    realtimeEpochMs: number;
+    /** Virtual clock advancement after each clock observation. */
+    clockStepNs: number;
+}
+interface ResourcePolicy {
+    /** Versioned baseline-normalized weighted Wasm instruction budget. */
+    instructionBudget: number;
+    /** Deterministic virtual elapsed-time budget, including sleeps and clock observations. */
+    logicalTimeLimitMs: number;
+    /** Hard upper bound for guest linear memory. */
+    memoryLimitBytes: number;
+    /** Combined stdout and stderr upper bound. */
+    outputLimitBytes: number;
+    /** Additional live VFS file bytes permitted above the mounted baseline. */
+    filesystemWriteLimitBytes: number;
+    /** Additional live VFS entries permitted above the mounted baseline. */
+    filesystemEntryLimit: number;
+    /** Host safety deadline; excluded from the deterministic transcript. */
+    wallTimeLimitMs: number;
+}
+type ExecutionTermination = "exited" | "instruction-limit" | "logical-time-limit" | "memory-limit" | "output-limit" | "filesystem-limit" | "wall-time-limit" | "trap";
+interface ExecutionMetrics {
+    /** Baseline-normalized weighted deterministic cost used for judging. */
+    cost: number | null;
+    /** Unadjusted weighted cost observed by the runtime core. */
+    rawCost: number | null;
+    /** Empty-program cost subtracted from rawCost. */
+    baselineCost: number;
+    /** Versioned compiler/runtime baseline identity. */
+    costProfile: string;
+    /** Meter policy used to interpret cost. */
+    costModel: string;
+    /** WARK-compatible static counts of original Wasm operators. */
+    operations: Readonly<Record<string, number>> | null;
+    /** Peak linear-memory allocation observed by the runner. */
+    memoryBytes: number | null;
+    /** Deterministic virtual time elapsed during execution. */
+    logicalTimeNs: number | null;
+    /** Peak live VFS file bytes, including the mounted baseline. */
+    filesystemBytes: number | null;
+    /** Peak live VFS inode count, excluding the root inode. */
+    filesystemEntries: number | null;
+    stdoutBytes: number | null;
+    stderrBytes: number | null;
+}
+interface RunConfig {
+    args: string[];
+    stdin: string;
+    env: Record<string, string>;
+    /** Absolute, normalized guest files mounted before execution. */
+    files?: Record<string, Uint8Array>;
+    /** Absolute, normalized guest files collected after execution. */
+    outputPaths?: string[];
+    /** Absolute, normalized initial working directory. */
+    cwd?: string;
+    determinism: DeterminismConfig;
+    resources: ResourcePolicy;
+}
+interface ProjectConfig extends BuildConfig, RunConfig {
+}
+interface Project {
+    id: string;
+    name: string;
+    files: ProjectFile[];
+    config: ProjectConfig;
+    activeFile: string;
+    updatedAt: number;
+    /** Verified archive-independent dependency input, if this project uses packages. */
+    dependencies?: DependencyBuildBundle;
+}
+type DiagnosticSeverity = "error" | "warning" | "info";
+interface Diagnostic {
+    severity: DiagnosticSeverity;
+    message: string;
+    file: string;
+    line: number;
+    column: number;
+    endLine?: number;
+    endColumn?: number;
+    source: string;
+    code?: string;
+}
+interface ArtifactMetadata {
+    /** WASM-OJ compatibility contract required to consume this artifact. */
+    wasmOjContract: typeof WASM_OJ_CONTRACT_VERSION;
+    id: string;
+    projectId: string;
+    cacheKey: string;
+    name: string;
+    language: Language;
+    target: TargetAbi;
+    optimization: OptimizationLevel;
+    createdAt: number;
+    durationMs: number;
+    size: number;
+    toolchains: string[];
+    /** Trusted empty-program cost profile selected by the compiler contract. */
+    costProfile: string;
+    /** Canonical dependency lock used for this build. */
+    dependencyLockSha256?: string;
+}
+interface WasmArtifact extends ArtifactMetadata {
+    kind: "wasm";
+    bytes: Uint8Array;
+}
+interface RuntimeBundleArtifact extends ArtifactMetadata {
+    kind: "runtime-bundle";
+    runtimePackage: string;
+    command: string;
+    entry: string;
+    files: Record<string, string | Uint8Array>;
+    manifest: string;
+}
+type BuildArtifact = WasmArtifact | RuntimeBundleArtifact;
+interface BuildResult {
+    success: boolean;
+    diagnostics: Diagnostic[];
+    artifact?: BuildArtifact;
+    stdout: string;
+    stderr: string;
+    cacheHit: boolean;
+    buildGraph?: {
+        hits: Partial<Record<"pch" | "object" | "link-result", number>>;
+        misses: Partial<Record<"pch" | "object" | "link-result", number>>;
+        stores: Partial<Record<"pch" | "object" | "link-result", number>>;
+    };
+}
+interface RunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+    /** Requested output files that existed when the process terminated. */
+    files: Record<string, Uint8Array>;
+    durationMs: number;
+    determinism: DeterminismConfig;
+    resources: ResourcePolicy;
+    termination: ExecutionTermination;
+    /** Runtime trap text when termination is `trap`; absent for normal guest exits. */
+    trapMessage?: string;
+    metrics: ExecutionMetrics;
+}
+interface InteractiveProgramConfig {
+    args: string[];
+    env: Record<string, string>;
+    files?: Record<string, Uint8Array>;
+    cwd?: string;
+    resources: ResourcePolicy;
+}
+interface InteractiveRunConfig {
+    contestant: InteractiveProgramConfig;
+    interactor: InteractiveProgramConfig;
+    determinism: DeterminismConfig;
+}
+interface InteractiveProcessResult {
+    code: number;
+    stderr: string;
+    termination: ExecutionTermination;
+    metrics: ExecutionMetrics;
+}
+interface InteractiveRunResult {
+    contestant: InteractiveProcessResult;
+    interactor: InteractiveProcessResult;
+    contestantToInteractor: string;
+    interactorToContestant: string;
+    durationMs: number;
+    determinism: DeterminismConfig;
+}
+type WorkerPhase = "initializing" | "restoring-cache" | "loading-toolchain" | "checking" | "compiling" | "linking" | "packaging" | "running";
+interface WorkerProgress {
+    phase: WorkerPhase;
+    label: string;
+    progress?: number;
+}
+/** Content-pinned host extension loaded inside the browser runner Worker. */
+interface BrowserRuntimeDriverPlugin {
+    /** Stable host-selected identity; the constructed RuntimeDriver must use the same ID. */
+    id: string;
+    /** Same-origin URL of one self-contained ESM module. */
+    moduleUrl: string;
+    /** Lowercase SHA-256 of the exact ESM source bytes. */
+    sha256: string;
+    /** Named factory export. Defaults to `createRuntimeDriver`. */
+    exportName?: string;
+}
+interface ToolchainProfile {
+    language: Language;
+    target: TargetAbi;
+    optimization: OptimizationLevel;
+}
+interface ToolchainAssetDescriptor {
+    /** Logical filename expected by the compiler/runtime implementation. */
+    path: string;
+    bytes: number;
+    sha256: string;
+    /** Exact package export used by deployment tooling. */
+    exportPath: string;
+}
+interface ToolchainDescriptor {
+    schema: typeof WASM_OJ_SCHEMAS.toolchainPackage;
+    id: string;
+    version: string;
+    wasmOjContract: typeof WASM_OJ_CONTRACT_VERSION;
+    languages: readonly Language[];
+    profiles: readonly ToolchainProfile[];
+    assets: readonly ToolchainAssetDescriptor[];
+}
+interface BrowserToolchainSource {
+    kind: "browser";
+    descriptor: ToolchainDescriptor;
+    baseUrl: string;
+}
+interface ServerToolchainSource {
+    kind: "server";
+    descriptor: ToolchainDescriptor;
+    directory: URL;
+}
+type ToolchainSource = BrowserToolchainSource | ServerToolchainSource;
+type CompilerTraceOperation = "workerInitialize" | "toolchainFetch" | "toolchainDecode" | "toolchainLoad" | "filesystemPrepare" | "commandStart" | "commandWait" | "projectCompile" | "runtimeShimCompile" | "link" | "projectSpawn" | "projectWait" | "runtimeShimSpawn" | "runtimeShimWait" | "linkSpawn" | "linkWait" | "projectOutputReady" | "runtimeShimOutputReady" | "linkOutputReady" | "artifactReadback";
+/** Host-observed compiler timing mark; excluded from deterministic contracts and cache keys. */
+interface CompilerTraceEvent {
+    schema: typeof WASM_OJ_SCHEMAS.compileTrace;
+    operation: CompilerTraceOperation;
+    state: "start" | "end";
+    monotonicMs: number;
+}
+type CompilerRequest = {
+    type: "initialize";
+    requestId: string;
+    toolchains: readonly BrowserToolchainSource[];
+} | {
+    type: "build";
+    requestId: string;
+    project: Project;
+    cacheKey: string;
+} | {
+    type: "quiesce";
+    requestId: string;
+};
+type RunnerRequest = {
+    type: "initialize";
+    requestId: string;
+    toolchains: readonly BrowserToolchainSource[];
+    additionalCostBaselines?: Readonly<Record<string, number>>;
+    runtimeDriverPlugins?: readonly BrowserRuntimeDriverPlugin[];
+} | {
+    type: "run";
+    requestId: string;
+    artifact: BuildArtifact;
+    config: RunConfig;
+} | {
+    type: "interact";
+    requestId: string;
+    contestant: BuildArtifact;
+    interactor: BuildArtifact;
+    config: InteractiveRunConfig;
+} | {
+    type: "clear-runtime-cache";
+    requestId: string;
+};
+type CompilerResponse = {
+    type: "ready";
+    requestId: string;
+} | {
+    type: "quiesced";
+    requestId: string;
+} | {
+    type: "progress";
+    requestId: string;
+    progress: WorkerProgress;
+} | {
+    type: "compile-trace";
+    requestId: string;
+    event: CompilerTraceEvent;
+} | {
+    type: "build-result";
+    requestId: string;
+    result: BuildResult;
+} | {
+    type: "error";
+    requestId: string;
+    code: string;
+    message: string;
+    stack?: string;
+};
+type RunnerResponse = {
+    type: "ready";
+    requestId: string;
+} | {
+    type: "progress";
+    requestId: string;
+    progress: WorkerProgress;
+} | {
+    type: "stream";
+    requestId: string;
+    stream: "stdout" | "stderr";
+    chunk: string;
+} | {
+    type: "run-result";
+    requestId: string;
+    result: RunResult;
+} | {
+    type: "interactive-result";
+    requestId: string;
+    result: InteractiveRunResult;
+} | {
+    type: "runtime-cache-cleared";
+    requestId: string;
+} | {
+    type: "error";
+    requestId: string;
+    code: string;
+    message: string;
+    stack?: string;
+};
+
+declare const WASM_OJ_ERROR_CODES: readonly ["operation-cancelled", "operation-conflict", "invalid-input", "unsupported", "integrity-failure", "compiler-failure", "runner-failure", "judge-failure", "replay-failure", "dependency-failure", "storage-failure", "initialization-failure", "disposed", "internal-failure"];
+type WasmOjErrorCode = (typeof WASM_OJ_ERROR_CODES)[number];
+declare const WASM_OJ_ERROR_STAGES: readonly ["operation", "compile", "prepare", "run", "judge", "replay", "dependency", "storage", "initialize"];
+type WasmOjErrorStage = (typeof WASM_OJ_ERROR_STAGES)[number];
+interface WasmOjErrorOptions extends ErrorOptions {
+    code: WasmOjErrorCode;
+    stage: WasmOjErrorStage;
+    retryable?: boolean;
+    operationId?: string;
+    details?: Readonly<Record<string, string | number | boolean | null>>;
+}
+interface WasmOjErrorRecord {
+    name: "WasmOjError";
+    message: string;
+    code: WasmOjErrorCode;
+    stage: WasmOjErrorStage;
+    retryable: boolean;
+    operationId?: string;
+    details?: Readonly<Record<string, string | number | boolean | null>>;
+}
+/** Stable infrastructure failure exposed at public asynchronous boundaries. */
+declare class WasmOjError extends Error {
+    readonly code: WasmOjErrorCode;
+    readonly stage: WasmOjErrorStage;
+    readonly retryable: boolean;
+    readonly operationId?: string;
+    readonly details?: Readonly<Record<string, string | number | boolean | null>>;
+    constructor(message: string, options: WasmOjErrorOptions);
+    toJSON(): WasmOjErrorRecord;
+}
+declare function asWasmOjError(error: unknown, options: Omit<WasmOjErrorOptions, "cause">): WasmOjError;
+
+export { DEPENDENCY_ECOSYSTEMS, LANGUAGES, WASM_OJ_CONTRACT_ID, WASM_OJ_CONTRACT_VERSION, WASM_OJ_ERROR_CODES, WASM_OJ_ERROR_STAGES, WASM_OJ_SCHEMAS, WASM_OJ_STORAGE, WasmOjError, asWasmOjError, assertLanguageIdentifier, isBuiltinLanguage };
+export type { ArtifactMetadata, BrowserRuntimeDriverPlugin, BrowserToolchainSource, BuildArtifact, BuildConfig, BuildResult, BuiltinLanguage, CompilerRequest, CompilerResponse, CompilerTraceEvent, CompilerTraceOperation, DependencyBuildBundle, DependencyEcosystem, DependencyLock, DependencyManifest, DependencyRequirement, DependencySourceFile, DeterminismConfig, Diagnostic, DiagnosticSeverity, ExecutionMetrics, ExecutionTermination, InteractiveProcessResult, InteractiveProgramConfig, InteractiveRunConfig, InteractiveRunResult, Language, LockedDependencyPackage, MaterializedDependencyPackage, OptimizationLevel, Project, ProjectConfig, ProjectFile, ResourcePolicy, RunConfig, RunResult, RunnerRequest, RunnerResponse, RuntimeBundleArtifact, ServerToolchainSource, TargetAbi, ToolchainAssetDescriptor, ToolchainDescriptor, ToolchainProfile, ToolchainSource, WasmArtifact, WasmOjErrorCode, WasmOjErrorOptions, WasmOjErrorRecord, WasmOjErrorStage, WorkerPhase, WorkerProgress };

package/dist/index.js

@@ -0,0 +1,166 @@
+//#region src/core/contract.ts
+/**
+* The single compatibility boundary shared by WASM-OJ compilers, runners,
+* artifacts, judge specifications, caches, and conformance evidence.
+*
+* Package and upstream toolchain versions remain independent release metadata;
+* they do not define WASM-OJ protocol compatibility.
+*/
+var WASM_OJ_CONTRACT_VERSION = 2;
+var WASM_OJ_CONTRACT_ID = `wasm-oj-v2`;
+var WASM_OJ_SCHEMAS = Object.freeze({
+	clangPins: `${WASM_OJ_CONTRACT_ID}/clang-pins`,
+	clangLibcxxPch: `${WASM_OJ_CONTRACT_ID}/clang-libcxx-pch`,
+	clangToolchain: `${WASM_OJ_CONTRACT_ID}/clang-toolchain`,
+	compileBatch: `${WASM_OJ_CONTRACT_ID}/compile-batch`,
+	compileTrace: `${WASM_OJ_CONTRACT_ID}/compile-trace`,
+	conformance: `${WASM_OJ_CONTRACT_ID}/conformance`,
+	conformanceEvidence: `${WASM_OJ_CONTRACT_ID}/conformance-evidence`,
+	conformanceMatrix: `${WASM_OJ_CONTRACT_ID}/conformance-matrix`,
+	cppDependencyLock: `${WASM_OJ_CONTRACT_ID}/cpp-dependency-lock`,
+	dependencyLock: `${WASM_OJ_CONTRACT_ID}/dependency-lock`,
+	dependencyOfflineBundle: `${WASM_OJ_CONTRACT_ID}/dependency-offline-bundle`,
+	incrementalBuildGraph: `${WASM_OJ_CONTRACT_ID}/incremental-build-graph`,
+	interactiveRequest: `${WASM_OJ_CONTRACT_ID}/interactive-request`,
+	goToolchain: `${WASM_OJ_CONTRACT_ID}/go-toolchain`,
+	objectCache: `${WASM_OJ_CONTRACT_ID}/object-cache`,
+	pythonToolchain: `${WASM_OJ_CONTRACT_ID}/python-toolchain`,
+	replayBundle: `${WASM_OJ_CONTRACT_ID}/replay-bundle`,
+	releaseManifest: `${WASM_OJ_CONTRACT_ID}/release-manifest`,
+	rustToolchain: `${WASM_OJ_CONTRACT_ID}/rust-toolchain`,
+	runRequest: `${WASM_OJ_CONTRACT_ID}/run-request`,
+	runtimeBundle: `${WASM_OJ_CONTRACT_ID}/runtime-bundle`,
+	runtimeCoreLicenses: `${WASM_OJ_CONTRACT_ID}/runtime-core-licenses`,
+	thirdPartyComponents: `${WASM_OJ_CONTRACT_ID}/third-party-components`,
+	wasmerSdkLicenses: `${WASM_OJ_CONTRACT_ID}/wasmer-sdk-licenses`,
+	toolchainPackage: `${WASM_OJ_CONTRACT_ID}/toolchain-package`
+});
+var WASM_OJ_STORAGE = Object.freeze({
+	database: `${WASM_OJ_CONTRACT_ID}:storage`,
+	databaseVersion: 2,
+	dependencyCache: `${WASM_OJ_CONTRACT_ID}:dependencies`,
+	incrementalBuildCache: `${WASM_OJ_CONTRACT_ID}:incremental-build-cache`,
+	runtimeFilesCache: `${WASM_OJ_CONTRACT_ID}:runtime-files`,
+	toolchainCache: `${WASM_OJ_CONTRACT_ID}:toolchains`
+});
+//#endregion
+//#region src/core/types.ts
+var LANGUAGES = Object.freeze([
+	"c",
+	"cpp",
+	"rust",
+	"python",
+	"javascript",
+	"typescript",
+	"go"
+]);
+function assertLanguageIdentifier(language) {
+	if (typeof language !== "string" || !language || language !== language.trim() || language.length > 128) throw new Error("Language identifiers must be non-empty, trimmed, and at most 128 characters.");
+}
+function isBuiltinLanguage(language) {
+	return LANGUAGES.includes(language);
+}
+var DEPENDENCY_ECOSYSTEMS = Object.freeze([
+	"cargo",
+	"npm",
+	"pypi",
+	"go",
+	"cpp"
+]);
+//#endregion
+//#region src/core/errors.ts
+var WASM_OJ_ERROR_CODES = Object.freeze([
+	"operation-cancelled",
+	"operation-conflict",
+	"invalid-input",
+	"unsupported",
+	"integrity-failure",
+	"compiler-failure",
+	"runner-failure",
+	"judge-failure",
+	"replay-failure",
+	"dependency-failure",
+	"storage-failure",
+	"initialization-failure",
+	"disposed",
+	"internal-failure"
+]);
+var WASM_OJ_ERROR_STAGES = Object.freeze([
+	"operation",
+	"compile",
+	"prepare",
+	"run",
+	"judge",
+	"replay",
+	"dependency",
+	"storage",
+	"initialize"
+]);
+/** Stable infrastructure failure exposed at public asynchronous boundaries. */
+var WasmOjError = class extends Error {
+	code;
+	stage;
+	retryable;
+	operationId;
+	details;
+	constructor(message, options) {
+		super(message, options);
+		if (!WASM_OJ_ERROR_CODES.includes(options.code)) throw new TypeError(`Invalid WASM-OJ error code '${String(options.code)}'.`);
+		if (!WASM_OJ_ERROR_STAGES.includes(options.stage)) throw new TypeError(`Invalid WASM-OJ error stage '${String(options.stage)}'.`);
+		if (options.retryable !== void 0 && typeof options.retryable !== "boolean") throw new TypeError("WASM-OJ error retryable must be a boolean.");
+		if (options.operationId !== void 0 && (typeof options.operationId !== "string" || !options.operationId || options.operationId !== options.operationId.trim() || options.operationId.length > 128)) throw new TypeError("WASM-OJ error operationId must be non-empty, trimmed, and at most 128 characters.");
+		this.name = "WasmOjError";
+		this.code = options.code;
+		this.stage = options.stage;
+		this.retryable = options.retryable ?? false;
+		this.operationId = options.operationId;
+		this.details = validatedDetails(options.details);
+	}
+	toJSON() {
+		return {
+			name: "WasmOjError",
+			message: this.message,
+			code: this.code,
+			stage: this.stage,
+			retryable: this.retryable,
+			...this.operationId === void 0 ? {} : { operationId: this.operationId },
+			...this.details === void 0 ? {} : { details: { ...this.details } }
+		};
+	}
+};
+function validatedDetails(value) {
+	if (value === void 0) return void 0;
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new TypeError("WASM-OJ error details must be a plain object.");
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) throw new TypeError("WASM-OJ error details must be a plain object.");
+	const entries = Object.entries(value);
+	if (entries.length > 32) throw new RangeError("WASM-OJ error details may contain at most 32 entries.");
+	const details = {};
+	for (const [key, detail] of entries) {
+		if (!key || key !== key.trim() || key.length > 128) throw new TypeError("WASM-OJ error detail keys must be non-empty, trimmed, and at most 128 characters.");
+		if (typeof detail === "string" && detail.length <= 4096) details[key] = detail;
+		else if (typeof detail === "number" && Number.isFinite(detail)) details[key] = detail;
+		else if (typeof detail === "boolean" || detail === null) details[key] = detail;
+		else throw new TypeError(`WASM-OJ error detail '${key}' has an unsupported value.`);
+	}
+	return Object.freeze(details);
+}
+function asWasmOjError(error, options) {
+	if (error instanceof WasmOjError) {
+		if (error.operationId !== void 0 || options.operationId === void 0) return error;
+		return new WasmOjError(error.message, {
+			code: error.code,
+			stage: error.stage,
+			retryable: error.retryable,
+			operationId: options.operationId,
+			details: error.details,
+			cause: error
+		});
+	}
+	return new WasmOjError(error instanceof Error ? error.message : String(error), {
+		...options,
+		cause: error
+	});
+}
+//#endregion
+export { DEPENDENCY_ECOSYSTEMS, LANGUAGES, WASM_OJ_CONTRACT_ID, WASM_OJ_CONTRACT_VERSION, WASM_OJ_ERROR_CODES, WASM_OJ_ERROR_STAGES, WASM_OJ_SCHEMAS, WASM_OJ_STORAGE, WasmOjError, asWasmOjError, assertLanguageIdentifier, isBuiltinLanguage };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@wasm-oj/contracts",
+  "version": "0.2.0",
+  "description": "Environment-neutral contracts and wire types for the WASM-OJ SDK.",
+  "license": "MIT",
+  "author": "JacobLinCool",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wasm-oj/forge.git",
+    "directory": "packages/contracts"
+  },
+  "homepage": "https://github.com/wasm-oj/forge#readme",
+  "bugs": {
+    "url": "https://github.com/wasm-oj/forge/issues"
+  },
+  "keywords": [
+    "online-judge",
+    "wasi",
+    "wasm"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24.18.0 <25"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-library.mjs --package @wasm-oj/contracts"
+  }
+}