adispatchd 0.0.0-stage → 0.1.0

package/dist/lifecycle/errors.js

@@ -0,0 +1,71 @@
+/**
+ * Error model of lifecycle actions: every failed attempt is persisted as an
+ * {@link ActionErrorInfo} (`action_attempts.error_json`, `run_actions.last_error_json`).
+ * The `retryable` flag decides whether further automatic attempts are made.
+ */
+import { OrchestratorError, SourceError, TemplateError, errorMessage, redactValue, } from '../core/index.js';
+/** Error raised by the lifecycle engine itself (action execution, invalid input). */
+export class LifecycleError extends OrchestratorError {
+    retryable;
+    outcomeUnknown;
+    constructor(code, message, options = {}) {
+        super(`lifecycle_${code}`, message, {
+            ...(options.details !== undefined ? { details: options.details } : {}),
+            ...(options.cause !== undefined ? { cause: options.cause } : {}),
+        });
+        this.retryable = options.retryable ?? false;
+        this.outcomeUnknown = options.outcomeUnknown ?? false;
+    }
+}
+/** Thrown when a chain of the same run is already being executed in this process. */
+export class LifecycleBusyError extends LifecycleError {
+    constructor(runId) {
+        super('busy', `Lifecycle actions of run ${runId} are already being executed`, { details: { runId } });
+    }
+}
+/**
+ * Convert any thrown value into an {@link ActionErrorInfo}.
+ *
+ * - `SourceError`: keeps `kind`, `retryable`, `outcomeUnknown`, `status`, `retryAfterMs`.
+ * - `TemplateError` and other `OrchestratorError`s: not retryable (configuration problem).
+ * - {@link LifecycleError}: its own flags.
+ * - Anything else (unexpected exception): retryable, so the configured attempts apply.
+ */
+export function describeActionError(err, redact = (s) => s) {
+    const message = redact(errorMessage(err));
+    if (err instanceof SourceError) {
+        return compact({
+            code: err.code,
+            message,
+            retryable: err.retryable,
+            outcomeUnknown: err.outcomeUnknown || undefined,
+            kind: err.kind,
+            status: err.status,
+            retryAfterMs: err.retryAfterMs,
+        });
+    }
+    if (err instanceof LifecycleError) {
+        return compact({
+            code: err.code,
+            message,
+            retryable: err.retryable,
+            outcomeUnknown: err.outcomeUnknown || undefined,
+            details: err.details ? redactValue(err.details, redact) : undefined,
+        });
+    }
+    if (err instanceof TemplateError) {
+        return compact({ code: err.code, message, retryable: false, details: err.details });
+    }
+    if (err instanceof OrchestratorError) {
+        return compact({ code: err.code, message, retryable: false });
+    }
+    return { code: 'lifecycle_unexpected_error', message, retryable: true };
+}
+function compact(info) {
+    const out = {};
+    for (const [key, value] of Object.entries(info))
+        if (value !== undefined)
+            out[key] = value;
+    return out;
+}
+//# sourceMappingURL=errors.js.map

package/dist/lifecycle/errors.js.map

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

package/dist/lifecycle/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Component `lifecycle` – public API (WI-07): lifecycle hook chains with
+ * action journal, retries, manual retry/skip and recovery (Spec §10).
+ * Other components import from this module only.
+ */
+export { LifecycleEngine, LIFECYCLE_ACTION_EVENT, LIFECYCLE_CHAIN_EVENT, DEFAULT_ACTION_RETRY, actionConfig, aggregateLifecycleStatus, stoppedAt, type HookContext, type HookResult, type LifecycleActionFailedPayload, type LifecycleEngineOptions, } from './engine.js';
+export { LifecycleError, LifecycleBusyError, describeActionError, type ActionErrorInfo } from './errors.js';
+export { parseRunSnapshot, resolveActionIdentity, hookTemplateScope, buildHookTemplateValues, buildShellActionContext, renderHookText, type ShellActionContext, } from './context.js';
+export type { SourceResolver } from './performers.js';

