@zq-silk/yui 0.15.6 → 0.15.8

package/dist/kernel/capabilityRegistry.js

@@ -0,0 +1,314 @@
+import { capabilitySchemaError, checkCapabilitySchema } from "./capabilitySchema.js";
+import { checkSurfaceDescriptors } from "../surface/surfaceContributions.js";
+/** Trusted owners may accompany a failed operation with its current read model.
+ * This is diagnostic data, not an operation receipt or an authority token. */
+export class CapabilityExecutionError extends Error {
+    value;
+    constructor(message, value) {
+        super(message);
+        this.value = structuredClone(value);
+    }
+}
+const effectRank = { query: 0, "local-mutation": 1, "external-operation": 2 };
+const reserved = new Set(["yui", "task", "context", "config", "job", "resource", "plugin", "runtime", "grant", "capability", "artifact", "environment", "project"]);
+/** One rebuildable descriptor view over the composition root's existing Host.
+ * Only the trusted root owns this object. Extensions receive a bound invocation
+ * port, never the registry/Host or an actor-selecting call interface. */
+export class CapabilityRegistry {
+    host;
+    authorize;
+    #descriptors = [];
+    #coreProviders = new Set();
+    constructor(host, authorize, builtins = []) {
+        this.host = host;
+        this.authorize = authorize;
+        this.#publish(builtins, true);
+        builtins.forEach((entry) => this.#coreProviders.add(entry.provider.id));
+    }
+    /** Publish a complete provider generation atomically after owner initialization.
+     * Failure leaves all existing descriptors intact. Host lifecycle remains owned
+     * by the root: publish replacement, then detach old generation when appropriate. */
+    register(descriptors) {
+        this.#publish(descriptors, false);
+    }
+    /** Data-only candidate check before author initialization; no acquisition or
+     * publication. Repeat immediately before publishing after any async work. */
+    checkRegistration(context, descriptors) {
+        const prepared = this.#prepare(descriptors, false);
+        if (!prepared.length)
+            throw new Error("Plugin must contribute capabilities.");
+        const available = [
+            ...this.search(context).filter((entry) => entry.provider.id !== prepared[0].provider.id),
+            ...prepared
+        ];
+        const check = (entry, path) => {
+            this.authorize(context, entry);
+            if (path.has(entry))
+                throw new Error("Required capability dependency cycle.");
+            for (const dependency of entry.required ?? []) {
+                const matches = available.filter((candidate) => candidate.name === dependency.name
+                    && candidate.contractVersion === dependency.contractVersion && candidate.unavailable === undefined);
+                if (matches.length !== 1)
+                    throw new Error(`Required capability is missing or ambiguous: ${dependency.name}.`);
+                check(matches[0], new Set([...path, entry]));
+            }
+        };
+        prepared.forEach((entry) => check(entry, new Set()));
+    }
+    disable(providerId) {
+        this.#descriptors = this.#descriptors.filter((entry) => entry.provider.id !== providerId);
+    }
+    search(context, query = "") {
+        const visibility = this.authorize(context);
+        const authorized = this.#descriptors.filter((entry) => visible(entry.scope, visibility))
+            .filter((entry) => {
+            try {
+                this.authorize(context, entry);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        return authorized.filter((entry) => `${entry.name} ${entry.summary}`.toLowerCase().includes(query.toLowerCase()))
+            .map((entry) => {
+            const unavailable = this.#unavailable(entry, authorized, new Set());
+            return unavailable === undefined ? entry : Object.freeze({ ...entry, unavailable });
+        });
+    }
+    describe(context, request) {
+        try {
+            const candidates = this.search(context).filter((entry) => entry.name === request.name
+                && (request.contractVersion === undefined || request.contractVersion === entry.contractVersion)
+                && (request.providerId === undefined || request.providerId === entry.provider.id));
+            if (!candidates.length)
+                return result("unavailable", "No authorized compatible Provider is available.");
+            const available = candidates.filter((entry) => entry.unavailable === undefined);
+            if (!available.length)
+                return {
+                    ...result("unavailable", candidates.map((entry) => `${entry.provider.id}: ${entry.unavailable}`).join("; ")),
+                    candidates
+                };
+            if (available.length > 1)
+                return { ...result("ambiguous", "Select an explicit Provider and contract version."), candidates };
+            const selected = available[0];
+            return {
+                ...result("value"), value: selected, candidates, provider: selected.provider,
+                selection: request.providerId === undefined ? "unique" : "explicit"
+            };
+        }
+        catch {
+            return result("denied", "Current call authority is unavailable.");
+        }
+    }
+    call(context, request) {
+        return this.#call(context, request, "external-operation");
+    }
+    async #call(context, request, ceiling, permissions) {
+        // Freeze one input snapshot across validation/acquisition and async nesting.
+        try {
+            request = deepFreeze(structuredClone(request));
+        }
+        catch {
+            return result("invalid", "Capability request must be cloneable data.");
+        }
+        const resolved = this.describe(context, request);
+        if (resolved.kind !== "value")
+            return resolved;
+        const descriptor = resolved.value;
+        const origin = { provider: descriptor.provider, selection: resolved.selection };
+        if (effectRank[descriptor.effect] > effectRank[ceiling]) {
+            return { ...result("denied", "Nested call exceeds the parent's effect boundary."), ...origin };
+        }
+        if (permissions !== undefined && descriptor.requiredPermissions.some((permission) => !permissions.includes(permission))) {
+            return { ...result("denied", "Nested call exceeds the parent's declared permissions."), ...origin };
+        }
+        const inputError = capabilitySchemaError(descriptor.inputSchema, request.input);
+        if (inputError)
+            return { ...result("invalid", inputError), ...origin };
+        if (descriptor.effect !== "query" && (typeof request.requestId !== "string" || !request.requestId.trim())) {
+            return { ...result("invalid", "Effectful calls require requestId."), ...origin };
+        }
+        try {
+            this.authorize(context, descriptor, request.input);
+        }
+        catch {
+            return { ...result("denied", "Current call authority was revoked."), ...origin };
+        }
+        const operations = [];
+        let effect = "none";
+        const observe = (operation) => {
+            operations.push(structuredClone(operation));
+            effect = accumulatedEffect(effect, operation.effect);
+        };
+        let entered = false;
+        try {
+            const value = await this.host.use(descriptor.provider, async (implementation) => {
+                entered = true;
+                let open = true;
+                const children = [];
+                try {
+                    return await implementation.invoke(descriptor.name, request.input, Object.freeze({
+                        context, requestId: request.requestId,
+                        observe: (operation) => {
+                            if (!open)
+                                throw new Error("Capability invocation has ended.");
+                            observe(operation);
+                        },
+                        call: (nested) => {
+                            if (!open)
+                                return Promise.resolve(result("denied", "Capability invocation has ended."));
+                            const child = this.#call(context, nested, descriptor.effect, descriptor.requiredPermissions).then((outcome) => {
+                                outcome.operations.forEach(observe);
+                                effect = accumulatedEffect(effect, outcome.effect);
+                                return outcome;
+                            });
+                            children.push(child);
+                            return child;
+                        }
+                    }));
+                }
+                finally {
+                    open = false;
+                    // A wrapper throwing early must not detach its already-issued child
+                    // operations from the returned evidence or release the parent handle.
+                    await Promise.all(children);
+                }
+            });
+            if (descriptor.effect === "local-mutation")
+                effect = accumulatedEffect(effect, "confirmed");
+            // An external implementation without an owner's operation reference is not
+            // proof of success. Preserve uncertainty rather than return a value success.
+            if (descriptor.effect === "external-operation" && !operations.length) {
+                return { kind: "failed", detail: "External implementation returned no operation evidence.", effect: "possible", operations, ...origin };
+            }
+            let output;
+            try {
+                output = JSON.parse(JSON.stringify(value, (_key, item) => {
+                    if ((typeof item === "number" && !Number.isFinite(item))
+                        || typeof item === "bigint" || typeof item === "function" || typeof item === "symbol") {
+                        throw new Error("Output contains a non-JSON value.");
+                    }
+                    return item;
+                }));
+            }
+            catch {
+                if (descriptor.effect !== "query")
+                    effect = accumulatedEffect(effect, "possible");
+                return { kind: "invalid", detail: "Output is not JSON serializable.", effect, operations, ...origin };
+            }
+            const outputError = capabilitySchemaError(descriptor.outputSchema, output);
+            if (outputError) {
+                if (descriptor.effect !== "query")
+                    effect = accumulatedEffect(effect, "possible");
+                return { kind: "invalid", detail: `Output ${outputError}`, effect, operations, ...origin };
+            }
+            return { kind: operations.length ? "operation" : "value", value: output, effect, operations, ...origin };
+        }
+        catch (error) {
+            // An unrelated observation (including a historical queued Job with none)
+            // cannot prove that a failing effectful wrapper performed no other action.
+            // Preserve the owner's precise facts while reporting wrapper uncertainty.
+            if (entered && descriptor.effect !== "query")
+                effect = accumulatedEffect(effect, "possible");
+            return {
+                kind: entered ? "failed" : "unavailable",
+                detail: error instanceof Error ? error.message : "Capability invocation failed.",
+                ...(error instanceof CapabilityExecutionError ? { value: error.value } : {}),
+                effect, operations, ...origin
+            };
+        }
+    }
+    #unavailable(entry, authorized, visiting) {
+        if (entry.unavailable !== undefined)
+            return entry.unavailable;
+        if (!this.host.isAvailable(entry.provider))
+            return "Provider implementation is not available.";
+        if (visiting.has(entry))
+            return "Required capability dependency cycle.";
+        const path = new Set([...visiting, entry]);
+        // Only declared exact name/version edges are checked. No installation,
+        // priority policy, version solver or persisted dependency state is involved.
+        const missing = entry.required?.filter((dependency) => !authorized.some((candidate) => (candidate.name === dependency.name && candidate.contractVersion === dependency.contractVersion
+            && this.#unavailable(candidate, authorized, path) === undefined)));
+        if (missing?.length)
+            return `Missing available required capabilities: ${missing.map((dependency) => `${dependency.name}@${dependency.contractVersion}`).join(", ")}.`;
+        return undefined;
+    }
+    #publish(descriptors, core) {
+        if (!descriptors.length)
+            return;
+        const prepared = this.#prepare(descriptors, core);
+        const provider = prepared[0].provider;
+        // Validate acquisition before publishing; no implementation is invoked.
+        if (prepared.some((entry) => !entry.unavailable)) {
+            const handle = this.host.acquire(provider);
+            try {
+                if (typeof handle.value?.invoke !== "function")
+                    throw new Error("Provider has no capability implementation.");
+            }
+            finally {
+                void handle.release();
+            }
+        }
+        this.#descriptors = [
+            ...this.#descriptors.filter((entry) => entry.provider.id !== provider.id),
+            ...prepared.map((entry) => deepFreeze(entry))
+        ];
+    }
+    #prepare(descriptors, core) {
+        if (!descriptors.length)
+            return [];
+        const prepared = structuredClone(descriptors);
+        const provider = prepared[0].provider;
+        if (!core && this.#coreProviders.has(provider.id))
+            throw new Error("Core Provider identity is reserved.");
+        const names = new Set();
+        for (const entry of prepared) {
+            if (!/^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+$/u.test(entry.name)
+                || !entry.contractVersion?.trim() || !entry.source?.trim()
+                || !Object.hasOwn(effectRank, entry.effect)
+                || !Array.isArray(entry.requiredPermissions)
+                || entry.requiredPermissions.some((permission) => typeof permission !== "string" || !permission.trim())) {
+                throw new Error("Invalid capability descriptor.");
+            }
+            if (!core && reserved.has(entry.name.split(".")[0]))
+                throw new Error("Core capability namespace is reserved.");
+            if (!["global", "project", "task"].includes(entry.scope.kind)
+                || (entry.scope.kind !== "global" && !entry.scope.id?.trim()))
+                throw new Error("Invalid capability scope.");
+            if (entry.provider.id !== provider.id || entry.provider.generation !== provider.generation) {
+                throw new Error("Publish one complete Provider generation at a time.");
+            }
+            const key = `${entry.name}@${entry.contractVersion}`;
+            if (names.has(key))
+                throw new Error(`Duplicate capability: ${key}.`);
+            names.add(key);
+            checkCapabilitySchema(entry.inputSchema);
+            checkCapabilitySchema(entry.outputSchema);
+            checkSurfaceDescriptors(entry);
+            for (const dependency of entry.required ?? []) {
+                if (!dependency.name?.trim() || !dependency.contractVersion?.trim())
+                    throw new Error("Invalid required capability.");
+            }
+        }
+        return [...prepared];
+    }
+}
+function visible(scope, visibility) {
+    return scope.kind === "global" || (scope.kind === "task"
+        ? visibility.taskIds.includes(scope.id) : visibility.projectIds.includes(scope.id));
+}
+function result(kind, detail) {
+    return { kind, effect: "none", operations: [], ...(detail === undefined ? {} : { detail }) };
+}
+function accumulatedEffect(a, b) {
+    return a === "confirmed" || b === "confirmed" ? "confirmed" : a === "possible" || b === "possible" ? "possible" : "none";
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === "object") {
+        Object.values(value).forEach(deepFreeze);
+        Object.freeze(value);
+    }
+    return value;
+}

