# Core Types
URL: /runtime/api/types



# Core Types [#core-types]

Operation results and plugin-author contracts share issues and artifacts.

## Result Types [#result-types]

`KernelResult<T>` discriminates plugin success and failure with `success`.

**`KernelSuccessResult`** — Successful kernel operation outcome. Non-fatal warnings are preserved in `issues` alongside the operation data.

- **`success`** (`true`, required)
- **`data`** (`T`, required)
- **`issues`** (`KernelIssue[]`, required)
- **`serializedNativeHandle`** (`unknown`, optional)
- **`sourceRevision`** (`Readonly<{ entry: string; files: Readonly<Record<string, ContentDigest | "missing">>; }> | undefined`, optional) — The source revision this result was computed from.

  Populated by the request-scoped operations (`evaluateModel`, `getParameters`, `exportModel`, `snapshotSource`); absent on autonomous preview results and on results produced before any closure was resolved.
- **`serializeNativeHandleSnapshot`** (`(() => unknown) | undefined`, optional) — Produce the durable native-handle snapshot on demand (D12).

  No display render reads a snapshot, so a kernel that can make one hands over this thunk and pays for it only where something asks: an export, a reheat, or a cache write. It resolves `undefined` once the handle it would read has been disposed, and is stripped from every published result — it is a function, and functions do not cross the wire.

**`KernelErrorResult`** — Failed kernel operation outcome. Inspect `issues` for error messages, source locations, and stack traces.

- **`success`** (`false`, required)
- **`issues`** (`KernelIssue[]`, required)
- **`sourceRevision`** (`Readonly<{ entry: string; files: Readonly<Record<string, ContentDigest | "missing">>; }> | undefined`, optional) — The source revision the failing operation had already resolved, when it got that far.

  A failure is the case provenance matters most for — "render failed" against bytes the caller has since replaced reads exactly like a failure against the current ones.

## Issue and Location Types [#issue-and-location-types]

**`KernelIssue`** — Diagnostic produced by a kernel operation — displayed in the editor's problem panel and used for error markers. The `code` discriminator is the canonical classification surface; consumers must never inspect `message` to decide how to handle an issue.

- **`message`** (`string`, required)
- **`code`** (`"OPERATION_TIMEOUT" | "KERNEL_BINDING_FAILED" | "KERNEL_CAPABILITY_MISSING" | "TRANSCODER_CAPABILITY_MISSING" | "TRANSCODER_OPTIONS_INVALID" | "TRANSCODER_INITIALIZATION_FAILED" | "TRANSCODER_EXECUTION_FAILED" | "TRANSCODER_TIMEOUT" | "BUNDLER_FAILED" | "MIDDLEWARE_FAILED" | "INVALID_SCHEMA" | "INVALID_ANNOTATION" | "INVALID_REFERENCE" | "RESOURCE_LIMIT" | "METADATA_CONFLICT" | "SEMANTICS_UNRESOLVED" | "REPRESENTATION_UNSUPPORTED" | "LEGACY_PROJECTION_LOSS" | "INVALID_RECORD" | "RENDER_ARTIFACT_MISSING" | "GLTF_BYTES_INVALID" | "SVG_DOCUMENT_INVALID" | "HANDLE_MISSING" | "VIEW_UNKNOWN" | "VIEW_UNAVAILABLE" | "VIEW_OPTIONS_INVALID" | "EXPORT_UNKNOWN" | "EXPORT_AMBIGUOUS" | "EXPORT_OPTIONS_INVALID" | "EVALUATE_OPTIONS_INVALID" | "EXPORT_ARTIFACT_SET_INVALID" | "RUNTIME_CONTENT_UNSUPPORTED" | "SOURCE_SNAPSHOT_CHANGED" | "SOURCE_SNAPSHOT_INVALID" | "GEOMETRY_INVALID" | "AUTHENTICATION_ERROR" | "RUNTIME" | "UNKNOWN"`, required) — Typed discriminator used by every consumer — `RuntimeClient`, the UI, telemetry — to classify the issue. Replaces all `issue.message.startsWith(...)` patterns.
- **`location`** (`ErrorLocation | undefined`, optional)
- **`stack`** (`string | undefined`, optional)
- **`stackFrames`** (`KernelStackFrame[] | undefined`, optional)
- **`details`** (`unknown`, optional)
- **`type`** (`KernelIssueType | undefined`, optional)
- **`severity`** (`IssueSeverity`, required)

**`KernelStackFrame`** — Stack frame captured during a kernel error, enriched with source mapping and visibility context for error reporting UI.

- **`fileName`** (`string | undefined`, optional)
- **`functionName`** (`string | undefined`, optional)
- **`lineNumber`** (`number | undefined`, optional)
- **`columnNumber`** (`number | undefined`, optional)
- **`source`** (`string | undefined`, optional)
- **`context`** (`FrameContext | undefined`, optional) — Classification of the frame's origin for visibility and error location purposes

**`ErrorLocation`** — Source location for an error (file, line, column range) used for editor markers and navigation.

- **`fileName`** (`string`, required)
- **`startLineNumber`** (`number`, required)
- **`startColumn`** (`number`, required)
- **`endLineNumber`** (`number | undefined`, optional)
- **`endColumn`** (`number | undefined`, optional)

`KernelIssueType` (`'compilation' | 'runtime' | 'kernel' | 'connection' | 'unknown'`) and `IssueSeverity` (`'error' | 'warning' | 'info'`) classify each issue. `kernelIssueCodeValues` enumerates the stable codes; `isKernelIssueCode` guards one.

## Document Results [#document-results]

**`Description`** — Kernel and parameter metadata found without evaluating.

- **`success`** (`boolean`, required)
- **`kernelId`** (`string | undefined`, required)
- **`issues`** (`readonly KernelIssue[]`, required)

