@vibesdotdev/workers 0.0.0-stage → 1.0.0-rc.3

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 VIBES DEV LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# Workers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Provider-neutral background jobs, queues, flows, scheduling, and observation.
+
+## Compose a host
+
+Use **@vibesdotdev/workers/common.plugin** for shared kinds, the Workers runtime
+client, memory queues, and remote queue capability. Use
+**@vibesdotdev/workers/consumer.plugin** for IPC consumers, local flows, dead
+letters, and consumer maintenance. This is the canonical full consumer
+composition.
+
+Cloud hosts can use **@vibesdotdev/workers/cloud.plugin**. Browser hosts can use
+**@vibesdotdev/workers/workers.browser.plugin** and contribute their own adapter
+and flow. A host that needs the persistent database queue composes
+**@vibesdotdev/workers/adapters/database/plugin** and binds the
+workers.database-queue storage record.
+
+Runnable and code execution each expose common and consumer slices. Code
+execution also has a cloud submission slice. Compose
+**@vibesdotdev/runnable/consumer.plugin** (owned by Runnable) and
+**@vibesdotdev/workers/code-execution/consumer.plugin** when their consumer
+implementations are needed. CLI, TUI, and Svelte surfaces live behind their own
+subpaths.
+
+Resolve WorkersClient through the runtime client owner with
+getVibesClient<WorkersClient>('workers', runtime), or use
+getWorkersClient(runtime). The handed runtime selects the adapter and owns the
+client's lifecycle.
+
+## Contract highlights
+
+Queue adapters are selected through open runtime descriptors. A host supplies
+the adapter and flow implementations for its scope. Feature code uses queue
+capability requirements and the Workers client rather than selecting adapters
+by provider id. Selection checks every declared requirement, including
+`crossHardware`, `keyedClaims`, and `coalescedEnqueue`; an incapable preferred
+adapter is not selected for a request it cannot satisfy.
+
+Runnable accepts credential references at its boundary. Secrets owns resolving
+the reference, creating credential-bearing child processes, and redacting their
+output. Runnable service origins resolve through `infra-contracts/service`, so
+the selected service implementation and host target override determine the
+origin. See [SPEC.md](SPEC.md) for the boundaries and typed refusals.
+
+IPC schedule files, including executable cron and timezone semantics, are
+validated as a whole before a due record can enqueue. Corrupt files are preserved
+and refused with `INVALID_INPUT / workers-schedules-corrupt`; unchanged corruption
+does not create a diagnostic loop. Disabled and completed records remain by
+default. Optional age-based archiving is disabled by default. Restore archived
+schedules with `WorkersClient.restoreArchivedSchedules(queueName, ids?)`.
+
+`getWorkersState()` reads state provided by `WorkersLoader`; it is the canonical
+Svelte accessor. The older `workersState` alias has been retired. External
+callers still using that alias are recorded in [SPEC.md](SPEC.md) for migration
+by their owning package.
+
+Cancellation records preserve attribution. Invocation cancellation requires a
+kernel RuntimeActor and reason; system cancellation records an explicit source
+and reason. A caller that aborts a wait keeps its own actor on the cancellation
+the queue records, and a deadline or runtime disposal records its own system
+source instead of demanding an actor. The queue, durable row, and job ledger
+retain that provenance; a row written before provenance existed stays without
+invented attribution. See [SPEC.md](SPEC.md) for the complete contract and typed
+refusals.
+
+For Svelte, import the explicit Svelte surface. WorkersLoader provides
+surface-local state, and the execute-code widget is loaded and registered when
+its tools/ui descriptor resolves.
+
+## Development
+
+- bun run check includes source tests and Svelte TypeScript.
+- bun run test exercises the composed runtime contracts.
+- bun run build emits production artifacts and the Svelte package.
+
+See [SPEC.md](SPEC.md) for public schema families, entry points, proof
+locations, and verification commands.

