@gajae-code/utils 0.15.6 → 0.16.0

package/dist/types/crash-journal.d.ts

@@ -4,6 +4,14 @@ export declare const CRASH_EVENT_MAX_BYTES = 512;
 export declare const CRASH_EVENT_KIND = "gjc-crash-event.v1";
 /** Preview cap for the message class carried by an event. */
 export declare const CRASH_EVENT_MESSAGE_MAX_BYTES = 256;
+/** Bounded execution provenance carried only on newly written occurrences. */
+export type CrashProvenance = "product" | "eval" | "bun_test";
+/**
+ * Classify only process-level harness modes that are explicit and stable.
+ * Everything else is product provenance, including source checkouts, CLI
+ * invocations, SDK/ACP hosts, and native-loader failures.
+ */
+export declare function detectCrashProvenance(argv?: readonly string[], env?: NodeJS.ProcessEnv, execArgv?: readonly string[]): CrashProvenance;
 export type CrashEvent = CrashOccurrenceEvent | CrashRefusedEvent | CrashReportedEvent | CrashRelayedEvent | CrashAcknowledgedEvent | CrashNudgedEvent;
 export interface CrashOccurrenceEvent {
     readonly kind: "occurrence";
@@ -13,6 +21,8 @@ export interface CrashOccurrenceEvent {
     readonly at: number;
     readonly errorName: string;
     readonly messageClass: string;
+    /** Legacy events omit this and are treated as product crashes. */
+    readonly provenance?: CrashProvenance;
 }
 export interface CrashRefusedEvent {
     readonly kind: "refused";

package/dist/types/postmortem.d.ts

@@ -5,6 +5,7 @@
  * in response to process exit, signals, or fatal exceptions. It is intended to
  * allow reliably releasing resources or shutting down subprocesses, files, sockets, etc.
  */
+import type { CrashProvenance } from "./crash-journal";
 import { redactCrashSecrets } from "./crash-redaction";
 export declare enum Reason {
     PRE_EXIT = "pre_exit",// Pre-exit phase (not used by default)
@@ -61,6 +62,7 @@ export declare function resetHandledErrorDedupeForTest(): void;
 interface CrashRecordOptions {
     path?: string;
     now?: Date;
+    provenance?: CrashProvenance;
 }
 /**
  * Register a process cleanup callback, to be run on shutdown, signal, or fatal error.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/utils",
-	"version": "0.15.6",
+	"version": "0.16.0",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.15.6",
+		"@gajae-code/natives": "0.16.0",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",

package/src/crash-journal.ts

@@ -22,6 +22,24 @@ export const CRASH_EVENT_KIND = "gjc-crash-event.v1";
 /** Preview cap for the message class carried by an event. */
 export const CRASH_EVENT_MESSAGE_MAX_BYTES = 256;
 
+/** Bounded execution provenance carried only on newly written occurrences. */
+export type CrashProvenance = "product" | "eval" | "bun_test";
+
+/**
+ * Classify only process-level harness modes that are explicit and stable.
+ * Everything else is product provenance, including source checkouts, CLI
+ * invocations, SDK/ACP hosts, and native-loader failures.
+ */
+export function detectCrashProvenance(
+	argv: readonly string[] = process.argv,
+	env: NodeJS.ProcessEnv = process.env,
+	execArgv: readonly string[] = process.execArgv,
+): CrashProvenance {
+	if (env.BUN_TEST !== undefined) return "bun_test";
+	if (execArgv[0] === "-e" || execArgv[0] === "--eval" || argv[0] === "-e" || argv[0] === "--eval") return "eval";
+	return "product";
+}
+
 export type CrashEvent =
 	| CrashOccurrenceEvent
 	| CrashRefusedEvent
@@ -38,6 +56,8 @@ export interface CrashOccurrenceEvent {
 	readonly at: number;
 	readonly errorName: string;
 	readonly messageClass: string;
+	/** Legacy events omit this and are treated as product crashes. */
+	readonly provenance?: CrashProvenance;
 }
 
 export interface CrashRefusedEvent {
@@ -109,6 +129,7 @@ export function formatCrashEventLine(event: CrashEvent): string {
 						id: event.recordId,
 						at: event.at,
 						n: sanitizeEventText(truncateUtf8(event.errorName, 64)),
+						...(event.provenance && event.provenance !== "product" ? { p: event.provenance } : {}),
 						...(messageClass === undefined ? {} : { m: messageClass }),
 					}
 				: event.kind === "reported"
@@ -181,7 +202,19 @@ export function parseCrashEventLine(line: string): CrashEvent | undefined {
 			if (typeof body.fpv !== "number" || !Number.isSafeInteger(body.fpv) || body.fpv < 1) return undefined;
 			const errorName = typeof body.n === "string" ? sanitizeEventText(body.n) : "Error";
 			const messageClass = typeof body.m === "string" ? sanitizeEventText(body.m) : "";
-			return { kind: "occurrence", fingerprint, fpv: body.fpv, recordId: body.id, at, errorName, messageClass };
+			const provenance = body.p === undefined ? undefined : body.p;
+			if (provenance !== undefined && provenance !== "product" && provenance !== "eval" && provenance !== "bun_test")
+				return undefined;
+			return {
+				kind: "occurrence",
+				fingerprint,
+				fpv: body.fpv,
+				recordId: body.id,
+				at,
+				errorName,
+				messageClass,
+				...(provenance === undefined ? {} : { provenance }),
+			};
 		}
 		case "reported": {
 			if (!fingerprint) return undefined;

package/src/postmortem.ts

@@ -13,7 +13,8 @@ import * as path from "node:path";
 import { isMainThread } from "node:worker_threads";
 import { BROKEN_PIPE_EXIT_CODE, createProcessStdoutEpipeClassifier } from "./broken-pipe";
 import { type CrashFingerprint, computeCrashFingerprint, formatCrashRecordMarker } from "./crash-fingerprint";
-import { appendCrashEvent, appendFatalCrashEvent } from "./crash-journal";
+import type { CrashProvenance } from "./crash-journal";
+import { appendCrashEvent, appendFatalCrashEvent, detectCrashProvenance } from "./crash-journal";
 import { redactCrashSecrets } from "./crash-redaction";
 import { getCrashEventsPath, getCrashLogPath, getHandledErrorEventsPath, getHandledErrorLogPath } from "./dirs";
 import * as logger from "./logger";
@@ -460,7 +461,8 @@ function boundCrashRecord(report: string, maxBytes: number = CRASH_RECORD_MAX_BY
  * `process.exit`. Returns the path written, or `undefined` on failure.
  */
 export function recordFatalCrash(label: string, reason: unknown, options: CrashRecordOptions = {}): string | undefined {
-	const written = writeCrashRecord(label, describeFatal(reason), options);
+	const provenance = detectCrashProvenance();
+	const written = writeCrashRecord(label, describeFatal(reason), { ...options, provenance });
 	if (!written) return undefined;
 	appendFatalCrashEvent(
 		{
@@ -471,12 +473,19 @@ export function recordFatalCrash(label: string, reason: unknown, options: CrashR
 			at: written.now.getTime(),
 			errorName: written.fingerprint.errorName,
 			messageClass: written.fingerprint.messageClass,
+			provenance,
 		},
 		getCrashEventsTarget(written.target, options.path),
 	);
 	return written.target;
 }
 
+/**
+ * Classify only process-level harness modes that are explicit and stable.
+ * Everything else is product provenance, including source checkouts, CLI
+ * invocations, SDK/ACP hosts, and native-loader failures.
+ */
+
 const handledErrorFingerprints = new Set<string>();
 const HANDLED_ERROR_FINGERPRINT_LIMIT = 256;
 
@@ -552,6 +561,7 @@ export function resetHandledErrorDedupeForTest(): void {
 interface CrashRecordOptions {
 	path?: string;
 	now?: Date;
+	provenance?: CrashProvenance;
 }
 
 interface WrittenCrashRecord {
@@ -591,7 +601,7 @@ function writeCrashRecord(
 		// The marker is the record's identity, so it is budgeted first and appended
 		// after truncation: an oversized body can never evict it.
 		const body = boundCrashRecord(
-			`${now.toISOString()} pid=${process.pid} [${label}] ` +
+			`${now.toISOString()} pid=${process.pid} [${label}${options.provenance && options.provenance !== "product" ? `;provenance=${options.provenance}` : ""}] ` +
 				`${redactCrashSecrets(fatal.name)}: ${redactCrashSecrets(fatal.message)}\n` +
 				`${stack}${payload}`,
 			CRASH_RECORD_MAX_BYTES - Buffer.byteLength(markerLine, "utf8") - 1,