@crouter/api 0.3.387 → 0.3.389

package/dist/core/env-name.d.ts

@@ -0,0 +1,6 @@
+export interface EnvNameValidation {
+    isValid: boolean;
+    errors: string[];
+}
+/** Validate an environment variable identifier without reading its value. */
+export declare function validateEnvVarName(name: unknown): EnvNameValidation;

package/dist/core/env-name.js

@@ -0,0 +1,9 @@
+/** Validate an environment variable identifier without reading its value. */
+export function validateEnvVarName(name) {
+    const errors = [];
+    if (typeof name !== 'string')
+        errors.push('env var name must be a string');
+    else if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+        errors.push('env var name must start with letter/underscore, followed by alphanumeric/underscore');
+    return { isValid: errors.length === 0, errors };
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,38 @@
+import { type ExitCodeValue } from '../types.js';
+export declare class CrtrError extends Error {
+    code: string;
+    exitCode: ExitCodeValue;
+    details?: Record<string, unknown>;
+    constructor(code: string, message: string, exitCode?: ExitCodeValue, details?: Record<string, unknown>);
+}
+export declare function notFound(message: string, details?: Record<string, unknown>): CrtrError;
+export declare function usage(message: string, details?: Record<string, unknown>): CrtrError;
+export declare function ambiguous(message: string, details?: Record<string, unknown>): CrtrError;
+export declare function network(message: string, details?: Record<string, unknown>): CrtrError;
+export declare function general(message: string, details?: Record<string, unknown>): CrtrError;
+/** A node's broker ENGINE failed to launch or bind its view socket — an
+ *  operational failure surfaced from deep in the spawn/revive path (e.g. the
+ *  front-door root create). It is NOT a bad request and NOT an internal crtr
+ *  bug: it carries a curated cause the caller needs, so it must never collapse
+ *  into a bare `internal` 500 with the message stripped.
+ *
+ *  The `details` deliberately carry the FULL `{error, message, next}` payload so
+ *  a server-thrown instance round-trips through crtrd verbatim: `toErrorBody`
+ *  surfaces it as a <500 body with structured details, and the client's
+ *  `apiErrorToCliError` (tier 2) reconstructs the exact code, message, and
+ *  actionable `next` instead of degrading to a generic `invalid_request`. */
+export declare function brokerLaunchFailed(message: string, next: string): CrtrError;
+export declare function nodeCreateRefused(message: string, next: string): CrtrError;
+/** Refuse, inside an app's sandboxed node, something only the person's own
+ *  terminal can reach (their stores, settings, or remote canvas targets) with
+ *  the daemon-operations `owner_only` refusal instead of an internal error
+ *  from touching storage the sandbox does not mount. */
+export declare function ownerOnly(reason: string, next: string): CrtrError;
+/** Refuse a CLI capability that was omitted from this run's allow-list with
+ *  the daemon-operations `scope_missing` refusal naming the missing string.
+ *  `scope` is an identity scope string (`crtr:act`); a bare capability name
+ *  (`act`) is read as `crtr:<name>` so it can never reach `covers()` unparsed. */
+export declare function requireScope(scope: string, command: string): void;
+/** Thrown by stub handlers for leaves not yet wired in P3+.
+ *  code='not_implemented', exitCode=GENERAL, next names the node. */
+export declare function notImplemented(node: string): CrtrError;

package/dist/core/errors.js

@@ -0,0 +1,90 @@
+import { ExitCode } from '../types.js';
+import { envScopes, scopeAllowed } from '../shared/env.js';
+export class CrtrError extends Error {
+    code;
+    exitCode;
+    details;
+    constructor(code, message, exitCode = ExitCode.GENERAL, details) {
+        super(message);
+        this.name = 'CrtrError';
+        this.code = code;
+        this.exitCode = exitCode;
+        this.details = details;
+    }
+}
+export function notFound(message, details) {
+    return new CrtrError('not_found', message, ExitCode.NOT_FOUND, details);
+}
+export function usage(message, details) {
+    return new CrtrError('usage', message, ExitCode.USAGE, details);
+}
+export function ambiguous(message, details) {
+    return new CrtrError('ambiguous', message, ExitCode.AMBIGUOUS, details);
+}
+export function network(message, details) {
+    return new CrtrError('network', message, ExitCode.NETWORK, details);
+}
+export function general(message, details) {
+    return new CrtrError('error', message, ExitCode.GENERAL, details);
+}
+/** A node's broker ENGINE failed to launch or bind its view socket — an
+ *  operational failure surfaced from deep in the spawn/revive path (e.g. the
+ *  front-door root create). It is NOT a bad request and NOT an internal crtr
+ *  bug: it carries a curated cause the caller needs, so it must never collapse
+ *  into a bare `internal` 500 with the message stripped.
+ *
+ *  The `details` deliberately carry the FULL `{error, message, next}` payload so
+ *  a server-thrown instance round-trips through crtrd verbatim: `toErrorBody`
+ *  surfaces it as a <500 body with structured details, and the client's
+ *  `apiErrorToCliError` (tier 2) reconstructs the exact code, message, and
+ *  actionable `next` instead of degrading to a generic `invalid_request`. */
+export function brokerLaunchFailed(message, next) {
+    const code = 'broker_launch_failed';
+    return new CrtrError(code, message, ExitCode.GENERAL, { error: code, message, next });
+}
+export function nodeCreateRefused(message, next) {
+    const code = 'node_create_refused';
+    return new CrtrError(code, message, ExitCode.GENERAL, { error: code, message, next });
+}
+/** Refuse, inside an app's sandboxed node, something only the person's own
+ *  terminal can reach (their stores, settings, or remote canvas targets) with
+ *  the daemon-operations `owner_only` refusal instead of an internal error
+ *  from touching storage the sandbox does not mount. */
+export function ownerOnly(reason, next) {
+    const code = 'owner_only';
+    const message = `${reason}; only the person's terminal can.`;
+    return new CrtrError(code, message, ExitCode.USAGE, { error: code, message, next });
+}
+/** Refuse a CLI capability that was omitted from this run's allow-list with
+ *  the daemon-operations `scope_missing` refusal naming the missing string.
+ *  `scope` is an identity scope string (`crtr:act`); a bare capability name
+ *  (`act`) is read as `crtr:<name>` so it can never reach `covers()` unparsed. */
+export function requireScope(scope, command) {
+    const required = scope.startsWith('crtr:') ? scope : `crtr:${scope}`;
+    const scopes = envScopes();
+    // A held entry that is not a parseable scope string covers nothing; it must
+    // not hide a valid entry later in the list.
+    const allowed = scopes === null || scopes === undefined || scopes.some((held) => {
+        try {
+            return scopeAllowed([held], required);
+        }
+        catch {
+            return false;
+        }
+    });
+    if (allowed)
+        return;
+    const code = 'scope_missing';
+    const message = `missing scope ${required}: this run was not launched with it, so \`${command}\` is not available.`;
+    throw new CrtrError(code, message, ExitCode.GENERAL, {
+        error: code,
+        message,
+        scope: required,
+        next: 'This capability was not granted to the run. Do not retry it — proceed without it and say so in your result.',
+    });
+}
+/** Thrown by stub handlers for leaves not yet wired in P3+.
+ *  code='not_implemented', exitCode=GENERAL, next names the node. */
+export function notImplemented(node) {
+    return new CrtrError('not_implemented', `${node} is not yet implemented.`, ExitCode.GENERAL, { next: 'This leaf is not yet wired.' });
+}

package/dist/core/events/emit.d.ts

@@ -0,0 +1,6 @@
+import type { BuildEnvelopeInput } from './types.js';
+export type EmitEventInput = Omit<BuildEnvelopeInput, 'component' | 'stream_id'>;
+/** Resolves after every broker event emitted so far has been appended or written to stderr. */
+export declare function flushBrokerLog(): Promise<void>;
+/** The only canonical write path. The bound source owns the destination component/path/stream; node_id identifies the event target, with a broker source enforcing its bound node. */
+export declare function emitEvent(input: EmitEventInput): boolean;

package/dist/core/events/emit.js

@@ -0,0 +1,42 @@
+import { appendBufferedDaemonRecord, appendRotatingRecord } from '../log.js';
+import { buildEnvelope } from './envelope.js';
+import { serializeEventRecord } from './serialize.js';
+import { eventSource } from './source.js';
+import { envExecutionId } from '../../shared/env.js';
+import { appendBrokerLog } from '../runtime/broker/daemon-ops.js';
+// A launched broker cannot open its node's records, so its events append through
+// the daemon in emit order. A record the daemon did not append goes to stderr,
+// which the daemon-opened broker.log fd captures.
+let brokerLogTail = Promise.resolve();
+/** Resolves after every broker event emitted so far has been appended or written to stderr. */
+export function flushBrokerLog() { return brokerLogTail; }
+function queueBrokerRecord(nodeId, record) {
+    brokerLogTail = brokerLogTail.then(async () => {
+        try {
+            const { appended } = await appendBrokerLog(nodeId, record);
+            if (!appended)
+                process.stderr.write(`[broker] log.jsonl refused record: ${record}\n`);
+        }
+        catch (error) {
+            process.stderr.write(`[broker] log.jsonl append failed (${error instanceof Error ? error.message : String(error)}): ${record}\n`);
+        }
+    });
+}
+/** The only canonical write path. The bound source owns the destination component/path/stream; node_id identifies the event target, with a broker source enforcing its bound node. */
+export function emitEvent(input) {
+    const source = eventSource();
+    if (source === undefined)
+        return false;
+    if (source.component === 'broker' && source.node_id !== undefined && input.node_id !== undefined && input.node_id !== source.node_id) {
+        throw new TypeError(`broker event target node_id must match bound node_id; received ${input.node_id}`);
+    }
+    if (input.level === 'debug' && process.env['CRTR_LOG'] !== 'debug')
+        return false;
+    const envelope = buildEnvelope({ ...input, component: source.component, ...(source.node_id === undefined ? {} : { node_id: source.node_id }), ...(source.stream_id === undefined ? {} : { stream_id: source.stream_id }) });
+    const record = serializeEventRecord(envelope);
+    if (source.component === 'broker' && source.node_id !== undefined && envExecutionId() !== undefined) {
+        queueBrokerRecord(source.node_id, record);
+        return true;
+    }
+    return source.component === 'daemon' ? appendBufferedDaemonRecord(source.path, record) : appendRotatingRecord(source.path, record);
+}

package/dist/core/events/envelope.d.ts

@@ -0,0 +1,2 @@
+import type { BuildEnvelopeInput, EventEnvelope } from './types.js';
+export declare function buildEnvelope(input: BuildEnvelopeInput): EventEnvelope;

package/dist/core/events/envelope.js

@@ -0,0 +1,84 @@
+import { errorClassCodes, eventErrorFromUnknown } from './errors.js';
+import { generateOperationId, operationIdContext, validateOperationId } from './operation-id.js';
+const eventName = /^[a-z][a-z0-9]*(?:[._][a-z0-9]+)*$/;
+const levels = new Set(['error', 'warn', 'info', 'debug']);
+const components = new Set(['daemon', 'broker', 'control-plane', 'front', 'sentinel']);
+const outcomes = new Set(['succeeded', 'failed', 'skipped']);
+const dispositions = new Set(['auto', 'manual', 'fatal']);
+const classes = new Set(errorClassCodes);
+function bytes(value) { return Buffer.byteLength(value, 'utf8'); }
+function requireString(value, name, cap = 128) {
+    if (typeof value !== 'string' || value === '' || bytes(value) > cap)
+        throw new TypeError(`${name} must be a non-empty string of at most ${cap} UTF-8 bytes`);
+    return value;
+}
+function normalizedTimestamp(value) {
+    if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T/.test(value))
+        throw new TypeError('ts must be an ISO 8601 timestamp');
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        throw new TypeError('ts must be an ISO 8601 timestamp');
+    return date.toISOString();
+}
+function checkedErrorClass(value) {
+    if (!classes.has(value.class))
+        throw new TypeError('error_class.class is invalid');
+    const result = { class: value.class };
+    if (value.status !== undefined) {
+        if (!Number.isInteger(value.status))
+            throw new TypeError('error_class.status must be an integer');
+        result.status = value.status;
+    }
+    if (value.provider !== undefined)
+        result.provider = requireString(value.provider, 'error_class.provider');
+    if (value.retry_disposition !== undefined) {
+        if (!dispositions.has(value.retry_disposition))
+            throw new TypeError('error_class.retry_disposition is invalid');
+        result.retry_disposition = value.retry_disposition;
+    }
+    return result;
+}
+export function buildEnvelope(input) {
+    if (!levels.has(input.level))
+        throw new TypeError('level is invalid');
+    if (!components.has(input.component))
+        throw new TypeError('component is invalid');
+    const event = requireString(input.event, 'event');
+    if (!eventName.test(event))
+        throw new TypeError('event must be a lowercase dotted identifier');
+    const operationId = input.operation_id === undefined ? operationIdContext.current() ?? generateOperationId() : validateOperationId(input.operation_id);
+    const result = {
+        v: 1,
+        ts: input.ts === undefined ? new Date().toISOString() : normalizedTimestamp(input.ts),
+        level: input.level,
+        event,
+        component: input.component,
+        operation_id: operationId,
+    };
+    if (input.node_id !== undefined)
+        result.node_id = requireString(input.node_id, 'node_id');
+    if (input.stream_id !== undefined)
+        result.stream_id = requireString(input.stream_id, 'stream_id');
+    if (input.duration_ms !== undefined) {
+        if (!Number.isFinite(input.duration_ms) || input.duration_ms < 0)
+            throw new TypeError('duration_ms must be finite and non-negative');
+        result.duration_ms = input.duration_ms;
+    }
+    if (input.outcome !== undefined) {
+        if (!outcomes.has(input.outcome))
+            throw new TypeError('outcome is invalid');
+        result.outcome = input.outcome;
+    }
+    if (input.attempt !== undefined) {
+        if (!Number.isInteger(input.attempt) || input.attempt <= 0)
+            throw new TypeError('attempt must be a positive integer');
+        result.attempt = input.attempt;
+    }
+    if (input.error_class !== undefined)
+        result.error_class = checkedErrorClass(input.error_class);
+    if (input.error !== undefined)
+        result.error = eventErrorFromUnknown(input.error);
+    if (input.fields !== undefined)
+        result.fields = input.fields;
+    return result;
+}

