@db3.ai/app 0.1.0-beta.1 → 0.1.0

package/dist/network/privateNetworkAddresses.js

@@ -0,0 +1,157 @@
+import { isIP } from 'node:net';
+/**
+ * Normalizes a URL hostname for address classification.
+ *
+ * WHATWG URL parsing already canonicalizes numeric IPv4 forms such as
+ * `2130706433` and `0x7f.1`. This helper additionally lowercases the value,
+ * removes IPv6 brackets and drops one trailing root-label dot so `localhost.`
+ * and `localhost` are treated the same.
+ *
+ * @param hostname - `URL.hostname` value to normalize.
+ * @returns Lowercase hostname or IP literal without brackets or a trailing dot.
+ *
+ * @example
+ * normalizedUrlHostname(new URL('http://[::1]/').hostname); // '::1'
+ */
+export function normalizedUrlHostname(hostname) {
+    return hostname.toLowerCase().replace(/^\[|\]$/g, '').replace(/\.$/, '');
+}
+/**
+ * Checks whether a hostname is reserved for the local machine.
+ *
+ * DNS names are otherwise judged by the addresses they resolve to, so this
+ * only covers names that never need a DNS query to reach loopback.
+ *
+ * @param hostname - Hostname normalized with {@link normalizedUrlHostname}.
+ * @returns True for `localhost` and any `*.localhost` name.
+ */
+export function isPrivateHostname(hostname) {
+    return hostname === 'localhost' || hostname.endsWith('.localhost');
+}
+/**
+ * Checks whether an IP address must not be reached by server-side requests.
+ *
+ * The policy blocks loopback, private, link-local (including cloud metadata),
+ * carrier-grade NAT, benchmarking, documentation, multicast and reserved
+ * ranges. IPv6 forms that embed an IPv4 address (mapped, NAT64 and 6to4) are
+ * judged by the embedded address, and tunnelling or deprecated forms that can
+ * reach IPv4 hosts indirectly are blocked outright. Values that are not valid
+ * IP literals return false so callers can resolve them as hostnames instead.
+ *
+ * @param address - IPv4 or IPv6 literal, with or without IPv6 brackets.
+ * @returns True when the address is private, local or reserved.
+ *
+ * @example
+ * isPrivateIpAddress('169.254.169.254'); // true
+ * isPrivateIpAddress('::ffff:7f00:1'); // true (IPv4-mapped 127.0.0.1)
+ * isPrivateIpAddress('93.184.216.34'); // false
+ */
+export function isPrivateIpAddress(address) {
+    const normalized = normalizedUrlHostname(address).replace(/%.*$/, '');
+    const version = isIP(normalized);
+    if (version === 4)
+        return isPrivateIpv4Octets(normalized.split('.').map(Number));
+    if (version === 6)
+        return isPrivateIpv6Hextets(expandIpv6(normalized));
+    return false;
+}
+/**
+ * Applies the IPv4 reserved-range policy to four parsed octets.
+ *
+ * @param octets - Parsed IPv4 octets.
+ * @returns True when the address belongs to a blocked range.
+ */
+function isPrivateIpv4Octets(octets) {
+    if (octets.length !== 4 || octets.some(octet => !Number.isInteger(octet) || octet < 0 || octet > 255)) {
+        return true;
+    }
+    const [first, second, third] = octets;
+    return first === 0
+        || first === 10
+        || first === 127
+        || (first === 100 && second >= 64 && second <= 127)
+        || (first === 169 && second === 254)
+        || (first === 172 && second >= 16 && second <= 31)
+        || (first === 192 && second === 0 && (third === 0 || third === 2))
+        || (first === 192 && second === 88 && third === 99)
+        || (first === 192 && second === 168)
+        || (first === 198 && (second === 18 || second === 19))
+        || (first === 198 && second === 51 && third === 100)
+        || (first === 203 && second === 0 && third === 113)
+        || first >= 224;
+}
+/**
+ * Applies the IPv6 reserved-range policy to eight expanded hextets.
+ *
+ * @param hextets - Expanded IPv6 address, or null when it could not be parsed.
+ * @returns True when the address belongs to a blocked range.
+ */
+function isPrivateIpv6Hextets(hextets) {
+    if (!hextets)
+        return true;
+    const [h0, h1, h2, h3, h4, h5, h6, h7] = hextets;
+    const leadingZeros = h0 === 0 && h1 === 0 && h2 === 0 && h3 === 0 && h4 === 0;
+    // ::ffff:a.b.c.d IPv4-mapped addresses reach the embedded IPv4 host.
+    if (leadingZeros && h5 === 0xffff)
+        return isPrivateIpv4Octets(ipv4FromHextets(h6, h7));
+    // ::, ::1 and deprecated ::a.b.c.d IPv4-compatible addresses.
+    if (leadingZeros && h5 === 0)
+        return true;
+    // 64:ff9b::/96 well-known NAT64 prefix translates to the embedded IPv4 host.
+    if (h0 === 0x64 && h1 === 0xff9b && h2 === 0 && h3 === 0 && h4 === 0 && h5 === 0) {
+        return isPrivateIpv4Octets(ipv4FromHextets(h6, h7));
+    }
+    // 64:ff9b:1::/48 local-use NAT64.
+    if (h0 === 0x64 && h1 === 0xff9b && h2 === 1)
+        return true;
+    // 2002::/16 6to4 embeds the relay's IPv4 address in the next 32 bits.
+    if (h0 === 0x2002)
+        return isPrivateIpv4Octets(ipv4FromHextets(h1, h2));
+    // 2001::/32 Teredo tunnelling and 2001:db8::/32 documentation.
+    if (h0 === 0x2001 && (h1 === 0 || h1 === 0xdb8))
+        return true;
+    // 100::/64 discard-only.
+    if (h0 === 0x100 && h1 === 0 && h2 === 0 && h3 === 0)
+        return true;
+    return (h0 & 0xfe00) === 0xfc00 // fc00::/7 unique local
+        || (h0 & 0xffc0) === 0xfe80 // fe80::/10 link-local
+        || (h0 & 0xffc0) === 0xfec0 // fec0::/10 deprecated site-local
+        || (h0 & 0xff00) === 0xff00; // ff00::/8 multicast
+}
+/**
+ * Converts two hextets holding an embedded IPv4 address into octets.
+ *
+ * @param high - Hextet containing the first two octets.
+ * @param low - Hextet containing the last two octets.
+ * @returns Four IPv4 octets.
+ */
+function ipv4FromHextets(high, low) {
+    return [high >> 8, high & 0xff, low >> 8, low & 0xff];
+}
+/**
+ * Expands a valid IPv6 literal into eight numeric hextets.
+ *
+ * Supports `::` compression and a trailing dotted IPv4 suffix.
+ *
+ * @param address - IPv6 literal already validated by `net.isIP`.
+ * @returns Eight hextets, or null when the literal cannot be expanded.
+ */
+function expandIpv6(address) {
+    let value = address;
+    const dotted = value.match(/^(.*:)(\d+\.\d+\.\d+\.\d+)$/);
+    if (dotted) {
+        const octets = dotted[2].split('.').map(Number);
+        value = `${dotted[1]}${((octets[0] << 8) | octets[1]).toString(16)}:${((octets[2] << 8) | octets[3]).toString(16)}`;
+    }
+    const [head, tail] = value.split('::');
+    const headParts = head ? head.split(':') : [];
+    const tailParts = tail === undefined ? [] : tail ? tail.split(':') : [];
+    const missing = 8 - headParts.length - tailParts.length;
+    if (tail === undefined ? missing !== 0 : missing < 0)
+        return null;
+    const hextets = [...headParts, ...Array(tail === undefined ? 0 : missing).fill('0'), ...tailParts]
+        .map(part => Number.parseInt(part, 16));
+    return hextets.length === 8 && hextets.every(part => Number.isInteger(part) && part >= 0 && part <= 0xffff)
+        ? hextets
+        : null;
+}

