@cat-factory/kernel 0.170.0 → 0.172.0

package/dist/shared/best-effort.d.ts

@@ -0,0 +1,28 @@
+import type { LogFields, Logger } from '../ports/logging.js';
+/**
+ * Describe a thrown value as log fields. The message is scrubbed with `redactSecrets`
+ * because an error surfaced from `fetch`, a shell spawn or a provider SDK routinely
+ * echoes the URL (with its query) or an auth header back in its text.
+ *
+ * Only the message and the constructor name are kept: a stack is high-volume and rarely
+ * the thing that identifies the failure in a structured log. Pass one explicitly when a
+ * specific site needs it.
+ */
+export declare function describeError(error: unknown): LogFields;
+/**
+ * Run `fn` and swallow any rejection, logging it at `warn` with `label` as the operation
+ * name. Returns `undefined` when the work failed, so a caller that wants the value can
+ * still branch on it, and never rejects.
+ *
+ * Use it for work that is genuinely optional. It is the WRONG tool when the failure should
+ * change what the caller does — that wants a real `try`/`catch` with a domain decision.
+ *
+ * ```ts
+ * void runBestEffort(logger, 'execution.autoStartDependents', () => this.autoStartDependents(id), {
+ *   workspaceId,
+ *   executionId,
+ * })
+ * ```
+ */
+export declare function runBestEffort<T>(logger: Logger, label: string, fn: () => Promise<T> | T, fields?: LogFields): Promise<T | undefined>;
+//# sourceMappingURL=best-effort.d.ts.map

package/dist/shared/best-effort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"best-effort.d.ts","sourceRoot":"","sources":["../../src/shared/best-effort.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAG5D;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAKvD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACxB,MAAM,GAAE,SAAc,GACrB,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAOxB"}

package/dist/shared/best-effort.js

@@ -0,0 +1,49 @@
+// The convention for a deliberately-swallowed failure. A background write, a tracker
+// echo, a lease release, a notification raise: work whose failure must NOT propagate into
+// the caller, but which was previously dropped by `.catch(() => {})` — leaving no log, no
+// metric and no marker (see `docs/initiatives/observability-logging-gaps.md`, B1).
+//
+// `runBestEffort` keeps the swallow and adds the evidence. Every drop becomes one
+// `warn` line naming the operation, with the cause scrubbed. Patterns and the rules for
+// when to use it: `backend/docs/logging.md`.
+import { redactSecrets } from './redact-secrets.logic.js';
+/**
+ * Describe a thrown value as log fields. The message is scrubbed with `redactSecrets`
+ * because an error surfaced from `fetch`, a shell spawn or a provider SDK routinely
+ * echoes the URL (with its query) or an auth header back in its text.
+ *
+ * Only the message and the constructor name are kept: a stack is high-volume and rarely
+ * the thing that identifies the failure in a structured log. Pass one explicitly when a
+ * specific site needs it.
+ */
+export function describeError(error) {
+    if (error instanceof Error) {
+        return { err: redactSecrets(error.message) ?? '', errKind: error.name };
+    }
+    return { err: redactSecrets(String(error)) ?? '', errKind: typeof error };
+}
+/**
+ * Run `fn` and swallow any rejection, logging it at `warn` with `label` as the operation
+ * name. Returns `undefined` when the work failed, so a caller that wants the value can
+ * still branch on it, and never rejects.
+ *
+ * Use it for work that is genuinely optional. It is the WRONG tool when the failure should
+ * change what the caller does — that wants a real `try`/`catch` with a domain decision.
+ *
+ * ```ts
+ * void runBestEffort(logger, 'execution.autoStartDependents', () => this.autoStartDependents(id), {
+ *   workspaceId,
+ *   executionId,
+ * })
+ * ```
+ */
+export async function runBestEffort(logger, label, fn, fields = {}) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        logger.warn(`best-effort ${label} failed`, { ...fields, ...describeError(error) });
+        return undefined;
+    }
+}
+//# sourceMappingURL=best-effort.js.map

package/dist/shared/best-effort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"best-effort.js","sourceRoot":"","sources":["../../src/shared/best-effort.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,0FAA0F;AAC1F,0FAA0F;AAC1F,mFAAmF;AACnF,EAAE;AACF,kFAAkF;AAClF,wFAAwF;AACxF,6CAA6C;AAG7C,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAEzD;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,EAAE,GAAG,EAAE,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,CAAA;IACzE,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,KAAK,EAAE,CAAA;AAC3E,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAc,EACd,KAAa,EACb,EAAwB,EACxB,MAAM,GAAc,EAAE;IAEtB,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAA;IACnB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CAAC,eAAe,KAAK,SAAS,EAAE,EAAE,GAAG,MAAM,EAAE,GAAG,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QAClF,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/kernel",
-  "version": "0.170.0",
+  "version": "0.172.0",
   "description": "Shared vocabulary, pure logic, and port interfaces for the Agent Architecture Board.",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
   "dependencies": {
     "ai": "^7.0.37",
     "yaml": "^2.9.0",
-    "@cat-factory/contracts": "0.177.0"
+    "@cat-factory/contracts": "0.179.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.10",