package/dist/core/events/errors.d.ts

@@ -0,0 +1,4 @@
+import { errorClassCodes, type ErrorClass, type ErrorClassHints, type EventError } from './types.js';
+export declare function errorClassFromError(error: unknown, hints?: ErrorClassHints): ErrorClass;
+export declare function eventErrorFromUnknown(error: unknown): EventError;
+export { errorClassCodes };

package/dist/core/events/errors.js

@@ -0,0 +1,69 @@
+import { errorClassCodes } from './types.js';
+const retryDispositions = new Set(['auto', 'manual', 'fatal']);
+function record(value) {
+    return typeof value === 'object' && value !== null ? value : undefined;
+}
+function text(value) {
+    return typeof value === 'string' ? value : '';
+}
+function statusFrom(error) {
+    const value = record(error)?.['status'];
+    return typeof value === 'number' && Number.isInteger(value) ? value : undefined;
+}
+function codeFrom(error) {
+    const value = record(error);
+    return text(value?.['code']) || text(value?.['errno']);
+}
+function messageFrom(error) {
+    if (typeof error === 'string')
+        return error;
+    if (error instanceof Error)
+        return error.message;
+    const value = record(error);
+    return text(value?.['message']) || text(value?.['statusText']) || text(value?.['reason']);
+}
+function classify(status, code, message) {
+    if (status === 429 || /rate.?limit|too many requests|quota/i.test(message))
+        return 'rate_limit';
+    if (status === 401 || status === 403 || /invalid_grant|refresh token|unauthori[sz]ed|invalid.?api.?key|authentication failed/i.test(message))
+        return 'auth';
+    if (/context overflow/i.test(message))
+        return 'context_overflow';
+    if (/model.{0,40}(not found|does not exist|not available)|not_found_error/i.test(message))
+        return 'model_not_found';
+    if (/wedged/i.test(message))
+        return 'wedged';
+    if (/^(ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOENT|ENOTFOUND|EAI_AGAIN|EPIPE|EHOSTUNREACH|ENETUNREACH)$/i.test(code) || /connection|econnreset|etimedout|enotfound|network|fetch failed|socket hang|timed? out|websocket.*(?:closed|error)/i.test(message))
+        return 'connection';
+    if ((status !== undefined && status >= 500) || /overloaded|capacity|server.{0,3}busy|temporarily unavailable|internal server error/i.test(message))
+        return 'overloaded';
+    if ((status !== undefined && status >= 400) || /protocol|invalid (?:frame|payload)|policy violation/i.test(message))
+        return 'protocol';
+    return 'unknown';
+}
+export function errorClassFromError(error, hints = {}) {
+    const status = hints.status ?? statusFrom(error);
+    const result = { class: classify(status, codeFrom(error), messageFrom(error)) };
+    if (status !== undefined)
+        result.status = status;
+    if (typeof hints.provider === 'string' && hints.provider !== '')
+        result.provider = hints.provider;
+    if (hints.retry_disposition !== undefined && retryDispositions.has(hints.retry_disposition))
+        result.retry_disposition = hints.retry_disposition;
+    return result;
+}
+export function eventErrorFromUnknown(error) {
+    if (error instanceof Error) {
+        const result = { type: error.name || 'Error', message: error.message };
+        if (typeof error.stack === 'string')
+            result.stack = error.stack;
+        if (error.cause !== undefined)
+            result.cause = error.cause instanceof Error ? error.cause.message : String(error.cause);
+        return result;
+    }
+    if (typeof error === 'string')
+        return { type: 'Error', message: error };
+    const value = record(error);
+    return { type: text(value?.['name']) || 'Error', message: text(value?.['message']) || String(error) };
+}
+export { errorClassCodes };

