adispatchd 0.0.0-stage → 0.1.0

package/dist/core/duration.js

@@ -0,0 +1,93 @@
+/**
+ * Parsers for human-friendly durations and sizes used in YAML config
+ * (e.g. `polling_interval: 30s`, `max_log_size_per_run: 100MB`).
+ */
+import { ValidationError } from './errors.js';
+const DURATION_UNITS = {
+    ms: 1,
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+};
+const DURATION_PATTERN = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/;
+/**
+ * Parse a duration string into milliseconds.
+ *
+ * Grammar: `<number><unit>` with unit `ms | s | m | h | d`, e.g. `100ms`, `30s`,
+ * `45m`, `6h`, `30d`, `1.5h`. Surrounding whitespace is ignored. Compound forms
+ * (`1h30m`), negative values, missing units and non-integer millisecond
+ * results are rejected with {@link ValidationError}.
+ */
+export function parseDuration(input) {
+    if (typeof input !== 'string')
+        throw new ValidationError(`Duration must be a string, got ${typeof input}`);
+    const match = DURATION_PATTERN.exec(input.trim());
+    if (!match) {
+        throw new ValidationError(`Invalid duration "${input}" (expected e.g. 100ms, 30s, 45m, 6h, 30d)`, { input });
+    }
+    const value = Number(match[1]);
+    const unit = DURATION_UNITS[match[2]];
+    const ms = value * unit;
+    if (!Number.isFinite(ms) || !Number.isSafeInteger(Math.round(ms)) || Math.abs(ms - Math.round(ms)) > 1e-9) {
+        throw new ValidationError(`Duration "${input}" does not resolve to whole milliseconds`, { input });
+    }
+    return Math.round(ms);
+}
+/** Like {@link parseDuration}, but returns `undefined` instead of throwing. */
+export function tryParseDuration(input) {
+    try {
+        return parseDuration(input);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Format milliseconds with the largest unit that divides it exactly (e.g. `90000` → `90s`). */
+export function formatDuration(ms) {
+    if (!Number.isSafeInteger(ms) || ms < 0)
+        throw new ValidationError(`Cannot format duration ${ms}`);
+    if (ms === 0)
+        return '0s';
+    for (const unit of ['d', 'h', 'm', 's']) {
+        const factor = DURATION_UNITS[unit];
+        if (ms % factor === 0)
+            return `${ms / factor}${unit}`;
+    }
+    return `${ms}ms`;
+}
+/**
+ * Size units. Decimal-looking units (`KB`, `MB`, `GB`) are interpreted as
+ * binary multiples (1 KB = 1024 B), matching common log-size conventions;
+ * `KiB`, `MiB`, `GiB` are accepted as explicit aliases.
+ */
+const SIZE_UNITS = {
+    b: 1,
+    kb: 1024,
+    kib: 1024,
+    mb: 1024 ** 2,
+    mib: 1024 ** 2,
+    gb: 1024 ** 3,
+    gib: 1024 ** 3,
+};
+const SIZE_PATTERN = /^(\d+(?:\.\d+)?)\s*([a-z]+)$/i;
+/**
+ * Parse a size string into bytes: `<number><unit>` with unit
+ * `B | KB | MB | GB | KiB | MiB | GiB` (case-insensitive), e.g. `100MB` →
+ * 104857600. Throws {@link ValidationError} on missing/unknown units.
+ */
+export function parseSize(input) {
+    if (typeof input !== 'string')
+        throw new ValidationError(`Size must be a string, got ${typeof input}`);
+    const match = SIZE_PATTERN.exec(input.trim());
+    const unit = match ? SIZE_UNITS[match[2].toLowerCase()] : undefined;
+    if (!match || unit === undefined) {
+        throw new ValidationError(`Invalid size "${input}" (expected e.g. 512KB, 100MB, 1GB)`, { input });
+    }
+    const bytes = Number(match[1]) * unit;
+    if (!Number.isFinite(bytes) || !Number.isSafeInteger(Math.floor(bytes))) {
+        throw new ValidationError(`Size "${input}" is out of range`, { input });
+    }
+    return Math.floor(bytes);
+}
+//# sourceMappingURL=duration.js.map

package/dist/core/duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.js","sourceRoot":"","sources":["../../src/core/duration.ts"],"names":[],"mappings":"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"}

package/dist/core/errors.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared error classes. Components throw these (or subclasses) so that callers
+ * can react on a stable `code` instead of parsing messages. Messages must
+ * never contain secrets (Spec §20.4).
+ */
+/** Base class for all expected orchestrator errors. */
+export declare class OrchestratorError extends Error {
+    /** Stable machine-readable code, e.g. `template_unknown_placeholder`. */
+    readonly code: string;
+    /** Optional JSON-serialisable diagnostic details (no secrets). */
+    readonly details: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+        details?: Record<string, unknown>;
+    });
+}
+/** Invalid input to a pure helper (duration, size, id, ...). */
+export declare class ValidationError extends OrchestratorError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/** A path would escape its permitted base directory or is otherwise unsafe. */
+export declare class PathTraversalError extends OrchestratorError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Classification of failures talking to an external source.
+ * - `auth`: credentials invalid/expired
+ * - `forbidden`: authenticated but not permitted (fail-closed, Spec §20.7)
+ * - `not_found`: item/resource does not exist (or is invisible)
+ * - `rate_limited`: retry after `retryAfterMs`
+ * - `transient`: network/5xx; retrying may help
+ * - `invalid`: request rejected as invalid (4xx other than above)
+ */
+export type SourceErrorKind = 'auth' | 'forbidden' | 'not_found' | 'rate_limited' | 'transient' | 'invalid';
+/** Error raised by {@link SourceAdapter} / {@link CredentialProvider} implementations. */
+export declare class SourceError extends OrchestratorError {
+    readonly kind: SourceErrorKind;
+    /** Whether repeating the same call may succeed. */
+    readonly retryable: boolean;
+    /**
+     * True when a mutating call may have taken effect although it failed
+     * (e.g. timeout after the request was sent). Lifecycle retries must then
+     * reconcile (e.g. `findCommentByMarker`) instead of blindly repeating (Spec §10).
+     */
+    readonly outcomeUnknown: boolean;
+    /** Suggested wait before retrying, if known. */
+    readonly retryAfterMs: number | undefined;
+    /** HTTP status, if the error originated from an HTTP response. */
+    readonly status: number | undefined;
+    constructor(kind: SourceErrorKind, message: string, options?: {
+        cause?: unknown;
+        details?: Record<string, unknown>;
+        retryable?: boolean;
+        outcomeUnknown?: boolean;
+        retryAfterMs?: number;
+        status?: number;
+    });
+}
+/** Narrowing helper for {@link OrchestratorError} with an optional code check. */
+export declare function isOrchestratorError(err: unknown, code?: string): err is OrchestratorError;
+/** Render any thrown value as a short message string (for persisting `error_json`). */
+export declare function errorMessage(err: unknown): string;

