@plurnk/plurnk-service 1.17.0 → 1.19.0

package/dist/server/Functionality.js

@@ -6,6 +6,7 @@ var _a;
 // generated executor family whose host verbs propose. An explicit
 // client mutation and an accepted model proposal converge on `invoke`.
 import { Validator } from "@plurnk/plurnk-contracts";
+import discoverySchema from "@plurnk/plurnk-contracts/schema/FunctionalityDiscoverQuery.json" with { type: "json" };
 import { isDeepStrictEqual } from "node:util";
 import { DocFile } from "@plurnk/plurnk-execs";
 import FunctionalityManager, { FUNCTIONALITY_VERBS, functionalityRuntimeDecl, } from "./FunctionalityManager.js";
@@ -14,6 +15,10 @@ import { generatedPathname } from "../core/plurnk-uri.js";
 const STATE_VERSION = 1;
 const FAMILY = /^[a-z][a-z0-9]*$/u;
 const ALIAS = /^[a-z][a-z0-9-]*$/u;
+// A family may declare its own alias grammar ({§functionality-adapter}); the coordinator enforces it
+// wherever an alias enters: admission, the service projection, and persisted state.
+const aliasPattern = (adapter) => adapter.aliasPattern ?? ALIAS;
+const scopesOf = (adapter) => adapter.scopes ?? ["workspace"];
 const EMPTY_STATE = Object.freeze({ version: STATE_VERSION, definitions: Object.freeze({}) });
 const SCHEMA = (name) => ({ $ref: `https://schemas.plurnk.xyz/v0/${name}.json` });
 const ALIAS_INPUT = Object.freeze({
@@ -49,21 +54,37 @@ class Functionality {
             throw new Error(`Functionality namespace owner '${namespaceOwner}' is already registered.`);
         if (!isRecord(adapter.definitionSchema))
             throw new Error(`Functionality family '${family}' requires a definition schema.`);
+        const scopes = scopesOf(adapter);
+        if (scopes.length === 0 || new Set(scopes).size !== scopes.length || scopes.some((scope) => scope !== "workspace" && scope !== "worker")) {
+            throw new Error(`Functionality family '${family}' declares invalid scopes.`);
+        }
+        const scopeProperties = scopes.length > 1
+            ? { scope: { enum: [...scopes], description: `Definition scope; model calls default to ${scopes[0]}.` } }
+            : {};
+        const scopedInput = (schema) => {
+            if (scopes.length === 1)
+                return schema;
+            const { $id: _id, ...source } = schema;
+            if (!isRecord(source.properties))
+                throw new Error(`Functionality ${family} input has no property map.`);
+            return { ...source, properties: { ...source.properties, ...scopeProperties } };
+        };
         const schemas = Object.freeze({
-            list: EMPTY_INPUT,
-            discover: SCHEMA("FunctionalityDiscoverQuery"),
+            list: scopedInput(EMPTY_INPUT),
+            discover: scopes.length === 1 ? SCHEMA("FunctionalityDiscoverQuery") : scopedInput(discoverySchema),
             add: Object.freeze({
                 type: "object",
                 additionalProperties: false,
                 required: ["definition"],
                 properties: {
+                    ...scopeProperties,
                     alias: { type: "string", minLength: 1 },
                     definition: adapter.definitionSchema,
                 },
             }),
-            enable: ALIAS_INPUT,
-            disable: ALIAS_INPUT,
-            remove: ALIAS_INPUT,
+            enable: scopedInput(ALIAS_INPUT),
+            disable: scopedInput(ALIAS_INPUT),
+            remove: scopedInput(ALIAS_INPUT),
         });
         // {§functionality-model-projection} — the taught `add` example must satisfy the schema it teaches.
         if (adapter.example !== undefined) {
@@ -79,23 +100,28 @@ class Functionality {
             activate: (context) => this.#activate(adapter, context),
             deactivate: (identity) => this.#deactivate(adapter, identity),
         });
-        for (const verb of FUNCTIONALITY_VERBS) {
-            this.#host.registerModuleAction({
-                name: `workspace.${family}.${verb}`,
-                scope: "workspace",
-                inputSchema: schemas[verb],
-                outputSchema: SCHEMA(verb === "list"
-                    ? "FunctionalityListResult"
-                    : verb === "discover"
-                        ? "FunctionalityDiscoverResult"
-                        : "FunctionalityMutationResult"),
-                handler: async (params, context) => {
-                    if (context.scope !== "workspace")
-                        throw new Error(`workspace.${family}.${verb} requires a workspace-scoped context.`);
-                    const { workspaceId } = context;
-                    return (await this.invoke(family, verb, params, { workspaceId }, "action")).body;
-                },
-            });
+        // {§functionality-scope} The action context binds one of the family's supported scopes.
+        for (const scope of scopes) {
+            for (const verb of FUNCTIONALITY_VERBS) {
+                this.#host.registerModuleAction({
+                    name: `${scope}.${family}.${verb}`,
+                    scope,
+                    inputSchema: schemas[verb],
+                    outputSchema: SCHEMA(verb === "list"
+                        ? "FunctionalityListResult"
+                        : verb === "discover"
+                            ? "FunctionalityDiscoverResult"
+                            : "FunctionalityMutationResult"),
+                    handler: async (params, context) => {
+                        if (context.scope === "worldless" || context.scope !== scope)
+                            throw new Error(`${scope}.${family}.${verb} requires a ${scope}-scoped context.`);
+                        const identity = context.scope === "worker"
+                            ? { workspaceId: context.workspaceId, workerId: context.workerId, scope }
+                            : { workspaceId: context.workspaceId, scope };
+                        return (await this.invoke(family, verb, params, identity, "action")).body;
+                    },
+                });
+            }
         }
         return {
             invoke: (verb, params, identity) => this.invoke(family, verb, params, identity, "action"),
@@ -109,7 +135,7 @@ class Functionality {
     // workspace exclusivity it could never win.
     async refresh(family, identity, options = {}) {
         const adapter = this.#adapter(family);
-        await this.#serialize(identity.workspaceId, family, async () => {
+        await this.#serialize(this.#key(identity.workspaceId, family), async () => {
             const current = this.#families.get(this.#key(identity.workspaceId, family));
             if (current === undefined)
                 return;
@@ -158,7 +184,7 @@ class Functionality {
         return out;
     }
     // The one lifecycle entry for both projections ({§functionality-model-mutation}).
-    async invoke(family, verb, params, identity, caller) {
+    async invoke(family, verb, params, identity, caller, options = {}) {
         const adapter = this.#adapter(family);
         const schema = this.#schemas.get(family)[verb];
         const validation = Validator.validateJsonSchemaInstance(schema, params);
@@ -170,11 +196,38 @@ class Functionality {
             });
         }
         const input = params;
-        switch (verb) {
-            case "list": return { status: 200, body: await this.#list(adapter, identity) };
-            case "discover": return { status: 200, body: await this.#discover(adapter, input, identity) };
-            default: return this.#host.mutateWorkspace(identity.workspaceId, adapter.namespaceOwner, caller, () => this.#serialize(identity.workspaceId, family, () => this.#mutate(adapter, verb, input, identity, caller)));
+        const scope = (input.scope ?? identity.scope ?? scopesOf(adapter)[0]);
+        if (!scopesOf(adapter).includes(scope) || (identity.scope !== undefined && identity.scope !== scope)) {
+            throw failure(family, "scope-mismatch", 400, `The ${family} operation's scope does not match its bound context.`, { retryable: false });
+        }
+        identity = { ...identity, scope };
+        if (verb === "discover") {
+            const { scope: _scope, ...query } = input;
+            return { status: 200, body: await this.#discover(adapter, query, identity, options) };
         }
+        // {§functionality-scope} — a worker-scoped family's list and mutations act for the invoking
+        // Worker. The state is that Worker's and nothing resident changes, so they serialize on the
+        // Worker's own lane and take no workspace exclusivity: a Worker shapes its environment while
+        // its siblings run.
+        if (scope === "worker") {
+            const workerId = _a.#workerOf(adapter, identity);
+            return this.#serialize(`${this.#key(identity.workspaceId, family)}:${workerId}`, () => this.#invokeForWorker(adapter, verb, input, identity, workerId, caller, options));
+        }
+        if (verb === "list")
+            return { status: 200, body: await this.#list(adapter, identity) };
+        return this.#host.mutateWorkspace(identity.workspaceId, adapter.namespaceOwner, caller, () => this.#serialize(this.#key(identity.workspaceId, family), () => this.#mutate(adapter, verb, input, identity, caller, options)));
+    }
+    // A worker-scoped verb that names no Worker is a defect at the projection, never a client
+    // failure: both projections name the Worker ({§functionality-model-projection}).
+    static #workerOf(adapter, identity) {
+        if (identity.workerId === undefined)
+            throw new Error(`${adapter.family} is worker-scoped; the invocation names no Worker.`);
+        return identity.workerId;
+    }
+    // The origin a definition carries when this family owns it locally. Service definitions
+    // always come from the adapter's own `available()`; everything else is the family's own.
+    static #localOrigin(identity) {
+        return identity.scope ?? "workspace";
     }
     #adapter(family) {
         const adapter = this.#adapters.get(family);
@@ -185,8 +238,7 @@ class Functionality {
     #key(workspaceId, family) {
         return `${workspaceId}:${family}`;
     }
-    #serialize(workspaceId, family, work) {
-        const key = this.#key(workspaceId, family);
+    #serialize(key, work) {
         const previous = this.#queues.get(key) ?? Promise.resolve();
         const next = previous.catch(() => undefined).then(work);
         this.#queues.set(key, next);
@@ -194,13 +246,13 @@ class Functionality {
     }
     async #activate(adapter, context) {
         const identity = { workspaceId: context.workspaceId };
-        await this.#serialize(identity.workspaceId, adapter.family, async () => {
+        await this.#serialize(this.#key(identity.workspaceId, adapter.family), async () => {
             const state = await this.#loadState(adapter, identity.workspaceId);
             await this.#publish(adapter, identity, state, { failure: "publish-unavailable", retain: context.retain, gate: "none" });
         });
     }
     async #deactivate(adapter, identity) {
-        await this.#serialize(identity.workspaceId, adapter.family, async () => {
+        await this.#serialize(this.#key(identity.workspaceId, adapter.family), async () => {
             const key = this.#key(identity.workspaceId, adapter.family);
             const family = this.#families.get(key);
             this.#families.delete(key);
@@ -210,30 +262,42 @@ class Functionality {
         });
     }
     async #loadState(adapter, workspaceId) {
