@zq-silk/yui 0.15.7 → 0.15.8

package/dist/kernel/capabilityRegistry.js

@@ -1,6 +1,16 @@
 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", "config", "job", "resource", "plugin", "runtime", "grant", "capability"]);
+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. */
@@ -21,6 +31,30 @@ export class CapabilityRegistry {
     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);
     }
@@ -70,7 +104,7 @@ export class CapabilityRegistry {
     call(context, request) {
         return this.#call(context, request, "external-operation");
     }
-    async #call(context, request, ceiling) {
+    async #call(context, request, ceiling, permissions) {
         // Freeze one input snapshot across validation/acquisition and async nesting.
         try {
             request = deepFreeze(structuredClone(request));
@@ -86,6 +120,9 @@ export class CapabilityRegistry {
         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 };
@@ -121,7 +158,7 @@ export class CapabilityRegistry {
                         call: (nested) => {
                             if (!open)
                                 return Promise.resolve(result("denied", "Capability invocation has ended."));
-                            const child = this.#call(context, nested, descriptor.effect).then((outcome) => {
+                            const child = this.#call(context, nested, descriptor.effect, descriptor.requiredPermissions).then((outcome) => {
                                 outcome.operations.forEach(observe);
                                 effect = accumulatedEffect(effect, outcome.effect);
                                 return outcome;
@@ -177,6 +214,7 @@ export class CapabilityRegistry {
             return {
                 kind: entered ? "failed" : "unavailable",
                 detail: error instanceof Error ? error.message : "Capability invocation failed.",
+                ...(error instanceof CapabilityExecutionError ? { value: error.value } : {}),
                 effect, operations, ...origin
             };
         }
@@ -200,6 +238,27 @@ export class CapabilityRegistry {
     #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))
@@ -227,26 +286,13 @@ export class CapabilityRegistry {
             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.");
             }
         }
-        // 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))
-        ];
+        return [...prepared];
     }
 }
 function visible(scope, visibility) {

package/dist/kernel/instanceHost.js

@@ -14,7 +14,7 @@ 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;
@@ -25,6 +25,16 @@ export class InstanceHost {
         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) {
@@ -86,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

@@ -6,14 +6,14 @@ import { createBuiltinCapabilities } from "./builtinCapabilities.js";
  * 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, signal = () => undefined) {
+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);
+    const capabilities = createBuiltinCapabilities(host, store, jobHandle.value, signal, contextProviders);
     return {
         host,
         capabilities,

package/dist/lifecycle/canonicalLifecycleEvent.js

@@ -1,3 +1,12 @@
+/**
+ * The smallest stable, provider-neutral Yui lifecycle vocabulary.
+ *
+ * Each phase is a durable semantic fact about a managed Agent Session or the
+ * AgentRun whose prompt it carries. Agent Drivers translate native signals into
+ * these phases; the scheduler and durable fold reason about phases, sources,
+ * and evidence — never about provider names.
+ */
+import { isAgentAdapterId } from "../agent/adapterCatalog.js";
 export function isPreInputReadinessSupported(capability) {
     return capability.status === "supported";
 }
@@ -9,17 +18,17 @@ export class CanonicalLifecycleError extends Error {
         this.name = "CanonicalLifecycleError";
     }
 }
-const TURN_SCOPED_PHASES = new Set([
+const RUN_SCOPED_PHASES = new Set([
     "prompt-pushed",
     "provider-accepted",
     "turn-progress",
     "turn-terminal"
 ]);
 /**
- * Phases that assert durable provider truth about a Turn. Every one must carry
- * the complete turn-scoped identity — turnId AND the generation fences
- * (nativeSessionId + runtimeGenerationId) AND, where the transport owns it, the receiptId —
- * because a missing or wrong fence must fail closed rather than advance a Turn or
+ * Phases that assert durable provider truth about a AgentRun. Every one must carry
+ * the complete turn-scoped identity — turnId AND the Session fences
+ * (nativeSessionId) AND, where the transport owns it, the receiptId —
+ * because a missing or wrong fence must fail closed rather than advance a AgentRun or
  * its successor.
  */
 const PROVIDER_TRUTH_PHASES = new Set([
@@ -34,7 +43,7 @@ const PROVIDER_TRUTH_PHASES = new Set([
  * (acceptance/progress/terminal), so neither a transport/liveness signal nor a
  * shape-only `adapter-mapped` observation can ever forge or terminalize a turn.
  * `adapter-mapped` remains permissible only for the pre-acceptance
- * session-started/ready phases, whose fold never advances Turn truth.
+ * session-started/ready phases, whose fold never advances AgentRun truth.
  */
 const PHASE_EVIDENCE_MATRIX = {
     "host-process-created": { sources: ["controller"], evidence: ["controller"] },
@@ -77,18 +86,15 @@ export function createCanonicalLifecycleEvent(input) {
         throw new CanonicalLifecycleError(`Phase ${input.phase} rejects evidence ${input.evidence}; only ${rule.evidence.join("/")} may prove it.`);
     }
     const fence = normalizeFence(input.fence);
-    if (TURN_SCOPED_PHASES.has(input.phase) && fence.turnId === undefined) {
-        throw new CanonicalLifecycleError(`Phase ${input.phase} requires a turnId fence.`);
+    if (RUN_SCOPED_PHASES.has(input.phase) && fence.runId === undefined) {
+        throw new CanonicalLifecycleError(`Phase ${input.phase} requires a runId fence.`);
     }
-    // Provider-truth phases must carry the complete generation fence so a stale or
-    // wrong generation can never advance the Turn.
+    // Provider-truth phases must carry the complete Session fence so a stale or
+    // wrong Session can never advance the AgentRun.
     if (PROVIDER_TRUTH_PHASES.has(input.phase)) {
         if (fence.nativeSessionId === undefined) {
             throw new CanonicalLifecycleError(`Phase ${input.phase} requires a nativeSessionId fence.`);
         }
-        if (fence.runtimeGenerationId === undefined) {
-            throw new CanonicalLifecycleError(`Phase ${input.phase} requires a runtimeGenerationId fence.`);
-        }
     }
     if (input.phase === "prompt-pushed" && fence.receiptId === undefined) {
         throw new CanonicalLifecycleError("A prompt-pushed event requires a transport receiptId.");
@@ -133,7 +139,7 @@ export function createCanonicalLifecycleEvent(input) {
  * The provider-neutral decision. Given a validated canonical event and the
  * consumer's current expectation, it returns what should happen — idempotent for
  * duplicates, deferred for not-yet-applicable facts, obsolete for stale/wrong
- * generation, fail-closed for contract violations. It reads only phase / source
+ * Session, fail-closed for contract violations. It reads only phase / source
  * / evidence / identity, never the adapter name, and mutates nothing.
  */
 export function foldCanonicalLifecycleEvent(event, expectation) {
@@ -154,10 +160,7 @@ export function foldCanonicalLifecycleEvent(event, expectation) {
             }
             // Discovery may bind a previously-unknown native id, but only under the
             // exact launch fence and only when none is bound yet.
-            if (expectation.boundNativeSessionId === undefined
-                && event.fence.nativeSessionId !== undefined
-                && event.fence.runtimeGenerationId !== undefined
-                && event.fence.runtimeGenerationId === expectation.fence.runtimeGenerationId) {
+            if (expectation.boundNativeSessionId === undefined && event.fence.nativeSessionId !== undefined) {
                 return { outcome: "bind-native-session", nativeSessionId: event.fence.nativeSessionId };
             }
             return { outcome: "mark-session-started" };
@@ -176,7 +179,7 @@ export function foldCanonicalLifecycleEvent(event, expectation) {
                 return { outcome: "obsolete", reason: "push-after-terminal" };
             if (expectation.accepted)
                 return { outcome: "obsolete", reason: "push-after-accepted" };
-            // Exactly one push: a repeat for an already-pushed Turn is a no-op, never a
+            // Exactly one push: a repeat for an already-pushed AgentRun is a no-op, never a
             // second Enter.
             if (expectation.pushed)
                 return { outcome: "idempotent", reason: "already-pushed" };
@@ -209,7 +212,7 @@ export function foldCanonicalLifecycleEvent(event, expectation) {
                 return { outcome: "idempotent", reason: "already-terminal" };
             if (expectation.accepted)
                 return { outcome: "advance-terminal" };
-            // A terminal for a pushed-but-unaccepted Turn must NOT promote acceptance;
+            // A terminal for a pushed-but-unaccepted AgentRun must NOT promote acceptance;
             // hold the immutable fact until (or unless) acceptance folds first.
             if (expectation.pushed)
                 return { outcome: "deferred", reason: "terminal-before-accept" };
@@ -219,12 +222,12 @@ export function foldCanonicalLifecycleEvent(event, expectation) {
     }
 }
 /**
- * Returns null when the event belongs to the expected generation/Turn, or a
+ * Returns null when the event belongs to the expected Session/AgentRun, or a
  * mismatch reason otherwise. Owner/adapter and turn-scoped turnId are always
  * compared. Provider-truth phases (acceptance/progress/terminal) require the
- * COMPLETE generation fence — nativeSessionId, runtimeGenerationId, and (for acceptance)
- * receiptId must be present and equal, so a missing or wrong generation/receipt
- * fails closed rather than advancing a Turn or its successor. Where a native id
+ * COMPLETE Session fence — nativeSessionId, and (for acceptance)
+ * receiptId must be present and equal, so a missing or wrong Session/receipt
+ * fails closed rather than advancing a AgentRun or its successor. Where a native id
  * is already bound, every turn-scoped fact must match it.
  */
 function matchesFence(expectation, event) {
@@ -239,29 +242,23 @@ function matchesFence(expectation, event) {
         return "fence-mismatch:agentId";
     if (expected.adapterId !== actual.adapterId)
         return "fence-mismatch:adapterId";
-    // Turn-scoped phases must name the exact expected Turn.
-    if (TURN_SCOPED_PHASES.has(phase)) {
-        if (expected.turnId === undefined)
+    // AgentRun-scoped phases must name the exact expected AgentRun.
+    if (RUN_SCOPED_PHASES.has(phase)) {
+        if (expected.runId === undefined)
             return "fence-mismatch:expected-turn-missing";
-        if (actual.turnId !== expected.turnId)
-            return "fence-mismatch:turnId";
+        if (actual.runId !== expected.runId)
+            return "fence-mismatch:runId";
     }
-    else if (actual.turnId !== undefined
-        && expected.turnId !== undefined
-        && actual.turnId !== expected.turnId) {
-        return "fence-mismatch:turnId";
+    else if (actual.runId !== undefined
+        && expected.runId !== undefined
+        && actual.runId !== expected.runId) {
+        return "fence-mismatch:runId";
     }
-    // Provider-truth phases require the complete, equal generation fence. A
+    // Provider-truth phases require the complete, equal Session fence. A
     // provider-accepted event additionally must carry the exact receipt it accepts.
     if (PROVIDER_TRUTH_PHASES.has(phase)) {
         if (actual.nativeSessionId === undefined)
             return "fence-mismatch:missing-native-session";
-        if (actual.runtimeGenerationId === undefined) {
-            return "fence-mismatch:missing-runtime-generation";
-        }
-        if (expected.runtimeGenerationId !== undefined && actual.runtimeGenerationId !== expected.runtimeGenerationId) {
-            return "fence-mismatch:runtimeGenerationId";
-        }
         // Once a native id is bound, every provider-truth fact must match it. Before
         // binding (discovery still open) the expected fence's own nativeSessionId, if
         // present, still constrains it.
@@ -279,7 +276,7 @@ function matchesFence(expectation, event) {
         return null;
     }
     // Pre-acceptance phases (host/session/ready and the transport push): compare
-    // the generation dimensions that are present on both sides. A push must match
+    // the Session dimensions that are present on both sides. A push must match
     // its expected receipt when both name one.
     if (actual.nativeSessionId !== undefined
         && expectation.boundNativeSessionId !== undefined
@@ -291,11 +288,6 @@ function matchesFence(expectation, event) {
         && actual.nativeSessionId !== expected.nativeSessionId) {
         return "fence-mismatch:nativeSessionId";
     }
-    if (actual.runtimeGenerationId !== undefined
-        && expected.runtimeGenerationId !== undefined
-        && actual.runtimeGenerationId !== expected.runtimeGenerationId) {
-        return "fence-mismatch:runtimeGenerationId";
-    }
     if (phase === "prompt-pushed"
         && actual.receiptId !== undefined
         && expected.receiptId !== undefined
@@ -308,7 +300,11 @@ function normalizeFence(fence) {
     const taskId = requireFenceText(fence.taskId, "taskId");
     const roleName = requireFenceText(fence.roleName, "roleName");
     const agentId = requireFenceText(fence.agentId, "agentId");
-    if (fence.adapterId !== "codex" && fence.adapterId !== "claude") {
+    // The fence names an adapter, and the catalog is what defines which adapters
+    // exist. Re-listing them here would silently exclude a catalogued adapter
+    // from the durable fold, which reads as an identity mismatch rather than as
+    // the missing registration it actually is.
+    if (!isAgentAdapterId(fence.adapterId)) {
         throw new CanonicalLifecycleError(`Unsupported adapter fence: ${String(fence.adapterId)}.`);
     }
     return Object.freeze({
@@ -316,11 +312,10 @@ function normalizeFence(fence) {
         roleName,
         agentId,
         adapterId: fence.adapterId,
-        ...(fence.turnId === undefined ? {} : { turnId: requireFenceText(fence.turnId, "turnId") }),
+        ...(fence.runId === undefined ? {} : { runId: requireFenceText(fence.runId, "runId") }),
         ...(fence.nativeSessionId === undefined
             ? {}
             : { nativeSessionId: requireFenceText(fence.nativeSessionId, "nativeSessionId") }),
-        ...(fence.runtimeGenerationId === undefined ? {} : { runtimeGenerationId: requireFenceText(fence.runtimeGenerationId, "runtimeGenerationId") }),
         ...(fence.receiptId === undefined ? {} : { receiptId: requireFenceText(fence.receiptId, "receiptId") })
     });
 }