**`Evaluation`** — One admitted evaluation; a failed evaluation never silently retains an older export source.

- **`success`** (`boolean`, required)
- **`id`** (`string`, required)
- **`transient`** (`boolean`, required)
- **`issues`** (`readonly KernelIssue[]`, required)
- **`sourceRevision`** (`Readonly<{ entry: string; files: Readonly<Record<string, ContentDigest | "missing">>; }> | undefined`, optional)

**`Rendering`** — One view projection, correlated to both its request and evaluation.

- **`success`** (`boolean`, required)
- **`view`** (`ViewId | undefined`, optional)
- **`requestId`** (`string`, required)
- **`evaluationId`** (`string`, required)
- **`instance`** (`string | undefined`, optional)
- **`transient`** (`boolean`, required)
- **`issues`** (`readonly KernelIssue[]`, required)
- **`sourceRevision`** (`Readonly<{ entry: string; files: Readonly<Record<string, ContentDigest | "missing">>; }> | undefined`, optional)

**`ExportResult`** — An export from the pinned committed evaluation.

- **`success`** (`boolean`, required)
- **`issues`** (`readonly KernelIssue[]`, required)
- **`sourceRevision`** (`Readonly<{ entry: string; files: Readonly<Record<string, ContentDigest | "missing">>; }> | undefined`, optional)

**`ViewOffer`** — An offered view with serializable option metadata.

- **`id`** (`Id`, required)
- **`title`** (`string`, required)
- **`mimeType`** (`string`, required)
- **`instances`** (`readonly Readonly<{ id: string; title: string; }>[] | undefined`, optional)
- **`options`** (`Readonly<{ schema: JSONSchema7; defaults: Readonly<Record<string, unknown>>; }> | undefined`, optional)

**`ExportOffer`** — An offered export with serializable option metadata.

- **`id`** (`Id`, required)
- **`title`** (`string`, required)
- **`mimeType`** (`string`, required)
- **`extension`** (`string`, required)
- **`options`** (`Readonly<{ schema: JSONSchema7; defaults: Readonly<Record<string, unknown>>; }> | undefined`, optional)

Document results always carry `issues`. Successful evaluations offer ordered view and export IDs, including an empty view list. A rendering correlates `requestId` and `evaluationId`; its `artifact` carries MIME type, content, and optional units. `hash` identifies its projected artifact. Successful exports carry a nonempty file tuple. Optional `sourceRevision` records evaluated source provenance.

`DocumentStatus` and `ViewStatus` describe separate owners. Their events and supersession outcomes are documented in [Client API](/runtime/api/client).

## Dependency Types [#dependency-types]

`Dependency` records inputs to cache identity and change detection:

**`FileDependency`** — A file dependency representing a source file or font file. The contentHash is a SHA-256 hash of the file's contents.

- **`type`** (`"file"`, required)
- **`path`** (`string`, required) — Path of the dependency within the runtime filesystem.
- **`contentHash`** (`string`, required) — SHA-256 hash of the file contents

**`MiddlewareDependency`** — File whose changes affect selected middleware operations.

- **`path`** (`string`, required)
- **`affects`** (`readonly ("describe" | "evaluate" | "render" | "export")[]`, required)
- **`watchDebounce`** (`number | undefined`, optional)

**`FrameworkDependency`** — A framework dependency representing the Tau framework version.

- **`type`** (`"framework"`, required)
- **`name`** (`"tau"`, required) — Framework name (always 'tau')
- **`version`** (`string`, required) — Version string from package.json

**`OptionDependency`** — An option dependency representing a kernel configuration option. Used to track mesh tolerances, backend arguments, etc.

- **`type`** (`"option"`, required)
- **`key`** (`string`, required) — Option key (e.g., 'tessellation', 'arguments')
- **`value`** (`unknown`, required) — Option value (serialized to JSON for hashing)

**`ParameterDependency`** — A parameter dependency representing user-provided parameter values. Used to invalidate cache when parameter values change.

- **`type`** (`"parameter"`, required)
- **`parameters`** (`Record<string, unknown>`, required) — Raw parameters object -- serialized in the final dependency hash pass

**`AssetDependency`** — An asset dependency representing a bundled asset (font, WASM, etc.). Used to invalidate cache when assets change between deployments.

- **`type`** (`"asset"`, required)
- **`name`** (`string`, required) — Asset identifier (e.g., 'font:Geist-Regular.ttf', 'wasm:opencascade')
- **`contentHash`** (`string`, required) — SHA-256 hash of the asset content

`FileDependency.path` is a canonical root-relative [runtime path](/runtime/concepts/path-namespaces), shared by filesystem and cache identity.

## Filesystem Types [#filesystem-types]

**`RuntimeFileSystemBase`** — Base filesystem interface for runtime backends. Aliases the canonical {@link FileSystemProvider} from `@taucad/filesystem` augmented with an optional `watch` subscription. Filesystem backends authored for the runtime (e.g. `fromFsLike`, `fromMemoryFs`, `fromNodeFs`) implement this shape; the runtime upgrades it into a {@link KernelFileSystem} at the worker boundary via the runtime's internal decorator. Paths are canonical and root-relative within the supplied runtime filesystem; `''` refers to that filesystem's root.

