@tochii/errors 0.0.0-stage → 0.1.6

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+## 0.1.6 (October 2026)
+
+<!-- release:start -->
+
+### CI
+- Updated workflows ([#b1a1b89](https://github.com/tochiResources/errors/commit/b1a1b89) by [T0chi](https://github.com/T0chi))
+
+<!-- release:end -->
+
+
+## 0.1.5 (October 2026)
+
+### CI
+- Added `dev` to `ci.yml`'s push branches ([#ff15308](https://github.com/tochiResources/errors/commit/ff15308) by [T0chi](https://github.com/T0chi))
+
+## 0.1.4 (October 2026)
+
+### CI
+- Updated workflows ([#b2e3380](https://github.com/tochiResources/errors/commit/b2e3380) by [T0chi](https://github.com/T0chi))
+
+## 0.1.3 (October 2026)
+
+### Chores
+- Set package to public ([#a8428d3](https://github.com/tochiResources/errors/commit/a8428d3) by [T0chi](https://github.com/T0chi))
+
+## 0.1.2 (October 2026)
+
+### CI
+- Updated added `dev` branch ([#4b928a6](https://github.com/tochiResources/errors/commit/4b928a6) by [T0chi](https://github.com/T0chi))
+- Updated changelog branch ([#59a6f69](https://github.com/tochiResources/errors/commit/59a6f69) by [T0chi](https://github.com/T0chi))
+- Updated packaging flow ([#b4f3dbb](https://github.com/tochiResources/errors/commit/b4f3dbb) by [T0chi](https://github.com/T0chi))
+### Chores
+- Added `CHANGELOG.md` ([#1b53d03](https://github.com/tochiResources/errors/commit/1b53d03) by [T0chi](https://github.com/T0chi))
+- Code cleanup ([#e914f15](https://github.com/tochiResources/errors/commit/e914f15) by [T0chi](https://github.com/T0chi))
+- Update package.json description ([#edf61d0](https://github.com/tochiResources/errors/commit/edf61d0) by [T0chi](https://github.com/T0chi))
+#### Errors
+- Initialize repository ([#e39bad5](https://github.com/tochiResources/errors/commit/e39bad5) by [T0chi](https://github.com/T0chi))
+
+## 0.1.1 (October 2026)
+
+### CI
+- Updated packaging flow ([#b4f3dbb](https://github.com/tochiResources/errors/commit/b4f3dbb) by T0chi)
+### Chores
+- Code cleanup ([#e914f15](https://github.com/tochiResources/errors/commit/e914f15) by T0chi)
+- Update package.json description ([#edf61d0](https://github.com/tochiResources/errors/commit/edf61d0) by T0chi)
+#### Errors
+- Initialize repository ([#e39bad5](https://github.com/tochiResources/errors/commit/e39bad5) by T0chi)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tochiResources
+
+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

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# @tochii/errors
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![tests](https://img.shields.io/github/actions/workflow/status/tochiResources/errors/ci.yml?label=tests&logo=github)](https://github.com/tochiResources/errors/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@tochii/errors.svg?color=cb3837&label=npm)](https://www.npmjs.com/package/@tochii/errors)
+
+Shared typed errors and stable error codes used in official tochiResources proejcts.
+
+- **Stable codes**: the string value is part of the contract; never reuse or rename one. Both TS and C# switch on it.
+- **Typed classes**: `instanceof ConfigError`, `instanceof IpcError`, per domain, all extending `TochiResError`.
+- **Serializable**: `serializeError` / `deserializeError` move errors across JSON-RPC unchanged (message, code, context, cause chain).
+- **Context**: every error can carry structured `context` for logging/telemetry.
+
+## Projects using @tochii/errors
+
+- [AeToOsb](https://github.com/tochiResources/AeToOsb)
+- [AeBrew](https://github.com/tochiResources/AeBrew)
+- [osu! Storyboarding toolkit](https://github.com/tochiResources/osb-toolkit)
+- [tochiResources Adobe CEP](https://github.com/tochiResources/cep)
+
+## Usage
+
+```ts
+import { ConfigError, ErrorCode, isTochiResError, serializeError } from '@tochii/errors';
+
+try {
+    throw new ConfigError('app.name is required', {
+        code: ErrorCode.ConfigMissing,
+        context: { field: 'name' },
+    });
+} catch (error) {
+    if (isTochiResError(error)) {
+        console.error(error.code, error.message, error.context);
+        socket.send(JSON.stringify(serializeError(error)));
+    }
+}
+```
+
+## Development
+
+- **node 22.5+**, **yarn 4**, **vitest 5**, **tsdown**
+
+```sh
+yarn install
+yarn build
+yarn lint
+yarn typecheck
+yarn test
+```
+
+## License
+
+MIT. See [LICENSE](/LICENSE).

package/csharp/Errors.cs

@@ -0,0 +1,275 @@
+using System;
+using System.Collections.Generic;
+
+namespace TochiRes.Errors;
+
+/// <summary>
+/// Stable error codes shared with the TypeScript side (<c>@tochii/errors</c>).
+/// Keep in sync with <c>src/codes.ts</c>. A code is part of the
+/// public contract: never rename or reuse one — add a new code instead.
+/// </summary>
+public static class ErrorCodes
+{
+    // General
+    public const string Unknown = "TOCHIRES_UNKNOWN";
+    public const string Internal = "TOCHIRES_INTERNAL";
+
+    // Config
+    public const string ConfigInvalid = "TOCHIRES_CONFIG_INVALID";
+    public const string ConfigMissing = "TOCHIRES_CONFIG_MISSING";
+
+    // Validation
+    public const string ValidationFailed = "TOCHIRES_VALIDATION_FAILED";
+
+    // API / HTTP boundary
+    public const string ApiBadRequest = "TOCHIRES_API_BAD_REQUEST";
+    public const string ApiUnauthorized = "TOCHIRES_API_UNAUTHORIZED";
+    public const string ApiForbidden = "TOCHIRES_API_FORBIDDEN";
+    public const string ApiNotFound = "TOCHIRES_API_NOT_FOUND";
+    public const string ApiConflict = "TOCHIRES_API_CONFLICT";
+    public const string ApiUnprocessable = "TOCHIRES_API_UNPROCESSABLE";
+    public const string ApiTooManyRequests = "TOCHIRES_API_TOO_MANY_REQUESTS";
+    public const string ApiTimeout = "TOCHIRES_API_TIMEOUT";
+    public const string ApiUnavailable = "TOCHIRES_API_UNAVAILABLE";
+
+    // IPC
+    public const string IpcTransport = "TOCHIRES_IPC_TRANSPORT";
+    public const string IpcProtocol = "TOCHIRES_IPC_PROTOCOL";
+    public const string IpcTimeout = "TOCHIRES_IPC_TIMEOUT";
+    public const string IpcAuth = "TOCHIRES_IPC_AUTH";
+    public const string IpcDisconnected = "TOCHIRES_IPC_DISCONNECTED";
+    public const string IpcBackpressure = "TOCHIRES_IPC_BACKPRESSURE";
+
+    // Codegen
+    public const string CodegenUnsupported = "TOCHIRES_CODEGEN_UNSUPPORTED";
+    public const string CodegenEmit = "TOCHIRES_CODEGEN_EMIT";
+    public const string CodegenRoundtrip = "TOCHIRES_CODEGEN_ROUNDTRIP";
+
+    // CSS
+    public const string CssParse = "TOCHIRES_CSS_PARSE";
+    public const string CssUnsupportedProperty = "TOCHIRES_CSS_UNSUPPORTED_PROPERTY";
+    public const string CssUnsupportedSelector = "TOCHIRES_CSS_UNSUPPORTED_SELECTOR";
+
+    // Native
+    public const string NativeModuleNotFound = "TOCHIRES_NATIVE_MODULE_NOT_FOUND";
+    public const string NativeMethodNotFound = "TOCHIRES_NATIVE_METHOD_NOT_FOUND";
+    public const string NativeCallFailed = "TOCHIRES_NATIVE_CALL_FAILED";
+
+    // Build
+    public const string BuildFailed = "TOCHIRES_BUILD_FAILED";
+    public const string BuildToolMissing = "TOCHIRES_BUILD_TOOL_MISSING";
+
+    // Package
+    public const string PackageFailed = "TOCHIRES_PACKAGE_FAILED";
+    public const string PackageSigning = "TOCHIRES_PACKAGE_SIGNING";
+
+    // Settings
+    public const string SettingsParse = "TOCHIRES_SETTINGS_PARSE";
+    public const string SettingsInvalid = "TOCHIRES_SETTINGS_INVALID";
+
+    // Path
+    public const string PathInvalid = "TOCHIRES_PATH_INVALID";
+    public const string PathAbsolute = "TOCHIRES_PATH_ABSOLUTE";
+
+    /// <summary>Every known code, for validation and diagnostics.</summary>
+    public static readonly IReadOnlyList<string> All = new[]
+    {
+        Unknown, Internal,
+        ConfigInvalid, ConfigMissing,
+        ValidationFailed,
+        ApiBadRequest, ApiUnauthorized, ApiForbidden, ApiNotFound, ApiConflict,
+        ApiUnprocessable, ApiTooManyRequests, ApiTimeout, ApiUnavailable,
+        IpcTransport, IpcProtocol, IpcTimeout, IpcAuth, IpcDisconnected, IpcBackpressure,
+        CodegenUnsupported, CodegenEmit, CodegenRoundtrip,
+        CssParse, CssUnsupportedProperty, CssUnsupportedSelector,
+        NativeModuleNotFound, NativeMethodNotFound, NativeCallFailed,
+        BuildFailed, BuildToolMissing,
+        PackageFailed, PackageSigning,
+        SettingsParse, SettingsInvalid,
+        PathInvalid, PathAbsolute,
+    };
+
+    private static readonly IReadOnlyDictionary<string, string> CategoryByCode =
+        new Dictionary<string, string>(StringComparer.Ordinal)
+        {
+            [Unknown] = "general",
+            [Internal] = "general",
+            [ConfigInvalid] = "config",
+            [ConfigMissing] = "config",
+            [ValidationFailed] = "validation",
+            [ApiBadRequest] = "api",
+            [ApiUnauthorized] = "api",
+            [ApiForbidden] = "api",
+            [ApiNotFound] = "api",
+            [ApiConflict] = "api",
+            [ApiUnprocessable] = "api",
+            [ApiTooManyRequests] = "api",
+            [ApiTimeout] = "api",
+            [ApiUnavailable] = "api",
+            [IpcTransport] = "ipc",
+            [IpcProtocol] = "ipc",
+            [IpcTimeout] = "ipc",
+            [IpcAuth] = "ipc",
+            [IpcDisconnected] = "ipc",
+            [IpcBackpressure] = "ipc",
+            [CodegenUnsupported] = "codegen",
+            [CodegenEmit] = "codegen",
+            [CodegenRoundtrip] = "codegen",
+            [CssParse] = "css",
+            [CssUnsupportedProperty] = "css",
+            [CssUnsupportedSelector] = "css",
+            [NativeModuleNotFound] = "native",
+            [NativeMethodNotFound] = "native",
+            [NativeCallFailed] = "native",
+            [BuildFailed] = "build",
+            [BuildToolMissing] = "build",
+            [PackageFailed] = "package",
+            [PackageSigning] = "package",
+            [SettingsParse] = "settings",
+            [SettingsInvalid] = "settings",
+            [PathInvalid] = "path",
+            [PathAbsolute] = "path",
+        };
+
+    /// <summary>Whether <paramref name="code"/> is one of the known stable codes.</summary>
+    public static bool IsKnown(string? code) => code is not null && CategoryByCode.ContainsKey(code);
+
+    /// <summary>The category a code belongs to, or <c>"general"</c> when unknown.</summary>
+    public static string CategoryOf(string? code) =>
+        code is not null && CategoryByCode.TryGetValue(code, out var category) ? category : "general";
+}
+
+/// <summary>
+/// Base exception for every error defined by this package.
+/// Mirrors <c>TochiResError</c> from the TypeScript implementation.
+/// </summary>
+public class TochiResException : Exception
+{
+    /// <summary>Stable error code — part of the public contract.</summary>
+    public string Code { get; }
+
+    /// <summary>Coarse category derived from <see cref="Code"/>.</summary>
+    public string Category { get; }
+
+    /// <summary>Structured, JSON-safe context for logging and telemetry.</summary>
+    public IReadOnlyDictionary<string, object?>? Context { get; }
+
+    public TochiResException(
+        string code,
+        string message,
+        Exception? innerException = null,
+        IReadOnlyDictionary<string, object?>? context = null)
+        : base(message, innerException)
+    {
+        Code = code;
+        Category = ErrorCodes.CategoryOf(code);
+        Context = context;
+    }
+}
+
+/// <summary>Configuration is missing or failed validation.</summary>
+public sealed class ConfigException : TochiResException
+{
+    public ConfigException(string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(ErrorCodes.ConfigInvalid, message, inner, context) { }
+
+    public ConfigException(string code, string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(code, message, inner, context) { }
+}
+
+/// <summary>A payload, schema or argument failed validation.</summary>
+public sealed class ValidationException : TochiResException
+{
+    public ValidationException(string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(ErrorCodes.ValidationFailed, message, inner, context) { }
+}
+
+/// <summary>An API/HTTP boundary failure (bad request, auth, not found, conflict, …).</summary>
+public sealed class ApiException : TochiResException
+{
+    public ApiException(string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(ErrorCodes.ApiBadRequest, message, inner, context) { }
+
+    public ApiException(string code, string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(code, message, inner, context) { }
+}
+
+/// <summary>An IPC transport, protocol, authentication or timeout failure.</summary>
+public sealed class IpcException : TochiResException
+{
+    public IpcException(string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(ErrorCodes.IpcTransport, message, inner, context) { }
+
+    public IpcException(string code, string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(code, message, inner, context) { }
+}
+
+/// <summary>A TS→C# code generator failed or hit an unsupported construct.</summary>
+public sealed class CodegenException : TochiResException
+{
+    public CodegenException(string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(ErrorCodes.CodegenEmit, message, inner, context) { }
+
+    public CodegenException(string code, string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(code, message, inner, context) { }
+}
+
+/// <summary>CSS input is invalid or outside the supported subset.</summary>
+public sealed class CssException : TochiResException
+{
+    public CssException(string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(ErrorCodes.CssParse, message, inner, context) { }
+
+    public CssException(string code, string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(code, message, inner, context) { }
+}
+
+/// <summary>A native module or method was missing, or a native call failed.</summary>
+public sealed class NativeException : TochiResException
+{
+    public NativeException(string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(ErrorCodes.NativeCallFailed, message, inner, context) { }
+
+    public NativeException(string code, string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(code, message, inner, context) { }
+}
+
+/// <summary>A build pipeline step failed or a required tool is missing.</summary>
+public sealed class BuildException : TochiResException
+{
+    public BuildException(string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(ErrorCodes.BuildFailed, message, inner, context) { }
+
+    public BuildException(string code, string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(code, message, inner, context) { }
+}
+
+/// <summary>A packaging, signing or notarization step failed.</summary>
+public sealed class PackageException : TochiResException
+{
+    public PackageException(string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(ErrorCodes.PackageFailed, message, inner, context) { }
+
+    public PackageException(string code, string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(code, message, inner, context) { }
+}
+
+/// <summary>Settings text could not be parsed or failed validation.</summary>
+public sealed class SettingsException : TochiResException
+{
+    public SettingsException(string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(ErrorCodes.SettingsInvalid, message, inner, context) { }
+
+    public SettingsException(string code, string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(code, message, inner, context) { }
+}
+
+/// <summary>A path was malformed or violated the relative-path rule.</summary>
+public sealed class PathException : TochiResException
+{
+    public PathException(string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(ErrorCodes.PathInvalid, message, inner, context) { }
+
+    public PathException(string code, string message, Exception? inner = null, IReadOnlyDictionary<string, object?>? context = null)
+        : base(code, message, inner, context) { }
+}

package/csharp/TochiRes.Errors.csproj

@@ -0,0 +1,40 @@
+<Project Sdk="Microsoft.NET.Sdk">
+    <PropertyGroup>
+        <TargetFrameworks>netstandard2.0;net8.0</TargetFrameworks>
+        <LangVersion>latest</LangVersion>
+        <Nullable>enable</Nullable>
+        <ImplicitUsings>disable</ImplicitUsings>
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
+        <NoWarn>$(NoWarn);CS1591</NoWarn>
+
+        <PackageJsonPath>$(MSBuildThisFileDirectory)../package.json</PackageJsonPath>
+
+        <PackageJsonVersion>$([System.Text.RegularExpressions.Regex]::Match($([System.IO.File]::ReadAllText('$(PackageJsonPath)')), '"version"\s*:\s*"([^"]+)"').Groups[1].Value)</PackageJsonVersion>
+        <PackageJsonDescription>$([System.Text.RegularExpressions.Regex]::Match($([System.IO.File]::ReadAllText('$(PackageJsonPath)')), '"description"\s*:\s*"([^"]*)"').Groups[1].Value)</PackageJsonDescription>
+        <PackageJsonRepositoryUrl>$([System.Text.RegularExpressions.Regex]::Match($([System.IO.File]::ReadAllText('$(PackageJsonPath)')), '"repository"\s*:\s*\{[^}]*"url"\s*:\s*"(?:git\+)?(https?://[^"]+?)(?:\.git)?"').Groups[1].Value)</PackageJsonRepositoryUrl>
+        <PackageJsonAuthor>$([System.Text.RegularExpressions.Regex]::Match($([System.IO.File]::ReadAllText('$(PackageJsonPath)')), '"author"\s*:\s*"([^"]*)"').Groups[1].Value)</PackageJsonAuthor>
+        <PackageJsonLicense>$([System.Text.RegularExpressions.Regex]::Match($([System.IO.File]::ReadAllText('$(PackageJsonPath)')), '"license"\s*:\s*"([^"]*)"').Groups[1].Value)</PackageJsonLicense>
+
+        <PackageId>TochiRes.Errors</PackageId>
+        <Version>$(PackageJsonVersion)</Version>
+        <Authors>$(PackageJsonAuthor)</Authors>
+        <Description>$(PackageJsonDescription)</Description>
+        <PackageLicenseExpression>$(PackageJsonLicense)</PackageLicenseExpression>
+        <RepositoryUrl>$(PackageJsonRepositoryUrl)</RepositoryUrl>
+        <RepositoryType>git</RepositoryType>
+        <PackageProjectUrl>$(PackageJsonRepositoryUrl)</PackageProjectUrl>
+        <PackageReadmeFile>README.md</PackageReadmeFile>
+        <PackageTags>errors;exceptions;error-codes</PackageTags>
+
+        <IncludeSymbols>true</IncludeSymbols>
+        <SymbolPackageFormat>snupkg</SymbolPackageFormat>
+        <PublishRepositoryUrl>true</PublishRepositoryUrl>
+        <EmbedUntrackedSources>true</EmbedUntrackedSources>
+        <ContinuousIntegrationBuild Condition="'$(CI)' == 'true'">true</ContinuousIntegrationBuild>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <None Include="../README.md" Pack="true" PackagePath="\" />
+        <PackageReference Include="Microsoft.SourceLink.GitHub" Version="10.0.403" PrivateAssets="all" />
+    </ItemGroup>
+</Project>

package/dist/codes-CCNEPVSz.d.ts

@@ -0,0 +1,97 @@
+//#region src/codes.d.ts
+/**
+ * Stable error codes shared by the TypeScript and C# implementations.
+ *
+ * A code is part of the public contract: it is persisted in logs, sent across
+ * the JSON-RPC boundary and switched on by consumers (including the C# mirror
+ * in `Errors.cs`).
+ * Never rename or reuse a code — add a new one and deprecate the old.
+ */
+declare const ErrorCode: {
+  /** An error that could not be classified. */
+  readonly Unknown: "TOCHIRES_UNKNOWN";
+  /** An invariant inside the library was violated. */
+  readonly Internal: "TOCHIRES_INTERNAL";
+  /** A configuration object failed validation. */
+  readonly ConfigInvalid: "TOCHIRES_CONFIG_INVALID";
+  /** A required configuration field is missing. */
+  readonly ConfigMissing: "TOCHIRES_CONFIG_MISSING";
+  /** A generic validation failure (payload, schema, argument). */
+  readonly ValidationFailed: "TOCHIRES_VALIDATION_FAILED";
+  /** The request was malformed or failed validation at an API boundary. */
+  readonly ApiBadRequest: "TOCHIRES_API_BAD_REQUEST";
+  /** Authentication is required, or the session/token is invalid. */
+  readonly ApiUnauthorized: "TOCHIRES_API_UNAUTHORIZED";
+  /** The authenticated principal is not allowed to perform the action. */
+  readonly ApiForbidden: "TOCHIRES_API_FORBIDDEN";
+  /** The requested resource does not exist. */
+  readonly ApiNotFound: "TOCHIRES_API_NOT_FOUND";
+  /** The request conflicts with the current state of the resource. */
+  readonly ApiConflict: "TOCHIRES_API_CONFLICT";
+  /** The payload was well-formed but is semantically invalid. */
+  readonly ApiUnprocessable: "TOCHIRES_API_UNPROCESSABLE";
+  /** The caller exceeded an imposed rate limit. */
+  readonly ApiTooManyRequests: "TOCHIRES_API_TOO_MANY_REQUESTS";
+  /** An upstream dependency did not respond in time. */
+  readonly ApiTimeout: "TOCHIRES_API_TIMEOUT";
+  /** A downstream dependency is unavailable. */
+  readonly ApiUnavailable: "TOCHIRES_API_UNAVAILABLE";
+  /** The IPC transport could not be opened or used. */
+  readonly IpcTransport: "TOCHIRES_IPC_TRANSPORT";
+  /** A JSON-RPC envelope was malformed or violated the protocol. */
+  readonly IpcProtocol: "TOCHIRES_IPC_PROTOCOL";
+  /** A request did not receive a response in time. */
+  readonly IpcTimeout: "TOCHIRES_IPC_TIMEOUT";
+  /** Token authentication failed. */
+  readonly IpcAuth: "TOCHIRES_IPC_AUTH";
+  /** The peer disconnected before the operation completed. */
+  readonly IpcDisconnected: "TOCHIRES_IPC_DISCONNECTED";
+  /** A stream was paused because the consumer fell behind. */
+  readonly IpcBackpressure: "TOCHIRES_IPC_BACKPRESSURE";
+  /** A TypeScript construct has no C# codegen mapping. */
+  readonly CodegenUnsupported: "TOCHIRES_CODEGEN_UNSUPPORTED";
+  /** A generator failed while emitting an artifact. */
+  readonly CodegenEmit: "TOCHIRES_CODEGEN_EMIT";
+  /** Generated output did not round-trip back to its source. */
+  readonly CodegenRoundtrip: "TOCHIRES_CODEGEN_ROUNDTRIP";
+  /** CSS input could not be parsed. */
+  readonly CssParse: "TOCHIRES_CSS_PARSE";
+  /** A CSS property is outside the supported subset. */
+  readonly CssUnsupportedProperty: "TOCHIRES_CSS_UNSUPPORTED_PROPERTY";
+  /** A CSS selector is outside the supported subset. */
+  readonly CssUnsupportedSelector: "TOCHIRES_CSS_UNSUPPORTED_SELECTOR";
+  /** A native module was not registered on the C# host. */
+  readonly NativeModuleNotFound: "TOCHIRES_NATIVE_MODULE_NOT_FOUND";
+  /** A native method was not registered on a module. */
+  readonly NativeMethodNotFound: "TOCHIRES_NATIVE_METHOD_NOT_FOUND";
+  /** A native method threw or returned an error. */
+  readonly NativeCallFailed: "TOCHIRES_NATIVE_CALL_FAILED";
+  /** A build pipeline step failed. */
+  readonly BuildFailed: "TOCHIRES_BUILD_FAILED";
+  /** A required build tool (dotnet, esbuild, …) is unavailable. */
+  readonly BuildToolMissing: "TOCHIRES_BUILD_TOOL_MISSING";
+  /** A packaging step failed. */
+  readonly PackageFailed: "TOCHIRES_PACKAGE_FAILED";
+  /** Signing or notarization failed. */
+  readonly PackageSigning: "TOCHIRES_PACKAGE_SIGNING";
+  /** Settings text could not be parsed. */
+  readonly SettingsParse: "TOCHIRES_SETTINGS_PARSE";
+  /** Settings values failed validation against their spec. */
+  readonly SettingsInvalid: "TOCHIRES_SETTINGS_INVALID";
+  /** A path was malformed. */
+  readonly PathInvalid: "TOCHIRES_PATH_INVALID";
+  /** An absolute path was supplied where only relative paths are allowed. */
+  readonly PathAbsolute: "TOCHIRES_PATH_ABSOLUTE";
+};
+/** Union of every stable error code. */
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+/** Coarse grouping used for reporting, filtering and C# exception types. */
+type ErrorCategory = 'general' | 'config' | 'validation' | 'api' | 'ipc' | 'codegen' | 'css' | 'native' | 'build' | 'package' | 'settings' | 'path';
+/** All codes, as an array — handy for exhaustiveness checks and docs. */
+declare const ERROR_CODES: ErrorCode[];
+/** Whether a value is one of the known stable codes. */
+declare function isErrorCode(value: unknown): value is ErrorCode;
+/** The category a code belongs to, or `'general'` for unknown codes. */
+declare function categoryOf(code: ErrorCode): ErrorCategory;
+//#endregion
+export { isErrorCode as a, categoryOf as i, ErrorCategory as n, ErrorCode as r, ERROR_CODES as t };

package/dist/codes.d.ts

@@ -0,0 +1,2 @@
+import { a as isErrorCode, i as categoryOf, n as ErrorCategory, r as ErrorCode, t as ERROR_CODES } from "./codes-CCNEPVSz.js";
+export { ERROR_CODES, ErrorCategory, ErrorCode, categoryOf, isErrorCode };

package/dist/codes.js

@@ -0,0 +1,136 @@
+//#region src/codes.ts
+/**
+* Stable error codes shared by the TypeScript and C# implementations.
+*
+* A code is part of the public contract: it is persisted in logs, sent across
+* the JSON-RPC boundary and switched on by consumers (including the C# mirror
+* in `Errors.cs`).
+* Never rename or reuse a code — add a new one and deprecate the old.
+*/
+const ErrorCode = {
+	/** An error that could not be classified. */
+	Unknown: "TOCHIRES_UNKNOWN",
+	/** An invariant inside the library was violated. */
+	Internal: "TOCHIRES_INTERNAL",
+	/** A configuration object failed validation. */
+	ConfigInvalid: "TOCHIRES_CONFIG_INVALID",
+	/** A required configuration field is missing. */
+	ConfigMissing: "TOCHIRES_CONFIG_MISSING",
+	/** A generic validation failure (payload, schema, argument). */
+	ValidationFailed: "TOCHIRES_VALIDATION_FAILED",
+	/** The request was malformed or failed validation at an API boundary. */
+	ApiBadRequest: "TOCHIRES_API_BAD_REQUEST",
+	/** Authentication is required, or the session/token is invalid. */
+	ApiUnauthorized: "TOCHIRES_API_UNAUTHORIZED",
+	/** The authenticated principal is not allowed to perform the action. */
+	ApiForbidden: "TOCHIRES_API_FORBIDDEN",
+	/** The requested resource does not exist. */
+	ApiNotFound: "TOCHIRES_API_NOT_FOUND",
+	/** The request conflicts with the current state of the resource. */
+	ApiConflict: "TOCHIRES_API_CONFLICT",
+	/** The payload was well-formed but is semantically invalid. */
+	ApiUnprocessable: "TOCHIRES_API_UNPROCESSABLE",
+	/** The caller exceeded an imposed rate limit. */
+	ApiTooManyRequests: "TOCHIRES_API_TOO_MANY_REQUESTS",
+	/** An upstream dependency did not respond in time. */
+	ApiTimeout: "TOCHIRES_API_TIMEOUT",
+	/** A downstream dependency is unavailable. */
+	ApiUnavailable: "TOCHIRES_API_UNAVAILABLE",
+	/** The IPC transport could not be opened or used. */
+	IpcTransport: "TOCHIRES_IPC_TRANSPORT",
+	/** A JSON-RPC envelope was malformed or violated the protocol. */
+	IpcProtocol: "TOCHIRES_IPC_PROTOCOL",
+	/** A request did not receive a response in time. */
+	IpcTimeout: "TOCHIRES_IPC_TIMEOUT",
+	/** Token authentication failed. */
+	IpcAuth: "TOCHIRES_IPC_AUTH",
+	/** The peer disconnected before the operation completed. */
+	IpcDisconnected: "TOCHIRES_IPC_DISCONNECTED",
+	/** A stream was paused because the consumer fell behind. */
+	IpcBackpressure: "TOCHIRES_IPC_BACKPRESSURE",
+	/** A TypeScript construct has no C# codegen mapping. */
+	CodegenUnsupported: "TOCHIRES_CODEGEN_UNSUPPORTED",
+	/** A generator failed while emitting an artifact. */
+	CodegenEmit: "TOCHIRES_CODEGEN_EMIT",
+	/** Generated output did not round-trip back to its source. */
+	CodegenRoundtrip: "TOCHIRES_CODEGEN_ROUNDTRIP",
+	/** CSS input could not be parsed. */
+	CssParse: "TOCHIRES_CSS_PARSE",
+	/** A CSS property is outside the supported subset. */
+	CssUnsupportedProperty: "TOCHIRES_CSS_UNSUPPORTED_PROPERTY",
+	/** A CSS selector is outside the supported subset. */
+	CssUnsupportedSelector: "TOCHIRES_CSS_UNSUPPORTED_SELECTOR",
+	/** A native module was not registered on the C# host. */
+	NativeModuleNotFound: "TOCHIRES_NATIVE_MODULE_NOT_FOUND",
+	/** A native method was not registered on a module. */
+	NativeMethodNotFound: "TOCHIRES_NATIVE_METHOD_NOT_FOUND",
+	/** A native method threw or returned an error. */
+	NativeCallFailed: "TOCHIRES_NATIVE_CALL_FAILED",
+	/** A build pipeline step failed. */
+	BuildFailed: "TOCHIRES_BUILD_FAILED",
+	/** A required build tool (dotnet, esbuild, …) is unavailable. */
+	BuildToolMissing: "TOCHIRES_BUILD_TOOL_MISSING",
+	/** A packaging step failed. */
+	PackageFailed: "TOCHIRES_PACKAGE_FAILED",
+	/** Signing or notarization failed. */
+	PackageSigning: "TOCHIRES_PACKAGE_SIGNING",
+	/** Settings text could not be parsed. */
+	SettingsParse: "TOCHIRES_SETTINGS_PARSE",
+	/** Settings values failed validation against their spec. */
+	SettingsInvalid: "TOCHIRES_SETTINGS_INVALID",
+	/** A path was malformed. */
+	PathInvalid: "TOCHIRES_PATH_INVALID",
+	/** An absolute path was supplied where only relative paths are allowed. */
+	PathAbsolute: "TOCHIRES_PATH_ABSOLUTE"
+};
+const CATEGORY_BY_CODE = {
+	[ErrorCode.Unknown]: "general",
+	[ErrorCode.Internal]: "general",
+	[ErrorCode.ConfigInvalid]: "config",
+	[ErrorCode.ConfigMissing]: "config",
+	[ErrorCode.ValidationFailed]: "validation",
+	[ErrorCode.ApiBadRequest]: "api",
+	[ErrorCode.ApiUnauthorized]: "api",
+	[ErrorCode.ApiForbidden]: "api",
+	[ErrorCode.ApiNotFound]: "api",
+	[ErrorCode.ApiConflict]: "api",
+	[ErrorCode.ApiUnprocessable]: "api",
+	[ErrorCode.ApiTooManyRequests]: "api",
+	[ErrorCode.ApiTimeout]: "api",
+	[ErrorCode.ApiUnavailable]: "api",
+	[ErrorCode.IpcTransport]: "ipc",
+	[ErrorCode.IpcProtocol]: "ipc",
+	[ErrorCode.IpcTimeout]: "ipc",
+	[ErrorCode.IpcAuth]: "ipc",
+	[ErrorCode.IpcDisconnected]: "ipc",
+	[ErrorCode.IpcBackpressure]: "ipc",
+	[ErrorCode.CodegenUnsupported]: "codegen",
+	[ErrorCode.CodegenEmit]: "codegen",
+	[ErrorCode.CodegenRoundtrip]: "codegen",
+	[ErrorCode.CssParse]: "css",
+	[ErrorCode.CssUnsupportedProperty]: "css",
+	[ErrorCode.CssUnsupportedSelector]: "css",
+	[ErrorCode.NativeModuleNotFound]: "native",
+	[ErrorCode.NativeMethodNotFound]: "native",
+	[ErrorCode.NativeCallFailed]: "native",
+	[ErrorCode.BuildFailed]: "build",
+	[ErrorCode.BuildToolMissing]: "build",
+	[ErrorCode.PackageFailed]: "package",
+	[ErrorCode.PackageSigning]: "package",
+	[ErrorCode.SettingsParse]: "settings",
+	[ErrorCode.SettingsInvalid]: "settings",
+	[ErrorCode.PathInvalid]: "path",
+	[ErrorCode.PathAbsolute]: "path"
+};
+/** All codes, as an array — handy for exhaustiveness checks and docs. */
+const ERROR_CODES = Object.values(ErrorCode);
+/** Whether a value is one of the known stable codes. */
+function isErrorCode(value) {
+	return typeof value === "string" && Object.hasOwn(CATEGORY_BY_CODE, value);
+}
+/** The category a code belongs to, or `'general'` for unknown codes. */
+function categoryOf(code) {
+	return CATEGORY_BY_CODE[code] ?? "general";
+}
+//#endregion
+export { ERROR_CODES, ErrorCode, categoryOf, isErrorCode };

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+import { a as isErrorCode, i as categoryOf, n as ErrorCategory, r as ErrorCode, t as ERROR_CODES } from "./codes-CCNEPVSz.js";
+import { a as TochiResErrorOptions, i as TochiResError, n as isSerializedError, o as serializeCause, r as serializeError, s as SerializedError, t as deserializeError } from "./serialize-xEOKnPuJ.js";
+//#region src/errors/options.d.ts
+/** Options shared by every domain error class (adds an optional code override). */
+interface DomainErrorOptions extends TochiResErrorOptions {
+  /** Override the class's default code. */
+  code?: ErrorCode;
+}
+//#endregion
+//#region src/errors/api.d.ts
+/** An API/HTTP boundary failure (bad request, auth, not found, conflict, …). */
+export declare class ApiError extends TochiResError {
+  constructor(message: string, options?: DomainErrorOptions);
+}
+//#endregion
+//#region src/errors/build.d.ts
+/** A build pipeline step failed or a required tool is missing. */
+export declare class BuildError extends TochiResError {
+  constructor(message: string, options?: DomainErrorOptions);
+}
+//#endregion
+//#region src/errors/codegen.d.ts
+/** A TS→C# code generator failed or hit an unsupported construct. */
+export declare class CodegenError extends TochiResError {
+  constructor(message: string, options?: DomainErrorOptions);
+}
+//#endregion
+//#region src/errors/config.d.ts
+/** Configuration is missing or failed validation. */
+export declare class ConfigError extends TochiResError {
+  constructor(message: string, options?: DomainErrorOptions);
+}
+//#endregion
+//#region src/errors/css.d.ts
+/** CSS input is invalid or outside the supported subset. */
+export declare class CssError extends TochiResError {
+  constructor(message: string, options?: DomainErrorOptions);
+}
+//#endregion
+//#region src/errors/ipc.d.ts
+/** An IPC transport, protocol, authentication or timeout failure. */
+export declare class IpcError extends TochiResError {
+  constructor(message: string, options?: DomainErrorOptions);
+}
+//#endregion
+//#region src/errors/native.d.ts
+/** A native module or method was missing, or a native call failed. */
+export declare class NativeError extends TochiResError {
+  constructor(message: string, options?: DomainErrorOptions);
+}
+//#endregion
+//#region src/errors/package.d.ts
+/** A packaging, signing or notarization step failed. */
+export declare class PackageError extends TochiResError {
+  constructor(message: string, options?: DomainErrorOptions);
+}
+//#endregion
+//#region src/errors/path.d.ts
+/** A path was malformed or violated the relative-path rule. */
+export declare class PathError extends TochiResError {
+  constructor(message: string, options?: DomainErrorOptions);
+}
+//#endregion
+//#region src/errors/settings.d.ts
+/** Settings text could not be parsed or failed validation. */
+export declare class SettingsError extends TochiResError {
+  constructor(message: string, options?: DomainErrorOptions);
+}
+//#endregion
+//#region src/errors/validation.d.ts
+/** A payload, schema or argument failed validation. */
+export declare class ValidationError extends TochiResError {
+  constructor(message: string, options?: DomainErrorOptions);
+}
+//#endregion
+//#region src/errors/index.d.ts
+/** Constructor shape shared by every domain error class. */
+type DomainErrorConstructor = new (message: string, options?: DomainErrorOptions) => TochiResError;
+/**
+ * The domain error class responsible for a code, or `undefined` for generic
+ * codes (which use {@link TochiResError} directly).
+ */
+export declare function errorClassFor(code: ErrorCode): DomainErrorConstructor | undefined;
+//#endregion
+//#region src/guard.d.ts
+/** Narrow a value to {@link TochiResError}. */
+export declare function isTochiResError(value: unknown): value is TochiResError;
+/** Whether a value is a {@link TochiResError} carrying one of the given codes. */
+export declare function hasErrorCode(value: unknown, ...codes: ErrorCode[]): boolean;
+/**
+ * Coerce any thrown value into a {@link TochiResError}.
+ *
+ * Already-typed errors pass through unchanged; native `Error`s and arbitrary
+ * thrown values are wrapped with {@link ErrorCode.Unknown} and kept as `cause`.
+ */
+export declare function toTochiResError(value: unknown, fallbackMessage?: string): TochiResError;
+/** Assert a condition, throwing a {@link TochiResError} with the given code if falsy. */
+export declare function assertTochiRes(condition: unknown, code: ErrorCode, message: string, options?: TochiResErrorOptions): asserts condition;
+//#endregion
+export { type DomainErrorConstructor, type DomainErrorOptions, ERROR_CODES, type ErrorCategory, ErrorCode, type SerializedError, TochiResError, type TochiResErrorOptions, categoryOf, deserializeError, isErrorCode, isSerializedError, serializeCause, serializeError };

package/dist/index.js

@@ -0,0 +1,28 @@
+import { ERROR_CODES, ErrorCode, categoryOf, isErrorCode } from "./codes.js";
+import { _ as serializeCause, a as ValidationError, c as PackageError, d as CssError, f as ConfigError, g as TochiResError, h as ApiError, i as errorClassFor, l as NativeError, m as BuildError, n as isSerializedError, o as SettingsError, p as CodegenError, r as serializeError, s as PathError, t as deserializeError, u as IpcError } from "./serialize-D7PDJ704.js";
+//#region src/guard.ts
+/** Narrow a value to {@link TochiResError}. */
+function isTochiResError(value) {
+	return value instanceof TochiResError;
+}
+/** Whether a value is a {@link TochiResError} carrying one of the given codes. */
+function hasErrorCode(value, ...codes) {
+	return value instanceof TochiResError && codes.includes(value.code);
+}
+/**
+* Coerce any thrown value into a {@link TochiResError}.
+*
+* Already-typed errors pass through unchanged; native `Error`s and arbitrary
+* thrown values are wrapped with {@link ErrorCode.Unknown} and kept as `cause`.
+*/
+function toTochiResError(value, fallbackMessage = "Unknown error") {
+	if (value instanceof TochiResError) return value;
+	if (value instanceof Error) return new TochiResError(ErrorCode.Unknown, value.message, { cause: value });
+	return new TochiResError(ErrorCode.Unknown, typeof value === "string" ? value : fallbackMessage, { cause: value });
+}
+/** Assert a condition, throwing a {@link TochiResError} with the given code if falsy. */
+function assertTochiRes(condition, code, message, options = {}) {
+	if (!condition) throw new TochiResError(code, message, options);
+}
+//#endregion
+export { ApiError, BuildError, CodegenError, ConfigError, CssError, ERROR_CODES, ErrorCode, IpcError, NativeError, PackageError, PathError, SettingsError, TochiResError, ValidationError, assertTochiRes, categoryOf, deserializeError, errorClassFor, hasErrorCode, isErrorCode, isSerializedError, isTochiResError, serializeCause, serializeError, toTochiResError };

package/dist/serialize-D7PDJ704.js

@@ -0,0 +1,249 @@
+import { ErrorCode, categoryOf, isErrorCode } from "./codes.js";
+//#region src/base.ts
+/**
+* Base class for every typed error in this package.
+*
+* Carries a stable {@link ErrorCode} (mirrored in C#), a derived
+* {@link ErrorCategory}, optional structured context and an optional cause
+* chain, and serializes to a {@link SerializedError} that survives JSON-RPC.
+*/
+var TochiResError = class extends Error {
+	/** Stable code — part of the public contract. */
+	code;
+	/** Coarse category derived from {@link code}. */
+	category;
+	/** Structured, JSON-safe context. */
+	context;
+	/** Underlying cause, if any. */
+	cause;
+	constructor(code, message, options = {}) {
+		super(message);
+		this.name = "TochiResError";
+		this.code = code;
+		this.category = categoryOf(code);
+		if (options.context !== void 0) this.context = options.context;
+		if (options.cause !== void 0) this.cause = options.cause;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+	/** Serialize this error (and its cause chain) to a wire-safe object. */
+	toJSON() {
+		const json = {
+			name: this.name,
+			code: this.code,
+			category: this.category,
+			message: this.message
+		};
+		if (this.stack) json.stack = this.stack;
+		if (this.context) json.context = this.context;
+		const cause = serializeCause(this.cause);
+		if (cause) json.cause = cause;
+		return json;
+	}
+};
+/** Serialize any value used as a `cause` into a {@link SerializedError}. */
+function serializeCause(value) {
+	if (value === void 0) return void 0;
+	if (value instanceof TochiResError) return value.toJSON();
+	if (value instanceof Error) {
+		const json = {
+			name: value.name || "Error",
+			code: ErrorCode.Unknown,
+			category: "general",
+			message: value.message
+		};
+		if (value.stack) json.stack = value.stack;
+		return json;
+	}
+	return {
+		name: "Error",
+		code: ErrorCode.Unknown,
+		category: "general",
+		message: stringifyUnknown$1(value)
+	};
+}
+function stringifyUnknown$1(value) {
+	if (typeof value === "string") return value;
+	try {
+		return JSON.stringify(value) ?? String(value);
+	} catch {
+		return String(value);
+	}
+}
+//#endregion
+//#region src/errors/api.ts
+/** An API/HTTP boundary failure (bad request, auth, not found, conflict, …). */
+var ApiError = class extends TochiResError {
+	constructor(message, options = {}) {
+		super(options.code ?? ErrorCode.ApiBadRequest, message, options);
+		this.name = "ApiError";
+	}
+};
+//#endregion
+//#region src/errors/build.ts
+/** A build pipeline step failed or a required tool is missing. */
+var BuildError = class extends TochiResError {
+	constructor(message, options = {}) {
+		super(options.code ?? ErrorCode.BuildFailed, message, options);
+		this.name = "BuildError";
+	}
+};
+//#endregion
+//#region src/errors/codegen.ts
+/** A TS→C# code generator failed or hit an unsupported construct. */
+var CodegenError = class extends TochiResError {
+	constructor(message, options = {}) {
+		super(options.code ?? ErrorCode.CodegenEmit, message, options);
+		this.name = "CodegenError";
+	}
+};
+//#endregion
+//#region src/errors/config.ts
+/** Configuration is missing or failed validation. */
+var ConfigError = class extends TochiResError {
+	constructor(message, options = {}) {
+		super(options.code ?? ErrorCode.ConfigInvalid, message, options);
+		this.name = "ConfigError";
+	}
+};
+//#endregion
+//#region src/errors/css.ts
+/** CSS input is invalid or outside the supported subset. */
+var CssError = class extends TochiResError {
+	constructor(message, options = {}) {
+		super(options.code ?? ErrorCode.CssParse, message, options);
+		this.name = "CssError";
+	}
+};
+//#endregion
+//#region src/errors/ipc.ts
+/** An IPC transport, protocol, authentication or timeout failure. */
+var IpcError = class extends TochiResError {
+	constructor(message, options = {}) {
+		super(options.code ?? ErrorCode.IpcTransport, message, options);
+		this.name = "IpcError";
+	}
+};
+//#endregion
+//#region src/errors/native.ts
+/** A native module or method was missing, or a native call failed. */
+var NativeError = class extends TochiResError {
+	constructor(message, options = {}) {
+		super(options.code ?? ErrorCode.NativeCallFailed, message, options);
+		this.name = "NativeError";
+	}
+};
+//#endregion
+//#region src/errors/package.ts
+/** A packaging, signing or notarization step failed. */
+var PackageError = class extends TochiResError {
+	constructor(message, options = {}) {
+		super(options.code ?? ErrorCode.PackageFailed, message, options);
+		this.name = "PackageError";
+	}
+};
+//#endregion
+//#region src/errors/path.ts
+/** A path was malformed or violated the relative-path rule. */
+var PathError = class extends TochiResError {
+	constructor(message, options = {}) {
+		super(options.code ?? ErrorCode.PathInvalid, message, options);
+		this.name = "PathError";
+	}
+};
+//#endregion
+//#region src/errors/settings.ts
+/** Settings text could not be parsed or failed validation. */
+var SettingsError = class extends TochiResError {
+	constructor(message, options = {}) {
+		super(options.code ?? ErrorCode.SettingsInvalid, message, options);
+		this.name = "SettingsError";
+	}
+};
+//#endregion
+//#region src/errors/validation.ts
+/** A payload, schema or argument failed validation. */
+var ValidationError = class extends TochiResError {
+	constructor(message, options = {}) {
+		super(options.code ?? ErrorCode.ValidationFailed, message, options);
+		this.name = "ValidationError";
+	}
+};
+//#endregion
+//#region src/errors/index.ts
+const CLASS_BY_CATEGORY = {
+	config: ConfigError,
+	validation: ValidationError,
+	api: ApiError,
+	ipc: IpcError,
+	codegen: CodegenError,
+	css: CssError,
+	native: NativeError,
+	build: BuildError,
+	package: PackageError,
+	settings: SettingsError,
+	path: PathError
+};
+/**
+* The domain error class responsible for a code, or `undefined` for generic
+* codes (which use {@link TochiResError} directly).
+*/
+function errorClassFor(code) {
+	const category = categoryOf(code);
+	return category === "general" ? void 0 : CLASS_BY_CATEGORY[category];
+}
+//#endregion
+//#region src/serialize.ts
+/** Serialize any thrown value into a {@link SerializedError}. */
+function serializeError(value) {
+	if (value instanceof TochiResError) return value.toJSON();
+	if (value instanceof Error) {
+		const json = {
+			name: value.name || "Error",
+			code: ErrorCode.Unknown,
+			category: "general",
+			message: value.message
+		};
+		if (value.stack) json.stack = value.stack;
+		return json;
+	}
+	return {
+		name: "Error",
+		code: ErrorCode.Unknown,
+		category: "general",
+		message: stringifyUnknown(value)
+	};
+}
+/** Whether a value looks like a {@link SerializedError}. */
+function isSerializedError(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const record = value;
+	return isErrorCode(record.code) && typeof record.message === "string";
+}
+/**
+* Rebuild a {@link TochiResError} (with the right domain subclass) from a
+* {@link SerializedError}, preserving the cause chain.
+*/
+function deserializeError(value) {
+	const record = typeof value === "object" && value !== null ? value : {};
+	const code = isErrorCode(record.code) ? record.code : ErrorCode.Unknown;
+	const message = typeof record.message === "string" ? record.message : "Unknown error";
+	const ErrorClass = errorClassFor(code);
+	const context = record.context;
+	const error = ErrorClass ? new ErrorClass(message, {
+		code,
+		context
+	}) : new TochiResError(code, message, context ? { context } : {});
+	if (record.stack) error.stack = record.stack;
+	if (record.cause) error.cause = deserializeError(record.cause);
+	return error;
+}
+function stringifyUnknown(value) {
+	if (typeof value === "string") return value;
+	try {
+		return JSON.stringify(value) ?? String(value);
+	} catch {
+		return String(value);
+	}
+}
+//#endregion
+export { serializeCause as _, ValidationError as a, PackageError as c, CssError as d, ConfigError as f, TochiResError as g, ApiError as h, errorClassFor as i, NativeError as l, BuildError as m, isSerializedError as n, SettingsError as o, CodegenError as p, serializeError as r, PathError as s, deserializeError as t, IpcError as u };

package/dist/serialize-xEOKnPuJ.d.ts

@@ -0,0 +1,66 @@
+import { n as ErrorCategory, r as ErrorCode } from "./codes-CCNEPVSz.js";
+//#region src/types.d.ts
+/**
+ * The wire representation of an error. Produced by {@link serializeError} and
+ * accepted by `deserializeError`; safe to embed in a JSON-RPC error object.
+ */
+interface SerializedError {
+  /** The error class name, e.g. `ConfigError`. */
+  name: string;
+  /** Stable {@link ErrorCode}. */
+  code: ErrorCode;
+  /** Coarse category derived from the code. */
+  category: ErrorCategory;
+  /** Human-readable message. */
+  message: string;
+  /** Stack trace, when available. */
+  stack?: string;
+  /** Structured, JSON-safe context for logging/telemetry. */
+  context?: Record<string, unknown>;
+  /** Serialized cause chain. */
+  cause?: SerializedError;
+}
+//#endregion
+//#region src/base.d.ts
+/** Options accepted by every {@link TochiResError}. */
+interface TochiResErrorOptions {
+  /** Underlying error/value that caused this one. */
+  cause?: unknown;
+  /** Structured, JSON-safe context for logging and telemetry. */
+  context?: Record<string, unknown>;
+}
+/**
+ * Base class for every typed error in this package.
+ *
+ * Carries a stable {@link ErrorCode} (mirrored in C#), a derived
+ * {@link ErrorCategory}, optional structured context and an optional cause
+ * chain, and serializes to a {@link SerializedError} that survives JSON-RPC.
+ */
+declare class TochiResError extends Error {
+  /** Stable code — part of the public contract. */
+  readonly code: ErrorCode;
+  /** Coarse category derived from {@link code}. */
+  readonly category: ErrorCategory;
+  /** Structured, JSON-safe context. */
+  readonly context?: Record<string, unknown>;
+  /** Underlying cause, if any. */
+  readonly cause?: unknown;
+  constructor(code: ErrorCode, message: string, options?: TochiResErrorOptions);
+  /** Serialize this error (and its cause chain) to a wire-safe object. */
+  toJSON(): SerializedError;
+}
+/** Serialize any value used as a `cause` into a {@link SerializedError}. */
+declare function serializeCause(value: unknown): SerializedError | undefined;
+//#endregion
+//#region src/serialize.d.ts
+/** Serialize any thrown value into a {@link SerializedError}. */
+declare function serializeError(value: unknown): SerializedError;
+/** Whether a value looks like a {@link SerializedError}. */
+declare function isSerializedError(value: unknown): value is SerializedError;
+/**
+ * Rebuild a {@link TochiResError} (with the right domain subclass) from a
+ * {@link SerializedError}, preserving the cause chain.
+ */
+declare function deserializeError(value: unknown): TochiResError;
+//#endregion
+export { TochiResErrorOptions as a, TochiResError as i, isSerializedError as n, serializeCause as o, serializeError as r, SerializedError as s, deserializeError as t };

package/dist/serialize.d.ts

@@ -0,0 +1,2 @@
+import { n as isSerializedError, r as serializeError, t as deserializeError } from "./serialize-xEOKnPuJ.js";
+export { deserializeError, isSerializedError, serializeError };

package/dist/serialize.js

@@ -0,0 +1,3 @@
+import "./codes.js";
+import { n as isSerializedError, r as serializeError, t as deserializeError } from "./serialize-D7PDJ704.js";
+export { deserializeError, isSerializedError, serializeError };

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@tochii/errors",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.6",
+  "description": "Shared typed errors and stable error codes used in official tochiResources proejcts.",
+  "license": "MIT",
+  "author": "T0chi",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tochiResources/errors.git"
+  },
+  "scripts": {
+    "build": "tsdown --config-loader unrun",
+    "format": "dbx fmt",
+    "lint": "dbx lint --fix",
+    "check": "dbx check",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "dbx": "dbx",
+    "commitlint": "commitlint",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
+    "@deltabox/toolchain": "^1.11.3",
+    "@types/node": "^22.10.2",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "husky": "^9.1.7",
+    "tsdown": "^0.23.0",
+    "tsx": "^4.23.13",
+    "typescript": "^6.0.3",
+    "unrun": "^0.3.1",
+    "vite": "^8.3.0",
+    "vite-plus": "^1.2.0",
+    "vitest": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "yarn@4.17.1",
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "files": [
+    "dist",
+    "csharp"
+  ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./codes": "./dist/codes.js",
+    "./serialize": "./dist/serialize.js",
+    "./package.json": "./package.json"
+  }
 }