package/dist/lifecycle/index.js

@@ -0,0 +1,9 @@
+/**
+ * Component `lifecycle` – public API (WI-07): lifecycle hook chains with
+ * action journal, retries, manual retry/skip and recovery (Spec §10).
+ * Other components import from this module only.
+ */
+export { LifecycleEngine, LIFECYCLE_ACTION_EVENT, LIFECYCLE_CHAIN_EVENT, DEFAULT_ACTION_RETRY, actionConfig, aggregateLifecycleStatus, stoppedAt, } from './engine.js';
+export { LifecycleError, LifecycleBusyError, describeActionError } from './errors.js';
+export { parseRunSnapshot, resolveActionIdentity, hookTemplateScope, buildHookTemplateValues, buildShellActionContext, renderHookText, } from './context.js';
+//# sourceMappingURL=index.js.map

package/dist/lifecycle/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lifecycle/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,YAAY,EACZ,wBAAwB,EACxB,SAAS,GAKV,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,mBAAmB,EAAwB,MAAM,aAAa,CAAC;AAC5G,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,EACvB,cAAc,GAEf,MAAM,cAAc,CAAC"}

package/dist/lifecycle/performers.d.ts

@@ -0,0 +1,66 @@
+import { type Executor, type HookName, type SourceAdapter, type SourceItem } from '../core/index.js';
+import type { ShellActionConfig, SourceCommentActionConfig, SourceUpdateActionConfig, WorkflowSnapshot } from '../config/index.js';
+import type { RunActionRecord, RunRecord } from '../persistence/index.js';
+/** Resolves the adapter of a configured source ID (`undefined` if unknown). */
+export type SourceResolver = (sourceId: string) => SourceAdapter | undefined;
+/** Everything one attempt needs. */
+export interface AttemptInput {
+    run: RunRecord;
+    snapshot: WorkflowSnapshot;
+    hook: HookName;
+    action: RunActionRecord;
+    /** Number of this attempt (1-based, over the whole journal history of the action). */
+    attempt: number;
+    /** True if the action had attempts before this one (→ reconcile comments first). */
+    hadPriorAttempts: boolean;
+    /** Fresh item handed in by the caller, if any. */
+    item: SourceItem | undefined;
+    signal: AbortSignal | undefined;
+    now: Date;
+}
+/** Successful attempt. */
+export interface AttemptResult {
+    /** External reference (comment ID), persisted as `external_key`. */
+    externalKey: string | null;
+    /** Journal/event details, e.g. applied labels, comment URL, `reconciled: true`. */
+    details: Record<string, unknown>;
+}
+/** Dependencies of the performers. */
+export interface PerformerDeps {
+    sources: SourceResolver;
+    executor: Executor;
+    dataDir: string;
+    shellCancelGraceMs: number;
+    maxShellLogBytes: number;
+}
+interface SourceTarget {
+    adapter: SourceAdapter;
+    item: SourceItem;
+}
+/** Adapter + item for source actions. Uses the caller's item if it matches the run, else re-reads it. */
+export declare function resolveSourceTarget(deps: Pick<PerformerDeps, 'sources'>, run: RunRecord, snapshot: WorkflowSnapshot, given: SourceItem | undefined): Promise<SourceTarget>;
+/** `source.update`: idempotent label change via the adapter (re-reads the item before writing). */
+export declare function performSourceUpdate(deps: PerformerDeps, input: AttemptInput, config: SourceUpdateActionConfig): Promise<AttemptResult>;
+/**
+ * `source.comment`: renders the message, then posts it with the marker
+ * `commentMarker(runId, actionId)`. If the action had attempts before
+ * (failed, outcome unknown, interrupted), an existing comment with the marker
+ * is searched first and, when found, taken as success instead of posting a duplicate.
+ */
+export declare function performSourceComment(deps: PerformerDeps, input: AttemptInput, config: SourceCommentActionConfig): Promise<AttemptResult>;
+/**
+ * Neutralize HTML comment openers in a comment body (`<!--` → `&lt;!--`).
+ * Rendered values such as `{result.message}` are untrusted worker output and
+ * must not be able to smuggle idempotency markers (`<!-- adispatchd:… -->`) or
+ * hidden content into the comment; the adapter appends the only real marker.
+ */
+export declare function neutralizeHtmlComments(body: string): string;
+/**
+ * `shell`: runs the command via the executor with the minimal environment
+ * (no controller env), the rendered `env`/`args`, a JSON context file with
+ * run + result (`ADISPATCH_CONTEXT_FILE`) and the action timeout. Exit code 0 =
+ * success; anything else (exit ≠ 0, signal, timeout, start error) fails the attempt.
+ * Working directory: the run workspace if it exists, else a per-attempt directory.
+ */
+export declare function performShell(deps: PerformerDeps, input: AttemptInput, config: ShellActionConfig): Promise<AttemptResult>;
+export {};

