Connect your Node.js app.
See its first evidence.

export * from "./classifier.js";
export * from "./schema.js";
export * from "./delivery-context.js";

import { z } from "zod";
export const EVIDENCE_SCHEMA_VERSION = "nestarc.evidence.v1";
export const sourceEvidenceStageSchema = z.enum([
    "http.request",
    "database.commit",
    "outbox.write",
    "queue.enqueue",
    "worker.result",
    "webhook.request",
    "external.effect",
    "connector",
]);
export const sourceEvidenceStatusSchema = z.enum([
    "started",
    "succeeded",
    "accepted",
    "failed",
    "interrupted",
]);
export const evidenceErrorCodeSchema = z.enum([
    "WORKER_FAILED",
    "WEBHOOK_TIMEOUT",
    "CONNECTOR_INTERRUPTED",
    "INTERNAL_ERROR",
]);
export const opaqueReferenceSchema = z
    .string()
    .regex(/^[A-Za-z0-9._:-]{1,128}$/, "Must be an opaque 1-128 character reference");
export const utcIsoTimestampSchema = z
    .string()
    .regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/, "Must be an ISO 8601 timestamp in UTC")
    .datetime({ offset: false });
function normalizeUtcIsoTimestamp(value) {
    const fractionStart = value.indexOf(".");
    if (fractionStart === -1) {
        return `${value.slice(0, -1)}.000000000Z`;
    }
    const fraction = value.slice(fractionStart + 1, -1).padEnd(9, "0");
    return `${value.slice(0, fractionStart)}.${fraction}Z`;
}
export function compareUtcIsoTimestamps(left, right) {
    const normalizedLeft = normalizeUtcIsoTimestamp(left);
    const normalizedRight = normalizeUtcIsoTimestamp(right);
    if (normalizedLeft === normalizedRight)
        return 0;
    return normalizedLeft < normalizedRight ? -1 : 1;
}
const sourceEvidenceEventObjectSchema = z
    .object({
    schemaVersion: z.literal(EVIDENCE_SCHEMA_VERSION),
    eventId: z.string().uuid(),
    executionId: opaqueReferenceSchema,
    operationId: opaqueReferenceSchema,
    tenantRef: opaqueReferenceSchema.optional(),
    stage: sourceEvidenceStageSchema,
    status: sourceEvidenceStatusSchema,
    occurredAt: utcIsoTimestampSchema,
    attempt: z.number().int().min(1).max(100).optional(),
    durationMs: z.number().int().min(0).max(86_400_000).optional(),
    errorCode: evidenceErrorCodeSchema.optional(),
})
    .strict();
function hasCompatibleErrorContext(event) {
    switch (event.errorCode) {
        case undefined:
            return true;
        case "WORKER_FAILED":
            return event.stage === "worker.result" && event.status === "failed";
        case "WEBHOOK_TIMEOUT":
            return event.stage === "webhook.request" && event.status === "failed";
        case "CONNECTOR_INTERRUPTED":
            return (event.stage === "connector" &&
                (event.status === "failed" || event.status === "interrupted"));
        case "INTERNAL_ERROR":
            return event.status === "failed";
    }
}
const compatibleErrorContext = {
    message: "Error code must match its source Evidence stage and status",
    path: ["errorCode"],
};
export const evidenceEventSchema = sourceEvidenceEventObjectSchema.refine(hasCompatibleErrorContext, compatibleErrorContext);
export const receivedEvidenceEventSchema = sourceEvidenceEventObjectSchema
    .extend({
    receivedAt: utcIsoTimestampSchema.optional(),
})
    .strict()
    .refine(hasCompatibleErrorContext, compatibleErrorContext);
export const executionStateSchema = z.enum([
    "confirmed-complete",
    "confirmed-failure",
    "outcome-unknown",
    "evidence-interrupted",
]);
export const classificationReasonSchema = z.enum([
    "external-effect-confirmed",
    "failure-reported",
    "webhook-outcome-unconfirmed",
    "evidence-stream-interrupted",
    "execution-in-progress",
]);
export const CLASSIFICATION_STATE_BY_REASON = {
    "external-effect-confirmed": "confirmed-complete",
    "failure-reported": "confirmed-failure",
    "webhook-outcome-unconfirmed": "outcome-unknown",
    "evidence-stream-interrupted": "evidence-interrupted",
    "execution-in-progress": "outcome-unknown",
};
export const timelineToneSchema = z.enum([
    "neutral",
    "positive",
    "warning",
    "negative",
]);
export const timelineEntrySchema = z
    .object({
    sequence: z.number().int().positive(),
    eventId: z.string().uuid(),
    stage: sourceEvidenceStageSchema,
    status: sourceEvidenceStatusSchema,
    occurredAt: utcIsoTimestampSchema,
    receivedAt: utcIsoTimestampSchema.optional(),
    attempt: z.number().int().min(1).max(100).optional(),
    durationMs: z.number().int().min(0).max(86_400_000).optional(),
    errorCode: evidenceErrorCodeSchema.optional(),
    title: z.string().min(1),
    tone: timelineToneSchema,
})
    .strict();