-        const raw = await this.#host.readWorkspaceModuleState(workspaceId, adapter.namespaceOwner);
+        return _a.#parseState(adapter, await this.#host.readWorkspaceModuleState(workspaceId, adapter.namespaceOwner), `workspace ${workspaceId}`, "workspace");
+    }
+    async #loadWorkerState(adapter, workerId) {
+        return _a.#parseState(adapter, await this.#host.readWorkerModuleState(workerId, adapter.namespaceOwner), `worker ${workerId}`, "worker");
+    }
+    static #parseState(adapter, raw, where, scope) {
         if (raw === null)
             return EMPTY_STATE;
         if (!isRecord(raw) || raw.version !== STATE_VERSION || !isRecord(raw.definitions)) {
-            throw new Error(`Functionality state for ${adapter.family} in workspace ${workspaceId} is not a version ${STATE_VERSION} record.`);
+            throw new Error(`Functionality state for ${adapter.family} in ${where} is not a version ${STATE_VERSION} record.`);
         }
         const definitions = {};
         for (const [alias, value] of Object.entries(raw.definitions)) {
-            if (!ALIAS.test(alias) || !isRecord(value))
+            if (!aliasPattern(adapter).test(alias) || !isRecord(value))
                 throw new Error(`Functionality state for ${adapter.family} has an invalid alias '${alias}'.`);
-            const { origin, enabled, definition } = value;
-            if ((origin !== "service" && origin !== "workspace") || typeof enabled !== "boolean") {
+            const { origin, enabled, definition, inherited } = value;
+            if ((origin !== "service" && origin !== "workspace" && origin !== "worker") || typeof enabled !== "boolean") {
                 throw new Error(`Functionality state for ${adapter.family} alias '${alias}' is malformed.`);
             }
-            if (origin === "workspace") {
+            if (origin !== "service" && origin !== scope && !(scope === "worker" && origin === "workspace" && scopesOf(adapter).includes("workspace"))) {
+                throw new Error(`Functionality state for ${adapter.family} alias '${alias}' has an invalid origin for ${scope} scope.`);
+            }
+            if (inherited !== undefined && (typeof inherited !== "string" || inherited.length === 0 || scope !== "worker")) {
+                throw new Error(`Functionality state for ${adapter.family} alias '${alias}' carries an invalid inheritance.`);
+            }
+            const provenance = inherited === undefined ? {} : { inherited };
+            if (origin === scope) {
                 const result = Validator.validateJsonSchemaInstance(adapter.definitionSchema, definition);
                 if (!result.valid)
                     throw new Error(`Functionality state for ${adapter.family} alias '${alias}' holds an invalid definition.`);
-                definitions[alias] = { origin, enabled, definition: definition };
+                definitions[alias] = { origin, enabled, definition: definition, ...provenance };
             }
             else {
                 if (definition !== undefined)
-                    throw new Error(`Functionality state for ${adapter.family} alias '${alias}' persists a service definition.`);
-                definitions[alias] = { origin, enabled };
+                    throw new Error(`Functionality state for ${adapter.family} alias '${alias}' persists a lower-layer definition.`);
+                definitions[alias] = { origin, enabled, ...provenance };
             }
         }
         return { version: STATE_VERSION, definitions };
@@ -243,33 +307,41 @@ class Functionality {
     }
     async #effective(adapter, identity, state) {
         const effective = new Map();
-        for (const service of await adapter.available(identity)) {
-            if (!ALIAS.test(service.alias))
-                throw new Error(`${adapter.family} service alias '${service.alias}' must match ${ALIAS}.`);
+        const local = _a.#localOrigin(identity);
+        const inheritsWorkspace = identity.scope === "worker" && scopesOf(adapter).includes("workspace");
+        const lower = inheritsWorkspace
+            ? [...(await this.#effective(adapter, { workspaceId: identity.workspaceId, scope: "workspace" }, await this.#loadState(adapter, identity.workspaceId))).values()]
+            : (await adapter.available(identity)).map((entry) => ({ ...entry, origin: "service" }));
+        for (const service of lower) {
+            if (!aliasPattern(adapter).test(service.alias))
+                throw new Error(`${adapter.family} service alias '${service.alias}' must match ${aliasPattern(adapter)}.`);
             const record = state.definitions[service.alias];
-            const enabled = record?.origin === "service" ? record.enabled : service.enabled;
-            effective.set(service.alias, { alias: service.alias, origin: "service", definition: service.definition, enabled });
+            const overlay = record !== undefined && record.origin !== local ? record : undefined;
+            const enabled = overlay === undefined ? service.enabled : overlay.enabled && (!inheritsWorkspace || service.enabled);
+            const inherited = overlay?.inherited === undefined ? {} : { inherited: overlay.inherited };
+            effective.set(service.alias, { alias: service.alias, origin: service.origin, definition: service.definition, enabled, ...inherited });
         }
         for (const [alias, record] of Object.entries(state.definitions)) {
-            if (record.origin !== "workspace")
+            if (record.origin !== local)
                 continue;
-            effective.set(alias, { alias, origin: "workspace", definition: record.definition, enabled: record.enabled });
+            const inherited = record.inherited === undefined ? {} : { inherited: record.inherited };
+            effective.set(alias, { alias, origin: local, definition: record.definition, enabled: record.enabled, ...inherited });
         }
         return new Map([...effective].toSorted(([left], [right]) => left.localeCompare(right)));
     }
     #projection(definition, outcome) {
-        if (!definition.enabled) {
-            return { alias: definition.alias, origin: definition.origin, state: "disabled", definition: definition.definition };
-        }
+        const base = {
+            alias: definition.alias, origin: definition.origin, definition: definition.definition,
+            ...(definition.inherited === undefined ? {} : { inherited: definition.inherited }),
+        };
+        if (!definition.enabled)
+            return { ...base, state: "disabled" };
         if (outcome === undefined)
             throw new Error(`enabled ${definition.alias} has no preparation outcome`);
         switch (outcome.state) {
-            case "active": return {
-                alias: definition.alias, origin: definition.origin, state: "active", definition: definition.definition,
-                ...(outcome.detail === undefined ? {} : { detail: outcome.detail }),
-            };
-            case "unavailable": return { alias: definition.alias, origin: definition.origin, state: "unavailable", definition: definition.definition, problem: outcome.problem };
-            case "authorization-required": return { alias: definition.alias, origin: definition.origin, state: "authorization-required", definition: definition.definition, authorization: outcome.authorization };
+            case "active": return { ...base, state: "active", ...(outcome.detail === undefined ? {} : { detail: outcome.detail }) };
+            case "unavailable": return { ...base, state: "unavailable", problem: outcome.problem };
+            case "authorization-required": return { ...base, state: "authorization-required", authorization: outcome.authorization };
         }
     }
     async #list(adapter, identity) {
@@ -283,34 +355,33 @@ class Functionality {
             definitions: [...effective.values()].map((definition) => this.#projection(definition, outcomes.get(definition.alias))),
         });
     }
-    async #discover(adapter, query, identity) {
-        const candidates = await adapter.discover(query, identity);
+    async #discover(adapter, query, identity, options) {
+        const candidates = await adapter.discover(query, identity, options);
         return Validator.assertFunctionalityDiscoverResult({ family: adapter.family, candidates: [...candidates] });
     }
-    async #mutate(adapter, verb, input, identity, caller) {
-        const key = this.#key(identity.workspaceId, adapter.family);
-        const family = this.#families.get(key);
-        if (family === undefined)
-            throw failure(adapter.family, "workspace-not-resident", 409, `Workspace ${identity.workspaceId} has no resident ${adapter.family} Functionality.`, { recovery: "Retry through a workspace operation, then retry.", retryable: false });
-        const effective = await this.#effective(adapter, identity, family.state);
-        const definitions = { ...family.state.definitions };
+    // The verb semantics, one implementation for every family ({§functionality-scope}): the next
+    // state, the alias it concerns, and how the mutation reports. Only publication differs by scope.
+    async #transition(adapter, verb, input, identity, caller, state, effective, options) {
+        const local = _a.#localOrigin(identity);
+        const here = local === "worker" ? "this worker" : "this workspace";
+        const definitions = { ...state.definitions };
         let alias;
         let status = 200;
         let removed = false;
         switch (verb) {
             case "add": {
-                const admitted = await adapter.admit(input, identity, caller);
+                const admitted = await adapter.admit(input, identity, caller, options);
                 alias = admitted.alias;
-                if (!ALIAS.test(alias))
-                    throw failure(adapter.family, "alias-invalid", 400, `Alias '${alias}' must match ${ALIAS}.`, { alias, retryable: false });
-                // A workspace definition may shadow a service definition of the same
+                if (!aliasPattern(adapter).test(alias))
+                    throw failure(adapter.family, "alias-invalid", 400, `Alias '${alias}' must match ${aliasPattern(adapter)}.`, { alias, retryable: false });
+                // A local definition may shadow a service definition of the same
                 // alias; removing it reveals the service baseline again, disabled.
                 const current = effective.get(alias);
-                if (current?.origin === "workspace" && !isDeepStrictEqual(current.definition, admitted.definition)) {
-                    throw failure(adapter.family, "alias-exists", 409, `'${alias}' already has a different workspace definition.`, { alias, recovery: "Use the existing definition, or remove it before adding its replacement.", retryable: false });
+                if (current?.origin === local && !isDeepStrictEqual(current.definition, admitted.definition)) {
+                    throw failure(adapter.family, "alias-exists", 409, `'${alias}' already has a different ${local} definition.`, { alias, recovery: "Use the existing definition, or remove it before adding its replacement.", retryable: false });
                 }
-                definitions[alias] = { origin: "workspace", definition: admitted.definition, enabled: true };
-                status = current?.origin === "workspace" ? 200 : 201;
+                definitions[alias] = { origin: local, definition: admitted.definition, enabled: true };
+                status = current?.origin === local ? 200 : 201;
                 break;
             }
             case "enable":
@@ -318,42 +389,36 @@ class Functionality {
                 alias = input.alias;
                 const current = effective.get(alias);
                 if (current === undefined)
-                    throw failure(adapter.family, "alias-unknown", 404, `'${alias}' is not available to this workspace.`, { alias, retryable: false });
-                definitions[alias] = current.origin === "workspace"
-                    ? { origin: "workspace", definition: current.definition, enabled: verb === "enable" }
-                    : { origin: "service", enabled: verb === "enable" };
+                    throw failure(adapter.family, "alias-unknown", 404, `'${alias}' is not available to ${here}.`, { alias, retryable: false });
+                definitions[alias] = current.origin === local
+                    ? { origin: local, definition: current.definition, enabled: verb === "enable" }
+                    : { origin: current.origin, enabled: verb === "enable" };
                 break;
             }
             case "remove": {
                 alias = input.alias;
                 const current = effective.get(alias);
                 if (current === undefined)
-                    throw failure(adapter.family, "alias-unknown", 404, `'${alias}' is not available to this workspace.`, { alias, retryable: false });
+                    throw failure(adapter.family, "alias-unknown", 404, `'${alias}' is not available to ${here}.`, { alias, retryable: false });
                 if (current.origin === "service")
                     throw failure(adapter.family, "alias-service-owned", 409, `'${alias}' is a service definition and cannot be removed here.`, { alias, recovery: `Disable it, or change the service configuration that contributes it.`, retryable: false });
+                if (current.origin !== local)
+                    throw failure(adapter.family, "alias-workspace-owned", 409, `'${alias}' is a workspace definition; remove it in workspace scope or disable it here.`, { alias, retryable: false });
                 await adapter.forget?.({ alias, definition: current.definition }, identity);
                 delete definitions[alias];
-                const revealed = (await adapter.available(identity)).some((service) => service.alias === alias);
+                const revealed = (await this.#effective(adapter, identity, EMPTY_STATE)).get(alias);
                 if (revealed)
-                    definitions[alias] = { origin: "service", enabled: false };
+                    definitions[alias] = { origin: revealed.origin, enabled: false };
                 removed = true;
                 break;
             }
             default: throw new Error(`unreachable verb ${verb}`);
         }
-        const nextState = { version: STATE_VERSION, definitions };
-        // Re-enabling an alias that is not active retries its preparation; an
-        // already-active alias keeps its live attachment.
-        const retry = verb === "enable" && family.prepared?.outcomes.get(alias)?.state !== "active";
-        const publication = await this.#publish(adapter, identity, nextState, {
-            failure: caller === "action" ? "reject" : "publish-unavailable",
-            retain: () => this.#host.retainWorkspace(identity.workspaceId),
-            gate: "none",
-            forceAlias: retry ? alias : null,
-        });
-        const effectiveAfter = await this.#effective(adapter, identity, nextState);
+        return { definitions, alias, status, removed };
+    }
+    #mutationResult(adapter, { alias, status, removed }, effectiveAfter, outcomes) {
         const definition = effectiveAfter.get(alias);