- **`id`** (`string`, required)
- **`capabilities`** (`ProviderCapabilities`, required)
- **`supportsHeadListing`** (`true | undefined`, optional) — Explicit opt-in to head-only listing; absent on exact-only legacy providers.
- **`readdirWithStats`** (`{ (path: string): Promise<DirectoryStatRow[]>; (path: string, options: { readonly content: "head"; }): Promise<Array<DirectoryStatRow<FileStat | HeadFileStat>>>; } | undefined`, optional) — Optional batched listing. Omission returns exact metadata; `head` omits unknown line counts.
- **`readFile`** (`{ (path: string): Promise<Uint8Array<ArrayBuffer>>; (path: string, encoding: "utf8"): Promise<string>; }`, required)
- **`writeFile`** (`(path: string, data: Uint8Array<ArrayBuffer> | string) => Promise<void>`, required) — Persist a file, creating any missing parent directories.
- **`writeFileChecked`** (`((input: Omit<CheckedFileWrite, "signal">) => Promise<CheckedFileWriteResult>) | undefined`, optional) — Atomically check current bytes and replace one file when this provider owns a real authority fence.
- **`deleteFileChecked`** (`((input: { path: string; preconditions: readonly FileWritePrecondition[]; }) => Promise<CheckedFileWriteResult>) | undefined`, optional) — Atomically check current bytes and delete one file under the same authority fence.
- **`appendFile`** (`((path: string, data: Uint8Array<ArrayBuffer> | string) => Promise<void>) | undefined`, optional) — Append bytes in enqueue order, creating the file and missing parent directories when absent.
- **`readdir`** (`(path: string) => Promise<string[]>`, required)
- **`stat`** (`(path: string) => Promise<FileStat>`, required)
- **`mkdir`** (`(path: string, options?: { recursive?: boolean; }) => Promise<void>`, required)
- **`unlink`** (`(path: string) => Promise<void>`, required)
- **`rmdir`** (`(path: string) => Promise<void>`, required)
- **`rename`** (`(from: string, to: string) => Promise<void>`, required)
- **`exists`** (`(path: string) => Promise<boolean>`, required)
- **`lstat`** (`(path: string) => Promise<FileStat>`, required)
- **`getFileMode`** (`((path: string) => Promise<FileMode>) | undefined`, optional) — Read a regular file's Git-compatible executable mode when the backend exposes it.
- **`setFileMode`** (`((path: string, mode: FileMode) => Promise<void>) | undefined`, optional) — Apply a Git-compatible regular-file mode without exposing an unrestricted chmod seam.
- **`dispose`** (`() => void`, required)
- **`readFileStream`** (`((path: string, options?: FileReadStreamOptions) => ReadableStream<Uint8Array<ArrayBuffer>>) | undefined`, optional) — Optional streaming read. When present, service routes through this instead of buffered readFile.
- **`readdirEntries`** (`((path: string) => Promise<DirectoryEntry[]>) | undefined`, optional) — Optional readdir carrying entry kinds. When present, tree walks skip the stat-per-child.
- **`refresh`** (`((prefixes?: readonly string[]) => Promise<void>) | undefined`, optional) — Refresh provider projections after an out-of-band mutation. Pass the absolute paths whose subtrees changed to scope the invalidation; omit them to drop everything.
- **`observe`** (`((listener: (facts: readonly ExternalChangeFact[]) => void) => Promise<(() => void) | undefined>) | undefined`, optional) — Report this root's own external changes. Declared only by a backend that can observe itself; the authority falls back to bounded snapshot polling for one that cannot, so capability presence — never backend identity — decides how a root is watched (charter D13).

  Resolves with a disposer, or with `undefined` when observation exists in principle but could not be armed here and polling must cover the root. A rejection means the root has no fallback and its derivatives are stale.
- **`watch`** (`((request: RuntimeWatchRequest, handler: (event: RuntimeWatchEvent) => void) => () => void) | undefined`, optional) — Subscribe to filesystem change events for the given paths. Returns an unsubscribe function. Events are filtered server-side.

**`KernelFileSystem`** — Enhanced filesystem interface seen inside kernel/bundler/middleware code. Extends the base primitives with higher-level helper methods built from the primitives by the runtime's internal decorator. Provider watch stays on the transport boundary and is not exposed through this kernel-facing facade. Distinct from the consumer-facing opaque `RuntimeFileSystem` value (`#filesystem/runtime-filesystem.js`) produced by `from*` factories and handed to a transport plugin's `client({ fileSystem })`; the transport unwraps the opaque value and upgrades the backing `RuntimeFileSystemBase` inside the runtime worker. Renamed from `RuntimeFileSystem` (R14) to disambiguate from the consumer-facing opaque brand. The `KernelFileSystem` name is exported only from the kernel-author subpath `@taucad/runtime/kernel`; the consumer barrel reserves `RuntimeFileSystem` for the opaque value. All methods operate on paths within the supplied runtime filesystem.

