@netgreener/runtime 0.1.0

package/dist/analyze/unboundedParallelismDetector.js

@@ -0,0 +1,57 @@
+/**
+ * Heuristic JS/TS twin of Python ``unbounded_asyncio_gather_with_io``.
+ *
+ * RD0 disposition → mechanism ``unbounded_parallelism`` / ``network.io``.
+ * Flags ``Promise.all(…map…fetch)`` style fan-out without an obvious concurrency cap.
+ */
+import { hasApiCall, PROMISE_ALL_RE, stripLineComment, } from './heuristicScan.js';
+import { languageForPath, } from './resourceFindingCandidate.js';
+const DETECTOR_ID = 'js.static.unbounded_promise_all';
+const DETECTOR_VERSION = '0.1.0';
+const LEGACY_ISSUE = 'unbounded_asyncio_gather_with_io';
+const MECHANISM = 'unbounded_parallelism';
+const TITLE = 'Unbounded Promise.all fan-out may spike concurrent I/O cost';
+/** Obvious concurrency caps we treat as not-unbounded (heuristic). */
+const CAP_HINT_RE = /\b(?:pLimit|p-limit|bottleneck|Semaphore|mapLimit|eachLimit|PromisePool|concurrency\s*:)\b/i;
+/**
+ * Detect unbounded Promise.all + API fan-out in one source file.
+ */
+export function detectUnboundedParallelismHits(source, relPath) {
+    const lines = source.split(/\r?\n/);
+    const hits = [];
+    const language = languageForPath(relPath);
+    const path = relPath.replace(/\\/g, '/');
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = stripLineComment(lines[i] ?? '');
+        const lineNo = i + 1;
+        if (!PROMISE_ALL_RE.test(line))
+            continue;
+        // Look at this line + next 2 for map/fetch / API signals and cap hints.
+        const window = [line, stripLineComment(lines[i + 1] ?? ''), stripLineComment(lines[i + 2] ?? '')]
+            .join(' ');
+        if (CAP_HINT_RE.test(window))
+            continue;
+        const hasFanOut = /\.map\s*\(/.test(window) || /\.flatMap\s*\(/.test(window) || hasApiCall(window);
+        if (!hasFanOut)
+            continue;
+        if (!hasApiCall(window) && !/\.map\s*\(/.test(window))
+            continue;
+        // Require API somewhere in the window (avoid Promise.all(localCpuWork))
+        if (!hasApiCall(window))
+            continue;
+        hits.push({
+            mechanism_id: MECHANISM,
+            primary_domain: 'network.io',
+            admission_domain: 'network.io',
+            title: TITLE,
+            rel_path: path,
+            start_line: lineNo,
+            end_line: lineNo,
+            language,
+            detector_id: DETECTOR_ID,
+            detector_version: DETECTOR_VERSION,
+            legacy_issue_type: LEGACY_ISSUE,
+        });
+    }
+    return hits;
+}

package/dist/analyze/validateResourceFinding.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Validate Analyze candidates against vendored ``resource_finding_v1`` JSON Schema.
+ * Mirrors observation-v1 Ajv usage; does not upload or change RunSession.
+ */
+import type { ResourceFindingCandidateV1 } from './resourceFindingCandidate.js';
+export type ResourceFindingValidationError = {
+    instancePath: string;
+    message: string;
+};
+export type ResourceFindingValidation = {
+    ok: boolean;
+    errors: ResourceFindingValidationError[];
+};
+/** Shape-check a single ``resource_finding_v1`` document. */
+export declare function validateResourceFindingCandidate(document: unknown): ResourceFindingValidation;
+/** Keep only schema-valid candidates (fail-closed for malformed emitter output). */
+export declare function filterValidResourceFindings(findings: ResourceFindingCandidateV1[]): ResourceFindingCandidateV1[];
+/** True when every finding validates. */
+export declare function allResourceFindingsValid(findings: Iterable<ResourceFindingCandidateV1>): boolean;

package/dist/analyze/validateResourceFinding.js

@@ -0,0 +1,46 @@
+/**
+ * Validate Analyze candidates against vendored ``resource_finding_v1`` JSON Schema.
+ * Mirrors observation-v1 Ajv usage; does not upload or change RunSession.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+let shapeValidator = null;
+function getValidator() {
+    if (!shapeValidator) {
+        const Ajv2020 = require('ajv/dist/2020.js').default;
+        const addFormats = require('ajv-formats').default;
+        const schema = JSON.parse(readFileSync(new URL('./schemas/resource-finding.schema.json', import.meta.url), 'utf8'));
+        const ajv = new Ajv2020({
+            strict: false,
+            strictNumbers: true,
+            allErrors: true,
+            ownProperties: true,
+        });
+        addFormats(ajv, ['date-time']);
+        shapeValidator = ajv.compile(schema);
+    }
+    return shapeValidator;
+}
+/** Shape-check a single ``resource_finding_v1`` document. */
+export function validateResourceFindingCandidate(document) {
+    const validate = getValidator();
+    const ok = Boolean(validate(document));
+    const errors = (validate.errors || []).map((e) => ({
+        instancePath: e.instancePath || '',
+        message: e.message || 'invalid',
+    }));
+    return { ok, errors };
+}
+/** Keep only schema-valid candidates (fail-closed for malformed emitter output). */
+export function filterValidResourceFindings(findings) {
+    return findings.filter((f) => validateResourceFindingCandidate(f).ok);
+}
+/** True when every finding validates. */
+export function allResourceFindingsValid(findings) {
+    for (const f of findings) {
+        if (!validateResourceFindingCandidate(f).ok)
+            return false;
+    }
+    return true;
+}

package/dist/bullmq.d.ts

@@ -0,0 +1,33 @@
+/**
+ * BullMQ worker binding (N3 / T2 Node analogue of Celery task_kwarg).
+ *
+ * No hard dependency on ``bullmq`` — wrap any processor that receives a job-like
+ * object with ``name`` + ``data``. Enqueue with organization_id (or configured
+ * kwarg) in ``job.data``.
+ */
+import { type NetGreenerRuntime, type NetGreenerRuntimeOptions } from './runtime.js';
+import { type TenantContext } from './tenantContext.js';
+/** Minimal BullMQ Job shape (avoid hard dependency). */
+export type BullMqJobLike = {
+    id?: string;
+    name?: string;
+    data?: Record<string, unknown>;
+};
+export type BullMqProcessorOptions = NetGreenerRuntimeOptions & {
+    /** Fallback service unit name when job.name is missing. */
+    defaultJobName?: string;
+};
+/**
+ * Wrap a BullMQ (or compatible) processor so each job:
+ * - binds tenant from ``job.data[NETGREENER_TENANT_TASK_KWARG]`` when configured
+ * - attributes outbound ``fetch`` to ``task:<job.name>``
+ * - records a runtime task sample for flush
+ */
+export declare function netgreenerBullMqProcessor<Job extends BullMqJobLike, Result>(processor: (job: Job) => Promise<Result> | Result, opts?: BullMqProcessorOptions): (job: Job) => Promise<Result>;
+/**
+ * Bind tenant + request attribution for one job without wrapping the whole Worker.
+ * Useful when you already own the processor loop.
+ */
+export declare function runBullMqJobWithNetGreener<Job extends BullMqJobLike, Result>(job: Job, fn: () => Promise<Result> | Result, opts?: BullMqProcessorOptions): Promise<Result>;
+export declare function getBullMqRuntime(): NetGreenerRuntime;
+export type { TenantContext };

package/dist/bullmq.js

@@ -0,0 +1,106 @@
+/**
+ * BullMQ worker binding (N3 / T2 Node analogue of Celery task_kwarg).
+ *
+ * No hard dependency on ``bullmq`` — wrap any processor that receives a job-like
+ * object with ``name`` + ``data``. Enqueue with organization_id (or configured
+ * kwarg) in ``job.data``.
+ */
+import { getRuntime, } from './runtime.js';
+import { loadTenantConfig, resolveTenantFromTaskData, runWithTenantContext, } from './tenantContext.js';
+import { runWithRequestAttribution } from './requestContext.js';
+import { beginProcessResourceSample, endProcessResourceSample, } from './processResources.js';
+function serviceUnitForJob(job, fallback) {
+    const name = String(job.name || fallback || 'job').trim() || 'job';
+    return `task:${name.slice(0, 240)}`;
+}
+/**
+ * Wrap a BullMQ (or compatible) processor so each job:
+ * - binds tenant from ``job.data[NETGREENER_TENANT_TASK_KWARG]`` when configured
+ * - attributes outbound ``fetch`` to ``task:<job.name>``
+ * - records a runtime task sample for flush
+ */
+export function netgreenerBullMqProcessor(processor, opts = {}) {
+    const runtime = getRuntime({
+        collector: 'bullmq_worker',
+        framework: 'bullmq',
+        ...opts,
+    });
+    runtime.start();
+    const tenantConfig = loadTenantConfig();
+    const fallbackName = opts.defaultJobName || 'job';
+    return async function netgreenerInstrumentedProcessor(job) {
+        if (!runtime.enabled) {
+            return await processor(job);
+        }
+        const tenant = resolveTenantFromTaskData(job?.data && typeof job.data === 'object' ? job.data : null, tenantConfig);
+        const serviceUnit = serviceUnitForJob(job, fallbackName);
+        const started = performance.now();
+        const resourceMark = beginProcessResourceSample();
+        let error = false;
+        const run = async () => {
+            try {
+                return await processor(job);
+            }
+            catch (err) {
+                error = true;
+                throw err;
+            }
+            finally {
+                const resources = endProcessResourceSample(resourceMark);
+                runtime.recordTask({
+                    serviceUnit,
+                    durationMs: performance.now() - started,
+                    error,
+                    tenantId: tenant?.tenantId ?? null,
+                    cpuTimeMs: resources.cpuTimeMs,
+                    peakRssKb: resources.rssKb,
+                });
+            }
+        };
+        return runWithTenantContext(tenant, () => runWithRequestAttribution({ serviceUnit }, () => run()));
+    };
+}
+/**
+ * Bind tenant + request attribution for one job without wrapping the whole Worker.
+ * Useful when you already own the processor loop.
+ */
+export function runBullMqJobWithNetGreener(job, fn, opts = {}) {
+    const runtime = getRuntime({
+        collector: 'bullmq_worker',
+        framework: 'bullmq',
+        ...opts,
+    });
+    runtime.start();
+    const tenantConfig = loadTenantConfig();
+    const tenant = resolveTenantFromTaskData(job?.data && typeof job.data === 'object' ? job.data : null, tenantConfig);
+    const serviceUnit = serviceUnitForJob(job, opts.defaultJobName || 'job');
+    const started = performance.now();
+    const resourceMark = beginProcessResourceSample();
+    let error = false;
+    const run = async () => {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            error = true;
+            throw err;
+        }
+        finally {
+            if (runtime.enabled) {
+                const resources = endProcessResourceSample(resourceMark);
+                runtime.recordTask({
+                    serviceUnit,
+                    durationMs: performance.now() - started,
+                    error,
+                    tenantId: tenant?.tenantId ?? null,
+                    cpuTimeMs: resources.cpuTimeMs,
+                    peakRssKb: resources.rssKb,
+                });
+            }
+        }
+    };
+    return runWithTenantContext(tenant, () => runWithRequestAttribution({ serviceUnit }, () => run()));
+}
+export function getBullMqRuntime() {
+    return getRuntime({ collector: 'bullmq_worker', framework: 'bullmq' });
+}

package/dist/cli/helpText.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared CLI help / version copy for the Node ``netgreener`` scaffold.
+ * Upload remains off; run/optimize stay stubs.
+ */
+export declare const CLI_VERSION = "0.1.0";
+export declare function formatRootHelp(): string;
+export declare function formatAnalyzeHelp(): string;
+export declare function formatStubHelp(command: 'run' | 'optimize'): string;

package/dist/cli/helpText.js

@@ -0,0 +1,99 @@
+/**
+ * Shared CLI help / version copy for the Node ``netgreener`` scaffold.
+ * Upload remains off; run/optimize stay stubs.
+ */
+export const CLI_VERSION = '0.1.0';
+export function formatRootHelp() {
+    return `NetGreener Node CLI ${CLI_VERSION} (scaffold)
+
+Usage:
+  netgreener <command> [options]
+  netgreener help [command]
+
+Commands:
+  analyze <projectDir>   Local resource Analyze (manifest + resource_finding_v1)
+  run                    (stub) Not implemented — will not upload
+  optimize               (stub) Not implemented — will not upload
+  help [command]         Show this help or a command's help
+  version                Show version
+
+Global:
+  -h, --help             Show this help
+  -V, --version          Show version
+
+Examples:
+  netgreener analyze ./my-app
+  netgreener analyze ./my-app --json-summary
+  netgreener analyze ./my-app --fail-on any --max-at-or-above 0
+  netgreener analyze ./my-app --paths src/hot.ts,src/retry.ts --findings-only
+  netgreener-analyze ./my-app          # alias bin (same Analyze path)
+
+Notes:
+  • Analyze prints local candidates only (upload=never).
+  • optimize / run are stubs (exit 2) — see OPTIMIZE_STUB.md; no upload / no patches.
+  • Does not modify RunSession / metering pipelines.
+  • VS Code: Node-first folders use this local Analyze path (same guarantee).
+
+Analyze options:  netgreener help analyze
+  Optimize stub:    netgreener help optimize
+`;
+}
+export function formatAnalyzeHelp() {
+    return `Usage: netgreener analyze <projectDir> [options]
+   (alias) netgreener-analyze <projectDir> [options]
+
+Print NetGreener Analyze scaffold output:
+  service_manifest_v0 + resource_finding_v1 candidates (JSON on stdout).
+
+Does not upload and does not modify RunSession / metering pipelines.
+
+Options:
+  --project-id <id>              Stamp project_id on candidates (default: local)
+  --paths a,b                    Explicit repo-relative source paths (comma-separated)
+  --findings-only                Emit findings JSON array only
+  --manifest-only                Emit service_manifest_v0 JSON only
+  --json-summary                 Emit netgreener_analyze_gate_summary_v0 only (CI)
+  --fail-on any|<mechanism>[,…]  Fail (exit 1) when matching candidates exceed cap
+  --max-at-or-above <n>          With --fail-on: allow up to N matches (default 0)
+  --quiet                        No stderr status lines
+  -h, --help                     Show this help
+
+Examples:
+  netgreener analyze ./fixtures/analyze-sample
+  netgreener analyze ./app --project-id 42 --quiet
+  netgreener analyze ./app --json-summary
+  netgreener analyze ./app --fail-on retry_amplification,external_api_overconsumption
+  netgreener analyze ./app --fail-on any --max-at-or-above 5
+  netgreener analyze ./app --paths src/server.ts --findings-only
+  netgreener-analyze ./app --manifest-only
+
+CI tip: pair --json-summary with --fail-on for gate annotations without upload.
+`;
+}
+export function formatStubHelp(command) {
+    if (command === 'optimize') {
+        return `netgreener optimize: not implemented yet in the Node CLI scaffold.
+
+This is an intentional stub (MP4 / N5), not a silent no-op:
+  • exit code 2 when invoked as a command
+  • no upload, no LLM call, no patch apply, no tree writes
+  • no api_server /optimize/* wiring
+
+Until a real JS/TS OptimizerProvider + VerificationProvider land behind the
+shared MP4 interfaces, use local Analyze only:
+
+  netgreener analyze <projectDir>
+  netgreener analyze <projectDir> --fail-on any --json-summary
+  netgreener help analyze
+
+Boundary doc: OPTIMIZE_STUB.md (in the @netgreener/runtime package root).
+`;
+    }
+    return `netgreener ${command}: not implemented yet in the Node CLI scaffold.
+
+No upload is performed. Use local Analyze instead:
+
+  netgreener analyze <projectDir>
+  netgreener help analyze
+`;
+}

package/dist/cli/netgreener.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * NetGreener Node CLI entry (scaffold).
+ *
+ *   netgreener analyze <dir>     — resource Analyze candidates (implemented)
+ *   netgreener run …             — stub (not implemented; no upload)
+ *   netgreener optimize …        — stub (not implemented; no upload)
+ *
+ * Does not change RunSession / metering pipelines. Upload remains off.
+ */
+/** Dispatch top-level ``netgreener`` commands. */
+export declare function runNetgreenerCli(argv: string[]): number;

package/dist/cli/netgreener.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * NetGreener Node CLI entry (scaffold).
+ *
+ *   netgreener analyze <dir>     — resource Analyze candidates (implemented)
+ *   netgreener run …             — stub (not implemented; no upload)
+ *   netgreener optimize …        — stub (not implemented; no upload)
+ *
+ * Does not change RunSession / metering pipelines. Upload remains off.
+ */
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { runAnalyzeCli } from '../analyze/cli.js';
+import { CLI_VERSION, formatAnalyzeHelp, formatRootHelp, formatStubHelp, } from './helpText.js';
+function stubCommand(name) {
+    process.stderr.write(formatStubHelp(name));
+    return 2;
+}
+function printHelpFor(topic) {
+    const key = (topic || '').trim().toLowerCase();
+    if (!key || key === 'help') {
+        process.stdout.write(formatRootHelp());
+        return 0;
+    }
+    if (key === 'analyze') {
+        process.stdout.write(formatAnalyzeHelp());
+        return 0;
+    }
+    if (key === 'run' || key === 'optimize') {
+        process.stderr.write(formatStubHelp(key));
+        return 0;
+    }
+    process.stderr.write(`Unknown help topic: ${topic}\n\n`);
+    process.stdout.write(formatRootHelp());
+    return 2;
+}
+/** Dispatch top-level ``netgreener`` commands. */
+export function runNetgreenerCli(argv) {
+    const [cmd, ...rest] = argv;
+    if (!cmd || cmd === '-h' || cmd === '--help') {
+        process.stdout.write(formatRootHelp());
+        return 0;
+    }
+    if (cmd === '-V' || cmd === '--version' || cmd === 'version') {
+        process.stdout.write(`${CLI_VERSION}\n`);
+        return 0;
+    }
+    if (cmd === 'help') {
+        return printHelpFor(rest[0]);
+    }
+    if (cmd === 'analyze') {
+        return runAnalyzeCli(rest);
+    }
+    if (cmd === 'run' || cmd === 'optimize') {
+        return stubCommand(cmd);
+    }
+    process.stderr.write(`Unknown command: ${cmd}\n\n`);
+    process.stdout.write(formatRootHelp());
+    return 2;
+}
+const invokedDirectly = typeof process.argv[1] === 'string' &&
+    pathToFileURL(resolve(process.argv[1])).href === import.meta.url;
+if (invokedDirectly) {
+    process.exitCode = runNetgreenerCli(process.argv.slice(2));
+}

package/dist/collectorIpc.d.ts

@@ -0,0 +1,28 @@
+/**
+ * NetGreener collector IPC client (MP2).
+ *
+ * Wire-compatible with Python ``collector_protocol``:
+ * 4-byte big-endian length + UTF-8 JSON object, max 256 KiB.
+ * Endpoint schemes: ``tcp://host:port`` (Windows/Linux) or ``unix:///abs/path`` (non-Windows).
+ */
+import { type Socket } from 'node:net';
+export declare const COLLECTOR_MAX_FRAME_BYTES: number;
+export type CollectorIpcAck = {
+    ok: boolean;
+    event_id?: string;
+    status?: string;
+    error?: string;
+};
+export declare class CollectorIpcError extends Error {
+    constructor(message: string);
+}
+export declare function normalizeCollectorEndpoint(endpoint: string): string;
+export declare function encodeCollectorFrame(payload: Record<string, unknown>): Buffer;
+export declare function recvCollectorFrame(socket: Socket): Promise<Record<string, unknown>>;
+export type SendCollectorEventOptions = {
+    endpoint: string;
+    payload: Record<string, unknown>;
+    timeoutMs?: number;
+};
+export declare function sendCollectorEvent(options: SendCollectorEventOptions): Promise<CollectorIpcAck>;
+export declare function newCollectorEventId(): string;

package/dist/collectorIpc.js

@@ -0,0 +1,189 @@
+/**
+ * NetGreener collector IPC client (MP2).
+ *
+ * Wire-compatible with Python ``collector_protocol``:
+ * 4-byte big-endian length + UTF-8 JSON object, max 256 KiB.
+ * Endpoint schemes: ``tcp://host:port`` (Windows/Linux) or ``unix:///abs/path`` (non-Windows).
+ */
+import { createConnection } from 'node:net';
+import { randomUUID } from 'node:crypto';
+import { URL } from 'node:url';
+export const COLLECTOR_MAX_FRAME_BYTES = 256 * 1024;
+export class CollectorIpcError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CollectorIpcError';
+    }
+}
+export function normalizeCollectorEndpoint(endpoint) {
+    const raw = endpoint.trim();
+    if (!raw)
+        throw new CollectorIpcError('collector endpoint is empty');
+    if (/^(tcp|unix):\/\//i.test(raw))
+        return raw;
+    // Allow host:port convenience form used in some local notes.
+    if (/^[^/]+:\d+$/.test(raw))
+        return `tcp://${raw}`;
+    throw new CollectorIpcError('Collector endpoint must use tcp:// or unix://');
+}
+export function encodeCollectorFrame(payload) {
+    const body = Buffer.from(JSON.stringify(payload), 'utf8');
+    if (body.length < 1 || body.length > COLLECTOR_MAX_FRAME_BYTES) {
+        throw new CollectorIpcError(`Collector frame must be 1..${COLLECTOR_MAX_FRAME_BYTES} bytes`);
+    }
+    const header = Buffer.alloc(4);
+    header.writeUInt32BE(body.length, 0);
+    return Buffer.concat([header, body]);
+}
+async function readExact(socket, size) {
+    if (size === 0)
+        return Buffer.alloc(0);
+    // Paused-mode reads on an exclusively owned ACK socket.
+    // Resolve readable/close wakes on setImmediate so a sync 'readable'
+    // re-entry cannot microtask-spin and starve response timers (Windows).
+    socket.pause();
+    const chunks = [];
+    let received = 0;
+    while (received < size) {
+        const chunk = socket.read(size - received);
+        if (chunk !== null && chunk.length > 0) {
+            chunks.push(chunk);
+            received += chunk.length;
+            continue;
+        }
+        if (socket.readableEnded || socket.destroyed) {
+            throw new CollectorIpcError('Collector peer closed the connection mid-frame');
+        }
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                socket.off('readable', onReadable);
+                socket.off('end', onClosed);
+                socket.off('close', onClosed);
+                socket.off('error', onError);
+                setImmediate(fn);
+            };
+            const onReadable = () => finish(() => resolve());
+            const onClosed = () => finish(() => reject(new CollectorIpcError('Collector peer closed the connection mid-frame')));
+            const onError = (err) => finish(() => reject(err));
+            socket.once('readable', onReadable);
+            socket.once('end', onClosed);
+            socket.once('close', onClosed);
+            socket.once('error', onError);
+            if (socket.readableEnded || socket.destroyed) {
+                onClosed();
+                return;
+            }
+            if (socket.readableLength > 0) {
+                onReadable();
+            }
+        });
+    }
+    return Buffer.concat(chunks);
+}
+export async function recvCollectorFrame(socket) {
+    const header = await readExact(socket, 4);
+    const length = header.readUInt32BE(0);
+    if (length < 1 || length > COLLECTOR_MAX_FRAME_BYTES) {
+        throw new CollectorIpcError(`Collector frame must be 1..${COLLECTOR_MAX_FRAME_BYTES} bytes`);
+    }
+    const body = await readExact(socket, length);
+    let parsed;
+    try {
+        parsed = JSON.parse(body.toString('utf8'));
+    }
+    catch {
+        throw new CollectorIpcError('Collector frame contains invalid JSON');
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new CollectorIpcError('Collector frame must contain a JSON object');
+    }
+    return parsed;
+}
+function connectCollector(endpoint, timeoutMs) {
+    const normalized = normalizeCollectorEndpoint(endpoint);
+    return new Promise((resolve, reject) => {
+        const url = new URL(normalized);
+        let socket;
+        const onError = (err) => {
+            socket.destroy();
+            reject(err);
+        };
+        if (url.protocol === 'tcp:') {
+            const host = url.hostname;
+            const port = Number(url.port);
+            if (!host || !Number.isFinite(port) || port <= 0) {
+                reject(new CollectorIpcError('TCP collector endpoint must include host and port'));
+                return;
+            }
+            socket = createConnection({ host, port });
+        }
+        else if (url.protocol === 'unix:') {
+            if (process.platform === 'win32') {
+                reject(new CollectorIpcError('Unix collector endpoints are unavailable on Windows'));
+                return;
+            }
+            const path = url.pathname;
+            if (!path || !path.startsWith('/')) {
+                reject(new CollectorIpcError('Unix collector endpoint must use an absolute path'));
+                return;
+            }
+            socket = createConnection({ path });
+        }
+        else {
+            reject(new CollectorIpcError('Collector endpoint must use tcp:// or unix://'));
+            return;
+        }
+        socket.setTimeout(timeoutMs);
+        socket.once('connect', () => {
+            socket.setTimeout(0);
+            socket.off('error', onError);
+            resolve(socket);
+        });
+        socket.once('timeout', () => {
+            socket.destroy();
+            reject(new CollectorIpcError('Collector connection timed out'));
+        });
+        socket.once('error', onError);
+    });
+}
+export async function sendCollectorEvent(options) {
+    const timeoutMs = Math.max(1, options.timeoutMs ?? 100);
+    const socket = await connectCollector(options.endpoint, timeoutMs);
+    try {
+        const frame = encodeCollectorFrame(options.payload);
+        await new Promise((resolve, reject) => {
+            socket.write(frame, (err) => (err ? reject(err) : resolve()));
+        });
+        const ack = await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                socket.destroy();
+                reject(new CollectorIpcError('Collector response timed out'));
+            }, timeoutMs);
+            recvCollectorFrame(socket)
+                .then((frame) => {
+                clearTimeout(timer);
+                resolve(frame);
+            })
+                .catch((err) => {
+                clearTimeout(timer);
+                reject(err);
+            });
+        });
+        return {
+            ok: ack.ok === true,
+            event_id: typeof ack.event_id === 'string' ? ack.event_id : undefined,
+            status: typeof ack.status === 'string' ? ack.status : undefined,
+            error: typeof ack.error === 'string' ? ack.error : undefined,
+        };
+    }
+    finally {
+        socket.destroy();
+    }
+}
+export function newCollectorEventId() {
+    return randomUUID();
+}