-        const projection = definition === undefined ? undefined : this.#projection(definition, publication.outcomes.get(alias));
+        const projection = definition === undefined ? undefined : this.#projection(definition, outcomes.get(alias));
         const body = Validator.assertFunctionalityMutationResult({
             status: projection?.state === "authorization-required" ? 202 : status,
             family: adapter.family,
@@ -363,6 +428,89 @@ class Functionality {
         });
         return { status: body.status, body };
     }
+    async #mutate(adapter, verb, input, identity, caller, options) {
+        const key = this.#key(identity.workspaceId, adapter.family);
+        const family = this.#families.get(key);
+        if (family === undefined)
+            throw failure(adapter.family, "workspace-not-resident", 409, `Workspace ${identity.workspaceId} has no resident ${adapter.family} Functionality.`, { recovery: "Retry through a workspace operation, then retry.", retryable: false });
+        const effective = await this.#effective(adapter, identity, family.state);
+        const transition = await this.#transition(adapter, verb, input, identity, caller, family.state, effective, options);
+        const nextState = { version: STATE_VERSION, definitions: transition.definitions };
+        // Re-enabling an alias that is not active retries its preparation; an
+        // already-active alias keeps its live attachment.
+        const retry = verb === "enable" && family.prepared?.outcomes.get(transition.alias)?.state !== "active";
+        const publication = await this.#publish(adapter, identity, nextState, {
+            failure: caller === "action" ? "reject" : "publish-unavailable",
+            retain: () => this.#host.retainWorkspace(identity.workspaceId),
+            gate: "none",
+            forceAlias: retry ? transition.alias : null,
+        });
+        const effectiveAfter = await this.#effective(adapter, identity, nextState);
+        return this.#mutationResult(adapter, transition, effectiveAfter, publication.outcomes);
+    }
+    // {§functionality-scope} — the Worker's own lane. State is read at each verb rather than held: the
+    // spawn reads the same row, and a Worker's row is written at its creation, so nothing in memory
+    // could be more current than the table.
+    async #invokeForWorker(adapter, verb, input, identity, workerId, caller, options) {
+        if (!this.#families.has(this.#key(identity.workspaceId, adapter.family)))
+            throw failure(adapter.family, "workspace-not-resident", 409, `Workspace ${identity.workspaceId} has no resident ${adapter.family} Functionality.`, { recovery: "Retry through a workspace operation, then retry.", retryable: false });
+        const state = await this.#loadWorkerState(adapter, workerId);
+        const effective = await this.#effective(adapter, identity, state);
+        if (verb === "list") {
+            const prepared = await this.#prepareForWorker(adapter, identity, effective, "publish-unavailable");
+            await prepared.commit();
+            return { status: 200, body: Validator.assertFunctionalityListResult({
+                    family: adapter.family,
+                    definitions: [...effective.values()].map((definition) => this.#projection(definition, prepared.outcomes.get(definition.alias))),
+                }) };
+        }
+        const transition = await this.#transition(adapter, verb, input, identity, caller, state, effective, options);
+        const nextState = { version: STATE_VERSION, definitions: transition.definitions };
+        const effectiveAfter = await this.#effective(adapter, identity, nextState);
+        const prepared = await this.#prepareForWorker(adapter, identity, effectiveAfter, caller === "action" ? "reject" : "publish-unavailable");
+        try {
+            await this.#host.replaceWorkerModuleState(workerId, adapter.namespaceOwner, _a.#persisted(nextState));
+        }
+        catch (cause) {
+            return _a.#abort(prepared, cause);
+        }
+        await prepared.commit();
+        return this.#mutationResult(adapter, transition, effectiveAfter, prepared.outcomes);
+    }
+    // A worker-scoped family's preparation yields outcomes only. It holds no residency — no runtimes,
+    // documents or snapshot ({§module-workspace-residency}) — because its definitions are read at the
+    // spawn that uses them rather than leased and cooled; the coordinator enforces that here.
+    async #prepareForWorker(adapter, identity, effective, failureMode) {
+        const enabled = _a.#enabled(effective);
+        const prepared = await adapter.prepare({
+            workspaceId: identity.workspaceId, enabled, previous: null, failure: failureMode,
+            retain: () => this.#host.retainWorkspace(identity.workspaceId),
+        });
+        try {
+            _a.#checkOutcomes(adapter, enabled, prepared);
+            if ((prepared.runtimes?.length ?? 0) > 0 || prepared.documents.length > 0 || prepared.snapshot !== null) {
+                throw new Error(`${adapter.family} is worker-scoped and holds no residency, yet its preparation published runtimes, documents or a snapshot.`);
+            }
+        }
+        catch (cause) {
+            return _a.#abort(prepared, cause);
+        }
+        return prepared;
+    }
+    static #enabled(effective) {
+        const enabled = new Map();
+        for (const definition of effective.values()) {
+            if (definition.enabled)
+                enabled.set(definition.alias, definition.definition);
+        }
+        return enabled;
+    }
+    static #checkOutcomes(adapter, enabled, prepared) {
+        for (const alias of enabled.keys()) {
+            if (!prepared.outcomes.has(alias))
+                throw new Error(`${adapter.family} preparation reported no outcome for enabled alias '${alias}'.`);
+        }
+    }
     // {§functionality-publication} — prepare, publish runtimes and state in one
     // host replacement, then commit; on any failure abort and keep the previous
     // snapshot authoritative. An execution stream stays pending until its