export const executionSummarySchema = z
    .object({
    executionId: opaqueReferenceSchema,
    operationId: opaqueReferenceSchema,
    tenantRef: opaqueReferenceSchema.optional(),
    state: executionStateSchema,
    reason: classificationReasonSchema,
    firstOccurredAt: utcIsoTimestampSchema,
    lastOccurredAt: utcIsoTimestampSchema,
    lastReceivedAt: utcIsoTimestampSchema.optional(),
    eventCount: z.number().int().positive(),
    retention: z.object({ windowDays: z.number().int().positive(), expiredHistory: z.boolean(), nextExpiryAt: utcIsoTimestampSchema.optional(), evaluatedAt: utcIsoTimestampSchema.optional() }).strict().optional(),
})
    .strict()
    .superRefine((execution, context) => {
    const expectedState = CLASSIFICATION_STATE_BY_REASON[execution.reason];
    if (execution.state !== expectedState) {
        context.addIssue({
            code: "custom",
            path: ["reason"],
            message: `Classification reason ${execution.reason} requires state ${expectedState}`,
        });
    }
});
export const classifiedExecutionSchema = executionSummarySchema
    .extend({
    timeline: z.array(timelineEntrySchema).min(1),
})
    .strict();
// A storage relationship problem is not an execution state or source Evidence.
export const executionDataIssueSchema = z
    .object({
    executionId: opaqueReferenceSchema,
    code: z.literal("EXECUTION_DATA_CONFLICT"),
})
    .strict();
export const listExecutionsResponseSchema = z
    .object({
    executions: z.array(executionSummarySchema),
    dataIssues: z.array(executionDataIssueSchema),
})
    .strict()
    .superRefine(({ executions, dataIssues }, context) => {
    const ids = [...executions, ...dataIssues].map(({ executionId }) => executionId);
    if (ids.length > 50 || new Set(ids).size !== ids.length) {
        context.addIssue({ code: "custom", message: "Recent results must contain at most 50 distinct executions" });
    }
});
export const ingestEvidenceResponseSchema = z
    .object({
    accepted: z.literal(true),
    duplicate: z.boolean(),
    eventId: z.string().uuid(),
    receivedAt: utcIsoTimestampSchema,
})
    .strict();
export const healthResponseSchema = z
    .object({
    status: z.literal("ok"),
})
    .strict();
export const apiErrorCodeSchema = z.enum([
    "UNAUTHORIZED",
    "INVALID_WORKSPACE_ID",
    "FORBIDDEN",
    "INVALID_JSON",
    "BODY_TOO_LARGE",
    "BODY_READ_TIMEOUT",
    "RATE_LIMITED",
    "LIMIT_UNAVAILABLE",
    "POLICY_ACCEPTANCE_REQUIRED",
    "POLICY_UNAVAILABLE",
    "INVALID_EVIDENCE",
    "INVALID_EXECUTION_ID",
    "EVENT_ID_CONFLICT",
    "EXECUTION_IDENTITY_CONFLICT",
    "EXECUTION_DATA_CONFLICT",
    "EXECUTION_NOT_FOUND",
    "CONFIGURATION_ERROR",
    "INTERNAL_ERROR",
]);
export const apiErrorResponseSchema = z
    .object({
    error: z
        .object({
        code: apiErrorCodeSchema,
        message: z.string().min(1),
    })
        .strict(),
})
    .strict();