package/dist/kernel/capabilitySchema.js

@@ -0,0 +1,91 @@
+import { isDeepStrictEqual } from "node:util";
+export function checkCapabilitySchema(schema) {
+    if (typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+        throw new Error("Capability schema must be an object.");
+    }
+    const keywords = new Set([
+        "type", "properties", "required", "additionalProperties", "items",
+        "enum", "const", "anyOf", "minLength", "minItems"
+    ]);
+    for (const key of Object.keys(schema)) {
+        if (!keywords.has(key))
+            throw new Error(`Unsupported schema keyword: ${key}.`);
+    }
+    if (schema.type !== undefined
+        && !["object", "array", "string", "number", "integer", "boolean", "null"].includes(schema.type)) {
+        throw new Error("Unsupported schema type.");
+    }
+    if (schema.required !== undefined && (!Array.isArray(schema.required)
+        || schema.required.some((key) => typeof key !== "string")))
+        throw new Error("Invalid schema required.");
+    for (const bound of [schema.minLength, schema.minItems]) {
+        if (bound !== undefined && (!Number.isSafeInteger(bound) || bound < 0))
+            throw new Error("Invalid schema bound.");
+    }
+    if (schema.enum !== undefined && (!Array.isArray(schema.enum) || schema.enum.length === 0)) {
+        throw new Error("Invalid schema enum.");
+    }
+    if (schema.anyOf !== undefined) {
+        if (!Array.isArray(schema.anyOf) || !schema.anyOf.length)
+            throw new Error("Invalid schema anyOf.");
+        schema.anyOf.forEach(checkCapabilitySchema);
+    }
+    if (schema.properties !== undefined) {
+        if (typeof schema.properties !== "object" || schema.properties === null || Array.isArray(schema.properties)) {
+            throw new Error("Invalid schema properties.");
+        }
+        Object.values(schema.properties).forEach(checkCapabilitySchema);
+    }
+    if (schema.items !== undefined)
+        checkCapabilitySchema(schema.items);
+    if (schema.additionalProperties !== undefined && typeof schema.additionalProperties !== "boolean") {
+        checkCapabilitySchema(schema.additionalProperties);
+    }
+}
+export function capabilitySchemaError(schema, value, path = "$") {
+    if ("const" in schema && !isDeepStrictEqual(value, schema.const))
+        return `${path}: unexpected value.`;
+    if (schema.enum && !schema.enum.some((item) => isDeepStrictEqual(item, value)))
+        return `${path}: not in enum.`;
+    if (schema.anyOf && !schema.anyOf.some((branch) => capabilitySchemaError(branch, value) === undefined)) {
+        return `${path}: no matching schema branch.`;
+    }
+    const type = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+    if (schema.type !== undefined && (schema.type === "integer"
+        ? typeof value !== "number" || !Number.isSafeInteger(value)
+        : type !== schema.type))
+        return `${path}: expected ${schema.type}.`;
+    if (typeof value === "number" && !Number.isFinite(value))
+        return `${path}: non-finite number.`;
+    if (typeof value === "string" && schema.minLength !== undefined && value.length < schema.minLength) {
+        return `${path}: string too short.`;
+    }
+    if (Array.isArray(value)) {
+        if (schema.minItems !== undefined && value.length < schema.minItems)
+            return `${path}: array too short.`;
+        if (schema.items) {
+            for (const [index, item] of value.entries()) {
+                const error = capabilitySchemaError(schema.items, item, `${path}[${index}]`);
+                if (error)
+                    return error;
+            }
+        }
+    }
+    else if (type === "object") {
+        const record = value;
+        for (const key of schema.required ?? []) {
+            if (!Object.hasOwn(record, key))
+                return `${path}.${key}: required.`;
+        }
+        for (const [key, item] of Object.entries(record)) {
+            const property = Object.hasOwn(schema.properties ?? {}, key) ? schema.properties[key] : undefined;
+            if (!property && schema.additionalProperties === false)
+                return `${path}.${key}: unexpected property.`;
+            const child = property ?? (typeof schema.additionalProperties === "object" ? schema.additionalProperties : undefined);
+            const error = child && capabilitySchemaError(child, item, `${path}.${key}`);
+            if (error)
+                return error;
+        }
+    }
+    return undefined;
+}