package/dist/network/publicAddressLookup.d.ts

@@ -0,0 +1,26 @@
+import { type LookupAddress, type LookupOptions } from 'node:dns';
+/** Callback shape used by `dns.lookup` for both single and `all` results. */
+type LookupCallback = (error: NodeJS.ErrnoException | null, address: string | LookupAddress[], family?: number) => void;
+/**
+ * DNS lookup that refuses to connect to private, local or reserved addresses.
+ *
+ * It has the same signature as `dns.lookup`, so it can be passed as the
+ * `lookup` socket option of Node's `http`, `https`, `net` and `tls` modules and
+ * to clients built on them (for example undici's `connect.lookup` or got's
+ * `dnsLookup`). Because the check runs when the socket connects, the address
+ * that is validated is the address that is used, which closes the DNS
+ * rebinding gap left by checking a hostname before a separate request.
+ *
+ * Node does not call `lookup` for IP-literal hosts, so literals (including
+ * redirect targets) must still be checked with {@link assertPublicUrl}.
+ *
+ * @param hostname - Hostname being connected to.
+ * @param options - Lookup options supplied by the socket layer.
+ * @param callback - Receives the validated address(es) or a `BlockedUrlError`.
+ *
+ * @example
+ * import { Agent } from 'undici';
+ * const dispatcher = new Agent({ connect: { lookup: publicAddressLookup } });
+ */
+export declare function publicAddressLookup(hostname: string, options: LookupOptions, callback: LookupCallback): void;
+export {};

