@lovelaces-io/storyteller 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,23 +1,48 @@
-// src/audiences/consoleAudience.ts
-function consoleAudience() {
-  return {
-    name: "console",
-    hear: (event) => {
-      const prefix = "Storyteller";
-      const style = event.level === "Information" ? "color:#16a34a;font-weight:600" : event.level === "Warning" ? "color:#f59e0b;font-weight:600" : "color:#dc2626;font-weight:600";
-      const header = `${prefix}: ${event.title}`;
-      console.groupCollapsed(`%c${header}`, style);
-      const payload = JSON.stringify(event, null, 2);
-      if (event.level === "Information") {
-        console.log(header, payload);
-      } else if (event.level === "Warning") {
-        console.warn(header, payload);
-      } else {
-        console.error(header, payload);
-      }
-      console.groupEnd();
-    }
-  };
+// src/environment.ts
+var LEVEL_RANK = {
+  Information: 0,
+  Warning: 1,
+  Error: 2
+};
+var LEVEL_ALIASES = {
+  info: "Information",
+  information: "Information",
+  tell: "Information",
+  warn: "Warning",
+  warning: "Warning",
+  oops: "Error",
+  error: "Error"
+};
+function toStoryLevel(input) {
+  if (!input) return "Information";
+  return LEVEL_ALIASES[String(input).toLowerCase()] ?? "Information";
+}
+function readEnvironmentValue(name) {
+  try {
+    const runtime = globalThis;
+    const value = runtime.process?.env?.[name];
+    return typeof value === "string" && value.length ? value.trim() : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function resolveMinimumLevel(requested) {
+  const value = requested ?? readEnvironmentValue("STORYTELLER_LEVEL");
+  if (!value) return "Information";
+  return LEVEL_ALIASES[String(value).toLowerCase()] ?? "Information";
+}
+function meetsLevel(level, minimum) {
+  return LEVEL_RANK[level] >= LEVEL_RANK[minimum];
+}
+function resolveOutputFormat(requested) {
+  const value = requested ?? readEnvironmentValue("STORYTELLER_FORMAT");
+  return value === "ndjson" ? "ndjson" : "text";
+}
+function resolveColors(requested) {
+  if (requested !== void 0) return requested;
+  const value = readEnvironmentValue("STORYTELLER_COLOR");
+  if (value === void 0) return true;
+  return !(value === "0" || value.toLowerCase() === "false");
 }
 
 // src/utils.ts
@@ -37,6 +62,9 @@ function getLevelColor(level) {
 function formatOrigin(origin) {
   if (!origin?.where) return;
   if (typeof origin.where === "string") return origin.where;
+  if (typeof origin.where !== "object" || Array.isArray(origin.where)) {
+    return String(origin.where);
+  }
   const whereRecord = origin.where;
   const priorityKeys = ["app", "service", "page", "component"];
   const priorityParts = priorityKeys.filter((key) => whereRecord[key] != null).map((key) => String(whereRecord[key]));
@@ -68,6 +96,472 @@ function countBrackets(line) {
   const closeCount = (line.match(/\]/g) || []).length;
   return openCount - closeCount;
 }
+var CONTEXT_LINE_LIMIT = 120;
+function summarizeContext(note) {
+  const parts = [];
+  appendContextParts(parts, note.what);
+  appendContextParts(parts, note.where);
+  if (note.error) {
+    const errorLine = [note.error.name, note.error.message].filter(Boolean).join(": ");
+    if (errorLine && errorLine !== note.note) parts.push(errorLine);
+  }
+  if (!parts.length) return void 0;
+  const joined = parts.join(" ");
+  const text = joined.length > CONTEXT_LINE_LIMIT ? `${joined.slice(0, CONTEXT_LINE_LIMIT)}\u2026` : joined;
+  return `{${text}}`;
+}
+function appendContextParts(parts, value) {
+  if (value == null) return;
+  if (typeof value !== "object") {
+    parts.push(String(value));
+    return;
+  }
+  if (Array.isArray(value)) {
+    parts.push(`[${value.length}]`);
+    return;
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    if (entry == null) continue;
+    if (key.startsWith("@")) continue;
+    parts.push(`${key}=${typeof entry === "object" ? summarizeNested(entry) : String(entry)}`);
+  }
+}
+function summarizeNested(value) {
+  if (Array.isArray(value)) return `[${value.length}]`;
+  if (value && typeof value === "object") return `{${Object.keys(value).length}}`;
+  return String(value);
+}
+
+// src/audiences/consoleAudience.ts
+var LEVEL_LABELS = {
+  Information: "info",
+  Warning: "warn",
+  Error: "oops"
+};
+var LEVEL_STYLES = {
+  Information: "color:#16a34a;font-weight:600",
+  Warning: "color:#f59e0b;font-weight:600",
+  Error: "color:#dc2626;font-weight:600"
+};
+function consoleAudience(options = {}) {
+  const colors = resolveColors(options.colors);
+  return {
+    name: "console",
+    hears: ["note", "story"],
+    hear: (emission) => {
+      if (emission.kind === "note") {
+        printNote(emission, colors);
+        return;
+      }
+      printStory(emission);
+    }
+  };
+}
+function printNote(note, colors) {
+  const time = readClockTime(note.timestamp);
+  const label = LEVEL_LABELS[note.level];
+  const origin = formatOrigin(note.origin);
+  const context = summarizeContext(note);
+  const head = colors ? `${getLevelColor(note.level)}${label}${ANSI.reset}` : label;
+  const line = [
+    colors ? `${ANSI.grayDark}${time}${ANSI.reset}` : time,
+    head,
+    origin ? colors ? `${ANSI.grayDark}${origin}${ANSI.reset}` : origin : void 0,
+    note.note,
+    context ? colors ? `${ANSI.grayDark}${context}${ANSI.reset}` : context : void 0
+  ].filter(Boolean).join("  ");
+  if (note.level === "Information") {
+    console.log(line);
+  } else if (note.level === "Warning") {
+    console.warn(line);
+  } else {
+    console.error(line);
+  }
+}
+function printStory(event) {
+  const prefix = "Storyteller";
+  const header = `${prefix}: ${event.title}`;
+  console.groupCollapsed(`%c${header}`, LEVEL_STYLES[event.level]);
+  const payload = JSON.stringify(event, null, 2);
+  if (event.level === "Information") {
+    console.log(header, payload);
+  } else if (event.level === "Warning") {
+    console.warn(header, payload);
+  } else {
+    console.error(header, payload);
+  }
+  console.groupEnd();
+}
+function readClockTime(timestamp) {
+  const timePart = timestamp.slice(11, 19);
+  return timePart.length === 8 ? timePart : timestamp;
+}
+
+// src/normalize.ts
+var REDACTED = "[redacted]";
+var DEFAULT_REDACT_KEYS = [
+  "password",
+  "passphrase",
+  "token",
+  "secret",
+  "apiKey",
+  "accessKey",
+  "authorization",
+  "auth",
+  "cookie",
+  "sessionId",
+  "privateKey",
+  "clientSecret",
+  "refreshToken"
+];
+var DEFAULT_MAX_DEPTH = 6;
+var DEFAULT_MAX_ARRAY_LENGTH = 100;
+var DEFAULT_MAX_PROPERTIES = 100;
+var DEFAULT_MAX_STRING_LENGTH = 8e3;
+var MAX_CAUSE_DEPTH = 5;
+var BINARY_PREVIEW_BYTES = 16;
+function normalizeValue(input, options = {}) {
+  const resolved = {
+    maxDepth: options.maxDepth ?? DEFAULT_MAX_DEPTH,
+    maxArrayLength: options.maxArrayLength ?? DEFAULT_MAX_ARRAY_LENGTH,
+    maxProperties: options.maxProperties ?? DEFAULT_MAX_PROPERTIES,
+    maxStringLength: options.maxStringLength ?? DEFAULT_MAX_STRING_LENGTH,
+    redactKeys: new Set(
+      (options.redactKeys ?? DEFAULT_REDACT_KEYS).map(normalizeKeyForMatching)
+    ),
+    redact: options.redact ?? true
+  };
+  try {
+    return normalizeUnknown(input, resolved, 0, "$", /* @__PURE__ */ new Map());
+  } catch (failure) {
+    return `[Unreadable: ${describeFailure(failure)}]`;
+  }
+}
+function normalizeError(rawError, options = {}) {
+  const resolved = {
+    maxDepth: options.maxDepth ?? DEFAULT_MAX_DEPTH,
+    maxArrayLength: options.maxArrayLength ?? DEFAULT_MAX_ARRAY_LENGTH,
+    maxProperties: options.maxProperties ?? DEFAULT_MAX_PROPERTIES,
+    maxStringLength: options.maxStringLength ?? DEFAULT_MAX_STRING_LENGTH,
+    redactKeys: new Set(
+      (options.redactKeys ?? DEFAULT_REDACT_KEYS).map(normalizeKeyForMatching)
+    ),
+    redact: options.redact ?? true
+  };
+  return normalizeErrorInternal(rawError, resolved, 0);
+}
+function normalizeErrorInternal(rawError, options, causeDepth) {
+  if (!(rawError instanceof Error)) {
+    if (isPlainRecord(rawError)) {
+      const record = rawError;
+      const message = typeof record["message"] === "string" ? record["message"] : void 0;
+      const name = typeof record["name"] === "string" ? record["name"] : void 0;
+      if (message !== void 0 || name !== void 0) {
+        return {
+          ...name !== void 0 ? { name } : {},
+          ...message !== void 0 ? { message } : {}
+        };
+      }
+    }
+    return { message: safeStringify(rawError, options.maxStringLength) };
+  }
+  const normalized = {
+    name: rawError.name,
+    message: rawError.message
+  };
+  if (rawError.stack !== void 0) {
+    normalized.stack = truncateString(rawError.stack, options.maxStringLength);
+  }
+  const cause = rawError.cause;
+  if (cause !== void 0) {
+    if (causeDepth >= MAX_CAUSE_DEPTH) {
+      normalized.cause = { "@truncated": { kind: "causeChain" } };
+    } else if (cause instanceof Error) {
+      normalized.cause = normalizeErrorInternal(cause, options, causeDepth + 1);
+    } else {
+      normalized.cause = normalizeUnknown(cause, options, 0, "$.cause", /* @__PURE__ */ new Map());
+    }
+  }
+  const aggregated = rawError.errors;
+  if (Array.isArray(aggregated)) {
+    normalized.errors = aggregated.slice(0, options.maxArrayLength).map((member) => normalizeErrorInternal(member, options, causeDepth + 1));
+  }
+  return normalized;
+}
+function normalizeUnknown(value, options, depth, path, ancestors) {
+  if (value === null) return null;
+  const valueType = typeof value;
+  if (valueType === "string") {
+    return truncateString(value, options.maxStringLength);
+  }
+  if (valueType === "number") {
+    return Number.isFinite(value) ? value : String(value);
+  }
+  if (valueType === "boolean") return value;
+  if (valueType === "undefined") return null;
+  if (valueType === "bigint") return `${String(value)}n`;
+  if (valueType === "symbol") return String(value);
+  if (valueType === "function") {
+    const name = value.name;
+    return `[Function: ${name ? name : "anonymous"}]`;
+  }
+  const objectValue = value;
+  const existingPath = ancestors.get(objectValue);
+  if (existingPath !== void 0) {
+    return `[Circular \u2192 ${existingPath}]`;
+  }
+  if (depth > options.maxDepth) {
+    return { "@truncated": { kind: "depth", depth: options.maxDepth } };
+  }
+  const wellKnown = normalizeWellKnown(objectValue, options, depth, path, ancestors);
+  if (wellKnown !== void 0) return wellKnown;
+  ancestors.set(objectValue, path);
+  try {
+    if (Array.isArray(objectValue)) {
+      return normalizeArray(objectValue, options, depth, path, ancestors);
+    }
+    return normalizeObject(objectValue, options, depth, path, ancestors);
+  } finally {
+    ancestors.delete(objectValue);
+  }
+}
+function normalizeWellKnown(value, options, depth, path, ancestors) {
+  if (value instanceof Error) {
+    return normalizeErrorInternal(value, options, 0);
+  }
+  if (value instanceof Date) {
+    const time = value.getTime();
+    return Number.isNaN(time) ? "[Invalid Date]" : value.toISOString();
+  }
+  if (value instanceof RegExp) return String(value);
+  if (value instanceof URL) return value.href;
+  if (value instanceof Map) {
+    const entries = {};
+    let index = 0;
+    let omitted = 0;
+    for (const [entryKey, entryValue] of value) {
+      if (index >= options.maxProperties) {
+        omitted += 1;
+        continue;
+      }
+      const keyLabel = safeStringify(entryKey, options.maxStringLength);
+      entries[keyLabel] = redactOrNormalize(
+        keyLabel,
+        entryValue,
+        options,
+        depth + 1,
+        `${path}.${keyLabel}`,
+        ancestors
+      );
+      index += 1;
+    }
+    return {
+      "@type": "Map",
+      entries,
+      ...omitted ? { "@truncated": { kind: "mapEntries", omitted } } : {}
+    };
+  }
+  if (value instanceof Set) {
+    const values = [];
+    let omitted = 0;
+    for (const member of value) {
+      if (values.length >= options.maxArrayLength) {
+        omitted += 1;
+        continue;
+      }
+      values.push(
+        normalizeUnknown(member, options, depth + 1, `${path}[${values.length}]`, ancestors)
+      );
+    }
+    return {
+      "@type": "Set",
+      values,
+      ...omitted ? { "@truncated": { kind: "setValues", omitted } } : {}
+    };
+  }
+  if (value instanceof WeakMap) return "[WeakMap]";
+  if (value instanceof WeakSet) return "[WeakSet]";
+  if (value instanceof Promise) return "[Promise]";
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+    return describeBinary(value);
+  }
+  const converted = callToJson(value);
+  if (converted !== void 0) {
+    return normalizeUnknown(converted, options, depth, path, ancestors);
+  }
+  return void 0;
+}
+function callToJson(value) {
+  let toJson;
+  try {
+    toJson = value.toJSON;
+  } catch {
+    return void 0;
+  }
+  if (typeof toJson !== "function") return void 0;
+  try {
+    return toJson.call(value);
+  } catch (failure) {
+    return `[Unreadable: ${describeFailure(failure)}]`;
+  }
+}
+function describeBinary(value) {
+  const typeName = readConstructorName(value) ?? "ArrayBuffer";
+  const byteLength = value.byteLength;
+  let preview;
+  try {
+    const bytes = value instanceof ArrayBuffer ? new Uint8Array(value, 0, Math.min(BINARY_PREVIEW_BYTES, byteLength)) : new Uint8Array(
+      value.buffer,
+      value.byteOffset,
+      Math.min(BINARY_PREVIEW_BYTES, value.byteLength)
+    );
+    preview = [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join(" ");
+  } catch {
+    preview = "";
+  }
+  return {
+    "@type": typeName,
+    byteLength,
+    ...preview ? { preview } : {},
+    ...byteLength > BINARY_PREVIEW_BYTES ? { "@truncated": { kind: "bytes", omitted: byteLength - BINARY_PREVIEW_BYTES } } : {}
+  };
+}
+function normalizeArray(value, options, depth, path, ancestors) {
+  const kept = [];
+  const limit = Math.min(value.length, options.maxArrayLength);
+  for (let index = 0; index < limit; index += 1) {
+    kept.push(
+      normalizeUnknown(value[index], options, depth + 1, `${path}[${index}]`, ancestors)
+    );
+  }
+  if (value.length > limit) {
+    kept.push({ "@truncated": { kind: "array", omitted: value.length - limit } });
+  }
+  return kept;
+}
+function normalizeObject(value, options, depth, path, ancestors) {
+  const result = {};
+  const className = readConstructorName(value);
+  if (className && className !== "Object") {
+    result["@type"] = className;
+  }
+  let keys;
+  try {
+    keys = Object.keys(value);
+  } catch {
+    return `[Unreadable: keys could not be listed]`;
+  }
+  let kept = 0;
+  let omitted = 0;
+  for (const key of keys) {
+    if (kept >= options.maxProperties) {
+      omitted += 1;
+      continue;
+    }
+    let propertyValue;
+    try {
+      propertyValue = value[key];
+    } catch (failure) {
+      result[key] = `[Unreadable: ${describeFailure(failure)}]`;
+      kept += 1;
+      continue;
+    }
+    if (propertyValue === void 0) continue;
+    result[key] = redactOrNormalize(
+      key,
+      propertyValue,
+      options,
+      depth + 1,
+      `${path}.${key}`,
+      ancestors
+    );
+    kept += 1;
+  }
+  if (omitted) {
+    result["@truncated"] = { kind: "properties", omitted };
+  }
+  return result;
+}
+function redactOrNormalize(key, value, options, depth, path, ancestors) {
+  if (options.redact && options.redactKeys.has(normalizeKeyForMatching(key))) {
+    return REDACTED;
+  }
+  return normalizeUnknown(value, options, depth, path, ancestors);
+}
+function normalizeKeyForMatching(key) {
+  return key.replace(/[^a-zA-Z0-9]/g, "").toLowerCase();
+}
+function readConstructorName(value) {
+  try {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype === null) return void 0;
+    const name = prototype.constructor?.name;
+    return typeof name === "string" && name.length ? name : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function isPlainRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function truncateString(value, maxLength) {
+  if (value.length <= maxLength) return value;
+  return `${value.slice(0, maxLength)}\u2026[+${value.length - maxLength} chars]`;
+}
+function safeStringify(value, maxLength) {
+  try {
+    return truncateString(String(value), maxLength);
+  } catch {
+    return "[unstringifiable]";
+  }
+}
+function describeFailure(failure) {
+  if (failure instanceof Error && failure.message) return failure.message;
+  try {
+    return String(failure);
+  } catch {
+    return "unknown error";
+  }
+}
+
+// src/audiences/ndjsonAudience.ts
+function ndjsonAudience(options = {}) {
+  const writer = options.stream ?? createDefaultWriter();
+  const minimumLevel = resolveMinimumLevel(options.level);
+  return {
+    name: options.name ?? "ndjson",
+    hears: ["note", "story"],
+    accepts: (emission) => meetsLevel(emission.level, minimumLevel),
+    hear: (emission) => {
+      writer.write(`${serializeEmission(emission)}
+`);
+    }
+  };
+}
+function serializeEmission(emission) {
+  try {
+    return JSON.stringify(emission);
+  } catch {
+    try {
+      return JSON.stringify(normalizeValue(emission));
+    } catch {
+      return JSON.stringify({
+        kind: emission.kind,
+        level: emission.level,
+        error: "[Unserializable emission]"
+      });
+    }
+  }
+}
+function createDefaultWriter() {
+  const runtime = globalThis;
+  const write = runtime.process?.stdout?.write;
+  if (typeof write === "function") {
+    const stdout = runtime.process.stdout;
+    return { write: (chunk) => write.call(stdout, chunk) };
+  }
+  return { write: (chunk) => console.log(chunk.replace(/\n$/, "")) };
+}
 
 // src/formatting.ts
 function formatStory(story, options = {}) {
@@ -239,40 +733,143 @@ var AudienceRegistry = class {
     return [...this.members.keys()];
   }
 };
-var Storyteller = class {
-  audience = new AudienceRegistry();
+var Storyteller = class _Storyteller {
+  audience;
   origin;
+  parentStoryId;
   notes = [];
+  narration;
+  minimumLevel;
+  onAudienceError;
+  maxInFlight;
+  /** Deliveries currently awaiting each audience, keyed by audience name */
+  inFlight = /* @__PURE__ */ new Map();
+  /** Emissions dropped for back-pressure since the current story began */
+  droppedEmissions = 0;
+  /** Identifies the story currently being collected; regenerated after each telling */
+  storyId = createStoryId();
+  /** Position of the next note within the current story */
+  nextSequence = 0;
   constructor(options) {
-    this.origin = options?.origin;
-    this.audience.add(consoleAudience());
+    const normalizedOrigin = normalizeOrigin(options?.origin);
+    if (normalizedOrigin) {
+      this.origin = normalizedOrigin;
+    }
+    if (options?.parentStoryId !== void 0) {
+      this.parentStoryId = options.parentStoryId;
+    }
+    this.narration = resolveNarration(options?.narration);
+    this.minimumLevel = resolveMinimumLevel(options?.level);
+    this.onAudienceError = options?.onAudienceError ?? reportAudienceErrorToConsole;
+    this.maxInFlight = options?.maxInFlight ?? DEFAULT_MAX_IN_FLIGHT;
+    if (options?.audience) {
+      this.audience = options.audience;
+    } else {
+      this.audience = new AudienceRegistry();
+      this.audience.add(
+        resolveOutputFormat(options?.format) === "ndjson" ? ndjsonAudience({ level: this.minimumLevel }) : consoleAudience()
+      );
+    }
     options?.audiences?.forEach((audience) => this.audience.add(audience));
   }
   /**
-   * Add a timestamped note to the current story.
-   * @param text - What happened
+   * Switch between collected and live narration at runtime.
+   * Takes effect on the next note; already-buffered notes are not replayed.
+   *
+   * @param narration - `collected` to buffer, `live` to emit each note as it happens
+   * @returns `this` for chaining
+   */
+  narrate(narration) {
+    this.narration = resolveNarration(narration);
+    return this;
+  }
+  /** The id of the story currently being collected */
+  get currentStoryId() {
+    return this.storyId;
+  }
+  /**
+   * Start a chapter: a child storyteller whose stories are linked back to this
+   * one by `parentStoryId`.
+   *
+   * Real work nests — an agent spawns subtasks, a batch runs per-item operations.
+   * A chapter keeps each of those a complete story in its own right while leaving
+   * the run reconstructable as a tree.
+   *
+   * The child shares this storyteller's audience registry, so audiences added
+   * later reach it too, and inherits narration, level and delivery settings.
+   * Its stories are separate records — a chapter is not folded into the parent's
+   * notes.
+   *
+   * @param options - Origin to merge over the parent's, and any setting to override
+   * @returns A child Storyteller
+   *
+   * @example
+   * ```ts
+   * for (const account of accounts) {
+   *   const chapter = story.chapter({ origin: { what: account.id } });
+   *   chapter.report("Fetching invoices");
+   *   chapter.finish(`Synced ${account.id}`);
+   * }
+   * ```
+   */
+  chapter(options = {}) {
+    const mergedOrigin = { ...this.origin, ...options.origin };
+    return new _Storyteller({
+      audience: this.audience,
+      // Captured now, so a parent that finishes first does not orphan its chapters
+      parentStoryId: this.storyId,
+      ...Object.keys(mergedOrigin).length ? { origin: mergedOrigin } : {},
+      narration: options.narration ?? this.narration,
+      level: options.level ?? this.minimumLevel,
+      onAudienceError: options.onAudienceError ?? this.onAudienceError,
+      maxInFlight: options.maxInFlight ?? this.maxInFlight
+    });
+  }
+  /**
+   * Report a beat of the current story.
+   *
+   * In collected narration the beat is buffered and leaves with the story. In live
+   * narration it is emitted the moment you call this, so whoever is tuned in sees
+   * the work as it happens.
+   *
+   * Accepts anything, not just a string — pass an error, an API response, a Map, a
+   * class instance — and the value is normalized into a storable shape with the note
+   * text derived from it.
+   *
+   * @param input - What happened: a message, or any value to describe
    * @param data - Optional context: who did it, what was involved, where it happened, any error
    * @returns `this` for chaining
    *
    * @example
    * ```ts
-   * story.note("Card charged", { what: { amount: "$42" }, where: "stripe" });
+   * story.report("Card charged", { what: { amount: "$42" }, where: "stripe" });
+   * story.report(await response.json());
    * ```
    */
-  note(text, data = {}) {
-    this.notes.push({
+  report(input, data = {}) {
+    const described = describeInput(input);
+    const level = toStoryLevel(data.level);
+    const note = {
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      note: text,
-      ...data.who ? { who: data.who } : {},
-      ...data.what ? { what: data.what } : {},
-      ...data.where ? { where: data.where } : {},
-      ...data.error ? { error: normalizeError(data.error) } : {}
-    });
+      sequence: this.nextSequence,
+      note: described.text,
+      ...level !== "Information" ? { level } : {},
+      ...data.who !== void 0 ? { who: normalizeValue(data.who) } : {},
+      ...data.what !== void 0 ? { what: normalizeValue(data.what) } : described.what !== void 0 ? { what: described.what } : {},
+      ...data.where !== void 0 ? { where: normalizeValue(data.where) } : {},
+      ...data.error !== void 0 ? { error: normalizeError(data.error) } : described.error !== void 0 ? { error: described.error } : {}
+    };
+    this.nextSequence += 1;
+    this.notes.push(note);
+    if (this.narration === "live" || data.live) {
+      this.emitNote(note, level, data.to);
+    }
     return this;
   }
-  /** Clear all accumulated notes without emitting a story */
+  /** Clear all accumulated notes without emitting a story, and start a new story id */
   reset() {
     this.notes = [];
+    this.startNewStory();
     return this;
   }
   /** Preview the current notes as a formatted report without emitting or clearing them */
@@ -287,27 +884,67 @@ var Storyteller = class {
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       level,
       title,
+      storyId: this.storyId,
+      ...this.parentStoryId !== void 0 ? { parentStoryId: this.parentStoryId } : {},
       ...this.origin ? { origin: this.origin } : {},
       notes: [...this.notes],
-      ...error ? { error: normalizeError(error) } : {}
+      ...error !== void 0 ? { error: normalizeError(error) } : {}
     };
     return formatStory(event, reportOptions);
   }
-  /** Tell a success story — everything went well */
+  /**
+   * Finish the story: emit everything collected so far as one record, and start fresh.
+   *
+   * @param title - What the story was about
+   * @param options - Level, and the error that ended it
+   * @returns A one-shot handle whose `.to()` overrides the audience list — call it
+   *   synchronously, delivery happens on the next microtask
+   *
+   * @example
+   * ```ts
+   * story.finish("Sync complete");
+   * story.finish("Sync failed", { level: "oops", error }).to("db");
+   * ```
+   */
+  finish(title, options = {}) {
+    return this.createDelivery(toStoryLevel(options.level), title, options.error);
+  }
+  /** @deprecated Use `finish(title)`. Removed at 1.0. */
   tell(title) {
-    return this.createDelivery("tell", title);
+    warnDeprecated("tell", "finish");
+    return this.createDelivery("Information", title);
   }
-  /** Tell a cautionary story — something was off but it's handled */
+  /** @deprecated Use `finish(title, { level: "warn" })`. Removed at 1.0. */
   warn(title) {
-    return this.createDelivery("warn", title);
+    warnDeprecated("warn", 'finish(title, { level: "warn" })');
+    return this.createDelivery("Warning", title);
   }
-  /** Tell an error story — something broke. Pass the error for automatic normalization. */
+  /** @deprecated Use `finish(title, { level: "oops", error })`. Removed at 1.0. */
   oops(title, error) {
-    return this.createDelivery("oops", title, error);
+    warnDeprecated("oops", 'finish(title, { level: "oops", error })');
+    return this.createDelivery("Error", title, error);
+  }
+  /** @deprecated Use `report()`. Removed at 1.0. */
+  note(input, data = {}) {
+    warnDeprecated("note", "report");
+    return this.report(input, data);
+  }
+  /** Emit a single note to the audiences listening for notes */
+  emitNote(note, level, only) {
+    const emission = {
+      ...note,
+      kind: "note",
+      storyId: this.storyId,
+      ...this.parentStoryId !== void 0 ? { parentStoryId: this.parentStoryId } : {},
+      sequence: note.sequence ?? 0,
+      level,
+      ...this.origin ? { origin: this.origin } : {}
+    };
+    void this.deliver(emission, only ? { only } : {});
   }
   /** Build a story event and schedule delivery, returning a handle to override the audience list */
-  createDelivery(method, title, error) {
-    const event = this.buildEvent(method, title, error);
+  createDelivery(level, title, error) {
+    const event = this.buildEvent(level, title, error);
     let delivered = false;
     let defaultCancelled = false;
     queueMicrotask(() => {
@@ -324,60 +961,173 @@ var Storyteller = class {
       }
     };
   }
-  /** Assemble the story event from current notes and clear notes for the next story */
-  buildEvent(method, title, error) {
+  /** Assemble the story event from current notes and start a fresh story */
+  buildEvent(level, title, error) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    const level = methodToLevel(method);
+    const storyId = this.storyId;
+    const droppedEmissions = this.droppedEmissions;
     const sortedNotes = [...this.notes].sort(
-      (noteA, noteB) => Date.parse(noteA.timestamp) - Date.parse(noteB.timestamp)
+      (noteA, noteB) => Date.parse(noteA.timestamp) - Date.parse(noteB.timestamp) || (noteA.sequence ?? 0) - (noteB.sequence ?? 0)
     );
     this.notes = [];
+    this.startNewStory();
     const durationMs = calculateNoteDuration2(sortedNotes).durationMs;
     const event = {
       timestamp: now,
       level,
       title,
+      storyId,
+      ...this.parentStoryId !== void 0 ? { parentStoryId: this.parentStoryId } : {},
       ...this.origin ? { origin: this.origin } : {},
       notes: sortedNotes,
       ...durationMs != null ? { durationMs } : {},
-      ...error ? { error: normalizeError(error) } : {}
+      ...droppedEmissions ? { droppedEmissions } : {},
+      ...error !== void 0 ? { error: normalizeError(error) } : {}
     };
     const eventWithSummary = event;
+    Object.defineProperty(eventWithSummary, "kind", {
+      value: "story",
+      enumerable: true
+    });
     Object.defineProperty(eventWithSummary, "summarize", {
       value: (options) => formatStory(event, options),
       enumerable: false
     });
     return eventWithSummary;
   }
-  /** Deliver a story event to matching audience members */
-  async deliver(event, options) {
+  /** Begin a new story: fresh id, sequence back to zero */
+  startNewStory() {
+    this.storyId = createStoryId();
+    this.nextSequence = 0;
+    this.droppedEmissions = 0;
+  }
+  /** Deliver an emission to the audience members listening for its kind */
+  async deliver(emission, options) {
+    if (!meetsLevel(emission.level, this.minimumLevel)) return;
     const targets = options?.only?.length ? this.audience.getOnly(options.only) : this.audience.getAll();
-    await Promise.allSettled(
-      targets.filter((member) => member.accepts ? member.accepts(event) : true).map((member) => member.hear(event))
+    await Promise.all(
+      targets.filter((member) => hearsKind(member, emission.kind)).filter((member) => this.acceptsSafely(member, emission)).map((member) => this.hearSafely(member, emission))
     );
   }
+  /** Run an audience's accepts() without letting a throw from it lose the emission */
+  acceptsSafely(member, emission) {
+    if (!member.accepts) return true;
+    try {
+      return member.accepts(emission);
+    } catch (error) {
+      this.handleAudienceError(error, member, emission);
+      return false;
+    }
+  }
+  /**
+   * Hand an emission to one audience, keeping its failures and its slowness
+   * contained: a throw is reported rather than swallowed, and a backlog is dropped
+   * rather than grown without limit.
+   */
+  async hearSafely(member, emission) {
+    const pending = this.inFlight.get(member.name) ?? 0;
+    if (pending >= this.maxInFlight) {
+      this.droppedEmissions += 1;
+      return;
+    }
+    this.inFlight.set(member.name, pending + 1);
+    try {
+      await member.hear(emission);
+    } catch (error) {
+      this.handleAudienceError(error, member, emission);
+    } finally {
+      const remaining = (this.inFlight.get(member.name) ?? 1) - 1;
+      if (remaining > 0) this.inFlight.set(member.name, remaining);
+      else this.inFlight.delete(member.name);
+    }
+  }
+  /** Report an audience failure without ever letting it reach caller code */
+  handleAudienceError(error, member, emission) {
+    try {
+      this.onAudienceError(error, member, emission);
+    } catch {
+    }
+  }
 };
-function methodToLevel(method) {
-  if (method === "tell") return "Information";
-  if (method === "warn") return "Warning";
-  return "Error";
-}
-function normalizeError(rawError) {
-  if (rawError instanceof Error) {
-    const normalized = {
-      name: rawError.name,
-      message: rawError.message
-    };
-    if (rawError.stack !== void 0) {
-      normalized.stack = rawError.stack;
+var warnedDeprecations = /* @__PURE__ */ new Set();
+function warnDeprecated(oldName, replacement) {
+  if (warnedDeprecations.has(oldName)) return;
+  if (readEnvironmentValue("STORYTELLER_DEPRECATION_WARNINGS") !== "1") return;
+  warnedDeprecations.add(oldName);
+  console.warn(
+    `Storyteller: ${oldName}() is deprecated and will be removed at 1.0 \u2014 use ${replacement}.`
+  );
+}
+var DEFAULT_MAX_IN_FLIGHT = 1e3;
+var AUDIENCE_ERROR_THROTTLE_MS = 5e3;
+var lastReportedAudienceError = /* @__PURE__ */ new Map();
+function reportAudienceErrorToConsole(error, member, emission) {
+  const now = Date.now();
+  const lastReported = lastReportedAudienceError.get(member.name);
+  if (lastReported !== void 0 && now - lastReported < AUDIENCE_ERROR_THROTTLE_MS) {
+    return;
+  }
+  lastReportedAudienceError.set(member.name, now);
+  const reason = error instanceof Error ? error.message : String(error);
+  console.error(
+    `Storyteller: audience "${member.name}" failed to hear a ${emission.kind} \u2014 ${reason}`
+  );
+}
+function hearsKind(member, kind) {
+  const kinds = member.hears ?? ["story"];
+  return kinds.includes(kind);
+}
+function resolveNarration(requested) {
+  const value = requested ?? readEnvironmentValue("STORYTELLER_NARRATION");
+  if (value === "live" || value === "both") return "live";
+  return "collected";
+}
+function createStoryId() {
+  try {
+    const runtimeCrypto = globalThis.crypto;
+    if (typeof runtimeCrypto?.randomUUID === "function") {
+      return runtimeCrypto.randomUUID();
     }
-    const cause = rawError.cause;
-    if (cause !== void 0) {
-      normalized.cause = cause;
+  } catch {
+  }
+  return `story-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function normalizeOrigin(origin) {
+  if (!origin) return void 0;
+  const normalized = {
+    ...origin.who !== void 0 ? { who: normalizeValue(origin.who) } : {},
+    ...origin.what !== void 0 ? { what: normalizeValue(origin.what) } : {},
+    ...origin.where !== void 0 ? { where: normalizeValue(origin.where) } : {}
+  };
+  return Object.keys(normalized).length ? normalized : void 0;
+}
+function describeInput(input) {
+  if (typeof input === "string") return { text: input };
+  if (input instanceof Error) {
+    const error = normalizeError(input);
+    const label = [error.name, error.message].filter(Boolean).join(": ");
+    return { text: label || "Error", error };
+  }
+  if (input === null) return { text: "null" };
+  if (input === void 0) return { text: "undefined" };
+  const normalized = normalizeValue(input);
+  if (typeof normalized !== "object" || normalized === null) {
+    return { text: String(normalized), what: normalized };
+  }
+  if (Array.isArray(normalized)) {
+    return { text: `Array(${normalized.length})`, what: normalized };
+  }
+  for (const key of ["message", "title", "name", "summary", "event"]) {
+    const candidate = normalized[key];
+    if (typeof candidate === "string" && candidate.length) {
+      return { text: candidate, what: normalized };
     }
-    return normalized;
   }
-  return { message: String(rawError) };
+  const typeName = normalized["@type"];
+  return {
+    text: typeof typeName === "string" ? typeName : "Object",
+    what: normalized
+  };
 }
 function calculateNoteDuration2(notes) {
   if (notes.length <= 1) {
@@ -396,7 +1146,10 @@ function calculateNoteDuration2(notes) {
 var sharedInstance;
 function useStoryteller(options = {}) {
   if (!sharedInstance || options.reset) {
-    sharedInstance = new Storyteller({ origin: options.origin });
+    sharedInstance = new Storyteller({
+      ...options.origin !== void 0 ? { origin: options.origin } : {},
+      ...options.narration !== void 0 ? { narration: options.narration } : {}
+    });
     return sharedInstance;
   }
   return sharedInstance;
@@ -406,9 +1159,11 @@ function useStoryteller(options = {}) {
 function dbAudience(insert) {
   return {
     name: "db",
-    accepts: (event) => event.level === "Warning" || event.level === "Error",
-    hear: async (event) => {
-      await insert(event);
+    hears: ["story"],
+    accepts: (emission) => emission.kind === "story" && (emission.level === "Warning" || emission.level === "Error"),
+    hear: async (emission) => {
+      if (emission.kind !== "story") return;
+      await insert(emission);
     }
   };
 }
@@ -515,6 +1270,9 @@ function writeStoryReport(stories, options = {}) {
 }
 export {
   ANSI,
+  AudienceRegistry,
+  DEFAULT_REDACT_KEYS,
+  REDACTED,
   Storyteller,
   consoleAudience,
   dbAudience,
@@ -522,7 +1280,17 @@ export {
   formatOrigin,
   formatStory,
   getLevelColor,
+  meetsLevel,
+  ndjsonAudience,
+  normalizeError,
+  normalizeValue,
+  readEnvironmentValue,
+  resolveColors,
+  resolveMinimumLevel,
+  resolveOutputFormat,
+  summarizeContext,
   summarizeStory,
+  toStoryLevel,
   useStoryteller,
   writeStoryReport
 };