@north-light/api 0.3.575 → 0.3.577

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.37";
+export declare const CONTRACT_LEVEL = "1.39";
 /** 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.37';
+export const CONTRACT_LEVEL = '1.39';
 /** 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/core/command-plugins/bundle.d.ts

@@ -131,6 +131,9 @@ export interface InstallBundleArchiveOptions<M> {
     /** Checked against the validated archive before anything is written; a
      *  returned message refuses the archive (a provider bundle naming another id). */
     accept?: (bundle: ValidatedBundle) => string | undefined;
+    /** Default true. False leaves the config version and state validator unwritten: the caller keeps the install record itself
+     *  (a cloud role's deployment-wide provider bundle has no person whose settings could hold it). */
+    record?: boolean;
 }
 export interface InstalledBundleArchive<M> {
     manifest: PluginManifest;
@@ -140,9 +143,9 @@ export interface InstalledBundleArchive<M> {
     staged: M;
 }
 /**
- * Validate `raw`, stage it beside the package root, swap it in, then record
- * the config version and the state validator — in that order, never the
- * reverse. A failure before the swap leaves the previous package untouched.
+ * Validate `raw`, stage it beside the package root, swap it in, then (unless
+ * `record` is false) record the config version and state validator. A failure
+ * before the swap leaves the previous package untouched.
  * The caller holds the plugin's swap lock (`bundleSwapLockPath`).
  */
 export declare function installBundleArchive<M>(name: string, raw: Uint8Array, options: InstallBundleArchiveOptions<M>): Promise<InstalledBundleArchive<M>>;

package/dist/core/command-plugins/bundle.js

@@ -517,9 +517,9 @@ export function writeStagedBundle(stagingRoot, manifest, bundle) {
     syncTree(stagingRoot);
 }
 /**
- * Validate `raw`, stage it beside the package root, swap it in, then record
- * the config version and the state validator — in that order, never the
- * reverse. A failure before the swap leaves the previous package untouched.
+ * Validate `raw`, stage it beside the package root, swap it in, then (unless
+ * `record` is false) record the config version and state validator. A failure
+ * before the swap leaves the previous package untouched.
  * The caller holds the plugin's swap lock (`bundleSwapLockPath`).
  */
 export async function installBundleArchive(name, raw, options) {
@@ -590,18 +590,15 @@ export async function installBundleArchive(name, raw, options) {
     finally {
         removePath(staging);
     }
-    // Directory swap, then the config's version, then the state's validator — in
-    // that order, and never the reverse. A process killed mid-sequence leaves the
-    // ledger naming an OLDER generation than the disk, which the next check
-    // repairs: the server 200s against a stale-or-absent validator, the hash says
-    // the tree on disk is already that generation, and only the ledger is
-    // rewritten. The forbidden state — a validator for a generation the disk does
-    // not have, and so a permanent 304 against a package that was never unpacked
-    // — is unreachable from this order.
-    await ensureScopeInitialized(scope, scopeRootPath);
-    await updateConfig(scope, (cfg) => {
-        cfg.plugins[name] = { enabled: options.enable ? true : (cfg.plugins[name]?.enabled ?? true), version };
-    });
-    await recordCheckedGeneration(scope, name, options.etag, { swapped: true });
+    // For ordinary installs: directory swap, then config version, then state validator. A process killed mid-sequence leaves the
+    // ledger naming an older generation than the disk, which the next check repairs. A cloud-role provider bundle has no person's
+    // settings to update; its caller records the validator after the swap in the deployment's plugin directory instead.
+    if (options.record !== false) {
+        await ensureScopeInitialized(scope, scopeRootPath);
+        await updateConfig(scope, (cfg) => {
+            cfg.plugins[name] = { enabled: options.enable ? true : (cfg.plugins[name]?.enabled ?? true), version };
+        });
+        await recordCheckedGeneration(scope, name, options.etag, { swapped: true });
+    }
     return { manifest, validated, version, root, staged };
 }

package/dist/core/io.js

@@ -360,7 +360,7 @@ export function apiErrorToCliError(err, next, options = {}) {
                     ? `Wait ${provider.retryAfterS}s, then retry; do not retry sooner.`
                     : err.status >= 500
                         ? 'This is a crtr bug, not a bad call. Retry; if it persists, report it (the daemon log holds the full cause).'
-                        : err.status === 404
+                        : err.status === 404 && provider.code === undefined
                             ? 'List nodes with `crtr node inspect list`.'
                             : 'Inspect the error and adjust the call. See -h for the schema.'),
         };

package/dist/core/runtime/broker/daemon-ops.d.ts

@@ -44,6 +44,10 @@ export declare function acknowledgeBrokerMail(nodeId: string, deliveries: MailRe
 export declare function recordBrokerTurn(nodeId: string, request: Omit<BrokerTurnRequest, 'expected_execution_id'>): Promise<BrokerTurnResultDTO>;
 export declare function mutateBrokerProviderRetry(nodeId: string, request: Omit<BrokerProviderRetryRequest, 'expected_execution_id'>): Promise<BrokerProviderRetryResultDTO>;
 export declare function mutateBrokerFault(nodeId: string, request: Omit<BrokerFaultRequest, 'expected_execution_id'>): Promise<BrokerFaultResultDTO>;
+/** A conversation store that refused writes past its deadline: the node's durable fault, written (execution-fenced) before the broker
+ *  exits so the control plane and a harness read the cause. The record is capped at 5 s: a failed or slow record is logged and the
+ *  exit proceeds. */
+export declare function recordConversationWriteFault(nodeId: string, error: unknown): Promise<void>;
 export declare function brokerRecovery(nodeId: string): Promise<RecoveryStateDTO>;
 /** Node-scoped fault writes are for non-broker clients such as attach transport.
  * Broker-owned recovery mutations use the execution-fenced wrappers above. */

package/dist/core/runtime/broker/daemon-ops.js

@@ -7,6 +7,7 @@ import { localClient } from '../../../api/node-transport.js';
 import { ApiError } from '../../../api/errors.js';
 import { envExecutionId } from '../../../shared/env.js';
 import { brokerSignalClient } from './signal-stream.js';
+import { emitEvent } from '../../events/emit.js';
 import { cachedBrokerNodeFields } from '../../../daemon/broker-signals/bus.js';
 import { fetchRunAttachments } from './attachments-fetch.js';
 import { reportRefNodeId } from '../../../shared/inbox-entry-body.js';
@@ -153,15 +154,27 @@ export function mutateBrokerProviderRetry(nodeId, request) {
 export function mutateBrokerFault(nodeId, request) {
     return daemonClient().mutateBrokerFault(nodeId, { ...request, expected_execution_id: brokerExecutionId() });
 }
+/** A conversation store that refused writes past its deadline: the node's durable fault, written (execution-fenced) before the broker
+ *  exits so the control plane and a harness read the cause. The record is capped at 5 s: a failed or slow record is logged and the
+ *  exit proceeds. */
+export async function recordConversationWriteFault(nodeId, error) {
+    const record = mutateBrokerFault(nodeId, {
+        op: 'record',
+        input: { link: 'daemon→node', op: 'conversation_write_failed', kind: 'other', retry: { disposition: 'manual' }, message: error instanceof Error ? error.message : String(error) },
+    });
+    await Promise.race([record, new Promise((_, reject) => setTimeout(() => reject(new Error('conversation_write_failed fault record timed out')), 5_000).unref())])
+        .catch((faultError) => emitEvent({ level: 'error', event: 'broker.daemon.operation.failed', node_id: nodeId, error: faultError, fields: { operation: 'conversation_write_fault_record' } }));
+}
 export function brokerRecovery(nodeId) {
     return daemonClient().getBrokerRecovery(nodeId, brokerExecutionId());
 }
 /** Node-scoped fault writes are for non-broker clients such as attach transport.
  * Broker-owned recovery mutations use the execution-fenced wrappers above. */
-export function recordNodeFault(nodeId, input) {
+export async function recordNodeFault(nodeId, input) {
+    // `async` so a process with no way to reach the API (no node token) rejects instead of throwing inside a socket handler.
     return daemonClient().recordNodeFault(nodeId, input);
 }
-export function clearNodeFault(nodeId, opts = {}) {
+export async function clearNodeFault(nodeId, opts = {}) {
     return daemonClient().clearNodeFault(nodeId, {
         ...(opts.link === undefined ? {} : { link: opts.link }),
         ...(opts.preserveEpisode === undefined ? {} : { preserve_episode: opts.preserveEpisode }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.575",
+  "version": "0.3.577",
   "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",