package/dist/adapters/database/database-queue.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Database queue — a distributed, persistent QueueAdapter over the
+ * `workers.database-queue` storage record (the shared `provider_jobs` table).
+ *
+ * Every database access goes through runtime storage; the host binds the
+ * table (Drizzle on D1/libsql in the cloud). A claim is one guarded
+ * `updateMany(id, status='pending')`, so two drainers never take the same
+ * job. Job events fan out through the provider-neutral job-event bridge.
+ */
+import type { StorageRecordInterface } from '@vibesdotdev/storage/interfaces/record';
+import { BaseQueueAdapter, type DequeueOptions, type EnqueueOptions, type Job, type JobEvent, type JobState, type JobStatus, type JobUpdate, type QueueAdapter, type QueueMetrics, type JobExecutionClaim, type JobWriteGuard, type JobRetryOptions, type JobMutationStamp, type KeyedClaimOptions, type KeyedClaimReceipt, type JobListOptions } from '../../core/queue-adapter.ts';
+import type { RuntimeJobEventBridge } from '../../kinds/schemas/job-event-bus.ts';
+import type { Cancellation } from '../../schemas/cancellation.ts';
+import { type DatabaseQueueRow } from './database-queue.record.descriptor.ts';
+export declare class DatabaseQueueAdapter<TJob = unknown, TResult = unknown> extends BaseQueueAdapter<TJob, TResult> implements QueueAdapter<TJob, TResult> {
+    private readonly record;
+    private readonly events;
+    private readonly eventHandlers;
+    /**
+     * In-process job-available listeners (the worker runner). The adapter
+     * shares one queue instance per queue name in a process, so a job this
+     * process enqueues or re-queues wakes its runner at once. A job another
+     * process enqueues has no cross-process notify on this adapter: the
+     * runner's lifecycle-paced poll picks it up.
+     */
+    private readonly availableHandlers;
+    private unsubscribeEvents;
+    constructor(record: StorageRecordInterface<DatabaseQueueRow>, queueName: string, events: RuntimeJobEventBridge);
+    private rowFence;
+    private requireRow;
+    private revisionConflict;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    /**
+     * A caller-supplied id is a dedupe key (keepsCallerAdmission): enqueueing over
+     * a failed or cancelled row resets it with the new input; over a pending,
+     * delayed, processing or completed row it is a no-op, so the enqueue stays idempotent.
+     */
+    enqueue(data: TJob, options?: EnqueueOptions): Promise<string>;
+    /**
+     * Keyed claim (`QueueAdapter.claimKeyed`): the shared rules decide on the
+     * row under the key, and the write is one fenced compare-and-set on that
+     * row (or the insert of an absent key), so claims from processes sharing
+     * the table start one key once. A claim that loses the write reads the
+     * winner's row and decides again.
+     */
+    claimKeyed(data: TJob, options: KeyedClaimOptions): Promise<KeyedClaimReceipt<TJob>>;
+    /** The row under a caller key, refusing a key another queue holds. */
+    private keyedRow;
+    /** A new admission of the job, one generation past the row it replaces. */
+    private admissionRow;
+    /**
+     * Write an admission over exactly the row it was decided on: `false` when a
+     * concurrent writer changed that row, or inserted the absent key, first.
+     */
+    private writeAdmission;
+    private announceAdmission;
+    onJobAvailable(handler: () => void): () => void;
+    private notifyAvailable;
+    dequeue(options?: DequeueOptions): Promise<Job<TJob> | null>;
+    getJob(jobId: string): Promise<Job<TJob> | null>;
+    updateJob(jobId: string, update: JobUpdate, guard: JobWriteGuard): Promise<JobMutationStamp>;
+    renewExecution(jobId: string, claim: JobExecutionClaim): Promise<void>;
+    releaseExecution(jobId: string, claim: JobExecutionClaim): Promise<void>;
+    cancelJob(jobId: string, cancellation: Cancellation): Promise<boolean>;
+    cancelJobGuarded(jobId: string, cancellation: Cancellation, guard: JobWriteGuard): Promise<boolean>;
+    private cancel;
+    retryJob(jobId: string, options: JobRetryOptions): Promise<string>;
+    getStatus(jobId: string): Promise<JobStatus>;
+    listJobs(state?: JobState, options?: JobListOptions): Promise<Job<TJob>[]>;
+    getMetrics(): Promise<QueueMetrics>;
+    subscribeToEvents(jobId: string, handler: (event: JobEvent) => void): () => void;
+    broadcastEvent(jobId: string, event: string, guard: JobWriteGuard, data?: JobEvent['data']): Promise<void>;
+    private toJob;
+    private publish;
+    private emit;
+}
+//# sourceMappingURL=database-queue.d.ts.map

package/dist/adapters/database/database-queue.d.ts.map

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