@astrale-os/sdk 0.5.0-beta.125 → 0.5.0-beta.126

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.5.0-beta.126](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.125...sdk-v0.5.0-beta.126) (2026-09-07)
+
+
+### Bug Fixes
+
+* expose runtime-safe schema error declarations ([#457](https://github.com/astrale-os/sdk/issues/457)) ([67e2fd1](https://github.com/astrale-os/sdk/commit/67e2fd1a92fca1096a928510405d8a6c6f0fd7ef))
+* preserve safe installation failure diagnostics ([#456](https://github.com/astrale-os/sdk/issues/456)) ([5466a9e](https://github.com/astrale-os/sdk/commit/5466a9e7aa597d114fcd947be26df5ce823d6277))
+
 ## [0.5.0-beta.125](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.124...sdk-v0.5.0-beta.125) (2026-09-07)
 
 

package/README.md

@@ -65,7 +65,7 @@ Schema authoring.
 Declare reusable business errors in `schema/modules/<module>/errors/` through the Schema facade:
 
 ```typescript
-import { error } from '@astrale-os/sdk/schema'
+import { error } from '@astrale-os/sdk/schema/errors'
 import { z } from 'zod'
 
 export const resourceUnavailable = error({
@@ -79,6 +79,8 @@ Register the declaration under a code in an Action or Workflow's options:
 `{ errors: { RESOURCE_UNAVAILABLE: resourceUnavailable } }`. Its handler can then
 `throw error('RESOURCE_UNAVAILABLE', { resource: id })` using the context factory.
 The builder validates and freezes declaration metadata while preserving exact details inference.
+Use `sdk/schema/errors` for declarations shared with handlers: this narrow entrypoint keeps the
+Schema compiler and Kernel Schema initialization out of the deployed Runtime.
 Error declarations are not yet published in the installed Kernel Schema.
 
 ## Development

package/dist/platform/schema/errors/index.d.ts

@@ -0,0 +1,3 @@
+/** Runtime-safe business-error declarations shared by Schema and handlers. */
+export { error } from '../error.js';
+export type { DeclaredErrorDefinition, DeclaredErrorFamily } from '../error.js';

package/dist/platform/schema/errors/index.js

@@ -0,0 +1,2 @@
+/** Runtime-safe business-error declarations shared by Schema and handlers. */
+export { error } from '../error.js';

package/dist/tooling/cli/astrale/failure.d.ts

@@ -1,3 +1,6 @@
 import type { AstraleProcessResult } from './process.js';
+/** Only sanitized CLI diagnostics may be promoted through installation failures. */
+export declare class AstraleCliError extends Error {
+}
 export declare function astraleFailure(command: string, result: AstraleProcessResult): Error;
 export declare function isDomainNotInstalledFailure(stderr: string): boolean;

package/dist/tooling/cli/astrale/failure.js

@@ -1,3 +1,6 @@
+/** Only sanitized CLI diagnostics may be promoted through installation failures. */
+export class AstraleCliError extends Error {
+}
 export function astraleFailure(command, result) {
     let diagnostic;
     try {
@@ -11,7 +14,7 @@ export function astraleFailure(command, result) {
     catch {
         // Never forward raw stderr because a credential-bearing command owns it.
     }
-    return new Error(`Astrale CLI ${command} failed${diagnostic === undefined ? '' : ` (${diagnostic})`}.`);
+    return new AstraleCliError(`Astrale CLI ${command} failed${diagnostic === undefined ? '' : ` (${diagnostic})`}.`);
 }
 function admittedCode(input) {
     return typeof input === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/u.test(input) ? input : undefined;

package/dist/tooling/cli/installation/reconcile.js

@@ -1,5 +1,5 @@
 import { astraleAuthorityArguments } from '../astrale/authority.js';
-import { isDomainNotInstalledFailure, astraleFailure } from '../astrale/failure.js';
+import { AstraleCliError, isDomainNotInstalledFailure, astraleFailure } from '../astrale/failure.js';
 import { runAstrale } from '../astrale/process.js';
 import { canonicalIssuer, decodeInstallationObservation } from './observation.js';
 /** Reconcile one observed Release without ever replacing a different issuer. */
@@ -57,10 +57,10 @@ export async function reconcileInstallation(input, dependencies = {
         after = await observe(input, origin, authority, executable, dependencies);
     }
     catch (cause) {
-        throw new AggregateError(installationFailure === undefined ? [cause] : [installationFailure, cause], 'Domain installation outcome is unknown because reconciliation failed.');
+        throw installationError(installationFailure === undefined ? [cause] : [installationFailure, cause], 'Domain installation outcome is unknown because reconciliation failed.');
     }
     if (installationFailure !== undefined && after === undefined) {
-        throw new AggregateError([installationFailure], 'Domain installation failed and no installed Release was observed.');
+        throw installationError([installationFailure], 'Domain installation failed and no installed Release was observed.');
     }
     if (after === undefined)
         throw new TypeError('Installed Domain was absent after installation.');
@@ -73,10 +73,16 @@ export async function reconcileInstallation(input, dependencies = {
     catch (cause) {
         if (installationFailure === undefined)
             throw cause;
-        throw new AggregateError([installationFailure, cause], 'Domain installation failed with a different observed Release.');
+        throw installationError([installationFailure, cause], 'Domain installation failed with a different observed Release.');
     }
     return evidence(before === undefined ? 'installed' : 'upgraded', input.target.instance, after);
 }
+function installationError(causes, message) {
+    const diagnostics = causes
+        .filter((cause) => cause instanceof AstraleCliError)
+        .map((cause) => cause.message);
+    return new AggregateError(causes, [message, ...diagnostics].join(' '));
+}
 async function observe(input, origin, authority, executable, dependencies) {
     const result = await dependencies.run({
         executable,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/sdk",
-  "version": "0.5.0-beta.125",
+  "version": "0.5.0-beta.126",
   "description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
   "keywords": [
     "astrale",
@@ -47,6 +47,10 @@
       "types": "./dist/platform/schema/icons/index.d.ts",
       "import": "./dist/platform/schema/icons/index.js"
     },
+    "./schema/errors": {
+      "types": "./dist/platform/schema/errors/index.d.ts",
+      "import": "./dist/platform/schema/errors/index.js"
+    },
     "./schema/addressing": {
       "types": "./dist/platform/schema/addressing/index.d.ts",
       "import": "./dist/platform/schema/addressing/index.js"