import { compareUtcIsoTimestamps } from "./schema.js";
const SOURCE_STAGE_TITLES = {
    "http.request": "HTTP request",
    "database.commit": "Database commit",
    "outbox.write": "Outbox write",
    "queue.enqueue": "Queue enqueue",
    "worker.result": "Worker result",
    "webhook.request": "Webhook request",
    "external.effect": "External effect",
    connector: "Evidence connector",
};
export class EvidenceInvariantError extends Error {
    constructor(message) {
        super(message);
        this.name = "EvidenceInvariantError";
    }
}
function compareEvents(left, right) {
    const occurredDifference = compareUtcIsoTimestamps(left.occurredAt, right.occurredAt);
    if (occurredDifference !== 0) {
        return occurredDifference;
    }
    return left.eventId.localeCompare(right.eventId);
}
function getLastReceivedAt(events) {
    let latest;
    for (const event of events) {
        if (event.receivedAt === undefined) {
            continue;
        }
        if (latest === undefined) {
            latest = event.receivedAt;
            continue;
        }
        const difference = compareUtcIsoTimestamps(event.receivedAt, latest);
        if (difference > 0 || (difference === 0 && event.receivedAt > latest)) {
            latest = event.receivedAt;
        }
    }
    return latest;
}
function timelineToneForSourceEvent(event) {
    if ((event.stage === "webhook.request" && event.errorCode === "WEBHOOK_TIMEOUT") ||
        (event.stage === "connector" &&
            (event.status === "failed" ||
                event.status === "interrupted" ||
                event.errorCode === "CONNECTOR_INTERRUPTED")) ||
        event.status === "interrupted") {
        return "warning";
    }
    if (event.status === "failed") {
        return "negative";
    }
    if (event.status === "succeeded" || event.status === "accepted") {
        return "positive";
    }
    return "neutral";
}
function toTimelineEntry(event, index) {
    return {
        sequence: index + 1,
        eventId: event.eventId,
        stage: event.stage,
        status: event.status,
        occurredAt: event.occurredAt,
        ...(event.receivedAt === undefined ? {} : { receivedAt: event.receivedAt }),
        ...(event.attempt === undefined ? {} : { attempt: event.attempt }),
        ...(event.durationMs === undefined ? {} : { durationMs: event.durationMs }),
        ...(event.errorCode === undefined ? {} : { errorCode: event.errorCode }),
        title: SOURCE_STAGE_TITLES[event.stage],
        tone: timelineToneForSourceEvent(event),
    };
}
function lastIndexMatching(events, predicate) {
    for (let index = events.length - 1; index >= 0; index -= 1) {
        const event = events[index];
        if (event !== undefined && predicate(event)) {
            return index;
        }
    }
    return -1;
}
function determineClassification(events) {
    const reversed = [...events].reverse();
    // LIFE-08: a later start/acceptance/interruption does not erase an explicit
    // external outcome report. Preserve source-time/event-ID order between
    // terminal reports; neither attempt numbers nor receipt times add authority.
    const externalEffect = reversed.find((event) => event.stage === "external.effect" &&
        (event.status === "succeeded" || event.status === "failed"));
    if (externalEffect?.status === "succeeded") {
        return {
            state: "confirmed-complete",
            reason: "external-effect-confirmed",
        };
    }
    if (externalEffect?.status === "failed") {
        return {
            state: "confirmed-failure",
            reason: "failure-reported",
        };
    }
    const confirmedFailureIndex = lastIndexMatching(events, (event) => event.status === "failed" &&
        event.stage !== "connector" &&
        !(event.stage === "webhook.request" && event.errorCode === "WEBHOOK_TIMEOUT"));
    const unconfirmedWebhookIndex = lastIndexMatching(events, (event) => event.stage === "webhook.request" &&
        (event.status === "accepted" ||
            event.status === "succeeded" ||
            event.errorCode === "WEBHOOK_TIMEOUT"));
    if (unconfirmedWebhookIndex > confirmedFailureIndex) {
        return {
            state: "outcome-unknown",
            reason: "webhook-outcome-unconfirmed",
        };
    }
    if (confirmedFailureIndex >= 0) {
        return {
            state: "confirmed-failure",
            reason: "failure-reported",
        };
    }
    const evidenceInterrupted = reversed.some((event) => event.stage === "connector" &&
        (event.status === "failed" ||
            event.status === "interrupted" ||
            event.errorCode === "CONNECTOR_INTERRUPTED"));
    if (evidenceInterrupted) {
        return {
            state: "evidence-interrupted",
            reason: "evidence-stream-interrupted",
        };
    }
    if (unconfirmedWebhookIndex >= 0) {
        return {
            state: "outcome-unknown",
            reason: "webhook-outcome-unconfirmed",
        };
    }
    return {
        state: "outcome-unknown",
        reason: "execution-in-progress",
    };
}
function assertConsistentExecution(events) {
    const first = events[0];
    if (first === undefined) {
        throw new EvidenceInvariantError("At least one evidence event is required");
    }
    const tenantRefs = new Set(events.flatMap((event) => (event.tenantRef === undefined ? [] : [event.tenantRef])));
    if (events.some((event) => event.executionId !== first.executionId || event.operationId !== first.operationId) ||
        tenantRefs.size > 1) {
        throw new EvidenceInvariantError("Evidence events must share an executionId, operationId, and tenantRef");
    }
}
export function classifyExecution(events) {
    assertConsistentExecution(events);
    const ordered = [...events].sort(compareEvents);
    const first = ordered[0];
    const last = ordered.at(-1);
    if (first === undefined || last === undefined) {
        throw new EvidenceInvariantError("At least one evidence event is required");
    }
    const classification = determineClassification(ordered);
    const tenantRef = ordered.find((event) => event.tenantRef !== undefined)?.tenantRef;
    const lastReceivedAt = getLastReceivedAt(ordered);
    return {
        executionId: first.executionId,
        operationId: first.operationId,
        ...(tenantRef === undefined ? {} : { tenantRef }),
        ...classification,
        firstOccurredAt: first.occurredAt,
        lastOccurredAt: last.occurredAt,
        ...(lastReceivedAt === undefined ? {} : { lastReceivedAt }),
        eventCount: ordered.length,
        timeline: ordered.map(toTimelineEntry),
    };
}
export function summarizeExecution(events) {
    const classified = classifyExecution(events);
    return {
        executionId: classified.executionId,
        operationId: classified.operationId,
        ...(classified.tenantRef === undefined
            ? {}
            : { tenantRef: classified.tenantRef }),
        state: classified.state,
        reason: classified.reason,
        firstOccurredAt: classified.firstOccurredAt,
        lastOccurredAt: classified.lastOccurredAt,
        ...(classified.lastReceivedAt === undefined
            ? {}
            : { lastReceivedAt: classified.lastReceivedAt }),
        eventCount: classified.eventCount,
    };
}

