@plurnk/plurnk-service 1.16.5 → 1.18.0

package/dist/server/Functionality.js

@@ -1,17 +1,22 @@
 var _a;
-// {§functionality-coordinator} — the one owner of the Worker Functionality
+// {§functionality-coordinator} — the one owner of the workspace Functionality
 // lifecycle above the family adapters (Agent Skills, MCP, outbound A2A). It owns
-// durable per-Worker state, lifecycle ordering, serialization, atomic
-// publication, and both projections: worker-scoped client actions and a
-// per-Worker generated executor family whose host verbs propose. An explicit
+// durable workspace state, lifecycle ordering, serialization, atomic
+// publication, and both projections: workspace-scoped client actions and 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 { isDeepStrictEqual } from "node:util";
+import { DocFile } from "@plurnk/plurnk-execs";
 import FunctionalityManager, { FUNCTIONALITY_VERBS, functionalityRuntimeDecl, } from "./FunctionalityManager.js";
 import Results, { OperationFailureError } from "../core/results.js";
 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 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({
@@ -34,7 +39,7 @@ class Functionality {
         this.#host = host;
     }
     // {§functionality-adapter} — registration publishes the family's client
-    // actions and its Worker capability provider at once.
+    // actions and its workspace capability provider at once.
     register(adapter) {
         const { family, namespaceOwner } = adapter;
         if (!FAMILY.test(family))
@@ -63,17 +68,28 @@ class Functionality {
             disable: ALIAS_INPUT,
             remove: ALIAS_INPUT,
         });
+        // {§functionality-model-projection} — the taught `add` example must satisfy the schema it teaches.
+        if (adapter.example !== undefined) {
+            const example = Validator.validateJsonSchemaInstance(schemas.add, adapter.example);
+            if (!example.valid) {
+                throw new Error(`Functionality family '${family}' teaches an add example that violates its own definition schema: ${JSON.stringify(example.errors)}`);
+            }
+        }
         this.#adapters.set(family, adapter);
         this.#owners.add(namespaceOwner);
         this.#schemas.set(family, schemas);
-        this.#host.registerWorkerCapabilityProvider(namespaceOwner, {
+        this.#host.registerWorkspaceCapabilityProvider(namespaceOwner, {
             activate: (context) => this.#activate(adapter, context),
             deactivate: (identity) => this.#deactivate(adapter, identity),
         });
+        // {§functionality-scope} — a worker-scoped family projects `worker.<family>.<verb>`, whose
+        // context names the Worker the verb acts for; every other family projects
+        // `workspace.<family>.<verb>`. One implementation sits beneath both.
+        const scope = adapter.scope ?? "workspace";
         for (const verb of FUNCTIONALITY_VERBS) {
             this.#host.registerModuleAction({
-                name: `worker.${family}.${verb}`,
-                scope: "worker",
+                name: `${scope}.${family}.${verb}`,
+                scope,
                 inputSchema: schemas[verb],
                 outputSchema: SCHEMA(verb === "list"
                     ? "FunctionalityListResult"
@@ -81,10 +97,12 @@ class Functionality {
                         ? "FunctionalityDiscoverResult"
                         : "FunctionalityMutationResult"),
                 handler: async (params, context) => {
-                    if (context.scope !== "worker")
-                        throw new Error(`worker.${family}.${verb} requires a worker-scoped context.`);
-                    const { workspaceId, workerId } = context;
-                    return (await this.invoke(family, verb, params, { workspaceId, workerId }, "action")).body;
+                    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 }
+                        : { workspaceId: context.workspaceId };
+                    return (await this.invoke(family, verb, params, identity, "action")).body;
                 },
             });
         }
@@ -93,20 +111,20 @@ class Functionality {
             refresh: (identity, options) => this.refresh(family, identity, options),
         };
     }
-    // Republish a family's unchanged state for one Worker — a live catalog
+    // Republish a family's unchanged state for one workspace — a live catalog
     // change, not a lifecycle mutation. Serialized like every publication.
     // `gate: "none"` publishes inside the caller's own held turn (turn admission
     // refreshing a family before packet assembly) instead of contending for
     // workspace exclusivity it could never win.
     async refresh(family, identity, options = {}) {
         const adapter = this.#adapter(family);
-        await this.#serialize(identity.workerId, family, async () => {
-            const current = this.#families.get(this.#key(identity.workerId, family));
+        await this.#serialize(this.#key(identity.workspaceId, family), async () => {
+            const current = this.#families.get(this.#key(identity.workspaceId, family));
             if (current === undefined)
                 return;
             await this.#publish(adapter, identity, current.state, {
                 failure: "publish-unavailable",
-                retain: () => this.#host.retainWorker(identity.workerId),
+                retain: () => this.#host.retainWorkspace(identity.workspaceId),
                 gate: options.gate ?? "wait",
             });
         });