- **`id`** (`string`, required)
- **`capabilities`** (`ProviderCapabilities`, required)
- **`supportsHeadListing`** (`true | undefined`, optional) — Explicit opt-in to head-only listing; absent on exact-only legacy providers.
- **`readdirWithStats`** (`{ (path: string): Promise<DirectoryStatRow[]>; (path: string, options: { readonly content: "head"; }): Promise<Array<DirectoryStatRow<FileStat | HeadFileStat>>>; } | undefined`, optional) — Optional batched listing. Omission returns exact metadata; `head` omits unknown line counts.
- **`readFile`** (`{ (path: string): Promise<Uint8Array<ArrayBuffer>>; (path: string, encoding: "utf8"): Promise<string>; }`, required)
- **`writeFile`** (`(path: string, data: Uint8Array<ArrayBuffer> | string) => Promise<void>`, required) — Persist a file, creating any missing parent directories.
- **`writeFileChecked`** (`((input: Omit<CheckedFileWrite, "signal">) => Promise<CheckedFileWriteResult>) | undefined`, optional) — Atomically check current bytes and replace one file when this provider owns a real authority fence.
- **`deleteFileChecked`** (`((input: { path: string; preconditions: readonly FileWritePrecondition[]; }) => Promise<CheckedFileWriteResult>) | undefined`, optional) — Atomically check current bytes and delete one file under the same authority fence.
- **`appendFile`** (`((path: string, data: Uint8Array<ArrayBuffer> | string) => Promise<void>) | undefined`, optional) — Append bytes in enqueue order, creating the file and missing parent directories when absent.
- **`readdir`** (`(path: string) => Promise<string[]>`, required)
- **`stat`** (`(path: string) => Promise<FileStat>`, required)
- **`mkdir`** (`(path: string, options?: { recursive?: boolean; }) => Promise<void>`, required)
- **`unlink`** (`(path: string) => Promise<void>`, required)
- **`rmdir`** (`(path: string) => Promise<void>`, required)
- **`rename`** (`(from: string, to: string) => Promise<void>`, required)
- **`exists`** (`(path: string) => Promise<boolean>`, required)
- **`lstat`** (`(path: string) => Promise<FileStat>`, required)
- **`getFileMode`** (`((path: string) => Promise<FileMode>) | undefined`, optional) — Read a regular file's Git-compatible executable mode when the backend exposes it.
- **`setFileMode`** (`((path: string, mode: FileMode) => Promise<void>) | undefined`, optional) — Apply a Git-compatible regular-file mode without exposing an unrestricted chmod seam.
- **`dispose`** (`() => void`, required)
- **`readFileStream`** (`((path: string, options?: FileReadStreamOptions) => ReadableStream<Uint8Array<ArrayBuffer>>) | undefined`, optional) — Optional streaming read. When present, service routes through this instead of buffered readFile.
- **`readdirEntries`** (`((path: string) => Promise<DirectoryEntry[]>) | undefined`, optional) — Optional readdir carrying entry kinds. When present, tree walks skip the stat-per-child.
- **`refresh`** (`((prefixes?: readonly string[]) => Promise<void>) | undefined`, optional) — Refresh provider projections after an out-of-band mutation. Pass the absolute paths whose subtrees changed to scope the invalidation; omit them to drop everything.
- **`observe`** (`((listener: (facts: readonly ExternalChangeFact[]) => void) => Promise<(() => void) | undefined>) | undefined`, optional) — Report this root's own external changes. Declared only by a backend that can observe itself; the authority falls back to bounded snapshot polling for one that cannot, so capability presence — never backend identity — decides how a root is watched (charter D13).

  Resolves with a disposer, or with `undefined` when observation exists in principle but could not be armed here and polling must cover the root. A rejection means the root has no fallback and its derivatives are stale.
- **`readFiles`** (`(paths: string[]) => Promise<Record<string, Uint8Array<ArrayBuffer>>>`, required) — Batch-read multiple files as binary. Default: `Promise.all(paths.map(readFile))`.
- **`readdirContents`** (`(directoryPath: string) => Promise<Record<string, Uint8Array<ArrayBuffer>>>`, required) — Read all file contents in a directory (skips subdirectories).
- **`readdirStat`** (`(directoryPath: string) => Promise<FileStatEntry[]>`, required) — Get stat information for all entries in a directory.
- **`ensureDir`** (`(path: string) => Promise<void>`, required) — Ensure a directory exists, creating parents as needed. Default: `mkdir(path, { recursive: true })`.

**`RuntimeFileSystem`** — Opaque consumer-facing filesystem handle. Reaching into the value to inspect the underlying handle is a type error: the brand is unexported, so consumer code cannot construct a matching value.

_No properties._

## Kernel Types [#kernel-types]

**`DescribeInput`** — Input for parameter description.

- **`entryPath`** (`string`, required)
- **`resolution`** (`Readonly<{ mode?: "default" | "declared-only"; profile?: typeof unitProfile; inferenceLanguage?: string; projectBindingDigest?: ContentDigest; sourceUnitDigest?: ContentDigest; }> | undefined`, optional)

**`DescribeResult`** — Parameter description envelope returned by a kernel.

- **`success`** (`boolean`, required)
- **`issues`** (`KernelIssue[]`, required)
- **`sourceRevision`** (`Readonly<{ entry: string; files: Readonly<Record<string, ContentDigest | "missing">>; }> | Readonly<{ entry: string; files: Readonly<Record<string, ContentDigest | "missing">>; }> | undefined`, optional) — The source revision the failing operation had already resolved, when it got that far.

  A failure is the case provenance matters most for — "render failed" against bytes the caller has since replaced reads exactly like a failure against the current ones. The source revision this result was computed from.

  Populated by the request-scoped operations (`evaluateModel`, `getParameters`, `exportModel`, `snapshotSource`); absent on autonomous preview results and on results produced before any closure was resolved.

**`ResolveInput`** — File whose dependencies are being resolved.

- **`entryPath`** (`string`, required)

**`ResolveOutput`** — Resolved and unresolved source dependencies.

- **`resolved`** (`string[]`, required) — Paths within the runtime filesystem that were resolved and read.
- **`unresolved`** (`string[]`, required) — Paths that could not be resolved.

**`KernelDefinition`** — Kernel authoring contract with exact per-view and per-export inference.