package/dist/network/publicAddressLookup.js

@@ -0,0 +1,42 @@
+import { lookup } from 'node:dns';
+import { BlockedUrlError } from './BlockedUrlError.js';
+import { PRIVATE_DESTINATION_MESSAGE } from './assertPublicUrl.js';
+import { isPrivateIpAddress } from './privateNetworkAddresses.js';
+/**
+ * DNS lookup that refuses to connect to private, local or reserved addresses.
+ *
+ * It has the same signature as `dns.lookup`, so it can be passed as the
+ * `lookup` socket option of Node's `http`, `https`, `net` and `tls` modules and
+ * to clients built on them (for example undici's `connect.lookup` or got's
+ * `dnsLookup`). Because the check runs when the socket connects, the address
+ * that is validated is the address that is used, which closes the DNS
+ * rebinding gap left by checking a hostname before a separate request.
+ *
+ * Node does not call `lookup` for IP-literal hosts, so literals (including
+ * redirect targets) must still be checked with {@link assertPublicUrl}.
+ *
+ * @param hostname - Hostname being connected to.
+ * @param options - Lookup options supplied by the socket layer.
+ * @param callback - Receives the validated address(es) or a `BlockedUrlError`.
+ *
+ * @example
+ * import { Agent } from 'undici';
+ * const dispatcher = new Agent({ connect: { lookup: publicAddressLookup } });
+ */
+export function publicAddressLookup(hostname, options, callback) {
+    lookup(hostname, { ...options, all: true }, (error, addresses) => {
+        if (error) {
+            callback(error, []);
+            return;
+        }
+        if (addresses.length === 0 || addresses.some(entry => isPrivateIpAddress(entry.address))) {
+            callback(Object.assign(new BlockedUrlError(PRIVATE_DESTINATION_MESSAGE), { code: 'ERR_BLOCKED_ADDRESS' }), []);
+            return;
+        }
+        if (options.all) {
+            callback(null, addresses);
+            return;
+        }
+        callback(null, addresses[0].address, addresses[0].family);
+    });
+}

package/dist/notifications/Notifications.d.ts

