apps 0.0.1-beta.43 → 0.0.1-beta.44

package/types/telemetry/src/recorded-failure.d.ts

@@ -1,20 +1,29 @@
 /**
- * Failures as Executor's telemetry records them. An error whose message can carry an app's own
- * text declares a fixed sentence instead (see `RecordedMessage`); traces and error reports record
- * that sentence with the error's name. The error itself, and what its caller receives, are
- * unchanged.
+ * Failures as Executor's telemetry records them. Traces and error reports keep an error's text only
+ * when Executor wrote it: a tagged error is recorded by its tag and the fixed sentence it declares
+ * (see `RecordedMessage`), or by its tag alone when it declares none. Its fields, message, stack and
+ * cause are not recorded, so a value an error carries for its caller, an app's text or a service's
+ * reply cannot reach telemetry by an error forgetting to declare. The error itself, and what its
+ * caller receives, are unchanged.
  */
 import { Cause } from "effect";
 /**
- * The error a trace or error report records in place of `error`. Its stack is generated here and
- * names no frames: the error's own stack begins with its message, which can span lines that look
- * like frames, so none of its text is kept. Traces still show where it failed through the
- * operation's own spans, which Effect appends to a recorded stack.
+ * The error a trace or error report records in place of `error`.
+ *
+ * - A tagged error is named by its tag: a field called `name`, such as a requested skill's or an
+ *   app's, replaces the error's own name. Its message is the sentence it declares, or empty. Its
+ *   stack is generated here and names no frames: the error's own stack begins with its message,
+ *   which can span lines that look like frames. Traces still show where it failed through the
+ *   operation's own spans, which Effect appends to a recorded stack.
+ * - Any other value that is not an `Error`, such as a plain object Effect would print as JSON, is
+ *   recorded as `UnrecognizedFailure` with no text.
+ * - An untagged `Error` is a defect or a platform's error: its message and stack come from the
+ *   JavaScript engine or a library and are kept, as they are the only diagnosis of an Executor bug.
+ *   Its cause is recorded by these same rules.
  */
 export declare const recordedError: (error: unknown) => unknown;
 /**
- * A failure's cause as traces record it. A defect is recorded the same way when it is an error that
- * declares a recorded message, such as a workflow failure a host turned into a defect; other
- * defects and interruptions are unchanged. Each reason keeps its annotations, which locate it.
+ * A failure's cause as traces record it: each failure and defect by `recordedError`. Interruptions
+ * are unchanged, and each reason keeps its annotations, which locate it.
  */
 export declare const recordedCause: <E>(cause: Cause.Cause<E>) => Cause.Cause<unknown>;

package/types/utils/src/api-error.d.ts

@@ -24,8 +24,10 @@ type Definition<Tag extends string, Fields extends Schema.Struct.Fields> = Heade
      */
     readonly message: string | ((fields: Schema.Struct.Type<Fields>) => string);
     /**
-     * What traces and error reports record instead of `message`, when the message quotes an app's
-     * own error or a service's stated error for its caller. Only fixed text and typed fields.
+     * What traces and error reports record beside the tag. A fixed `message` is recorded as is; a
+     * message derived from fields is recorded only through this, from fixed text and closed fields,
+     * never a value the caller chose, an app's text or a service's reply. Without it the error is
+     * recorded by its tag alone.
      */
     readonly recorded?: (fields: Schema.Struct.Type<Fields>) => string;
 };

package/types/utils/src/recorded-message.d.ts

@@ -1,8 +1,11 @@
 /**
- * What traces and error reports record for an error in place of its message. An error declares
- * one when its message can carry text from outside Executor: an app's own error or output, or an
- * error a service stated through an app. That text still reaches the caller the error is for;
- * Executor's telemetry records only this fixed sentence, beside the error's name.
+ * The fixed sentence traces and error reports record for a tagged error, beside its tag. Telemetry
+ * records no other text from a tagged error: one that declares no sentence is recorded by its tag
+ * alone (`@executor-js/telemetry/recorded-failure`). Declare one from fixed text and closed fields
+ * only, never from a value the caller supplied (a slug, a name, a tool name, an argument's key),
+ * an app's own text or a service's reply. That text still reaches the caller the error is for.
+ * `ApiError` and `UserFacingError` declare a fixed message for you; a message derived from fields
+ * declares `recorded`.
  */
 export declare const RecordedMessage: unique symbol;
 /** The fixed sentence an error declares for telemetry, if it declares one. */

package/types/utils/src/user-facing-error.d.ts

@@ -43,8 +43,10 @@ type Definition<Tag extends string, Fields extends Schema.Struct.Fields> = Heade
         readonly [Key in keyof PresentationProperties | "_tag" | "message"]?: never;
     };
     /**
-     * What traces and error reports record instead of the description, when the description quotes
-     * an app's own error or a service's stated error for its caller. Only fixed text and typed fields.
+     * What traces and error reports record beside the tag. A fixed description is recorded as is; a
+     * presentation derived from fields is recorded only through this, from fixed text and closed
+     * fields, never a value the caller chose, an app's text or a service's reply. Without it the
+     * error is recorded by its tag alone.
      */
     readonly recorded?: (fields: Schema.Struct.Type<Fields>) => string;
 } & (ErrorPresentation | {

package/js/chunk-EG72MSVK.js

@@ -1,16 +0,0 @@
-import {
-  Predicate_exports
-} from "./chunk-IFJU5SYQ.js";
-
-// ../utils/src/recorded-message.ts
-var RecordedMessage = /* @__PURE__ */ Symbol.for("@executor-js/utils/RecordedMessage");
-var recordedMessage = (error) => {
-  if (!Predicate_exports.hasProperty(error, RecordedMessage)) return void 0;
-  const message = error[RecordedMessage];
-  return typeof message === "string" ? message : void 0;
-};
-
-export {
-  RecordedMessage,
-  recordedMessage
-};