- **`permissions`** (`RuntimePluginPermissions | undefined`, optional) — Declarative review metadata; runtime execution does not enforce these permissions.
- **`id`** (`Id`, required)
- **`extensions`** (`Extensions`, required)
- **`detectImport`** (`RegExp | undefined`, optional)
- **`builtinModuleNames`** (`readonly string[] | undefined`, optional)
- **`name`** (`string`, required)
- **`version`** (`string`, required)
- **`implementationAssets`** (`readonly RuntimeImplementationAsset[] | undefined`, optional)
- **`optionsSchema`** (`OptionsSchema | undefined`, optional)
- **`evaluateOptionsSchema`** (`EvaluateSchema | undefined`, optional)
- **`cancellation`** (`"cooperative" | undefined`, optional)
- **`views`** (`CheckedDeclarations<Views, Readonly<{ title: string; mimeType: MediaType; optionsSchema?: ObjectOptionsSchema; content?: RuntimeContentDeclaration; instances?: true; }>>`, required)
- **`exports`** (`CheckedDeclarations<Exports, Readonly<{ title: string; mimeType: MediaType; extension: string; optionsSchema?: ObjectOptionsSchema; content?: RuntimeContentDeclaration; }>>`, required)
- **`initialize`** (`(options: ParsedOptions<OptionsSchema>, services: KernelServices) => Promise<Context>`, required)
- **`resolve`** (`(input: ResolveInput, services: KernelServices, context: Context) => Promise<ResolveOutput>`, required)
- **`describe`** (`(input: DescribeInput, services: KernelServices, context: Context) => Promise<DescribeResult>`, required)
- **`evaluate`** (`(input: EvaluateInput<EvaluateSchema>, services: KernelServices, context: Context) => Promise<EvaluateOutput<Handle, NoInfer<Views>, NoInfer<Exports>>>`, required)
- **`render`** (`((input: RenderInput<NoInfer<Handle>, NoInfer<Views>>, services: KernelServices, context: NoInfer<Context>) => Promise<RenderOutput>) | undefined`, optional)
- **`export`** (`((input: ExportInput<NoInfer<Handle>, NoInfer<Exports>>, services: KernelServices, context: NoInfer<Context>) => Promise<ExportOutput>) | undefined`, optional)
- **`isHandleValid`** (`((input: Readonly<{ handle: Handle; }>, services: KernelServices, context: Context) => boolean | Promise<boolean>) | undefined`, optional)
- **`releaseHandle`** (`((input: Readonly<{ handle: Handle; }>, services: KernelServices, context: Context) => void) | undefined`, optional)
- **`onDispose`** (`((context: Context) => Promise<void>) | undefined`, optional)
- **`serializeHandle`** (`((input: Readonly<{ handle: Handle; }>, services: KernelServices, context: Context) => Serialized) | undefined`, optional)
- **`deserializeHandle`** (`((input: Readonly<{ serialized: Serialized; }>, services: KernelServices, context: Context) => Handle) | undefined`, optional)

**`KernelServices`** — Operation-scoped services passed to kernel hooks.

- **`signal`** (`AbortSignal`, required) — Operation-scoped cancellation signal. Fresh for each operation; pass it to cancellable platform APIs and do not retain it for later work.
- **`operationId`** (`number | undefined`, optional) — Identity of the runtime operation this call belongs to. Every kernel call inside one operation — a render's dependency, parameter and geometry calls — shares it, and the runtime treats the workspace as unchanged for that operation's duration; any other call carries a different value. Key per-operation reuse of workspace reads on it. Hosts that do not scope calls into operations, such as test doubles, omit it, and nothing should then be reused.
- **`filesystem`** (`KernelFileSystem`, required) — Rooted filesystem capability; all paths are canonical and relative to its root.
- **`logger`** (`RuntimeLogger`, required) — Logger with kernel name pre-configured
- **`fileContentCache`** (`ReadonlyMap<string, string | Uint8Array<ArrayBuffer>>`, required) — Read-only view of file contents cached by normalized runtime path during dependency computation.
- **`bundler`** (`KernelBundler`, required) — Esbuild bundler for JS/TS kernels. Lazily initialised on first access.
- **`tracer`** (`RuntimeSpanTracer`, required) — Span tracer for kernel-authored performance instrumentation
- **`compute`** (`KernelComputeCapability`, required) — Compute reuse facet for the active operation. `off` carries no operations at all.
- **`getCompiledWasmModule`** (`(url: string) => WebAssembly.Module | undefined`, required) — Resolve a host-compiled WASM module by its absolute asset URL.
- **`execute`** (`(code: string) => Promise<ExecuteResult>`, required) — Execute bundled JS/TS code via dynamic import and return the module exports. Browser uses Blob URL, Node.js uses data URL.

**`ViewDeclaration`** — Static declaration and validation metadata for a view.

- **`title`** (`string`, required)
- **`mimeType`** (`SharedMediaType`, required)
- **`optionsSchema`** (`ObjectOptionsSchema | undefined`, optional)
- **`content`** (`RuntimeContentDeclaration | undefined`, optional)
- **`instances`** (`true | undefined`, optional)

**`ExportDeclaration`** — Static declaration and validation metadata for an export.

- **`title`** (`string`, required)
- **`mimeType`** (`SharedMediaType`, required)
- **`extension`** (`string`, required)
- **`optionsSchema`** (`ObjectOptionsSchema | undefined`, optional)
- **`content`** (`RuntimeContentDeclaration | undefined`, optional)

**`ViewInstance`** — One named instance of a declared view.

- **`id`** (`string`, required)
- **`title`** (`string`, required)

`evaluate` returns an opaque handle plus the ordered view and export IDs this result offers. The first offered view is the default. Views can expose named instances; `render` selects one view and optional instance without evaluating again.

**`EvaluateInput`** — Validated evaluation input.

- **`entryPath`** (`string`, required)
- **`parameters`** (`Readonly<Record<string, unknown>>`, required)
- **`options`** (`ParsedOptions<Schema>`, required)

**`EvaluateOutput`** — Kernel output before runtime admission and serialization.

