@holokai/neuron-sdk 0.6.0 → 0.7.0

package/dist/{transport-Va7tTRVO.d.mts → transport-BhFVHvR7.d.mts}

@@ -788,6 +788,12 @@ interface NeuronLogger {
     warn(meta: Record<string, unknown>, msg?: string): void;
     error(meta: Record<string, unknown>, msg?: string): void;
 }
+/** What a handler states when it fails a lease; see {@link HandlerContext.fail}. */
+interface HandlerFailureOptions {
+    code?: string;
+    details?: unknown;
+    kind?: 'terminal' | 'retryable';
+}
 /** Per-handler context passed to `neuron.handle(...)` callbacks. */
 interface HandlerContext {
     /** Lease metadata for this delivery. */
@@ -815,13 +821,13 @@ interface HandlerContext {
         data?: unknown;
     }): void;
     /**
-     * Terminal failure — short-circuits the handler with a non-retryable
-     * nack containing the given reason. Throws an internal error to bail
-     * out of the handler; do not catch it.
+     * Fail the lease with a nack and bail out of the handler; do not catch the
+     * throw. `reason` is the sentence a reader sees; `code` names the failure;
+     * `details` carries any structured facts (never required to understand the
+     * reason). `kind` defaults to `terminal` (the same input will not succeed);
+     * `retryable` says the same input may succeed later.
      */
-    fail(reason: string, opts?: {
-        code?: string;
-    }): never;
+    fail(reason: string, opts?: HandlerFailureOptions): never;
 }
 /**
  * Low-level capability registration: type + scope + concurrency + optional
@@ -952,4 +958,4 @@ interface TransportCallbacks {
     }) => void;
 }
 
-export type { AuthCallback as A, Capability as C, Handler as H, JsonSchema as J, LeasePayload as L, NeuronLogger as N, PostPath as P, ServerToNeuronFrame as S, Transport as T, CapabilityHandleOptions as a, CapabilityRegistration as b, TransportCallbacks as c, ClientFrame as d, HandlerContext as e, HeartbeatInFlightEntry as f, TaskPayload as g };
+export type { AuthCallback as A, Capability as C, Handler as H, JsonSchema as J, LeasePayload as L, NeuronLogger as N, PostPath as P, ServerToNeuronFrame as S, Transport as T, CapabilityHandleOptions as a, CapabilityRegistration as b, TransportCallbacks as c, ClientFrame as d, HandlerContext as e, HandlerFailureOptions as f, HeartbeatInFlightEntry as g, TaskPayload as h };

package/dist/{transport-Va7tTRVO.d.ts → transport-BhFVHvR7.d.ts}

@@ -788,6 +788,12 @@ interface NeuronLogger {
     warn(meta: Record<string, unknown>, msg?: string): void;
     error(meta: Record<string, unknown>, msg?: string): void;
 }
+/** What a handler states when it fails a lease; see {@link HandlerContext.fail}. */
+interface HandlerFailureOptions {
+    code?: string;
+    details?: unknown;
+    kind?: 'terminal' | 'retryable';
+}
 /** Per-handler context passed to `neuron.handle(...)` callbacks. */
 interface HandlerContext {
     /** Lease metadata for this delivery. */
@@ -815,13 +821,13 @@ interface HandlerContext {
         data?: unknown;
     }): void;
     /**
-     * Terminal failure — short-circuits the handler with a non-retryable
-     * nack containing the given reason. Throws an internal error to bail
-     * out of the handler; do not catch it.
+     * Fail the lease with a nack and bail out of the handler; do not catch the
+     * throw. `reason` is the sentence a reader sees; `code` names the failure;
+     * `details` carries any structured facts (never required to understand the
+     * reason). `kind` defaults to `terminal` (the same input will not succeed);
+     * `retryable` says the same input may succeed later.
      */
-    fail(reason: string, opts?: {
-        code?: string;
-    }): never;
+    fail(reason: string, opts?: HandlerFailureOptions): never;
 }
 /**
  * Low-level capability registration: type + scope + concurrency + optional
@@ -952,4 +958,4 @@ interface TransportCallbacks {
     }) => void;
 }
 
-export type { AuthCallback as A, Capability as C, Handler as H, JsonSchema as J, LeasePayload as L, NeuronLogger as N, PostPath as P, ServerToNeuronFrame as S, Transport as T, CapabilityHandleOptions as a, CapabilityRegistration as b, TransportCallbacks as c, ClientFrame as d, HandlerContext as e, HeartbeatInFlightEntry as f, TaskPayload as g };
+export type { AuthCallback as A, Capability as C, Handler as H, JsonSchema as J, LeasePayload as L, NeuronLogger as N, PostPath as P, ServerToNeuronFrame as S, Transport as T, CapabilityHandleOptions as a, CapabilityRegistration as b, TransportCallbacks as c, ClientFrame as d, HandlerContext as e, HandlerFailureOptions as f, HeartbeatInFlightEntry as g, TaskPayload as h };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holokai/neuron-sdk",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "SDK for building Holokai neurons — connect to a BigBrain gateway over HTTP+SSE or Electron IPC and execute capability-typed tasks.",
   "license": "MIT",
   "author": "Holokai",