@@ -0,0 +1,27 @@
+import type { UserIdentity, UserIdentityModel } from '../auth/index.js';
+import type { InApp } from '../in-app/index.js';
+import type { Mail } from '../mail/index.js';
+import type * as notifications from './contracts/index.js';
+/** Coordinates application-owned notification classes with framework channels. */
+export declare class Notifications<TUser extends UserIdentity = UserIdentity> {
+    #private;
+    private readonly inApp;
+    private readonly mail;
+    private readonly identityModel;
+    /**
+     * Creates the notification coordinator used by app().notifications.
+     *
+     * @param inApp - Durable framework inbox service.
+     * @param mail - Provider-neutral framework mail service.
+     * @param identityModel - Application identity model used to resolve ID recipients.
+     */
+    constructor(inApp: InApp, mail: Mail, identityModel: UserIdentityModel<TUser>);
+    /**
+     * Delivers one notification to one or more users through its `via()` channels.
+     *
+     * @param recipients - User model, ID, or an array mixing both forms.
+     * @param notification - Application-owned routing and channel renderers.
+     * @returns One delivery result per distinct resolved user.
+     */
+    send(recipients: notifications.NotificationRecipient<TUser> | readonly notifications.NotificationRecipient<TUser>[], notification: notifications.Notification<TUser>): Promise<notifications.NotificationDelivery[]>;
+}

package/dist/notifications/Notifications.js

@@ -0,0 +1,99 @@
+import { createHash } from 'node:crypto';
+/** Coordinates application-owned notification classes with framework channels. */
+export class Notifications {
+    inApp;
+    mail;
+    identityModel;
+    /**
+     * Creates the notification coordinator used by app().notifications.
+     *
+     * @param inApp - Durable framework inbox service.
+     * @param mail - Provider-neutral framework mail service.
+     * @param identityModel - Application identity model used to resolve ID recipients.
+     */
+    constructor(inApp, mail, identityModel) {
+        this.inApp = inApp;
+        this.mail = mail;
+        this.identityModel = identityModel;
+    }
+    /**
+     * Delivers one notification to one or more users through its `via()` channels.
+     *
+     * @param recipients - User model, ID, or an array mixing both forms.
+     * @param notification - Application-owned routing and channel renderers.
+     * @returns One delivery result per distinct resolved user.
+     */
+    async send(recipients, notification) {
+        if (!notification.type?.trim())
+            throw new Error('Notification type is required.');
+        const users = await this.#resolveUsers(recipients);
+        const deliveries = [];
+        for (const user of users)
+            deliveries.push(await this.#deliver(user, notification));
+        return deliveries;
+    }
+    /**
+     * Delivers selected channels for one canonical user.
+     *
+     * @param user - Resolved application identity.
+     * @param notification - Application-owned routing and content definition.
+     * @returns Accepted in-app and mail outcomes for the recipient.
+     */
+    async #deliver(user, notification) {
+        const userId = String(user.id);
+        const channels = [...new Set(notification.via(user))];
+        if (!channels.length)
+            return { userId, inApp: null, mail: null };
+        if (channels.some(channel => !['inApp', 'mail'].includes(channel)))
+            throw new Error(`Notification "${notification.type}" selected an unsupported channel.`);
+        const scope = notification.scope?.(user) ?? { type: 'account' };
+        const key = notification.key?.(user);
+        let inApp = null;
+        let mail = null;
+        if (channels.includes('inApp')) {
+            if (!notification.toInApp)
+                throw new Error(`Notification "${notification.type}" selected inApp without a toInApp() renderer.`);
+            [inApp] = await this.inApp.send(userId, notification.toInApp(user), { scope, type: notification.type, key });
+        }
+        if (channels.includes('mail')) {
+            if (!notification.toMail)
+                throw new Error(`Notification "${notification.type}" selected mail without a toMail() renderer.`);
+            mail = await this.mail.send(withDeliveryKey(notification.toMail(user), notification.type, key, userId));
+        }
+        return { userId, inApp, mail };
+    }
+    /**
+     * Resolves model and ID inputs, rejecting missing identities before delivery.
+     *
+     * @param recipients - User model, ID, or bounded array of either form.
+     * @returns Distinct canonical users in first-seen order.
+     */
+    async #resolveUsers(recipients) {
+        const input = Array.isArray(recipients) ? recipients : [recipients];
+        if (input.length > 100)
+            throw new Error('Notifications accepts at most 100 recipients per send.');
+        const users = new Map();
+        for (const recipient of input) {
+            const user = typeof recipient === 'string' ? await this.identityModel.find(recipient) : recipient;
+            if (!user?.id)
+                throw new Error('Notification recipient is unavailable.');
+            users.set(String(user.id), user);
+        }
+        return [...users.values()];
+    }
+}
+/**
+ * Adds a stable provider retry identity when the renderer did not provide one.
+ *
+ * @param message - Provider-neutral mail content rendered by the notification.
+ * @param type - Stable notification type.
+ * @param key - Optional application-owned occurrence key.
+ * @param userId - Canonical recipient identity.
+ * @returns Original or copied message with an idempotency key when possible.
+ */
+function withDeliveryKey(message, type, key, userId) {
+    if (message.idempotencyKey || !key)
+        return message;
+    const hash = createHash('sha256').update(JSON.stringify([type, key, userId])).digest('hex');
+    return { ...message, idempotencyKey: `notification/${hash}` };
+}