- **`handle`** (`Handle`, required)
- **`issues`** (`readonly KernelIssue[] | undefined`, optional)
- **`views`** (`readonly Extract<keyof Views, string>[] | undefined`, optional)
- **`exports`** (`readonly Extract<keyof Exports, string>[] | undefined`, optional)
- **`instances`** (`{ readonly [Id in keyof Views]?: (Views[Id] extends { readonly instances: true; } ? readonly Readonly<{ id: string; title: string; }>[] : never) | undefined; } | undefined`, optional)

**`RenderInput`** — Per-view render input narrowed by the selected view identifier.

- **`handle`** (`({ handle: Handle; view: keyof Views; options: ParsedOptions<SchemaOf<Views[keyof Views]>>; } & InstanceFor<Views[keyof Views]> & ContentHookInputFor<ContentOf<Views[keyof Views]>>)["handle"]`, required)
- **`view`** (`({ handle: Handle; view: keyof Views; options: ParsedOptions<SchemaOf<Views[keyof Views]>>; } & InstanceFor<Views[keyof Views]> & ContentHookInputFor<ContentOf<Views[keyof Views]>>)["view"]`, required)
- **`options`** (`({ handle: Handle; view: keyof Views; options: ParsedOptions<SchemaOf<Views[keyof Views]>>; } & InstanceFor<Views[keyof Views]> & ContentHookInputFor<ContentOf<Views[keyof Views]>>)["options"]`, required)
- **`instance`** (`({ handle: Handle; view: keyof Views; options: ParsedOptions<SchemaOf<Views[keyof Views]>>; } & InstanceFor<Views[keyof Views]> & ContentHookInputFor<ContentOf<Views[keyof Views]>>)["instance"] | undefined`, optional)

**`RenderOutput`** — Rendered content before runtime attaches the declared media type.

- **`content`** (`string | Uint8Array<ArrayBuffer>`, required)
- **`units`** (`Readonly<CadUnits> | undefined`, optional)
- **`issues`** (`readonly KernelIssue[] | undefined`, optional)
- **`mimeType`** (`undefined`, optional)

**`ExportInput`** — Export input narrowed by the selected export identifier.

- **`handle`** (`({ handle: Handle; exportId: keyof Exports; options: ParsedOptions<SchemaOf<Exports[keyof Exports]>>; } & ContentHookInputFor<ContentOf<Exports[keyof Exports]>>)["handle"]`, required)
- **`exportId`** (`({ handle: Handle; exportId: keyof Exports; options: ParsedOptions<SchemaOf<Exports[keyof Exports]>>; } & ContentHookInputFor<ContentOf<Exports[keyof Exports]>>)["exportId"]`, required)
- **`options`** (`({ handle: Handle; exportId: keyof Exports; options: ParsedOptions<SchemaOf<Exports[keyof Exports]>>; } & ContentHookInputFor<ContentOf<Exports[keyof Exports]>>)["options"]`, required)

**`ExportOutput`** — Kernel export output before runtime admission.

- **`files`** (`NonemptyExportFiles`, required)
- **`issues`** (`readonly KernelIssue[] | undefined`, optional)

## Bundler Types [#bundler-types]

**`BundlerDefinition`** — Definition for a bundler module loaded via defineBundler(). Bundler modules are ES modules dynamically imported by the worker runtime. The bundler owns both bundling AND execution because the execution model is inherently tied to the bundler's output format. Detection (detectImports) and production (bundle) are separate operations: - detectImports: discovers what bare specifiers are used (no modules needed) - bundle: produces runnable code (modules must be registered first) This separation eliminates the chicken-and-egg problem: detection runs without modules registered, then the framework selects and initializes the kernel (which registers real modules), then bundle() produces code. Type parameters are inferred automatically: - Context from initialize() return type - Options from optionsSchema (when provided)