import { z } from 'zod';
import { opaqueReferenceSchema } from './schema.js';
/** Customer-owned durable metadata, NOT an Evidence wire payload or credential.
 * The observation decision is immutable for the execution. Old/missing context
 * is never upgraded to enabled during restore. Only trusted DB/outbox/job records
 * may supply this value; parsing does not authenticate its origin.
 */
export const deliveryEvidenceContextSchema = z.object({
    contextVersion: z.literal('nestarc.delivery.v1'),
    executionId: opaqueReferenceSchema,
    operationId: opaqueReferenceSchema,
    tenantRef: opaqueReferenceSchema,
    observation: z.enum(['enabled', 'interrupted', 'disabled']),
}).strict();
/** Validate only after reading an authenticated/trusted durable DB, outbox or job record.
 * This does not authenticate a caller or make request-supplied context trustworthy.
 * Missing, conflicting or old context disables observation without changing business work.
 */
export function contextFromTrustedRecord(record) {
    const parsed = deliveryEvidenceContextSchema.safeParse(record.evidenceContext);
    if (!parsed.success || parsed.data.executionId !== record.executionId ||
        parsed.data.operationId !== record.operationId || parsed.data.tenantRef !== record.tenantRef)
        return null;
    return Object.freeze(parsed.data);
}

import { randomUUID } from 'node:crypto';
import { evidenceEventSchema, } from './schema.js';
import { deliveryEvidenceContextSchema } from './delivery-context.js';
export { contextFromTrustedRecord } from './delivery-context.js';
export { checkConnection } from './connection-check.js';
export const DEFAULT_COLLECTOR_URL = 'https://reliability.nestarc.dev';
// A cold HTTPS request plus the collector's bounded admission/authentication
// and persistence work can exceed two seconds. This is an export lifetime,
// never time awaited by the application's business operation.
export const EVIDENCE_EXPORT_TIMEOUT_MS = 5_000;
const producerStages = {
    relay: ['queue.enqueue'],
    worker: ['worker.result', 'webhook.request'],
    receiver: ['webhook.request', 'external.effect'],
};
function boundedInteger(value, fallback, maximum) {
    return value !== undefined && Number.isSafeInteger(value) && value > 0
        ? Math.min(value, maximum)
        : fallback;
}
function boundedPending(value) {
    return value !== undefined && Number.isSafeInteger(value) && value >= 0
        ? Math.min(value, 4_096)
        : 16;
}
/** A configuration error disables observation instead of failing business startup.
 * Tokens are sent only to the configured origin, never a redirect or URL suffix.
 */