package/dist/notifications/contracts/Notification.d.ts

@@ -0,0 +1,56 @@
+import type { InAppMessage, InAppScope } from '../../in-app/index.js';
+import type { MailMessage } from '../../mail/index.js';
+/** Framework delivery channels currently supported by notification classes. */
+export type NotificationChannel = 'inApp' | 'mail';
+/** Minimum persisted identity accepted by the notification service. */
+export interface NotificationUser {
+    /** Stable application identity used for delivery ownership and deduplication. */
+    id: string | null;
+}
+/**
+ * Application-owned notification content and routing policy.
+ *
+ * Channel renderers return data only. They must not persist messages, contact
+ * providers or depend on an active HTTP request.
+ */
+export interface Notification<TUser extends NotificationUser = NotificationUser> {
+    /** Stable application-owned type used for inbox filtering and deduplication. */
+    readonly type: string;
+    /**
+     * Selects delivery channels for one resolved user.
+     *
+     * @param user - Persisted recipient, available for future preference checks.
+     * @returns Distinct supported channels to deliver.
+     */
+    via(user: TUser): readonly NotificationChannel[];
+    /**
+     * Resolves recipient scope for authorization and inbox queries.
+     *
+     * @param user - Persisted recipient receiving this occurrence.
+     * @returns Account scope by default, or an application-owned scope.
+     */
+    scope?(user: TUser): InAppScope;
+    /**
+     * Returns a stable business identity used to deduplicate retries.
+     *
+     * @param user - Persisted recipient receiving this occurrence.
+     * @returns Application-owned occurrence key, or undefined for no deduplication.
+     */
+    key?(user: TUser): string | undefined;
+    /**
+     * Renders durable in-app content when `via()` selects `inApp`.
+     *
+     * @param user - Persisted recipient receiving this occurrence.
+     * @returns Validated content stored in the recipient's inbox.
+     */
+    toInApp?(user: TUser): InAppMessage;
+    /**
+     * Renders email content when `via()` selects `mail`.
+     *
+     * @param user - Persisted recipient receiving this occurrence.
+     * @returns Provider-neutral mail content ready for the configured transport.
+     */
+    toMail?(user: TUser): MailMessage;
+}
+/** User model or stable ID accepted by notification delivery. */
+export type NotificationRecipient<TUser extends NotificationUser> = TUser | string;

package/dist/notifications/contracts/Notification.js

@@ -0,0 +1 @@
+export {};

package/dist/notifications/contracts/NotificationDelivery.d.ts

@@ -0,0 +1,11 @@
+import type { InAppAcceptance } from '../../in-app/index.js';
+import type { MailDelivery } from '../../mail/index.js';
+/** Accepted channel outcomes for one resolved user. */
+export interface NotificationDelivery {
+    /** Stable recipient identity. */
+    userId: string;
+    /** Durable in-app acceptance, or null when the notification omitted the channel. */
+    inApp: InAppAcceptance | null;
+    /** Mail transport acceptance, or null when the renderer omitted the channel. */
+    mail: MailDelivery | null;
+}