@@ -370,12 +518,10 @@ class Functionality {
     async #publish(adapter, identity, nextState, options) {
         const key = this.#key(identity.workspaceId, adapter.family);
         const previous = this.#families.get(key)?.prepared ?? null;
-        const effective = await this.#effective(adapter, identity, nextState);
-        const enabled = new Map();
-        for (const definition of effective.values()) {
-            if (definition.enabled)
-                enabled.set(definition.alias, definition.definition);
-        }
+        // A worker-scoped family's workspace publication carries only its manager: what is enabled
+        // is decided per Worker, at each verb and each spawn ({§functionality-scope}).
+        const effective = !scopesOf(adapter).includes("workspace") ? new Map() : await this.#effective(adapter, { ...identity, scope: "workspace" }, nextState);
+        const enabled = _a.#enabled(effective);
         const prepared = await adapter.prepare({
             workspaceId: identity.workspaceId,
             enabled,
@@ -386,11 +532,8 @@ class Functionality {
         });
         let runtimes;
         try {
-            for (const alias of enabled.keys()) {
-                if (!prepared.outcomes.has(alias))
-                    throw new Error(`${adapter.family} preparation reported no outcome for enabled alias '${alias}'.`);
-            }
-            for (const runtime of prepared.runtimes) {
+            _a.#checkOutcomes(adapter, enabled, prepared);
+            for (const runtime of prepared.runtimes ?? []) {
                 if (runtime.namespaceOwner !== adapter.namespaceOwner) {
                     throw new Error(`${adapter.family} prepared a runtime owned by '${runtime.namespaceOwner}' instead of '${adapter.namespaceOwner}'.`);
                 }
@@ -400,11 +543,12 @@ class Functionality {
                 decl: functionalityRuntimeDecl(adapter.family, adapter.summary, await this.#documentBody(adapter)),
                 executor: new FunctionalityManager({
                     family: adapter.family, workspaceId: identity.workspaceId, coordinator: this,
-                    inputSchemas: this.#schemas.get(adapter.family), example: adapter.example, discovery: adapter.discovery,
+                    traits: adapter.traits, inputSchemas: this.#schemas.get(adapter.family), example: adapter.example, discovery: adapter.discovery,
                 }),
                 availability: { available: true, detail: "workspace Functionality manager" },
+                ...(adapter.scheme === undefined ? {} : { scheme: adapter.scheme }),
             };
-            runtimes = [manager, ...prepared.runtimes];
+            runtimes = [manager, ...(prepared.runtimes ?? [])];
         }
         catch (cause) {
             return _a.#abort(prepared, cause);