package/dist/lifecycle/performers.js

@@ -0,0 +1,179 @@
+/**
+ * Execution of single lifecycle action attempts (Spec §10):
+ * `source.update`, `source.comment` (with idempotency marker) and `shell`.
+ * One call = one attempt; retry policy and journal handling live in the engine.
+ */
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+import { commentMarker, dataPaths, } from '../core/index.js';
+import { buildHookTemplateValues, buildShellActionContext, hookTemplateScope, isSourceWorkflow, itemFromRun, renderHookText, resolveActionIdentity, } from './context.js';
+import { LifecycleError } from './errors.js';
+/** Adapter + item for source actions. Uses the caller's item if it matches the run, else re-reads it. */
+export async function resolveSourceTarget(deps, run, snapshot, given) {
+    if (!isSourceWorkflow(snapshot) || !snapshot.source) {
+        throw new LifecycleError('no_source', `Workflow "${snapshot.workflow.id}" has no source; source actions are not possible`);
+    }
+    const adapter = deps.sources(snapshot.source.id);
+    if (!adapter) {
+        throw new LifecycleError('source_unavailable', `Source "${snapshot.source.id}" is not available`, {
+            details: { sourceId: snapshot.source.id },
+        });
+    }
+    const derived = itemFromRun(run);
+    if (!derived)
+        throw new LifecycleError('no_item', `Run ${run.id} is not bound to a source item`);
+    if (given && given.key === derived.key)
+        return { adapter, item: given };
+    const item = await adapter.getItem(derived.itemId);
+    if (!item) {
+        throw new LifecycleError('item_not_found', `Item ${derived.key} no longer exists or is not visible`, {
+            details: { itemKey: derived.key },
+        });
+    }
+    return { adapter, item };
+}
+function requireIdentity(input, config) {
+    const identity = resolveActionIdentity(config, input.snapshot);
+    if (!identity)
+        throw new LifecycleError('no_identity', `No identity for action "${config.id}" (action → workflow → source)`);
+    return identity;
+}
+/** `source.update`: idempotent label change via the adapter (re-reads the item before writing). */
+export async function performSourceUpdate(deps, input, config) {
+    const identity = requireIdentity(input, config);
+    const { adapter, item } = await resolveSourceTarget(deps, input.run, input.snapshot, input.item);
+    const result = await adapter.applyUpdate(item, { labels: { add: config.labels.add, remove: config.labels.remove } }, identity);
+    return { externalKey: null, details: { changed: result.changed, ...(result.applied ? { applied: result.applied } : {}) } };
+}
+/**
+ * `source.comment`: renders the message, then posts it with the marker
+ * `commentMarker(runId, actionId)`. If the action had attempts before
+ * (failed, outcome unknown, interrupted), an existing comment with the marker
+ * is searched first and, when found, taken as success instead of posting a duplicate.
+ */
+export async function performSourceComment(deps, input, config) {
+    const identity = requireIdentity(input, config);
+    // Render before any API call: template errors are permanent and must not post anything.
+    const scope = hookTemplateScope(input.snapshot, input.hook);
+    const probeValues = buildHookTemplateValues({ ...input, item: input.item ?? itemFromRun(input.run) });
+    renderHookText(config.message, probeValues, scope);
+    const { adapter, item } = await resolveSourceTarget(deps, input.run, input.snapshot, input.item);
+    const marker = commentMarker(input.run.id, input.action.id);
+    if (input.hadPriorAttempts) {
+        const existing = await adapter.findCommentByMarker(item, marker, identity);
+        if (existing) {
+            return {
+                externalKey: existing.id,
+                details: { reconciled: true, marker, ...(existing.url ? { url: existing.url } : {}) },
+            };
+        }
+    }
+    const values = buildHookTemplateValues({ ...input, item, ...(adapter.repository ? { repository: adapter.repository } : {}) });
+    const body = neutralizeHtmlComments(renderHookText(config.message, values, scope));
+    const ref = await adapter.postComment(item, body, marker, identity);
+    return { externalKey: ref.id, details: { marker, ...(ref.url ? { url: ref.url } : {}) } };
+}
+/**
+ * Neutralize HTML comment openers in a comment body (`<!--` → `&lt;!--`).
+ * Rendered values such as `{result.message}` are untrusted worker output and
+ * must not be able to smuggle idempotency markers (`<!-- adispatchd:… -->`) or
+ * hidden content into the comment; the adapter appends the only real marker.
+ */
+export function neutralizeHtmlComments(body) {
+    return body.replace(/<!--/g, '&lt;!--');
+}
+async function isDirectory(p) {
+    if (!p)
+        return false;
+    try {
+        return (await stat(p)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `shell`: runs the command via the executor with the minimal environment
+ * (no controller env), the rendered `env`/`args`, a JSON context file with
+ * run + result (`ADISPATCH_CONTEXT_FILE`) and the action timeout. Exit code 0 =
+ * success; anything else (exit ≠ 0, signal, timeout, start error) fails the attempt.
+ * Working directory: the run workspace if it exists, else a per-attempt directory.
+ */
+export async function performShell(deps, input, config) {
+    const { run, snapshot, hook, action } = input;
+    const item = input.item ?? itemFromRun(run);
+    const scope = hookTemplateScope(snapshot, hook);
+    const values = buildHookTemplateValues({ run, snapshot, hook, item, now: input.now });
+    const args = config.args.map((a) => renderHookText(a, values, scope));
+    const env = {};
+    for (const [name, template] of Object.entries(config.env))
+        env[name] = renderHookText(template, values, scope);
+    const paths = dataPaths(deps.dataDir).run(run.id);
+    const attemptDir = path.join(paths.runDir, 'actions', String(action.id), `attempt-${input.attempt}`);
+    const logDir = path.join(paths.logDir, 'actions', String(action.id), `attempt-${input.attempt}`);
+    const files = {
+        contextFile: path.join(attemptDir, 'context.json'),
+        resultFile: path.join(attemptDir, 'result.json'),
+        stdoutLog: path.join(logDir, 'stdout.log'),
+        stderrLog: path.join(logDir, 'stderr.log'),
+    };
+    const useWorkspace = await isDirectory(run.workspacePath);
+    const workingDirectory = useWorkspace && run.workspacePath ? run.workspacePath : path.join(attemptDir, 'cwd');
+    const context = buildShellActionContext({
+        run,
+        snapshot,
+        hook,
+        item,
+        action: { id: action.id, name: action.name, ordinal: action.ordinal, attempt: input.attempt },
+    });
+    const proc = await deps.executor.start({
+        runId: run.id,
+        workflowId: snapshot.workflow.id,
+        command: config.command,
+        args,
+        workingDirectory,
+        createDirectory: !useWorkspace,
+        env,
+        secrets: {},
+        context,
+        files,
+        timeouts: { maxDurationMs: config.timeoutMs },
+        cancelGraceMs: deps.shellCancelGraceMs,
+        maxLogBytes: deps.maxShellLogBytes,
+    });
+    const onAbort = () => {
+        proc.cancel().catch(() => undefined);
+    };
+    input.signal?.addEventListener('abort', onAbort, { once: true });
+    if (input.signal?.aborted)
+        onAbort();
+    const outcome = await proc.wait().finally(() => input.signal?.removeEventListener('abort', onAbort));
+    const logs = { stdout: files.stdoutLog, stderr: files.stderrLog };
+    const base = { exitCode: outcome.exitCode, signal: outcome.signal, logs };
+    if (outcome.spawnError) {
+        throw new LifecycleError('shell_start_error', `Shell action could not be started: ${outcome.spawnError.message}`, {
+            retryable: true,
+            details: { ...base, spawnError: outcome.spawnError },
+        });
+    }
+    if (outcome.cancelled) {
+        throw new LifecycleError('shell_cancelled', 'Shell action was cancelled', { retryable: true, details: base });
+    }
+    if (outcome.timedOut) {
+        throw new LifecycleError('shell_timeout', `Shell action exceeded its timeout (${config.timeoutMs} ms)`, {
+            retryable: true,
+            details: base,
+        });
+    }
+    if (outcome.signal) {
+        throw new LifecycleError('shell_signal', `Shell action was terminated by ${outcome.signal}`, { retryable: true, details: base });
+    }
+    if (outcome.exitCode !== 0) {
+        throw new LifecycleError('shell_exit', `Shell action exited with code ${String(outcome.exitCode)}`, {
+            retryable: true,
+            details: base,
+        });
+    }
+    return { externalKey: null, details: { exitCode: 0, logs } };
+}
+//# sourceMappingURL=performers.js.map

package/dist/lifecycle/performers.js.map

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

package/dist/notifications/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Component `notifications` – public API (WI-10): persisted central
+ * orchestrator notifications with asynchronous webhook delivery (Spec §18).
+ * Other components import from this module only.
+ */
+export { NotificationService, DEFAULT_NOTIFICATION_RETRY_DELAYS_MS, DEFAULT_NOTIFICATION_TIMEOUT_MS, summarize, webhookBody, type NotificationServiceOptions, type NotificationView, } from './service.js';

package/dist/notifications/index.js

@@ -0,0 +1,7 @@
+/**
+ * Component `notifications` – public API (WI-10): persisted central
+ * orchestrator notifications with asynchronous webhook delivery (Spec §18).
+ * Other components import from this module only.
+ */
+export { NotificationService, DEFAULT_NOTIFICATION_RETRY_DELAYS_MS, DEFAULT_NOTIFICATION_TIMEOUT_MS, summarize, webhookBody, } from './service.js';
+//# sourceMappingURL=index.js.map

package/dist/notifications/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/notifications/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,mBAAmB,EACnB,oCAAoC,EACpC,+BAA+B,EAC/B,SAAS,EACT,WAAW,GAGZ,MAAM,cAAc,CAAC"}

package/dist/notifications/service.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Central orchestrator notifications (Spec §18): `retry_block_created`,
+ * `lifecycle_action_failed`, `recovery_failed`.
+ *
+ * Flow: {@link NotificationService.notify} persists the notification plus one
+ * delivery row per subscribed channel synchronously (a few SQLite writes,
+ * never network I/O) and wakes the dispatcher; the dispatcher delivers due
+ * deliveries asynchronously as JSON `POST` to the webhook channels with a
+ * timeout, retries with backoff and stores every attempt. Delivery problems
+ * are logged and persisted, never propagated: orchestration must not hang or
+ * fail because a webhook is down.
+ *
+ * Secrets: webhook URLs (literal or from env) and header values are
+ * registered with the shared {@link SecretRedactor}; error texts never
+ * contain the URL and are redacted before they are stored or logged.
+ */
+import { SecretRedactor, type Clock, type FetchLike, type Logger, type NotificationEventType, type Notifier, type Timers } from '../core/index.js';
+import type { NotificationsConfig } from '../config/index.js';
+import type { NotificationDeliveryRecord, NotificationRecord, Repositories } from '../persistence/index.js';
+/** Default backoff between delivery attempts (attempt n failed → wait `delays[n-1]`). */
+export declare const DEFAULT_NOTIFICATION_RETRY_DELAYS_MS: readonly number[];
+/** Default request timeout of one webhook call. */
+export declare const DEFAULT_NOTIFICATION_TIMEOUT_MS = 10000;
+/** Notification with its channel deliveries (API / SSE shape). */
+export interface NotificationView extends NotificationRecord {
+    deliveries: NotificationDeliveryRecord[];
+}
+/** Options of {@link NotificationService}. */
+export interface NotificationServiceOptions {
+    repositories: Pick<Repositories, 'notifications'>;
+    /** Live notification settings (`config.global.notifications`). */
+    settings: () => NotificationsConfig;
+    /** Environment for `url_env` / `headers_env` (default `process.env`). */
+    env?: Readonly<Record<string, string | undefined>>;
+    /** HTTP client (default global `fetch`). */
+    fetch?: FetchLike;
+    clock?: Clock;
+    timers?: Timers;
+    logger?: Logger;
+    /** Shared redactor (URLs/header values are registered here). */
+    redactor?: SecretRedactor;
+    /** Request timeout per attempt (default 10 s). */
+    timeoutMs?: number;
+    /** Backoff delays; max attempts = `delays.length + 1` (default 5 s, 30 s, 2 min, 10 min, 30 min). */
+    retryDelaysMs?: readonly number[];
+    /** Called (after commit) whenever a notification or one of its deliveries changed (SSE). */
+    onChange?: (notification: NotificationView) => void;
+}
+/** See module docs. Implements the core {@link Notifier} contract. */
+export declare class NotificationService implements Notifier {
+    private readonly options;
+    private readonly repos;
+    private readonly clock;
+    private readonly timers;
+    private readonly logger;
+    private readonly redactor;
+    private readonly fetchFn;
+    private readonly env;
+    private readonly timeoutMs;
+    private readonly delays;
+    private started;
+    private stopped;
+    private timer;
+    private running;
+    private again;
+    private readonly inflight;
+    constructor(options: NotificationServiceOptions);
+    /** Max attempts per delivery. */
+    get maxAttempts(): number;
+    /**
+     * Persist a notification (if its event type is enabled) and schedule the
+     * delivery. Synchronous, never throws.
+     */
+    notify(type: NotificationEventType, payload: Record<string, unknown>): void;
+    /** Start dispatching (also delivers notifications left pending by a previous process). */
+    start(): void;
+    /**
+     * Stop the dispatcher: no new attempts; in-flight requests get `graceMs`
+     * to finish, then they are aborted (they stay `pending` and are retried by
+     * the next process).
+     */
+    stop(graceMs?: number): Promise<void>;
+    /** Resolves when no dispatcher pass is running (tests). */
+    whenIdle(): Promise<void>;
+    /** Notifications (newest first) with their deliveries. */
+    list(options?: {
+        state?: NotificationRecord['deliveryState'];
+        limit?: number;
+        offset?: number;
+    }): NotificationView[];
+    /** One notification with deliveries, or `null`. */
+    get(id: number): NotificationView | null;
+    /**
+     * Manually re-queue all `failed` deliveries of a notification. Returns the
+     * updated notification, or `null` if it does not exist.
+     */
+    retry(id: number): {
+        notification: NotificationView;
+        requeued: number;
+    } | null;
+    /** Wake the dispatcher (no-op before `start()` / after `stop()`). */
+    kick(): void;
+    private armTimer;
+    private dispatch;
+    private deliver;
+    private post;
+    private registerChannelSecrets;
+    /** Re-register channel secrets after a configuration reload. */
+    refreshSecrets(): void;
+    private emit;
+}
+/** JSON body posted to webhook channels (Slack-compatible `text` + structured data). */
+export declare function webhookBody(n: NotificationRecord): Record<string, unknown>;
+/** One-line human-readable summary of a notification. */
+export declare function summarize(type: NotificationEventType, p: Record<string, unknown>): string;