package/dist/notifications/contracts/NotificationDelivery.js

@@ -0,0 +1 @@
+export {};

package/dist/notifications/contracts/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Notification.js';
+export * from './NotificationDelivery.js';

package/dist/notifications/contracts/index.js

@@ -0,0 +1,2 @@
+export * from './Notification.js';
+export * from './NotificationDelivery.js';

package/dist/notifications/index.d.ts

@@ -0,0 +1,2 @@
+export * from './contracts/index.js';
+export { Notifications } from './Notifications.js';

package/dist/notifications/index.js

@@ -0,0 +1,2 @@
+export * from './contracts/index.js';
+export { Notifications } from './Notifications.js';

package/dist/queue/JobRunAttempt.d.ts

@@ -0,0 +1,16 @@
+import { ActiveRecord } from '../db/ActiveRecord.js';
+declare const JobRunAttempt_base: import("../db/index.js").DefinedActiveRecord<typeof ActiveRecord, {
+    id: import("../db/index.js").UlidField;
+    runId: import("../db/index.js").StringField;
+    tenantId: import("../db/index.js").StringField;
+    attempt: import("../db/index.js").IntegerField;
+    deliveryId: import("../db/index.js").StringField;
+    status: import("../db/index.js").StringField;
+    error: import("../db/index.js").TextField;
+    startedAt: import("../db/index.js").TimestampField;
+    completedAt: import("../db/index.js").TimestampField;
+}>;
+/** Retains each execution boundary, including attempts interrupted before a handler could fail itself. */
+export declare class JobRunAttempt extends JobRunAttempt_base {
+}
+export {};

package/dist/queue/JobRunAttempt.js

@@ -0,0 +1,17 @@
+import { ActiveRecord } from '../db/ActiveRecord.js';
+/** Retains each execution boundary, including attempts interrupted before a handler could fail itself. */
+export class JobRunAttempt extends ActiveRecord.define({
+    table: 'job_run_attempts',
+    fields: field => ({
+        id: field.ulid(),
+        runId: field.string({ column: 'run_id', required: true, length: 26, index: true }),
+        tenantId: field.string({ column: 'tenant_id', required: true, length: 100, index: true }),
+        attempt: field.integer({ required: true }),
+        deliveryId: field.string({ column: 'delivery_id', required: true, length: 100 }),
+        status: field.string({ required: true, length: 30 }),
+        error: field.text(),
+        startedAt: field.timestamp({ column: 'started_at', required: true }),
+        completedAt: field.timestamp({ column: 'completed_at' }),
+    }),
+}) {
+}

package/dist/queue/JobRunEvent.d.ts

@@ -0,0 +1,15 @@
+import { ActiveRecord } from '../db/ActiveRecord.js';
+declare const JobRunEvent_base: import("../db/index.js").DefinedActiveRecord<typeof ActiveRecord, {
+    id: import("../db/index.js").UlidField;
+    runId: import("../db/index.js").StringField;
+    tenantId: import("../db/index.js").StringField;
+    attempt: import("../db/index.js").IntegerField;
+    level: import("../db/index.js").ChoiceStringField;
+    message: import("../db/index.js").StringField;
+    data: import("../db/index.js").JsonField<Record<string, unknown> | null>;
+    createdAt: import("../db/index.js").TimestampField;
+}>;
+/** Append-only diagnostic evidence for a run; applications control access and retention. */
+export declare class JobRunEvent extends JobRunEvent_base {
+}
+export {};

package/dist/queue/JobRunEvent.js

@@ -0,0 +1,16 @@
+import { ActiveRecord } from '../db/ActiveRecord.js';
+/** Append-only diagnostic evidence for a run; applications control access and retention. */
+export class JobRunEvent extends ActiveRecord.define({
+    table: 'job_run_events',
+    fields: field => ({
+        id: field.ulid(),
+        runId: field.string({ column: 'run_id', required: true, length: 26, index: true }),
+        tenantId: field.string({ column: 'tenant_id', required: true, length: 100, index: true }),
+        attempt: field.integer({ required: true, default: 0 }),
+        level: field.choice({ choices: ['info', 'warning', 'error'], required: true, default: 'info' }),
+        message: field.string({ required: true, length: 1024 }),
+        data: field.json(),
+        createdAt: field.timestamp({ column: 'created_at', auto: 'create' }),
+    }),
+}) {
+}