@@ -114,20 +132,33 @@ class Functionality {
     families() {
         return [...this.#adapters.keys()].toSorted();
     }
-    // Await every queued publication (boundary publications included). Shutdown
-    // and tests settle before inspecting or closing durable state.
-    async settle(workerId) {
+    // Join outstanding invocations before inspecting or closing durable state.
+    // Rejections have already been delivered to their action or execution stream.
+    async settle(workspaceId) {
         const pending = [...this.#queues]
-            .filter(([key]) => workerId === undefined || key.startsWith(`${workerId}:`))
+            .filter(([key]) => workspaceId === undefined || key.startsWith(`${workspaceId}:`))
             .map(([, queue]) => queue.catch(() => undefined));
         await Promise.all(pending);
     }
     // {§functionality-documents} — the family-generated documents of every
-    // published family for one Worker, addressed under its generated subtree.
-    documents(workerId) {
+    // published family for one workspace, projected under each reader's generated subtree.
+    // {§functionality-document-body} — read once per family from the adapter's package, the same
+    // `docs/<tag>.md` rule runtimes use. A family that ships no file has a header-only document.
+    #documentBodies = new Map();
+    #documentBody(adapter) {
+        let body = this.#documentBodies.get(adapter.family);
+        if (body === undefined) {
+            body = adapter.docsDir === undefined
+                ? Promise.resolve("")
+                : DocFile.read(adapter.docsDir, adapter.family).then((text) => text ?? "");
+            this.#documentBodies.set(adapter.family, body);
+        }
+        return body;
+    }
+    documents(workspaceId) {
         const out = [];
         for (const [key, family] of this.#families) {
-            if (!key.startsWith(`${workerId}:`) || family.prepared === null)
+            if (!key.startsWith(`${workspaceId}:`) || family.prepared === null)
                 continue;
             for (const document of family.prepared.documents) {
                 out.push({ pathname: generatedPathname(document.pathname), content: document.content });
@@ -148,11 +179,31 @@ 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.#serialize(identity.workerId, family, () => this.#mutate(adapter, verb, input, identity, caller));
+        if (verb === "discover")
+            return { status: 200, body: await this.#discover(adapter, input, identity) };
+        // {§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 (adapter.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));
         }
+        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)));
+    }
+    // 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(adapter) {
+        return adapter.scope === "worker" ? "worker" : "workspace";
     }
     #adapter(family) {
         const adapter = this.#adapters.get(family);
@@ -160,26 +211,25 @@ class Functionality {
             throw failure(family, "family-unknown", 404, `No Functionality family '${family}' is registered.`, { retryable: false });
         return adapter;
     }
-    #key(workerId, family) {
-        return `${workerId}:${family}`;
+    #key(workspaceId, family) {
+        return `${workspaceId}:${family}`;
     }
-    #serialize(workerId, family, work) {
-        const key = this.#key(workerId, family);
+    #serialize(key, work) {
         const previous = this.#queues.get(key) ?? Promise.resolve();
         const next = previous.catch(() => undefined).then(work);
         this.#queues.set(key, next);
         return next;
     }
     async #activate(adapter, context) {
-        const identity = { workspaceId: context.workspaceId, workerId: context.workerId };
-        await this.#serialize(identity.workerId, adapter.family, async () => {
-            const state = await this.#loadState(adapter, identity.workerId);
+        const identity = { workspaceId: context.workspaceId };
+        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.workerId, adapter.family, async () => {
-            const key = this.#key(identity.workerId, adapter.family);
+        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);
             if (family?.prepared !== null && family?.prepared !== undefined) {
@@ -187,31 +237,40 @@ class Functionality {
             }
         });
     }