package/dist/core/events/operation-id.d.ts

@@ -0,0 +1,4 @@
+import type { OperationId, OperationIdContext } from './types.js';
+export declare function validateOperationId(value: unknown): OperationId;
+export declare function generateOperationId(): OperationId;
+export declare const operationIdContext: OperationIdContext;

package/dist/core/events/operation-id.js

@@ -0,0 +1,24 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomBytes } from 'node:crypto';
+const OPERATION_ID = /^(?!0{32}$)[0-9a-f]{32}$/;
+const storage = new AsyncLocalStorage();
+export function validateOperationId(value) {
+    if (typeof value !== 'string' || !OPERATION_ID.test(value))
+        throw new TypeError('operation_id must be 32 lowercase non-zero hexadecimal characters');
+    return value;
+}
+export function generateOperationId() {
+    let value;
+    do
+        value = randomBytes(16).toString('hex');
+    while (value === '00000000000000000000000000000000');
+    return validateOperationId(value);
+}
+export const operationIdContext = {
+    current: () => storage.getStore(),
+    run: (operationId, callback) => storage.run(validateOperationId(operationId), callback),
+    fresh: (callback) => {
+        const operationId = generateOperationId();
+        return storage.run(operationId, () => callback(operationId));
+    },
+};

package/dist/core/events/serialize.d.ts