package/dist/queue/JobRunStoppedError.d.ts

@@ -0,0 +1,6 @@
+/** Cooperative stop requested by an operator or a job-owned blocking policy. */
+export declare class JobRunStoppedError extends Error {
+    readonly status: 'blocked' | 'cancelled';
+    /** Captures a durable stop reason without treating expected stops as provider exceptions. */
+    constructor(status: 'blocked' | 'cancelled', message: string);
+}

package/dist/queue/JobRunStoppedError.js

@@ -0,0 +1,10 @@
+/** Cooperative stop requested by an operator or a job-owned blocking policy. */
+export class JobRunStoppedError extends Error {
+    status;
+    /** Captures a durable stop reason without treating expected stops as provider exceptions. */
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'JobRunStoppedError';
+    }
+}

package/dist/queue/Queue.d.ts

@@ -1,8 +1,8 @@
+import type { QueueableJobContract as QueueableJob } from './contracts/QueueableJobContract.js';
 import type { Database } from '../db/index.js';
 import { type QueueMonitor } from './queueMonitor.js';
 import { QueueEvents } from './QueueEvents.js';
 import { QueueWorker } from './QueueWorker.js';
-import { type QueueableJob } from './QueueableJob.js';
 import type * as queue from './contracts/index.js';
 export type { QueueOptions, QueueService, QueueWorkOptions } from './contracts/index.js';
 /**
@@ -12,6 +12,7 @@ export type { QueueOptions, QueueService, QueueWorkOptions } from './contracts/i
  * callers can either process one job at a time or start a worker loop over the same API.
  */
 export declare class Queue implements queue.QueueService {
+    #private;
     private readonly db;
     private readonly options;
     private readonly handlers;
@@ -20,9 +21,17 @@ export declare class Queue implements queue.QueueService {
     readonly events: QueueEvents;
     constructor(db: Database, options?: queue.QueueOptions);
     /**
-     * Returns the queue lifecycle monitor attached to this queue, when enabled.
+     * Returns the configured transport name for atomic database dispatch.
      */
+    get driverName(): string;
+    /** Reports worker presence through the application-owned sink without changing delivery semantics. */
+    reportWorker(snapshot: queue.QueueWorkerSnapshot): Promise<void>;
+    /** Returns the optional queue lifecycle monitor. */
     get queueMonitor(): QueueMonitor | null;
+    /** Registers app-owned stable job names atomically and returns cleanup for this process only. */
+    registerJobs(owner: string, jobs: readonly queue.QueueableJobClass[], run?: queue.QueueJobRunner): () => void;
+    /** Checks active, delayed, reserved and chained payloads after producers have been quiesced. */
+    hasPendingJobs(jobPrefix: string): Promise<boolean>;
     /**
      * Returns recent terminal failures from the configured queue driver.
      *
@@ -125,9 +134,15 @@ export declare class Queue implements queue.QueueService {
      */
     private lostLeaseError;
     /**
-     * Starts a polling worker for a queue unless workers are disabled by configuration.
+     * Discovers named queues without reading or changing job payloads.
+     * @throws When a custom driver does not implement wildcard discovery.
      */
-    startWorker(queue?: string, options?: queue.QueueWorkerOptions): QueueWorker | null;
+    queueNames(): Promise<string[]>;
+    /**
+     * Starts a polling worker for a named queue or selection unless disabled.
+     * @example queue.startWorker({ queues: '*', excludeQueues: ['articles'] });
+     */
+    startWorker(queue?: string | queue.QueueSelection, options?: queue.QueueWorkerOptions): QueueWorker | null;
     private resolveDriver;
     /**
      * Returns a positive reservation timeout for queue claims and heartbeats.