- **`name`** (`string`, required) — Human-readable bundler name, used in logs and error messages
- **`version`** (`string`, required) — Semantic version string for cache-key computation and diagnostics
- **`extensions`** (`string[]`, required) — File extensions this bundler handles (e.g., ['ts', 'js', 'tsx', 'jsx']).
- **`optionsSchema`** (`z.ZodType<Options, unknown, z.core.$ZodTypeInternals<Options, unknown>> | undefined`, optional) — Zod schema for validating and typing bundler options. Options type is inferred from this schema.
- **`initialize`** (`(options: Options, runtime: BundlerInitRuntime) => Promise<Context>`, required) — Initialize the bundler. Receives user-provided options plus framework runtime services.
- **`detectImports`** (`(input: BundleInput, runtime: BundlerRuntime, context: Context) => Promise<DetectImportsResult>`, required) — Detect which bare-specifier modules are imported transitively. Resolves relative imports normally but marks bare specifiers as external. Returns detected modules and project dependencies without producing runnable code. This is the primary mechanism for kernel selection -- no module stubs required.
- **`bundle`** (`(input: BundleInput, runtime: BundlerRuntime, context: Context) => Promise<BundleResult>`, required) — Produce runnable code with all registered modules resolved. Called AFTER kernel selection and initialization (modules are registered).
- **`execute`** (`(input: { code: string; }, runtime: BundlerRuntime, context: Context) => Promise<ExecuteResult>`, required) — Execute bundled code (tied to this bundler's output format).
- **`registerModule`** (`(input: { name: string; module: BuiltinModule; }, context: Context) => void`, required) — Register a builtin module for resolution during bundle().
- **`clearExecutionCache`** (`((code: string | undefined, context: Context) => void) | undefined`, optional) — Invalidate cached execution results after source changes.
- **`onDispose`** (`((context: Context) => Promise<void>) | undefined`, optional) — Clean up bundler resources (e.g., esbuild.stop()).

**`KernelBundler`** — Bundler service exposed to kernels.

- **`bundle`** (`(entryPath: string) => Promise<BundleResult>`, required)
- **`resolveDependencies`** (`(entryPath: string) => Promise<GetDependenciesResult>`, required)
- **`registerModule`** (`(name: string, entry: BuiltinModule) => void`, required)

**`BundleResult`** — Result of bundling one entry and its transitive dependencies.

- **`code`** (`string`, required)
- **`sourceMap`** (`string | undefined`, optional)
- **`issues`** (`KernelIssue[]`, required)
- **`success`** (`boolean`, required)
- **`dependencies`** (`string[]`, required)
- **`unresolvedPaths`** (`string[]`, required)

**`BuiltinModule`** — A preloaded module registered with a runtime bundler.

- **`code`** (`string`, required)
- **`version`** (`string`, required)
- **`globalName`** (`string | undefined`, optional)

## Tracer Types [#tracer-types]

**`TelemetryEntry`** — Completed worker telemetry span.

- **`name`** (`string`, required)
- **`startTime`** (`number`, required)
- **`duration`** (`number`, required)
- **`detail`** (`Record<string, unknown> | undefined`, optional)
- **`workerTimeOrigin`** (`number`, required)

**`SpanHandle`** — Handle returned by `RuntimeSpanTracer.startSpan()`. Call `end()` when the traced operation completes.

- **`end`** (`(attributes?: Record<string, string | number | boolean>) => void`, required)

**`RuntimeSpanTracer`** — Lightweight tracing interface exposed to kernel modules and middleware. Creates hierarchical spans without requiring an OpenTelemetry SDK dependency. Spans are collected by the framework and displayed in the Kernel Panel.

- **`startSpan`** (`(name: string, attributes?: Record<string, string | number | boolean>) => SpanHandle`, required) — Begin a new named span, optionally attaching key-value attributes for filtering.

## Artifacts and Plugin Results [#artifacts-and-plugin-results]

**`Artifact`** — A single rendered view with its declared media type and optional units.

- **`mimeType`** (`SharedMediaType`, required)
- **`content`** (`string | Uint8Array<ArrayBuffer>`, required)
- **`units`** (`Readonly<CadUnits> | undefined`, optional)

**`EvaluateResult`** — Admitted evaluation envelope and native replay carrier.

- **`success`** (`boolean`, required)
- **`issues`** (`KernelIssue[]`, required)
- **`sourceRevision`** (`Readonly<{ entry: string; files: Readonly<Record<string, ContentDigest | "missing">>; }> | Readonly<{ entry: string; files: Readonly<Record<string, ContentDigest | "missing">>; }> | undefined`, optional) — The source revision the failing operation had already resolved, when it got that far.

  A failure is the case provenance matters most for — "render failed" against bytes the caller has since replaced reads exactly like a failure against the current ones. The source revision this result was computed from.

  Populated by the request-scoped operations (`evaluateModel`, `getParameters`, `exportModel`, `snapshotSource`); absent on autonomous preview results and on results produced before any closure was resolved.

**`RenderResult`** — Admitted render artifact envelope.

- **`success`** (`boolean`, required)
- **`issues`** (`KernelIssue[]`, required)
- **`sourceRevision`** (`Readonly<{ entry: string; files: Readonly<Record<string, ContentDigest | "missing">>; }> | Readonly<{ entry: string; files: Readonly<Record<string, ContentDigest | "missing">>; }> | undefined`, optional) — The source revision the failing operation had already resolved, when it got that far.

  A failure is the case provenance matters most for — "render failed" against bytes the caller has since replaced reads exactly like a failure against the current ones. The source revision this result was computed from.

  Populated by the request-scoped operations (`evaluateModel`, `getParameters`, `exportModel`, `snapshotSource`); absent on autonomous preview results and on results produced before any closure was resolved.

**`KernelExportResult`** — Admitted nonempty export envelope.

- **`success`** (`boolean`, required)
- **`issues`** (`KernelIssue[]`, required)
- **`sourceRevision`** (`Readonly<{ entry: string; files: Readonly<Record<string, ContentDigest | "missing">>; }> | Readonly<{ entry: string; files: Readonly<Record<string, ContentDigest | "missing">>; }> | undefined`, optional) — The source revision the failing operation had already resolved, when it got that far.

  A failure is the case provenance matters most for — "render failed" against bytes the caller has since replaced reads exactly like a failure against the current ones. The source revision this result was computed from.

  Populated by the request-scoped operations (`evaluateModel`, `getParameters`, `exportModel`, `snapshotSource`); absent on autonomous preview results and on results produced before any closure was resolved.

**`KnownArtifact`** — Validated CAD media known to the runtime's built-in viewers.

- **`units`** (`Readonly<CadUnits> | undefined`, optional)
- **`mimeType`** (`"model/gltf-binary" | "image/svg+xml"`, required)
- **`content`** (`string | Uint8Array<ArrayBuffer>`, required)

`Artifact` accepts open MIME types with text or bytes. `asKnownArtifact` narrows GLB and SVG; other MIME types remain valid. `ExportOutput` carries a nonempty ordered `ExportFile` tuple; `RenderOutput` carries one artifact whose MIME type matches the selected declaration.

## Conversion Types [#conversion-types]

**`TranscodeInput`** — Input for a transcoder conversion operation. When `Edges` is a concrete tuple of {@link TranscoderEdge}, `TranscodeInput<Edges>` becomes a discriminated union: narrowing on `input.to` narrows `input.from` to the matching edge's source format and narrows `input.options` to `z.input` of that edge's `optionsSchema` (or `Record<string, unknown>` when no schema is declared).

- **`from`** (`unknown`, required)
- **`to`** (`unknown`, required)
- **`files`** (`ExportFile[]`, required)
- **`options`** (`ResolveEdgeOptions<Edges[number]>`, required)

**`TranscodeResult`** — Result of a transcoder conversion operation.

- **`success`** (`boolean`, required)
- **`issues`** (`KernelIssue[]`, required)
- **`sourceRevision`** (`Readonly<{ entry: string; files: Readonly<Record<string, ContentDigest | "missing">>; }> | Readonly<{ entry: string; files: Readonly<Record<string, ContentDigest | "missing">>; }> | undefined`, optional) — The source revision the failing operation had already resolved, when it got that far.

  A failure is the case provenance matters most for — "render failed" against bytes the caller has since replaced reads exactly like a failure against the current ones. The source revision this result was computed from.

  Populated by the request-scoped operations (`evaluateModel`, `getParameters`, `exportModel`, `snapshotSource`); absent on autonomous preview results and on results produced before any closure was resolved.

`TranscoderServices` supplies the logger, tracer, and cancellation signal. `MediaType` names artifact MIME types; `JSONSchema7` carries serializable option metadata.

## Content and Capability Types [#content-and-capability-types]

Framework-owned content requirements stay separate from plugin-owned option schemas. A route advertises supported content and an `ExportFidelity` (`'brep' | 'mesh'`) used by route ranking.

**`RuntimeContentInput`** — Framework-owned content requirements shared by render and export operations.

- **`includeEdges`** (`boolean | undefined`, optional)
- **`includeTopology`** (`boolean | undefined`, optional)

**`ContentCapability`** — JSON Schema plus operation defaults for the content keys on one route.

- **`schema`** (`JSONSchema7`, required)
- **`defaults`** (`Pick<Readonly<{ readonly includeEdges?: boolean | undefined; readonly includeTopology?: boolean | undefined; }>, Keys>`, required)

**`ExportRoute`** — A single export route exposed by the worker. Represents either a direct kernel export (when {@link ExportRoute.transcoderId} is `undefined` and `sourceFormat === targetFormat`) or a single-hop transcoder-routed export. Routes are ordered in {@link CapabilitiesManifest.routes} by manifest preference: the framework selects the first matching route for a target format, optionally narrowed by a kernel hint via {@link RuntimeClient.bestRouteFor }. The `Kernels` and `Transcoders` generics flow as a top-level type bag through {@link RuntimeClient }, allowing each leaf field (`targetFormat`, `kernelId`, `sourceFormat`, `transcoderId`, `defaults`) to project narrowly via the `Known*` helper types in `@taucad/runtime`. Wide defaults preserve today's `FileExtension`/`string`/`Record<string, unknown>` shape so the on-wire manifest type emitted by the worker stays unchanged.

- **`targetFormat`** (`Format`, required)
- **`kernelId`** (`Kernel`, required)
- **`sourceFormat`** (`KnownSourceFormats<Kernels>`, required)
- **`transcoderId`** (`KnownTranscoderIds<Transcoders> | undefined`, optional)
- **`fidelity`** (`ExportFidelity`, required)
- **`exportOptions`** (`{ schema: JSONSchema7; defaults: Format extends keyof MergeExportMap<CollectFormatMap<ReadonlyArray<Extract<Kernels[number], KernelPlugin<any, any, Kernel, any, any>>>>, Transcoders> ? MergeExportMap<CollectFormatMap<ReadonlyArray<Extract<Kernels[number], KernelPlugin<any, any, Kernel, any, any>>>>, Transcoders>[Format] : Record<string, unknown>; }`, required)
- **`content`** (`ContentCapability<ExportContentFor<Kernels, Middleware, Transcoders, Format, Kernel>> | undefined`, optional) — Framework content supported by this exact concrete route. Omitted when empty.

**`RenderCapability`** — Pre-computed JSON Schema and defaults for a kernel's render options. Indexed by kernel id in {@link CapabilitiesManifest.renderCapabilities} for O(1) lookup of the active kernel's render-option form. The `Kernel` generic narrows `defaults` to the specific render options inferred from the registered kernel's `render.optionsSchema` via {@link RenderOptionsFor}.

- **`renderOptions`** (`{ schema: JSONSchema7; defaults: RenderOptionsFor<Kernels, Kernel>; }`, required)
- **`content`** (`ContentCapability<RenderContentFor<Kernels, Middleware, Kernel>> | undefined`, optional) — Framework content supported by this kernel's composed render route.
- **`cancellation`** (`"cooperative" | undefined`, optional) — Cooperative cancellation support for in-flight renders.

**`CapabilitiesManifest`** — Complete capabilities manifest emitted by the worker during initialization and re-emitted whenever the runtime's resolved capabilities change. Consumers are encouraged to access this manifest only through the helpers exposed on {@link RuntimeClient } (`routesFor`, `bestRouteFor`) so framework tiebreak rules stay encapsulated. The `Kernels` and `Transcoders` generics flow from {@link RuntimeClient } so route fields and per-kernel render schemas narrow to exactly the registered plugins. Wide defaults reproduce the on-wire manifest shape emitted by the worker.

- **`registrations`** (`readonly RuntimeCapabilityRegistration<Kernels>[]`, required)
- **`routes`** (`readonly ExportRoute<Kernels, Middleware, Transcoders, KnownTargetFormats<Kernels, Transcoders>, CollectKernelIds<Kernels>>[]`, required)
- **`renderCapabilities`** (`{ [K in CollectKernelIds<Kernels>]?: { renderOptions: { schema: JSONSchema7; defaults: RenderOptionsFor<Kernels, K>; }; content?: ContentCapability<RenderContentFor<Kernels, Middleware, K>>; cancellation?: "cooperative"; } | undefined; }`, required)

## Related [#related]

* [Handle Errors](/runtime/guides/error-handling)
* [Live Rendering](/runtime/guides/live-rendering)
* [API: Client](/runtime/api/client)
* [API: Filesystem](/runtime/api/filesystem)