@@ -0,0 +1,4 @@
+import type { EventEnvelope } from './types.js';
+export declare const MAX_EVENT_RECORD_BYTES = 65536;
+/** Serializes a bounded NDJSON record without its newline; appendRotatingRecord owns that byte. */
+export declare function serializeEventRecord(envelope: EventEnvelope): string;

package/dist/core/events/serialize.js

@@ -0,0 +1,199 @@
+export const MAX_EVENT_RECORD_BYTES = 65_536;
+const MAX_STRING_BYTES = 4_096;
+const MAX_KEY_BYTES = 128;
+const MAX_ERROR_STACK_BYTES = 16_384;
+const MAX_DEPTH = 4;
+const MAX_MEMBERS = 64;
+// Bounds total normalize() work regardless of graph shape: MAX_DEPTH/MAX_MEMBERS
+// alone permit a tiny SHARED-reference graph (no cycle, so the WeakSet guard
+// never fires) to fan out combinatorially — e.g. four levels of 64 shared
+// children reach 64^4 visits. This budget caps total node visits so one event
+// cannot stall or exhaust its process regardless of how references are shared.
+const MAX_NORMALIZE_UNITS = 5_000;
+function byteLength(value) { return Buffer.byteLength(value, 'utf8'); }
+function truncate(value, cap) {
+    if (byteLength(value) <= cap)
+        return { value, altered: false };
+    const suffix = '…';
+    const target = cap - byteLength(suffix);
+    let used = 0;
+    let result = '';
+    for (const character of value) {
+        const size = byteLength(character);
+        if (used + size > target)
+            break;
+        result += character;
+        used += size;
+    }
+    return { value: result + suffix, altered: true };
+}
+function unsupported(value) {
+    if (value === undefined)
+        return '[Unsupported undefined]';
+    if (typeof value === 'function')
+        return `[Unsupported function${value.name ? ` ${value.name}` : ''}]`;
+    if (typeof value === 'symbol')
+        return `[Unsupported ${String(value)}]`;
+    return `[Unsupported ${value?.constructor?.name ?? typeof value}]`;
+}
+function normalize(value, depth, active, budget) {
+    if (budget.remaining <= 0)
+        return { value: '[Omitted]', altered: true, dropped: 0 };
+    budget.remaining -= 1;
+    if (value === null || typeof value === 'boolean')
+        return { value, altered: false, dropped: 0 };
+    if (typeof value === 'string') {
+        const limited = truncate(value, MAX_STRING_BYTES);
+        return { value: limited.value, altered: limited.altered, dropped: 0 };
+    }
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? { value, altered: false, dropped: 0 } : { value: String(value), altered: true, dropped: 0 };
+    if (typeof value === 'bigint')
+        return { value: value.toString(), altered: true, dropped: 0 };
+    if (value instanceof Date) {
+        const rendered = Number.isNaN(value.getTime()) ? 'Invalid Date' : value.toISOString();
+        return { value: rendered, altered: true, dropped: 0 };
+    }
+    if (typeof value !== 'object' || value === undefined)
+        return { value: unsupported(value), altered: true, dropped: 0 };
+    if (active.has(value))
+        return { value: '[Circular]', altered: true, dropped: 0 };
+    if (depth >= MAX_DEPTH)
+        return { value: '[Max depth]', altered: true, dropped: 0 };
+    active.add(value);
+    try {
+        if (Array.isArray(value)) {
+            const count = Math.min(value.length, MAX_MEMBERS);
+            const items = [];
+            let altered = value.length > count;
+            let dropped = value.length - count;
+            for (let index = 0; index < count; index += 1) {
+                if (budget.remaining <= 0) {
+                    altered = true;
+                    dropped += count - index;
+                    break;
+                }
+                const item = normalize(value[index], depth + 1, active, budget);
+                items.push(item.value);
+                altered ||= item.altered;
+                dropped += item.dropped;
+            }
+            return { value: items, altered, dropped };
+        }
+        let keys;
+        try {
+            keys = Object.keys(value).sort();
+        }
+        catch {
+            return { value: '[Unsupported object]', altered: true, dropped: 0 };
+        }
+        const selected = keys.slice(0, MAX_MEMBERS);
+        const output = {};
+        let altered = keys.length > selected.length;
+        let dropped = keys.length - selected.length;
+        for (let index = 0; index < selected.length; index += 1) {
+            const key = selected[index];
+            if (budget.remaining <= 0) {
+                altered = true;
+                dropped += selected.length - index;
+                break;
+            }
+            const limitedKey = truncate(key, MAX_KEY_BYTES);
+            let child;
+            try {
+                child = normalize(value[key], depth + 1, active, budget);
+            }
+            catch {
+                child = { value: '[Unsupported property]', altered: true, dropped: 0 };
+            }
+            // Two distinct original keys can truncate to the same bounded key (e.g. two
+            // 200-byte keys sharing their first 127 bytes). Silently overwriting would
+            // under-report the omission; count the collision as dropped instead.
+            if (Object.prototype.hasOwnProperty.call(output, limitedKey.value)) {
+                altered = true;
+                dropped += 1;
+                continue;
+            }
+            output[limitedKey.value] = child.value;
+            altered ||= limitedKey.altered || child.altered;
+            dropped += child.dropped;
+        }
+        return { value: output, altered, dropped };
+    }
+    finally {
+        active.delete(value);
+    }
+}
+function normalizeError(error) {
+    const type = truncate(String(error.type), MAX_KEY_BYTES);
+    const message = truncate(String(error.message), MAX_STRING_BYTES);
+    const result = { type: type.value, message: message.value };
+    let altered = type.altered || message.altered;
+    if (error.stack !== undefined) {
+        const stack = truncate(String(error.stack), MAX_ERROR_STACK_BYTES);
+        result.stack = stack.value;
+        altered ||= stack.altered;
+    }
+    if (error.cause !== undefined) {
+        const cause = truncate(String(error.cause), MAX_STRING_BYTES);
+        result.cause = cause.value;
+        altered ||= cause.altered;
+    }
+    return { value: result, altered };
+}
+function encoded(value) { return JSON.stringify(value); }
+function recordBytes(value) { return byteLength(encoded(value)) + 1; }
+/** Serializes a bounded NDJSON record without its newline; appendRotatingRecord owns that byte. */
+export function serializeEventRecord(envelope) {
+    const normalizedFields = envelope.fields === undefined ? undefined : normalize(envelope.fields, 0, new WeakSet(), { remaining: MAX_NORMALIZE_UNITS });
+    const normalizedError = envelope.error === undefined ? undefined : normalizeError(envelope.error);
+    const record = {
+        v: 1,
+        ts: envelope.ts,
+        level: envelope.level,
+        event: envelope.event,
+        component: envelope.component,
+        operation_id: envelope.operation_id,
+        ...(envelope.node_id === undefined ? {} : { node_id: envelope.node_id }),
+        ...(envelope.stream_id === undefined ? {} : { stream_id: envelope.stream_id }),
+        ...(envelope.duration_ms === undefined ? {} : { duration_ms: envelope.duration_ms }),
+        ...(envelope.outcome === undefined ? {} : { outcome: envelope.outcome }),
+        ...(envelope.attempt === undefined ? {} : { attempt: envelope.attempt }),
+        ...(envelope.error_class === undefined ? {} : { error_class: envelope.error_class }),
+        ...(normalizedError === undefined ? {} : { error: normalizedError.value }),
+        ...(normalizedFields === undefined ? {} : { fields: normalizedFields.value }),
+    };
+    const originalBytes = recordBytes(record);
+    const altered = normalizedFields?.altered === true || normalizedError?.altered === true || originalBytes > MAX_EVENT_RECORD_BYTES;
+    let dropped = normalizedFields?.dropped ?? 0;
+    if (altered)
+        Object.assign(record, { record_truncated: true, original_bytes: originalBytes, dropped_fields_count: dropped });
+    while (recordBytes(record) > MAX_EVENT_RECORD_BYTES && record['fields'] !== undefined) {
+        const fields = record['fields'];
+        const keys = Object.keys(fields);
+        if (keys.length === 0) {
+            delete record['fields'];
+            break;
+        }
+        keys.sort((left, right) => {
+            const bySize = byteLength(encoded(fields[right])) - byteLength(encoded(fields[left]));
+            return bySize !== 0 ? bySize : right < left ? -1 : right > left ? 1 : 0;
+        });
+        delete fields[keys[0]];
+        dropped += 1;
+        record.record_truncated = true;
+        record.original_bytes = originalBytes;
+        record.dropped_fields_count = dropped;
+    }
+    const error = record['error'];
+    if (recordBytes(record) > MAX_EVENT_RECORD_BYTES && error?.stack !== undefined)
+        delete error.stack;
+    if (recordBytes(record) > MAX_EVENT_RECORD_BYTES && error?.cause !== undefined)
+        delete error.cause;
+    if (recordBytes(record) > MAX_EVENT_RECORD_BYTES && error !== undefined)
+        error.message = truncate(error.message, 64).value;
+    const result = encoded(record);
+    if (byteLength(result) + 1 > MAX_EVENT_RECORD_BYTES)
+        throw new RangeError('event record cannot fit within 64 KiB');
+    return result;
+}