package/dist/core/errors.js

@@ -0,0 +1,72 @@
+/**
+ * Shared error classes. Components throw these (or subclasses) so that callers
+ * can react on a stable `code` instead of parsing messages. Messages must
+ * never contain secrets (Spec §20.4).
+ */
+/** Base class for all expected orchestrator errors. */
+export class OrchestratorError extends Error {
+    /** Stable machine-readable code, e.g. `template_unknown_placeholder`. */
+    code;
+    /** Optional JSON-serialisable diagnostic details (no secrets). */
+    details;
+    constructor(code, message, options = {}) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = new.target.name;
+        this.code = code;
+        this.details = options.details;
+    }
+}
+/** Invalid input to a pure helper (duration, size, id, ...). */
+export class ValidationError extends OrchestratorError {
+    constructor(message, details) {
+        super('validation_error', message, details ? { details } : {});
+    }
+}
+/** A path would escape its permitted base directory or is otherwise unsafe. */
+export class PathTraversalError extends OrchestratorError {
+    constructor(message, details) {
+        super('path_traversal', message, details ? { details } : {});
+    }
+}
+/** Error raised by {@link SourceAdapter} / {@link CredentialProvider} implementations. */
+export class SourceError extends OrchestratorError {
+    kind;
+    /** Whether repeating the same call may succeed. */
+    retryable;
+    /**
+     * True when a mutating call may have taken effect although it failed
+     * (e.g. timeout after the request was sent). Lifecycle retries must then
+     * reconcile (e.g. `findCommentByMarker`) instead of blindly repeating (Spec §10).
+     */
+    outcomeUnknown;
+    /** Suggested wait before retrying, if known. */
+    retryAfterMs;
+    /** HTTP status, if the error originated from an HTTP response. */
+    status;
+    constructor(kind, message, options = {}) {
+        super(`source_${kind}`, message, options);
+        this.kind = kind;
+        this.retryable = options.retryable ?? (kind === 'transient' || kind === 'rate_limited');
+        this.outcomeUnknown = options.outcomeUnknown ?? false;
+        this.retryAfterMs = options.retryAfterMs;
+        this.status = options.status;
+    }
+}
+/** Narrowing helper for {@link OrchestratorError} with an optional code check. */
+export function isOrchestratorError(err, code) {
+    return err instanceof OrchestratorError && (code === undefined || err.code === code);
+}
+/** Render any thrown value as a short message string (for persisting `error_json`). */
+export function errorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === 'string')
+        return err;
+    try {
+        return JSON.stringify(err);
+    }
+    catch {
+        return String(err);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,uDAAuD;AACvD,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,yEAAyE;IAChE,IAAI,CAAS;IACtB,kEAAkE;IACzD,OAAO,CAAsC;IAEtD,YAAY,IAAY,EAAE,OAAe,EAAE,OAAO,GAA2D,EAAE;QAC7G,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IACjC,CAAC;CACF;AAED,gEAAgE;AAChE,MAAM,OAAO,eAAgB,SAAQ,iBAAiB;IACpD,YAAY,OAAe,EAAE,OAAiC;QAC5D,KAAK,CAAC,kBAAkB,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACjE,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,OAAO,kBAAmB,SAAQ,iBAAiB;IACvD,YAAY,OAAe,EAAE,OAAiC;QAC5D,KAAK,CAAC,gBAAgB,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC/D,CAAC;CACF;AAaD,0FAA0F;AAC1F,MAAM,OAAO,WAAY,SAAQ,iBAAiB;IACvC,IAAI,CAAkB;IAC/B,mDAAmD;IAC1C,SAAS,CAAU;IAC5B;;;;OAIG;IACM,cAAc,CAAU;IACjC,gDAAgD;IACvC,YAAY,CAAqB;IAC1C,kEAAkE;IACzD,MAAM,CAAqB;IAEpC,YACE,IAAqB,EACrB,OAAe,EACf,OAAO,GAOH,EAAE;QAEN,KAAK,CAAC,UAAU,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,cAAc,CAAC,CAAC;QACxF,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,KAAK,CAAC;QACtD,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;QACzC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC/B,CAAC;CACF;AAED,kFAAkF;AAClF,MAAM,UAAU,mBAAmB,CAAC,GAAY,EAAE,IAAa;IAC7D,OAAO,GAAG,YAAY,iBAAiB,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AACvF,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,IAAI,GAAG,YAAY,KAAK;QAAE,OAAO,GAAG,CAAC,OAAO,CAAC;IAC7C,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC;IACxC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/core/ids.d.ts

@@ -0,0 +1,57 @@
+import { type Clock } from './clock.js';
+/**
+ * Allowed pattern for IDs declared in YAML (workflow, source, identity, view
+ * IDs): starts with a letter or digit, then letters, digits, `_`, `-`; max 64
+ * characters. Such IDs are safe as path segments and as key prefixes.
+ */
+export declare const CONFIG_ID_PATTERN: RegExp;
+/** True if `id` matches {@link CONFIG_ID_PATTERN}. */
+export declare function isValidConfigId(id: string): boolean;
+/**
+ * Format a timestamp as compact, lexicographically sortable, path-safe UTC
+ * string: `YYYYMMDDTHHMMSSZ` (or with milliseconds `YYYYMMDDTHHMMSSmmmZ`).
+ * Used for `{timestamp}` and in run IDs.
+ */
+export declare function formatCompactTimestamp(date: Date, withMillis?: boolean): string;
+/** Pattern of run IDs produced by {@link createRunId}. */
+export declare const RUN_ID_PATTERN: RegExp;
+/** Options for {@link createRunId}. */
+export interface RunIdOptions {
+    clock?: Clock;
+    /** Source of random bytes (injectable for deterministic tests). */
+    randomBytes?: (size: number) => Uint8Array;
+}
+/**
+ * Create a new run ID: `run-<YYYYMMDDTHHMMSSmmmZ>-<8 hex>`, e.g.
+ * `run-20261016T190000123Z-3fa2c91b`. IDs are unique (32 random bits per
+ * millisecond), sort chronologically as strings, and are safe as path segments
+ * and in URLs.
+ */
+export declare function createRunId(options?: RunIdOptions): string;
+/** True if `id` has the run ID format (see {@link createRunId}). */
+export declare function isValidRunId(id: string): boolean;
+/** Separator between source ID and item ID in a {@link sourceItemKey}. */
+export declare const SOURCE_ITEM_KEY_SEPARATOR = ":";
+/**
+ * Globally unique key of an external item across all sources (Spec §12, §17):
+ * `<sourceId>:<itemId>`, e.g. `project_a:123`. `sourceId` must be a valid
+ * config ID (therefore contains no `:`); `itemId` is adapter-defined, stable,
+ * non-empty and must not contain NUL or newlines.
+ *
+ * This key is used for locks, blocks, run history and view enrichment.
+ */
+export declare function sourceItemKey(sourceId: string, itemId: string): string;
+/** Inverse of {@link sourceItemKey}. Throws {@link ValidationError} for malformed keys. */
+export declare function parseSourceItemKey(key: string): {
+    sourceId: string;
+    itemId: string;
+};
+/** Prefix of comment idempotency markers. */
+export declare const COMMENT_MARKER_PREFIX = "adispatchd";
+/**
+ * Stable, unobtrusive idempotency marker for a lifecycle action, e.g.
+ * `adispatchd:run-20261016T190000123Z-3fa2c91b:a12`. The source adapter decides how
+ * to embed it (GitHub: HTML comment) and finds it again via
+ * `SourceAdapter.findCommentByMarker` (Spec §10).
+ */
+export declare function commentMarker(runId: string, actionId: string | number): string;

package/dist/core/ids.js

@@ -0,0 +1,88 @@
+/**
+ * Identifier helpers: run IDs (Spec §9), global source item keys (Spec §17),
+ * config IDs and idempotency markers for comments (Spec §10).
+ */
+import { randomBytes } from 'node:crypto';
+import { systemClock } from './clock.js';
+import { ValidationError } from './errors.js';
+/**
+ * Allowed pattern for IDs declared in YAML (workflow, source, identity, view
+ * IDs): starts with a letter or digit, then letters, digits, `_`, `-`; max 64
+ * characters. Such IDs are safe as path segments and as key prefixes.
+ */
+export const CONFIG_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+/** True if `id` matches {@link CONFIG_ID_PATTERN}. */
+export function isValidConfigId(id) {
+    return CONFIG_ID_PATTERN.test(id);
+}
+/**
+ * Format a timestamp as compact, lexicographically sortable, path-safe UTC
+ * string: `YYYYMMDDTHHMMSSZ` (or with milliseconds `YYYYMMDDTHHMMSSmmmZ`).
+ * Used for `{timestamp}` and in run IDs.
+ */
+export function formatCompactTimestamp(date, withMillis = false) {
+    const iso = date.toISOString(); // 2026-10-16T19:00:00.123Z
+    const base = `${iso.slice(0, 4)}${iso.slice(5, 7)}${iso.slice(8, 10)}T${iso.slice(11, 13)}${iso.slice(14, 16)}${iso.slice(17, 19)}`;
+    return withMillis ? `${base}${iso.slice(20, 23)}Z` : `${base}Z`;
+}
+/** Pattern of run IDs produced by {@link createRunId}. */
+export const RUN_ID_PATTERN = /^run-\d{8}T\d{9}Z-[0-9a-f]{8}$/;
+/**
+ * Create a new run ID: `run-<YYYYMMDDTHHMMSSmmmZ>-<8 hex>`, e.g.
+ * `run-20261016T190000123Z-3fa2c91b`. IDs are unique (32 random bits per
+ * millisecond), sort chronologically as strings, and are safe as path segments
+ * and in URLs.
+ */
+export function createRunId(options = {}) {
+    const clock = options.clock ?? systemClock;
+    const rnd = (options.randomBytes ?? randomBytes)(4);
+    const hex = Buffer.from(rnd).toString('hex').padStart(8, '0').slice(0, 8);
+    return `run-${formatCompactTimestamp(clock.now(), true)}-${hex}`;
+}
+/** True if `id` has the run ID format (see {@link createRunId}). */
+export function isValidRunId(id) {
+    return RUN_ID_PATTERN.test(id);
+}
+/** Separator between source ID and item ID in a {@link sourceItemKey}. */
+export const SOURCE_ITEM_KEY_SEPARATOR = ':';
+/**
+ * Globally unique key of an external item across all sources (Spec §12, §17):
+ * `<sourceId>:<itemId>`, e.g. `project_a:123`. `sourceId` must be a valid
+ * config ID (therefore contains no `:`); `itemId` is adapter-defined, stable,
+ * non-empty and must not contain NUL or newlines.
+ *
+ * This key is used for locks, blocks, run history and view enrichment.
+ */
+export function sourceItemKey(sourceId, itemId) {
+    if (!isValidConfigId(sourceId))
+        throw new ValidationError(`Invalid source id "${sourceId}"`, { sourceId });
+    if (itemId === '' || /[\0\r\n]/.test(itemId))
+        throw new ValidationError(`Invalid item id "${itemId}"`, { itemId });
+    return `${sourceId}${SOURCE_ITEM_KEY_SEPARATOR}${itemId}`;
+}
+/** Inverse of {@link sourceItemKey}. Throws {@link ValidationError} for malformed keys. */
+export function parseSourceItemKey(key) {
+    const idx = key.indexOf(SOURCE_ITEM_KEY_SEPARATOR);
+    if (idx <= 0 || idx === key.length - 1)
+        throw new ValidationError(`Invalid source item key "${key}"`, { key });
+    const sourceId = key.slice(0, idx);
+    const itemId = key.slice(idx + 1);
+    sourceItemKey(sourceId, itemId); // validates both parts
+    return { sourceId, itemId };
+}
+/** Prefix of comment idempotency markers. */
+export const COMMENT_MARKER_PREFIX = 'adispatchd';
+/**
+ * Stable, unobtrusive idempotency marker for a lifecycle action, e.g.
+ * `adispatchd:run-20261016T190000123Z-3fa2c91b:a12`. The source adapter decides how
+ * to embed it (GitHub: HTML comment) and finds it again via
+ * `SourceAdapter.findCommentByMarker` (Spec §10).
+ */
+export function commentMarker(runId, actionId) {
+    const action = String(actionId);
+    if (!/^[A-Za-z0-9_.-]+$/.test(runId) || !/^[A-Za-z0-9_.-]+$/.test(action)) {
+        throw new ValidationError('Marker parts must match [A-Za-z0-9_.-]+', { runId, actionId: action });
+    }
+    return `${COMMENT_MARKER_PREFIX}:${runId}:${action}`;
+}
+//# sourceMappingURL=ids.js.map

package/dist/core/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../src/core/ids.ts"],"names":[],"mappings":"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"}

package/dist/core/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared contracts of the orchestrator: domain types, component interfaces and
+ * small pure helpers. Other components import core only via this module.
+ */
+export * from './clock.js';
+export * from './duration.js';
+export * from './errors.js';
+export * from './ids.js';
+export * from './logger.js';
+export * from './paths.js';
+export * from './template.js';
+export * from './types.js';
+export * from './worker-protocol.js';

package/dist/core/index.js

@@ -0,0 +1,14 @@
+/**
+ * Shared contracts of the orchestrator: domain types, component interfaces and
+ * small pure helpers. Other components import core only via this module.
+ */
+export * from './clock.js';
+export * from './duration.js';
+export * from './errors.js';
+export * from './ids.js';
+export * from './logger.js';
+export * from './paths.js';
+export * from './template.js';
+export * from './types.js';
+export * from './worker-protocol.js';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC"}

package/dist/core/logger.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Minimal structured logging with secret redaction (Spec §20.4).
+ *
+ * Log records are JSON lines: `{ time, level, msg, ...bindings, ...fields }`.
+ * Every record passes through a redaction hook before it is written, so known
+ * secret values and secret-looking keys never reach the sink.
+ */
+import { type Clock } from './clock.js';
+/** Supported log levels in ascending severity. */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Structured, JSON-serialisable context attached to a log record. */
+export type LogFields = Record<string, unknown>;
+/** Structured logger used by all components (injected, never global). */
+export interface Logger {
+    debug(msg: string, fields?: LogFields): void;
+    info(msg: string, fields?: LogFields): void;
+    warn(msg: string, fields?: LogFields): void;
+    error(msg: string, fields?: LogFields): void;
+    /** Derive a logger that adds `bindings` to every record (e.g. `{ component: 'scheduler' }`). */
+    child(bindings: LogFields): Logger;
+}
+/** Hook that removes secrets from a string. Must be pure and cheap. */
+export type Redactor = (text: string) => string;
+/** Replacement text for redacted values. */
+export declare const REDACTED = "[REDACTED]";
+/** True if values under `key` must always be redacted. */
+export declare function isSecretKey(key: string): boolean;
+/**
+ * Registry of known secret values (tokens, keys) that are replaced by
+ * {@link REDACTED} in any text passed through {@link SecretRedactor.redact}.
+ * Best-effort only: a secret that is transformed (e.g. base64) is not detected (Spec §24.8).
+ */
+export declare class SecretRedactor {
+    private readonly secrets;
+    /** Register a secret value. Values shorter than 4 characters are ignored. */
+    add(secret: string | undefined | null): void;
+    /** Forget a secret value (e.g. after token expiry). */
+    remove(secret: string): void;
+    /** Number of registered secrets. */
+    get size(): number;
+    /** Replace every registered secret occurring in `text`. Longest secrets are replaced first. */
+    redact(text: string): string;
+    /** The redactor as a plain function, suitable for {@link ConsoleLoggerOptions.redact}. */
+    readonly asRedactor: Redactor;
+}
+/**
+ * Deep-copy `value`, replacing values under secret-looking keys and applying
+ * `redact` to every string. Handles cycles and Error objects.
+ */
+export declare function redactValue(value: unknown, redact?: Redactor, seen?: WeakSet<object>): unknown;
+/** Options for {@link ConsoleLogger}. */
+export interface ConsoleLoggerOptions {
+    /** Minimum level written. Default `info`. */
+    level?: LogLevel;
+    /** Time source for the `time` field. Default {@link systemClock}. */
+    clock?: Clock;
+    /** Secret redaction hook applied to every string in the record. */
+    redact?: Redactor;
+    /** Line sink. Default writes to `process.stderr`. */
+    sink?: (line: string) => void;
+    /** Fields added to every record. */
+    bindings?: LogFields;
+}
+/** Logger writing one JSON object per line (default: stderr). */
+export declare class ConsoleLogger implements Logger {
+    private readonly level;
+    private readonly clock;
+    private readonly redact;
+    private readonly sink;
+    private readonly bindings;
+    constructor(options?: ConsoleLoggerOptions);
+    debug(msg: string, fields?: LogFields): void;
+    info(msg: string, fields?: LogFields): void;
+    warn(msg: string, fields?: LogFields): void;
+    error(msg: string, fields?: LogFields): void;
+    child(bindings: LogFields): Logger;
+    private write;
+}
+/** A log record captured by {@link MemoryLogger}. */
+export interface CapturedLogRecord {
+    level: LogLevel;
+    msg: string;
+    fields: LogFields;
+}
+/** Logger that keeps (redacted) records in memory; intended for tests. */
+export declare class MemoryLogger implements Logger {
+    private readonly redact;
+    private readonly bindings;
+    /** Shared record list (children append to the root's list). */
+    readonly records: CapturedLogRecord[];
+    constructor(redact?: Redactor, bindings?: LogFields, records?: CapturedLogRecord[]);
+    debug(msg: string, fields?: LogFields): void;
+    info(msg: string, fields?: LogFields): void;
+    warn(msg: string, fields?: LogFields): void;
+    error(msg: string, fields?: LogFields): void;
+    child(bindings: LogFields): Logger;
+    private push;
+}
+/** Logger that discards everything. */
+export declare const noopLogger: Logger;