function collectorEndpoint(value, allowLoopback) {
    try {
        const url = new URL(value ?? DEFAULT_COLLECTOR_URL);
        const transportAllowed = url.protocol === 'https:' || (allowLoopback && url.protocol === 'http:' &&
            ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname));
        if (!transportAllowed || url.username || url.password || url.search || url.hash || url.pathname !== '/')
            return null;
        return `${url.origin}/v1/evidence`;
    }
    catch {
        return null;
    }
}
export class EvidenceReporter {
    endpoint;
    ingestToken;
    fetchImpl;
    timeoutMs;
    maxInFlight;
    maxPending;
    maxObservationLifetimeMs;
    activeExports = 0;
    waitingExports = [];
    maxTrackedExecutions;
    executionTtlMs;
    executions = new Map();
    cleanupTimer;
    lastMonotonicTime = 0;
    closed = false;
    pendingEmits = new Set();
    losses = {
        invalid: 0, unregistered: 0, suppressed: 0, identity: 0, capacity: 0, expired: 0,
        closed: 0, credential: 0, rejected: 0, transport: 0,
    };
    transportFailures = {
        timeout: 0, network: 0, responseCleanup: 0,
    };
    constructor(options) {
        this.endpoint = collectorEndpoint(options.collectorUrl, options.allowLoopback === true);
        this.ingestToken = typeof options.ingestToken === 'string' && options.ingestToken.length <= 512 ? options.ingestToken : '';
        this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
        this.timeoutMs = boundedInteger(options.timeoutMs, EVIDENCE_EXPORT_TIMEOUT_MS, 10_000);
        this.maxInFlight = boundedInteger(options.maxInFlight, 1, 4_096);
        this.maxPending = boundedPending(options.maxPending);
        this.maxObservationLifetimeMs = boundedInteger(options.maxObservationLifetimeMs, 30_000, 30_000);
        this.maxTrackedExecutions = boundedInteger(options.maxTrackedExecutions, 4_096, 4_096);
        this.executionTtlMs = boundedInteger(options.executionTtlMs, 300_000, 300_000);
    }
    /** Silent by default. Adapters may record only these fixed diagnostic messages. */
    warn(message) { void message; }
    // Bare emit/report require admission; only the separate durable-context path
    // can restore enabled observations. Business work still receives an ID when
    // observation capacity is exhausted (persist a disabled downstream context).
    createExecutionId() {
        const executionId = randomUUID();
        this.pruneExecutions();
        if (!this.closed && this.executions.size < this.maxTrackedExecutions) {
            this.executions.set(executionId, {
                expiresAt: this.monotonicNow() + this.executionTtlMs,
                lastOccurredAt: 0,
                interrupted: false,
            });
            this.scheduleCleanup();
        }
        return executionId;
    }
    /** Snapshot the immutable downstream decision while the API owns admission.
     * Persist this with the operation/outbox. Null/legacy context stays disabled.
     * An interrupted execution must persist 'interrupted' BEFORE dispatching work.
     */
    createDeliveryContext(identity, interrupted = false) {
        this.pruneExecutions();
        const state = this.executions.get(identity.executionId);
        const parsed = deliveryEvidenceContextSchema.safeParse({
            ...identity, contextVersion: 'nestarc.delivery.v1',
            observation: !state || this.closed || this.endpoint === null || !this.ingestToken.trim() ? 'disabled' :
                interrupted || state.interrupted ? 'interrupted' : 'enabled',
        });
        if (!parsed.success) {
            this.drop('invalid');
            return null;
        }
        if (state) {
            if (state.restored || !this.matchesIdentity(state, parsed.data)) {
                this.drop('identity');
                return null;
            }
            if (state.deliveryContext && state.deliveryContext.observation !== parsed.data.observation) {
                this.drop('identity');
                return null;
            }
            state.identity = { operationId: identity.operationId, tenantRef: identity.tenantRef };
            state.deliveryContext = Object.freeze(parsed.data);
        }
        return Object.freeze(parsed.data);
    }
    /** Only call with context read from a trusted durable business record.
     * Restore is explicit; bare emit/report still cannot register missing IDs.
     * No historical event is synthesized and no send is retried.
     */
    emitDelivery(candidate, producer, input) {
        const context = this.restoreDelivery(candidate, producer, input.stage, input.status);
        if (!context)
            return Promise.resolve(false);
        return this.emit({ ...input, executionId: context.executionId,
            operationId: context.operationId, tenantRef: context.tenantRef });
    }
    /** Re-delivery of an existing observation must preserve its entire envelope. */
    reportDelivery(candidate, producer, event) {
        const parsed = deliveryEvidenceContextSchema.safeParse(candidate);
        if (!parsed.success)
            return this.drop('invalid');
        if (event.executionId !== parsed.data.executionId || event.operationId !== parsed.data.operationId ||
            event.tenantRef !== parsed.data.tenantRef)
            return this.drop('identity');
        if (!this.restoreDelivery(parsed.data, producer, event.stage, event.status))
            return Promise.resolve(false);
        return this.report(event);
    }
    restoreDelivery(candidate, producer, stage, status) {
        this.pruneExecutions();
        const parsed = deliveryEvidenceContextSchema.safeParse(candidate);
        const allowedStatus = producer === 'relay' ? status === 'succeeded' :
            producer === 'receiver' && stage === 'webhook.request' ? status === 'accepted' :
                status === 'succeeded' || status === 'failed';
        if (!parsed.success || !producerStages[producer]?.includes(stage) || !allowedStatus) {
            this.drop('invalid');
            return null;
        }
        const context = parsed.data;
        if (this.closed) {
            this.drop('closed');
            return null;
        }
        if (context.observation !== 'enabled') {
            this.drop('suppressed');
            return null;
        }
        let state = this.executions.get(context.executionId);
        if (state?.interrupted) {
            this.drop('suppressed');
            return null;
        }
        if (state?.deliveryContext && state.deliveryContext.observation !== 'enabled') {
            this.drop('suppressed');
            return null;
        }
        if (state && !this.matchesIdentity(state, context)) {
            this.drop('identity');
            return null;
        }
        if (!state) {
            if (this.executions.size >= this.maxTrackedExecutions) {
                this.drop('capacity');
                return null;
            }
            state = { expiresAt: this.monotonicNow() + this.executionTtlMs,
                lastOccurredAt: 0, interrupted: false, restored: true };
            this.executions.set(context.executionId, state);
            this.scheduleCleanup();
        }
        state.identity = { operationId: context.operationId, tenantRef: context.tenantRef };
        state.deliveryContext = Object.freeze(context);
        return context;
    }
    matchesIdentity(state, input) {
        return !state.identity || (state.identity.operationId === input.operationId && state.identity.tenantRef === input.tenantRef);
    }
    drop(reason) {
        this.losses[reason] = Math.min(Number.MAX_SAFE_INTEGER, this.losses[reason] + 1);
        return Promise.resolve(false);
    }
    getLossCounts() { return { ...this.losses }; }
    /** Subcounts of losses.transport, not additional losses or persistence receipts.
     * Fixed aggregate categories never contain event IDs, URLs or error contents.
     */
    getTransportFailureCounts() {
        return { ...this.transportFailures };
    }
    getQueueDiagnostics() {
        return { waitingExports: this.waitingExports.length, maxPending: this.maxPending,
            maxObservationLifetimeMs: this.maxObservationLifetimeMs };
    }
    emit(input) {
        this.pruneExecutions();
        const state = this.executions.get(input.executionId);
        if (this.closed)
            return this.drop('closed');
        if (state === undefined)
            return this.drop('unregistered');
        if (state.interrupted)
            return this.drop('suppressed');
        const next = Math.max(Date.now(), state.lastOccurredAt + 1);
        return this.report({
            schemaVersion: 'nestarc.evidence.v1',
            eventId: randomUUID(),
            occurredAt: new Date(next).toISOString(),
            ...input,
        });
    }
    interrupt(input) {
        void this.emit({
            ...input,
            stage: 'connector',
            status: 'interrupted',
            errorCode: 'CONNECTOR_INTERRUPTED',
        });
    }
    report(candidate) {
        this.pruneExecutions();
        const state = this.executions.get(candidate.executionId);
        if (this.closed)
            return this.drop('closed');
        if (state === undefined)
            return this.drop('unregistered');
        if (state.interrupted)
            return this.drop('suppressed');
        const parsed = evidenceEventSchema.safeParse(candidate);
        if (!parsed.success) {
            this.warn('Dropped invalid outbound evidence event');
            return this.drop('invalid');
        }
        if (!this.matchesIdentity(state, parsed.data))
            return this.drop('identity');
        // Restored producers cannot declare a new process-local interruption: its
        // durable execution-wide policy must be chosen before dispatch instead.
        if ((state.restored || state.deliveryContext?.observation === 'enabled') &&
            parsed.data.stage === 'connector')
            return this.drop('invalid');
        state.lastOccurredAt = Math.max(state.lastOccurredAt, Date.parse(parsed.data.occurredAt));
        // Suppression takes effect even if the interruption cannot be exported.
        if (parsed.data.stage === 'connector' &&
            (parsed.data.status === 'interrupted' || parsed.data.status === 'failed' ||
                parsed.data.errorCode === 'CONNECTOR_INTERRUPTED')) {
            state.interrupted = true;
        }
        if (this.endpoint === null)
            return this.drop('invalid');
        if (!this.ingestToken.trim()) {
            this.warn('Evidence export skipped: ingest credential is not configured');
            return this.drop('credential');
        }
        if (this.activeExports >= this.maxInFlight && this.waitingExports.length >= this.maxPending) {
            this.warn('Dropped evidence because the exporter is at capacity');
            return this.drop('capacity');
        }
        let resolve;
        const pending = new Promise(settle => { resolve = settle; });
        const item = {
            event: parsed.data,
            expiresAt: this.monotonicNow() + this.maxObservationLifetimeMs,
            finish: accepted => { this.pendingEmits.delete(pending); resolve(accepted); },
        };
        this.pendingEmits.add(pending);
        if (this.activeExports < this.maxInFlight)
            this.startExport(item);
        else {
            this.waitingExports.push(item);
            item.timer = setTimeout(() => {
                const index = this.waitingExports.indexOf(item);
                if (index === -1)
                    return;
                this.waitingExports.splice(index, 1);
                void this.drop('expired');
                item.finish(false);
            }, this.maxObservationLifetimeMs);
            item.timer.unref?.();
        }
        return pending;
    }
    startExport(item) {
        clearTimeout(item.timer);
        const remaining = item.expiresAt - this.monotonicNow();
        if (remaining <= 0) {
            void this.drop('expired');
            item.finish(false);
            return;
        }
        this.activeExports += 1;
        // No queued item re-enters report/restore or changes its source timestamps.
        // Already admitted observations also finish after close(), within their
        // original absolute lifetime. Failed sends are never queued a second time.
        void this.exportEvent(item.event, Math.min(this.timeoutMs, remaining)).then(accepted => {
            this.activeExports -= 1;
            item.finish(accepted);
            this.drainExports();
        });
    }
    drainExports() {
        while (this.activeExports < this.maxInFlight && this.waitingExports.length) {
            this.startExport(this.waitingExports.shift());
        }
    }
    async exportEvent(event, remainingMs) {
        const controller = new AbortController();
        let timeout;
        let timedOut = false;
        let responseReceived = false;
        const deadline = new Promise((_resolve, reject) => {
            timeout = setTimeout(() => {
                timedOut = true;
                controller.abort();
                reject(new Error('Evidence export deadline exceeded'));
            }, remainingMs);
            timeout.unref?.();
        });
        try {
            const exporting = (async () => {
                const response = await this.fetchImpl(this.endpoint, {
                    method: 'POST',
                    redirect: 'error',
                    headers: {
                        authorization: `Bearer ${this.ingestToken}`,
                        'content-type': 'application/json',
                    },
                    body: JSON.stringify(event),
                    signal: controller.signal,
                });
                responseReceived = true;
                // The collector body is unused. Both accepted and rejected responses
                // own the capacity slot until cancellation settles or the request is
                // aborted. Keep this in the raced operation so a late response from an
                // injected fetch that ignores abort still has its body discarded.
                await response.body?.cancel();
                if (controller.signal.aborted)
                    return false;
                if (!response.ok) {
                    this.warn(`Evidence collector rejected event (${response.status})`);
                    this.drop('rejected');
                }
                return response.ok;
            })();
            // Cancellation itself can reject or never settle; aborting the network
            // request must not make the business-facing promise wait on that cleanup.
            return await Promise.race([exporting, deadline]);
        }
        catch {
            this.warn('Evidence export failed open');
            this.drop('transport');
            const reason = timedOut ? 'timeout' : responseReceived ? 'responseCleanup' : 'network';
            this.transportFailures[reason] = Math.min(Number.MAX_SAFE_INTEGER, this.transportFailures[reason] + 1);
            return false;
        }
        finally {
            clearTimeout(timeout);
            controller.abort();
        }
    }
    async resetForTests() {
        if (process.env.NODE_ENV !== 'test') {
            throw new Error('Evidence reporter reset is only available with NODE_ENV=test');
        }
        await Promise.allSettled([...this.pendingEmits]);
        this.clearExecutions();
    }
    close() {
        this.closed = true;
        this.clearExecutions();
    }
    async flush() {
        // Admitted observations retain their absolute lifetime while waiting and
        // their remaining bounded deadline during network/body cleanup.
        await Promise.allSettled([...this.pendingEmits]);
    }
    /** Compatibility hooks for NestJS; ordinary Node applications use close/flush. */
    onModuleDestroy() { this.close(); }
    async beforeApplicationShutdown() { await this.flush(); }
    getDiagnostics() {
        this.pruneExecutions();
        return {
            activeExports: this.activeExports,
            pendingEmits: this.pendingEmits.size,
            trackedExecutions: this.executions.size,
            interruptedExecutions: [...this.executions.values()].filter(state => state.interrupted).length,
        };
    }
    monotonicNow() {
        this.lastMonotonicTime = Math.max(this.lastMonotonicTime, performance.now());
        return this.lastMonotonicTime;
    }
    pruneExecutions() {
        const now = this.monotonicNow();
        // Fixed TTL + monotonic admission preserve expiry order in insertion order.
        for (const [id, state] of this.executions) {
            if (state.expiresAt > now)
                break;
            this.executions.delete(id);
        }
        if (this.executions.size === 0 && this.cleanupTimer !== undefined) {
            clearTimeout(this.cleanupTimer);
            this.cleanupTimer = undefined;
        }
    }
    scheduleCleanup() {
        if (this.cleanupTimer !== undefined)
            return;
        const oldest = this.executions.values().next().value;
        if (oldest === undefined)
            return;
        this.cleanupTimer = setTimeout(() => {
            this.cleanupTimer = undefined;
            this.pruneExecutions();
            this.scheduleCleanup();
        }, Math.max(1, Math.ceil(oldest.expiresAt - this.monotonicNow())));
        this.cleanupTimer.unref?.();
    }
    clearExecutions() {
        clearTimeout(this.cleanupTimer);
        this.cleanupTimer = undefined;
        this.executions.clear();
    }
}

