# `nupp.workers.spi` Shared interfaces for structured worker implementations. The workers module selects an implementation during initialization. A provider owns its lane scheduler, but uses the canonical Scope, Task, Status, and submitted-signature types declared here. A scope is reached only through a task scope's `fork`, which owns one privately. Generic spawn must preserve the exact argument and result packs of the sendable function. Arguments and results cross isolated Lua states as copies. Only explicitly supported engine-backed affine owners move; arbitrary closures, pointers, coroutines, and Lua-owned affine resources cannot be copied as task arguments. Runtime validation must also reject unsupported value graphs that static types cannot exclude. A task's result count preserves embedded and trailing nil values. `await` returns that exact pack or raises failure/cancellation; `isDone` reports terminal settlement, `status` reports scheduler state, and `cancel` reports whether it made the first cancellation request. Scope cleanup settles all children, including those never awaited, before propagating unobserved failure. Cancellation uses `nupp.runtime.cancellation`. Blocking waits cooperate with the selected suspension implementation and must not discover implementations during settlement. Each lane uses the artifact's immutable SPI index and loads independent module instances. Provider objects and Lua closures are never transferred between lanes. ## Types ### `Provider` _interface_ ```nupp interface Provider ... ``` Complete worker implementation protocol, including structured-task integration. Implement generic spawn and ownership guarantees through the shared scope types. #### Members | Name | Kind | Description | | --- | --- | --- | | [`priority`](#nupp.workers.spi.Provider.priority) | field | | | [`openScope`](#nupp.workers.spi.Provider.openScope) | method | Creates canonical scope state for task integration, with an optional monotonic deadline and observer. | | [`settle`](#nupp.workers.spi.Provider.settle) | method | Waits for a task and returns status, packed values, exact count, and problem. | | [`runScheduler`](#nupp.workers.spi.Provider.runScheduler) | method | Runs provider scheduler progress using its retained lane state. | | [`defineSendable`](#nupp.workers.spi.Provider.defineSendable) | method | Associates an executable function with its module/member identity. | | [`describeSendable`](#nupp.workers.spi.Provider.describeSendable) | method | Describes a submitted function and captures for destination-lane execution. | #### `priority` _field_ ```nupp priority: integer? ``` `@readonly` #### `openScope` _method_ ```nupp openScope: function(deadline: number?, observer: any): Scope ``` `@readonly` Creates canonical scope state for task integration, with an optional monotonic deadline and observer. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `deadline` | `number?` | | | `observer` | `any` | | ##### Returns | Type | Description | | --- | --- | | `Scope` | | #### `settle` _method_ ```nupp settle: function(task: any): (string, {any}?, integer, any) ``` `@readonly` Waits for a task and returns status, packed values, exact count, and problem. Status is done, failed, or cancelled; cancellation preserves its shared identity. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `task` | `any` | | ##### Returns | Type | Description | | --- | --- | | `string` | | | `{any}?` | | | `integer` | | | `any` | | #### `runScheduler` _method_ ```nupp runScheduler: function(): nil ``` `@readonly` Runs provider scheduler progress using its retained lane state. ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `defineSendable` _method_ ```nupp defineSendable: function(moduleName: string, member: string, fn: any): nil ``` `@readonly` Associates an executable function with its module/member identity. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `moduleName` | `string` | | | `member` | `string` | | | `fn` | `any` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `describeSendable` _method_ ```nupp describeSendable: function(fn: any, moduleName: string, member: string, ...: any): any ``` `@readonly` Describes a submitted function and captures for destination-lane execution. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `fn` | `any` | | | `moduleName` | `string` | | | `member` | `string` | | | `...` | `any` | | ##### Returns | Type | Description | | --- | --- | | `any` | | ### `Scope` _record_ ```nupp record Scope ... ``` A family of parallel child tasks, owned by the task scope whose `fork` opened it. #### Members | Name | Kind | Description | | --- | --- | --- | | [`spawn`](#nupp.workers.spi.Scope.spawn) | method | Starts one sendable function with copied arguments. | | [`close`](#nupp.workers.spi.Scope.close) | method | Waits for every child, raising the first failure nothing observed. | #### `spawn` _method_ ```nupp spawn: function(borrows self: Scope, ...: unpackof Submitted(F), F): Task ``` Starts one sendable function with copied arguments. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Scope` | | | `...` | `unpackof Submitted(F)` | | | `?` | `F` | | ##### Returns | Type | Description | | --- | --- | | `Task\` | | #### `close` _method_ ```nupp close: function(borrows self: Scope): nil ``` Waits for every child, raising the first failure nothing observed. Idempotent. Under a suspension handler it parks until every child has settled, and without one it blocks. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Scope` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | ### `Status` _type_ ```nupp type Status = "queued" | "running" | "done" | "failed" | "cancelled" ``` Where a task is: waiting to start, running, or settled one of three ways. A closed union, so a `switch` over it needs no `else`. `nupp.tasks` names it `Status`. ### `Submittable` _type_ ```nupp type Submittable = @sendable function(...: any): any ``` What may actually be submitted: a module member, or an outlined literal whose effectively-final captures can be copied to another lane. Exported so a task scope can hold its `fork` to the same bound without linking this module. ### `Task` _type_ ```nupp type Task = TaskType(F) ``` The typed handle for one started function, which `nupp.tasks` names `Task`. Its `await` result pack is the function's, which is why this is derived from the function type rather than declared once over `any`. `status` answers a [`nupp.workers.spi.Status`](#nupp.workers.spi.Status). #### Type parameters | Name | Description | | --- | --- | | `F` | | ## Functions ### `Submitted` _comptime function_ ```nupp @comptime function Submitted(F: type): typepack ``` `@comptime` The arguments a submitted function takes, once its whole signature is known to be copyable. Reached only from `spawn`: naming `Task` describes a handle rather than a crossing, so a signature is held to this where it is submitted and nowhere else. #### Arguments | Name | Type | Description | | --- | --- | --- | | `F` | `type` | | #### Returns | Type | Description | | --- | --- | | `typepack` | |