-    async #loadState(adapter, workerId) {
-        const raw = await this.#host.readWorkerModuleState(workerId, adapter.namespaceOwner);
+    async #loadState(adapter, workspaceId) {
+        return _a.#parseState(adapter, await this.#host.readWorkspaceModuleState(workspaceId, adapter.namespaceOwner), `workspace ${workspaceId}`);
+    }
+    async #loadWorkerState(adapter, workerId) {
+        return _a.#parseState(adapter, await this.#host.readWorkerModuleState(workerId, adapter.namespaceOwner), `worker ${workerId}`);
+    }
+    static #parseState(adapter, raw, where) {
         if (raw === null)
             return EMPTY_STATE;
         if (!isRecord(raw) || raw.version !== STATE_VERSION || !isRecord(raw.definitions)) {
-            throw new Error(`Functionality state for ${adapter.family} on worker ${workerId} 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 !== "worker") || 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 === "worker") {
+            if (inherited !== undefined && (typeof inherited !== "string" || inherited.length === 0 || adapter.scope !== "worker")) {
+                throw new Error(`Functionality state for ${adapter.family} alias '${alias}' carries an invalid inheritance.`);
+            }
+            const provenance = inherited === undefined ? {} : { inherited };
+            if (origin === _a.#localOrigin(adapter)) {
                 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 };
+                definitions[alias] = { origin, enabled, ...provenance };
             }
         }
         return { version: STATE_VERSION, definitions };
@@ -222,38 +281,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}.`);
+            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 inherited = record?.origin === "service" && record.inherited !== undefined ? { inherited: record.inherited } : {};
+            effective.set(service.alias, { alias: service.alias, origin: "service", definition: service.definition, enabled, ...inherited });
         }
         for (const [alias, record] of Object.entries(state.definitions)) {
-            if (record.origin !== "worker")
+            const local = _a.#localOrigin(adapter);
+            if (record.origin !== local)
                 continue;
-            effective.set(alias, { alias, origin: "worker", 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) {
-        const family = this.#families.get(this.#key(identity.workerId, adapter.family));
+        const family = this.#families.get(this.#key(identity.workspaceId, adapter.family));
         if (family === undefined)
-            throw failure(adapter.family, "worker-not-resident", 409, `Worker ${identity.workerId} has no resident ${adapter.family} Functionality.`, { recovery: "Activate the Worker through an ordinary operation, then retry.", retryable: false });
+            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 outcomes = family.prepared?.outcomes ?? new Map();
         return Validator.assertFunctionalityListResult({
@@ -265,13 +327,12 @@ class Functionality {
         const candidates = await adapter.discover(query, identity);
         return Validator.assertFunctionalityDiscoverResult({ family: adapter.family, candidates: [...candidates] });
     }
-    async #mutate(adapter, verb, input, identity, caller) {
-        const key = this.#key(identity.workerId, adapter.family);
-        const family = this.#families.get(key);
-        if (family === undefined)
-            throw failure(adapter.family, "worker-not-resident", 409, `Worker ${identity.workerId} has no resident ${adapter.family} Functionality.`, { recovery: "Activate the Worker through an ordinary 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) {
+        const local = _a.#localOrigin(adapter);
+        const here = adapter.scope === "worker" ? "this worker" : "this workspace";
+        const definitions = { ...state.definitions };
         let alias;
         let status = 200;
         let removed = false;
@@ -279,14 +340,16 @@ class Functionality {
             case "add": {
                 const admitted = await adapter.admit(input, identity, caller);
                 alias = admitted.alias;
-                if (!ALIAS.test(alias))
-                    throw failure(adapter.family, "alias-invalid", 400, `Alias '${alias}' must match ${ALIAS}.`, { alias, retryable: false });
-                // A worker 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.
-                if (effective.get(alias)?.origin === "worker")
-                    throw failure(adapter.family, "alias-exists", 409, `'${alias}' is already this Worker's own definition.`, { alias, recovery: "Enable, disable, or remove the existing definition, or add under another alias.", retryable: false });
-                definitions[alias] = { origin: "worker", definition: admitted.definition, enabled: true };
-                status = 201;
+                const current = effective.get(alias);
+                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: local, definition: admitted.definition, enabled: true };
+                status = current?.origin === local ? 200 : 201;
                 break;
             }
             case "enable":
@@ -294,9 +357,9 @@ 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 Worker.`, { alias, retryable: false });
-                definitions[alias] = current.origin === "worker"
-                    ? { origin: "worker", definition: current.definition, 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: "service", enabled: verb === "enable" };
                 break;
             }
@@ -304,7 +367,7 @@ 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 Worker.`, { 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 });
                 await adapter.forget?.({ alias, definition: current.definition }, identity);
@@ -317,19 +380,11 @@ class Functionality {
             }
             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.retainWorker(identity.workerId),
-            gate: caller === "operation" ? "wait" : "try",
-            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,
@@ -339,86 +394,168 @@ class Functionality {
         });
         return { status: body.status, body };
     }
-    // {§functionality-publication} — prepare, publish runtimes and state in one
-    // host replacement, then commit; on any failure abort and keep the previous
-    // snapshot authoritative. A model caller's publication waits for its own
-    // turn boundary in the same serialized lane, so the next packet sees it.
-    async #publish(adapter, identity, nextState, options) {
-        const key = this.#key(identity.workerId, adapter.family);
-        const previous = this.#families.get(key)?.prepared ?? null;
-        const effective = await this.#effective(adapter, identity, nextState);
+    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 transition = await this.#transition(adapter, verb, input, identity, caller, family.state, effective);
+        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) {
+        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);
+        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
+    // workspace publication completes; it never acknowledges a future commit.
+    async #publish(adapter, identity, nextState, options) {
+        const key = this.#key(identity.workspaceId, adapter.family);
+        const previous = this.#families.get(key)?.prepared ?? null;
+        // 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 = adapter.scope === "worker" ? new Map() : await this.#effective(adapter, identity, nextState);
+        const enabled = _a.#enabled(effective);
         const prepared = await adapter.prepare({
             workspaceId: identity.workspaceId,
-            workerId: identity.workerId,
             enabled,
             previous: previous?.snapshot ?? null,
             failure: options.failure,
             retain: options.retain,
             ...(options.forceAlias ? { force: options.forceAlias } : {}),
         });
-        for (const alias of enabled.keys()) {
-            if (!prepared.outcomes.has(alias))
-                throw new Error(`${adapter.family} preparation reported no outcome for enabled alias '${alias}'.`);
-        }
-        const manager = {
-            namespaceOwner: adapter.namespaceOwner,
-            decl: functionalityRuntimeDecl(adapter.family, adapter.summary),
-            executor: new FunctionalityManager({
-                family: adapter.family, workspaceId: identity.workspaceId, workerId: identity.workerId, coordinator: this,
-                definitionSchema: adapter.definitionSchema, example: adapter.example, discovery: adapter.discovery,
-            }),
-            availability: { available: true, detail: "Worker Functionality manager" },
-        };
-        const runtimes = [manager, ...prepared.runtimes];
-        for (const runtime of prepared.runtimes) {
-            if (runtime.namespaceOwner !== adapter.namespaceOwner) {
-                await prepared.abort();
-                throw new Error(`${adapter.family} prepared a runtime owned by '${runtime.namespaceOwner}' instead of '${adapter.namespaceOwner}'.`);
+        let runtimes;
+        try {
+            _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}'.`);
+                }
             }
+            const manager = {
+                namespaceOwner: adapter.namespaceOwner,
+                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,
+                }),
+                availability: { available: true, detail: "workspace Functionality manager" },
+            };
+            runtimes = [manager, ...(prepared.runtimes ?? [])];
+        }
+        catch (cause) {
+            return _a.#abort(prepared, cause);
         }
         const commit = async () => {
-            // The host reconciles the Worker's documents inside the replacement,
-            // so the snapshot it reads must already be the next one; a failed
-            // replacement restores the previous snapshot before aborting.
             const before = this.#families.get(key);
-            this.#families.set(key, { state: nextState, prepared });
             try {
-                await this.#host.replaceWorkerCapabilities({
+                await this.#host.replaceWorkspaceCapabilities({
                     workspaceId: identity.workspaceId,
-                    workerId: identity.workerId,
                     namespaceOwner: adapter.namespaceOwner,
                     state: _a.#persisted(nextState),
                     runtimes,
-                }, { gate: options.gate });
+                }, {
+                    gate: options.gate,
+                    publish: () => {
+                        this.#families.set(key, { state: nextState, prepared });
+                        return () => {
+                            if (before === undefined)
+                                this.#families.delete(key);
+                            else
+                                this.#families.set(key, before);
+                        };
+                    },
+                });
             }
             catch (cause) {
-                if (before === undefined)
-                    this.#families.delete(key);
-                else
-                    this.#families.set(key, before);
-                await prepared.abort();
-                throw cause;
+                return _a.#abort(prepared, cause);
             }
             await prepared.commit();
         };
-        if (options.gate !== "wait") {
-            await commit();
-            return { outcomes: prepared.outcomes };
-        }
-        // Inside the caller's own turn the workspace is held by that turn:
-        // publication queues behind it in this family's lane and settles
-        // before the next packet. The caller learns the preparation outcome now.
-        const pending = (this.#queues.get(key) ?? Promise.resolve()).catch(() => undefined).then(commit);
-        this.#queues.set(key, pending.catch((cause) => {
-            console.error(`[plurnk] ${adapter.family} publication for worker ${identity.workerId} failed at its turn boundary:`, cause);
-        }));
+        await commit();
         return { outcomes: prepared.outcomes };
     }
+    static async #abort(prepared, cause) {
+        try {
+            await prepared.abort();
+        }
+        catch (abortCause) {
+            throw new AggregateError([cause, abortCause], "Functionality publication and candidate cleanup failed");
+        }
+        throw cause;
+    }
 }
 _a = Functionality;
 export default Functionality;