import { z } from 'zod';
import { opaqueReferenceSchema } from './schema.js';
const authorizedResponse = z.object({
    schemaVersion: z.literal('nestarc.connection-test.v1'),
    status: z.literal('authorized'),
    workspaceId: opaqueReferenceSchema,
    checkedAt: z.iso.datetime({ offset: false }),
    evidenceStored: z.literal(false),
}).strict();
/** A manual, bounded authorization/admission probe. It inserts no Evidence and
 * does not prove persistence, dashboard access, business completion or future health.
 */
export async function checkConnection(options) {
    let url;
    try {
        url = new URL(options.collectorUrl ?? 'https://reliability.nestarc.dev');
        if ((url.protocol !== 'https:' && !(options.allowLoopback === true && url.protocol === 'http:' &&
            ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname))) || url.username || url.password ||
            url.search || url.hash || url.pathname !== '/' || !options.ingestToken?.trim() ||
            options.ingestToken.length > 512 || (options.expectedWorkspaceId !== undefined &&
            !opaqueReferenceSchema.safeParse(options.expectedWorkspaceId).success))
            return { status: 'invalid-configuration' };
    }
    catch {
        return { status: 'invalid-configuration' };
    }
    const controller = new AbortController();
    let timeout;
    const deadline = new Promise(resolve => {
        timeout = setTimeout(() => { controller.abort(); resolve({ status: 'unavailable' }); }, 5_000);
    });
    try {
        return await Promise.race([deadline, (async () => {
                const response = await (options.fetchImpl ?? globalThis.fetch)(`${url.origin}/v1/connection-test`, {
                    method: 'POST', redirect: 'error', signal: controller.signal,
                    headers: { authorization: `Bearer ${options.ingestToken}`, 'content-type': 'application/json' },
                    body: '{}',
                });
                if (response.status !== 200) {
                    await response.body?.cancel();
                    return { status: response.status === 401 ? 'unauthorized' : response.status === 403 ? 'not-ready' :
                            response.status === 429 ? 'limited' : 'unavailable' };
                }
                if (response.headers.get('content-type')?.split(';', 1)[0]?.trim().toLowerCase() !== 'application/json' || !response.body) {
                    await response.body?.cancel();
                    return { status: 'invalid-response' };
                }
                const reader = response.body.getReader();
                const chunks = [];
                let bytes = 0;
                try {
                    while (true) {
                        const part = await reader.read();
                        if (part.done)
                            break;
                        bytes += part.value.byteLength;
                        if (bytes > 2_048)
                            return { status: 'invalid-response' };
                        chunks.push(part.value);
                    }
                }
                finally {
                    await reader.cancel();
                }
                const joined = new Uint8Array(bytes);
                let offset = 0;
                for (const chunk of chunks) {
                    joined.set(chunk, offset);
                    offset += chunk.byteLength;
                }
                let body;
                try {
                    body = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(joined));
                }
                catch {
                    return { status: 'invalid-response' };
                }
                const parsed = authorizedResponse.safeParse(body);
                if (!parsed.success || controller.signal.aborted)
                    return { status: 'invalid-response' };
                if (options.expectedWorkspaceId !== undefined && options.expectedWorkspaceId !== parsed.data.workspaceId) {
                    return { status: 'workspace-mismatch' };
                }
                return parsed.data;
            })()]);
    }
    catch {
        return { status: 'unavailable' };
    }
    finally {
        clearTimeout(timeout);
        controller.abort();
    }
}