package/dist/kernel/instanceHost.js

@@ -14,11 +14,27 @@ export class InstanceHost {
         void drained.catch(() => undefined);
         const ref = Object.freeze({ ...implementation });
         this.#instances.set(key, {
-            implementation: ref, value, references: 0, detached: false,
+            implementation: ref, value, references: 0, detached: false, disposed: false,
             disposers: [...ownedDisposers], drained, resolve, reject
         });
         return ref;
     }
+    /** Read-only availability for the rebuildable capability directory. This is
+     * not an acquisition or a grant; acquire still checks immediately before use. */
+    isAvailable(implementation) {
+        const instance = this.#instances.get(implementationKey(implementation));
+        return !this.#closed && instance !== undefined && !instance.detached;
+    }
+    /** Only the Host reports actual reference/disposal facts. Metadata consumers
+     * must not persist these observations as independently writable state. */
+    inspect(providerId) {
+        return [...this.#instances.values()].filter((instance) => instance.implementation.id === providerId && !instance.disposed)
+            .map((instance) => Object.freeze({
+            implementation: instance.implementation,
+            references: instance.references,
+            accepting: !this.#closed && !instance.detached
+        }));
+    }
     acquire(implementation) {
         const instance = this.#instances.get(implementationKey(implementation));
         if (this.#closed || instance === undefined || instance.detached) {
@@ -80,6 +96,7 @@ export class InstanceHost {
             // Re-attaching a generation must not resurrect an old reference.
             instance.value = undefined;
             instance.disposers = [];
+            instance.disposed = true;
             if (errors.length)
                 throw new AggregateError(errors, "Instance cleanup failed.");
         })();

package/dist/kernel/kernelPorts.js

@@ -1,19 +1,22 @@
 import { createDurableJobControl } from "../controller/jobControl.js";
 import { JOB_RUNNER_IMPLEMENTATION } from "../job/durableJob.js";
 import { InstanceHost } from "./instanceHost.js";
+import { createBuiltinCapabilities } from "./builtinCapabilities.js";
 /** Called once by the existing Controller root. Does not open a Store, start
  * another Controller, or provide arbitrary persistence to plugin code.
  * T02 registers contributions on this Host and wraps this same Job control.
  */
-export function createKernelPorts(store, runner) {
+export function createKernelPorts(store, runner, signal = () => undefined, contextProviders = []) {
     const host = new InstanceHost();
     const runnerImplementation = host.attach(JOB_RUNNER_IMPLEMENTATION, runner);
     const runnerHandle = host.acquire(runnerImplementation);
     const jobImplementation = host.attach({ id: "yui:job-control", generation: "1" }, createDurableJobControl(store));
     // The Controller is a long-lived consumer of this exact implementation.
     const jobHandle = host.acquire(jobImplementation);
+    const capabilities = createBuiltinCapabilities(host, store, jobHandle.value, signal, contextProviders);
     return {
         host,
+        capabilities,
         jobImplementation,
         runnerImplementation,
         runner: runnerHandle.value,