@north-light/api 0.3.534 → 0.3.536

package/dist/api/client.d.ts

@@ -65,6 +65,8 @@ export interface CrtrClientOptions {
      *  started has terminally failed (it exited before becoming ready), so the
      *  wait ends immediately with that text instead of polling out the window. */
     coldStartFailure?: () => string | undefined;
+    /** A local relay that was deliberately released ends an availability wait. */
+    availabilityFailure?: () => Error | undefined;
     /** Strict wall-clock window (ms) for local API availability after a cold
      * socket or interrupted response. Each probe is capped to the remaining
      * budget. Defaults to `HEALTHZ_POLL_WINDOW_MS`. */
@@ -113,6 +115,7 @@ export declare class CrtrClient {
     private readonly onColdSocket?;
     private readonly coldStartDiagnostic?;
     private readonly coldStartFailure?;
+    private readonly availabilityFailure?;
     private readonly coldStartPollWindowMs;
     /** Set when the last availability wait ended on a daemon startup failure, whose message already says why. */
     private startupFailureReported;

package/dist/api/client.js

@@ -61,6 +61,7 @@ export class CrtrClient {
     onColdSocket;
     coldStartDiagnostic;
     coldStartFailure;
+    availabilityFailure;
     coldStartPollWindowMs;
     /** Set when the last availability wait ended on a daemon startup failure, whose message already says why. */
     startupFailureReported = false;
@@ -82,6 +83,8 @@ export class CrtrClient {
             this.coldStartDiagnostic = opts.coldStartDiagnostic;
         if (opts.coldStartFailure !== undefined)
             this.coldStartFailure = opts.coldStartFailure;
+        if (opts.availabilityFailure !== undefined)
+            this.availabilityFailure = opts.availabilityFailure;
         this.coldStartPollWindowMs = opts.coldStartPollWindowMs ?? HEALTHZ_POLL_WINDOW_MS;
     }
     // Health / status
@@ -898,6 +901,11 @@ export class CrtrClient {
                 response = await this.transport(method, path, body, opts);
             }
             catch (err) {
+                if (this.isColdSocketError(err) || this.isInterruptedSocketError(err)) {
+                    const released = this.availabilityFailure?.();
+                    if (released !== undefined)
+                        throw released;
+                }
                 if (this.isColdSocketError(err)) {
                     try {
                         await this.handleColdSocket(err, opts.deadlineAt);
@@ -1143,12 +1151,18 @@ export class CrtrClient {
         if (remainingBudgetMs !== undefined && remainingBudgetMs <= 0)
             throw budgetExhausted(deadlineAt);
         let startupFailure;
+        let releaseFailure;
         try {
             await waitForDaemonAvailability({
                 windowMs: Math.min(this.coldStartPollWindowMs, remainingBudgetMs ?? this.coldStartPollWindowMs),
                 initialError,
-                retry: (error) => error !== startupFailure,
+                retry: (error) => error !== startupFailure && error !== releaseFailure,
                 probe: async (timeoutMs) => {
+                    const unavailable = this.availabilityFailure?.();
+                    if (unavailable !== undefined) {
+                        releaseFailure = unavailable;
+                        throw unavailable;
+                    }
                     const failure = this.coldStartFailure?.();
                     if (failure !== undefined) {
                         startupFailure = new ApiError(503, 'daemon_unavailable', `crtrd failed to start: ${failure}`);

package/dist/api/contract.d.ts

@@ -1,5 +1,5 @@
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export declare const CONTRACT_LEVEL = "1.26";
+export declare const CONTRACT_LEVEL = "1.27";
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export declare const REQUIRED_CONTRACT_HEADER = "Crouter-Required-Contract";
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

package/dist/api/contract.js

@@ -12,7 +12,7 @@
 //
 // PURITY (spec §3.1): Node built-ins + `src/api/*` only.
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export const CONTRACT_LEVEL = '1.26';
+export const CONTRACT_LEVEL = '1.27';
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export const REQUIRED_CONTRACT_HEADER = 'Crouter-Required-Contract';
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

package/dist/api/dto/nodes.d.ts

@@ -273,6 +273,8 @@ export interface ListNodesQuery {
     top_level?: boolean;
     /** Restrict to the subtree under this node. */
     under?: NodeIdDTO;
+    /** With `under`: also return the node itself and the human ask nodes below it, which the plain subtree leaves out. */
+    under_inclusive?: boolean;
     /** Only nodes with a dangling/hanging manager edge. */
     hanging?: boolean;
     /** Opt into richer per-node payloads that require filesystem reads. */

package/dist/api/dto/recovery.d.ts

@@ -85,10 +85,11 @@ export interface BrokerProviderRetryResultDTO {
 }
 export interface BrokerProviderRetryRequest {
     expected_execution_id: string;
-    op: 'record-pending' | 'admit' | 'reopen' | 'invalidate' | 'clear';
+    op: 'record-pending' | 'admit' | 'reopen' | 'invalidate' | 'clear' | 'settle-rejected';
     session_id: string;
     fault_id?: string;
     retry?: FaultRetry;
+    reopen?: boolean;
     input?: BrokerFaultInputDTO;
 }
 export interface RecoveryStateDTO {

package/dist/core/canvas/paths.d.ts

@@ -39,6 +39,11 @@ export declare function isolatedNodeHome(nodeId: string, grantee: string): strin
 /** The HOME a node's processes get: its own home in an isolated run, else the app's. */
 export declare function nodeHome(nodeId: string, grantee: string, isolated: boolean): string;
 export declare function nodeRunDir(nodeId: string): string;
+/** File the daemon leaves in a node's run folder when its broker was released on purpose (idle-release, park,
+ *  finish, cancel) and removes when the broker is launched again. A background job's `crtr` call that finds its
+ *  relay socket gone reads it, without asking the daemon, to tell a release from a restart. */
+export declare const BROKER_RELEASED_MARKER = "broker-released";
+export declare const BROKER_RELAY_GENERATION = "cli-relay-generation";
 /** The run's scope allow-list as a JSON array, beside `broker-launch.json`. */
 export declare function scopesFilePath(nodeId: string): string;
 export declare function contextDir(nodeId: string, grantee?: string): string;

package/dist/core/canvas/paths.js

@@ -96,6 +96,11 @@ export function nodeRunDir(nodeId) {
     assertSafeNodeId(nodeId);
     return process.platform === 'linux' ? join(socketDir(), 'nodes', nodeId) : join(nodeRecordDir(nodeId), 'run');
 }
+/** File the daemon leaves in a node's run folder when its broker was released on purpose (idle-release, park,
+ *  finish, cancel) and removes when the broker is launched again. A background job's `crtr` call that finds its
+ *  relay socket gone reads it, without asking the daemon, to tell a release from a restart. */
+export const BROKER_RELEASED_MARKER = 'broker-released';
+export const BROKER_RELAY_GENERATION = 'cli-relay-generation';
 /** The run's scope allow-list as a JSON array, beside `broker-launch.json`. */
 export function scopesFilePath(nodeId) {
     return join(nodeRunDir(nodeId), 'scopes.json');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.534",
+  "version": "0.3.536",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",