#!/usr/bin/env node
import { checkConnection } from './connection-check.js';
if (process.argv.length !== 2) {
    console.error('Use NESTARC_INGEST_TOKEN in the environment; this command accepts no arguments.');
    process.exitCode = 1;
}
else {
    const result = await checkConnection({
        ingestToken: process.env.NESTARC_INGEST_TOKEN ?? '',
        ...(process.env.NESTARC_COLLECTOR_URL ? { collectorUrl: process.env.NESTARC_COLLECTOR_URL } : {}),
        ...(process.env.NESTARC_WORKSPACE_ID ? { expectedWorkspaceId: process.env.NESTARC_WORKSPACE_ID } : {}),
        allowLoopback: process.env.NESTARC_ALLOW_LOOPBACK === '1',
    });
    // Never print credentials, workspace IDs, response bodies or transport errors.
    console.log(JSON.stringify({ status: result.status, evidenceStored: false }));
    if (result.status !== 'authorized')
        process.exitCode = 1;
}

{
  "schemaVersion": "nestarc.sdk-release.v1",
  "package": "@nestarc/evidence",
  "version": "0.3.0",
  "publisher": "Nestarc",
  "archive": {
    "url": "https://reliability.nestarc.dev/downloads/nestarc-evidence-0.3.0.tgz",
    "path": "/downloads/nestarc-evidence-0.3.0.tgz",
    "bytes": 30459,
    "sha256": "4ffb06af8f2d5a4457238695e0010fd3fe6c79139579695b16e094e5166485c5"
  },
  "runtime": "Node.js 22.12 or later with ESM",
  "dependencies": {
    "zod": "^4.1.5"
  },
  "sourceScope": "The seven JavaScript runtime modules shipped inside this exact SDK archive. Type declarations, integration guidance and a local example are also included in the archive.",
  "sourceFiles": [
    {
      "path": "dist/index.js",
      "sha256": "50acf8552c73a58ba416e75da13c299545fe167cf673619d41756c158f072f6b",
      "bytes": 101
    },
    {
      "path": "dist/schema.js",
      "sha256": "a2e4423574ca3dc7670cc9930eeebe608620b1ed19b7dfc9d1c9f974ede1120b",
      "bytes": 7485
    },
    {
      "path": "dist/classifier.js",
      "sha256": "dbdbd27fc5cb3c35514f66c02c99ee390c7731f6ad1ae61e551afe33c03a682b",
      "bytes": 7343
    },
    {
      "path": "dist/delivery-context.js",
      "sha256": "39d5641ba32a51bba8994106541a3e98f9adf5c135f39e9fac39d0d50cfb614c",
      "bytes": 1348
    },
    {
      "path": "dist/node.js",
      "sha256": "6bee0e621f00b9ba424874201227182e6c78e0c701bede2bfa16e7ae7b69b420",
      "bytes": 19017
    },
    {
      "path": "dist/connection-check.js",
      "sha256": "8c6af5360f8ef05e27e4de1e2eb99d564740191427179df3013b79bc9a8fff96",
      "bytes": 4306
    },
    {
      "path": "dist/connection-check-cli.js",
      "sha256": "353084bdfbe33417a21cb6d92ffcc4dea42c58c5c37b59b2ab80713ddd33141d",
      "bytes": 884
    }
  ],
  "changes": [
    "Version 0.3.0 adds a bounded in-memory waiting queue: one active send and up to 16 waiting observations per reporter by default.",
    "Each observation keeps its event ID and original occurrence time. Its total lifetime, including queueing and sending, is capped at 30 seconds.",
    "A send remains bounded while its response body is cancelled. Timeout, network and response-cleanup losses have separate aggregate counters.",
    "Failed sends are not automatically retried. Evidence export does not determine your business result."
  ],
  "usage": {
    "termsUrl": "/terms/evaluation?releaseDigest=3a76f02c853fe0bf481b23d42dd8f3658a9e5e6075283dfa12c83fd9ecc31636",
    "termsVersion": "evaluation-2.0",
    "licenseDeclaredInPackage": false,
    "notice": "Nestarc distributes this SDK for connecting an authorized system to the service under its published beta terms. No separate open-source license is declared in the package."
  },
  "verificationScope": "The checksum identifies the SDK archive and the listed source files. It is not an independent security certification and does not pin the transitive dependencies installed by npm."
}