package/dist/core/events/source.d.ts

@@ -0,0 +1,16 @@
+import type { EventComponent } from './types.js';
+export interface BoundEventSource {
+    component: EventComponent;
+    path: string;
+    node_id?: string;
+    stream_id?: string;
+}
+export declare function bindDaemonEventSource(): void;
+export declare function bindBrokerEventSource(nodeId: string): void;
+export declare function eventSource(): BoundEventSource | undefined;
+/** Test-only: clear the process-global binding. A single test process can
+ * legitimately play several components in sequence (an in-process revive binds
+ * a broker source via host.ts's bind-if-unbound; a later daemon-tick test then
+ * inherits it and trips emit's cross-node guard). Production processes bind
+ * exactly once and never reset. */
+export declare function resetEventSourceForTests(): void;

package/dist/core/events/source.js

@@ -0,0 +1,31 @@
+import { join } from 'node:path';
+import { crtrHome, isSafeNodeId, jobDir } from '../canvas/paths.js';
+let bound;
+function equal(left, right) {
+    return left.component === right.component && left.path === right.path && left.node_id === right.node_id && left.stream_id === right.stream_id;
+}
+function bind(source) {
+    if (bound === undefined) {
+        bound = source;
+        return;
+    }
+    if (!equal(bound, source))
+        throw new Error('event source is already bound for this process');
+}
+export function bindDaemonEventSource() {
+    bind({ component: 'daemon', path: join(crtrHome(), 'crtrd.log') });
+}
+export function bindBrokerEventSource(nodeId) {
+    if (!isSafeNodeId(nodeId))
+        throw new TypeError('node_id must be a non-empty path segment of at most 128 UTF-8 bytes');
+    bind({ component: 'broker', node_id: nodeId, path: join(jobDir(nodeId), 'log.jsonl') });
+}
+export function eventSource() { return bound; }
+/** Test-only: clear the process-global binding. A single test process can
+ * legitimately play several components in sequence (an in-process revive binds
+ * a broker source via host.ts's bind-if-unbound; a later daemon-tick test then
+ * inherits it and trips emit's cross-node guard). Production processes bind
+ * exactly once and never reset. */
+export function resetEventSourceForTests() {
+    bound = undefined;
+}