@zackbart/connecta 0.24.4 → 0.26.0

package/dist/runtime/connector-scope.js

@@ -0,0 +1,72 @@
+// The Effect face of connector scope teardown (src/connector-scope.ts).
+//
+// closeConnectorScope() is the Promise shell over closeScope() below. An
+// Effect caller that owns a Scope registers the close as that scope's
+// finalizer instead, so teardown runs however the work inside it ends.
+import { Duration, Effect } from "effect";
+import { detach } from "./run.js";
+/** Enough for local transport abort/close without letting cleanup own latency. */
+const CONNECTOR_SCOPE_CLOSE_BUDGET_MS = 100;
+/**
+ * Bound on cleanup continued after the caller-facing window expires.
+ *
+ * `remoteMcp` spends at most one second asking the downstream to terminate its
+ * session, leaving another second for the local close. Custom hooks still get a
+ * finite background window: handing a never-settling promise to a Worker's
+ * `waitUntil` would otherwise keep the invocation alive until the platform cap.
+ */
+const CONNECTOR_SCOPE_DEFER_BUDGET_MS = 2_000;
+/**
+ * Succeed when `work` settles or `budgetMs` expires, whichever is first; never
+ * fail. The loser is interrupted, so a close that finishes early leaves no
+ * timer behind. Interrupting the wait leaves `work` running: nothing here can
+ * cancel a connector's close, only stop waiting for it.
+ */
+function waitAtMost(work, budgetMs) {
+    return Effect.raceAllFirst([
+        Effect.promise(() => work),
+        Effect.sleep(Duration.millis(budgetMs)),
+    ]);
+}
+/**
+ * Tell a connector that a scope owned by the core has ended, with the contract
+ * closeConnectorScope() documents: best-effort, never failing, waited on for a
+ * small fixed window, with a bounded tail handed to `defer` when the runtime
+ * has one. The hook is called when the effect runs, not when it is built.
+ */
+export function closeScope(connector, ctx, defer) {
+    return Effect.suspend(() => {
+        let settled;
+        try {
+            const closing = connector.closeScope?.(ctx);
+            if (!closing)
+                return Effect.void;
+            // Attach both handlers before either timer can win, so a late rejection
+            // is consumed rather than becoming an unhandled rejection.
+            settled = closing.then(() => { }, () => { });
+        }
+        catch {
+            // The scope is over whether or not the connector managed to clean it up.
+            return Effect.void;
+        }
+        if (defer) {
+            try {
+                detach(waitAtMost(settled, CONNECTOR_SCOPE_DEFER_BUDGET_MS), {
+                    waitUntil: defer,
+                });
+            }
+            catch {
+                // A runtime hook is best-effort too; the caller cap still applies.
+            }
+        }
+        return waitAtMost(settled, CONNECTOR_SCOPE_CLOSE_BUDGET_MS);
+    });
+}
+/**
+ * Close the connector scope when the enclosing Scope closes — on success,
+ * failure, or interruption alike. Callers still own the at-most-once
+ * guarantee: register the finalizer once per connector scope.
+ */
+export function closeScopeOnExit(connector, ctx, defer) {
+    return Effect.addFinalizer(() => closeScope(connector, ctx, defer));
+}

package/dist/runtime/run.js

@@ -0,0 +1,174 @@
+// The one place an Effect becomes a Promise.
+//
+// Connecta's published surface is Promise-shaped and stays that way; Effect is
+// an implementation detail behind it. Every edge where a fiber starts runs
+// through this module, so the rules for that crossing live in one file instead
+// of being re-derived at each call site — and test/purity.test.ts fails if any
+// other file under src/ calls Effect.run*, runFork, forkDaemon, or
+// ManagedRuntime.make.
+//
+// Two things the stock runners get wrong for this codebase:
+//
+// - The default MixedScheduler yields through setImmediate, which vitest's
+//   fake timers replace. A fiber that yields under vi.useFakeTimers() then
+//   waits for a timer tick nobody advances. Yielding through a microtask keeps
+//   fibers moving under fakes, and Workers never had setImmediate to begin
+//   with. The cost is that a fiber never yields to I/O, which is why CPU-heavy
+//   work stays out of Effect loops.
+// - Effect.runPromise rejects an interrupted fiber with a generic "All fibers
+//   interrupted without error". Callers of withDeadline today see the abort
+//   reason the caller chose, and runEdge keeps it that way.
+import { Cause, Context, Duration, Effect, Exit, ManagedRuntime, Scheduler, } from "effect";
+/** Yield to the scheduler through the microtask queue, never a timer. */
+function setMicrotask(task) {
+    let cancelled = false;
+    queueMicrotask(() => {
+        if (!cancelled)
+            task();
+    });
+    return () => {
+        cancelled = true;
+    };
+}
+/** The scheduler every edge-run fiber uses; see the header for why. */
+export const microtaskScheduler = new Scheduler.MixedScheduler("async", setMicrotask);
+const runExit = Effect.runPromiseExitWith(Context.make(Scheduler.Scheduler, microtaskScheduler));
+function abortReason(signal) {
+    return signal?.reason ?? new DOMException("aborted", "AbortError");
+}
+/**
+ * Turn a failed Exit back into the value a Promise caller would have seen.
+ *
+ * An interrupt caused by the caller's signal wins, as the abort does in
+ * withDeadline's race. Otherwise the first typed failure is rethrown as is,
+ * then the first defect — never a wrapper, because callers check `instanceof`,
+ * `name`, and `message` on connecta's own error classes.
+ */
+function rethrow(cause, signal) {
+    const reasons = cause.reasons;
+    if (signal?.aborted && reasons.some(Cause.isInterruptReason)) {
+        throw abortReason(signal);
+    }
+    const failure = reasons.find(Cause.isFailReason);
+    if (failure)
+        throw failure.error;
+    const defect = reasons.find(Cause.isDieReason);
+    if (defect)
+        throw defect.defect;
+    throw abortReason(signal);
+}
+const disposedRuntimes = new WeakSet();
+/** Wrap a layer as an EdgeRuntime without building it. */
+export function makeEdgeRuntime(layer) {
+    return ManagedRuntime.make(layer);
+}
+/**
+ * Release a runtime's layer resources. Idempotent, and never rejects: a
+ * finalizer that fails has nobody left to report to.
+ */
+export async function disposeEdgeRuntime(runtime) {
+    if (disposedRuntimes.has(runtime))
+        return;
+    disposedRuntimes.add(runtime);
+    // Through runExit rather than runtime.dispose(), whose runner yields on
+    // Effect's default scheduler — the one vitest's fake timers freeze.
+    await runExit(runtime.disposeEffect);
+}
+/**
+ * The effect with the runtime's services provided, building them first when
+ * no run has yet. The build runs on the calling fiber's scheduler, so it is
+ * the microtask scheduler here, as everything else is.
+ */
+function provideRuntime(effect, runtime) {
+    if (disposedRuntimes.has(runtime)) {
+        return Effect.die(new Error("This Connecta has been closed."));
+    }
+    const built = runtime.cachedContext;
+    if (built)
+        return Effect.provideContext(effect, built);
+    return Effect.flatMap(runtime.contextEffect, (context) => Effect.provideContext(effect, context));
+}
+export async function runEdge(effect, options = {}) {
+    const exit = await runExit(options.runtime
+        ? provideRuntime(effect, options.runtime)
+        // Without a runtime the overloads admit only an effect that requires
+        // nothing, so there is nothing to provide.
+        : effect, options.signal ? { signal: options.signal } : undefined);
+    if (Exit.isSuccess(exit))
+        return exit.value;
+    return rethrow(exit.cause, options.signal);
+}
+/**
+ * Fail with the signal's abort reason once it aborts; never succeed.
+ *
+ * Race it against work that should stop when the signal does. A signal
+ * aborted without a reason fails with an AbortError, as `fetch` would.
+ */
+export function fromSignal(signal) {
+    return Effect.callback((resume) => {
+        // Remove the listener on every path, firing included. `once` already
+        // drops it from a real AbortSignal, but the cleanup below runs only on
+        // interruption, and a signal-shaped wrapper sees no removal otherwise.
+        const onAbort = () => {
+            signal.removeEventListener("abort", onAbort);
+            resume(Effect.fail(abortReason(signal)));
+        };
+        if (signal.aborted) {
+            onAbort();
+            return;
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+        return Effect.sync(() => signal.removeEventListener("abort", onAbort));
+    });
+}
+/**
+ * The Effect form of withDeadline (src/timeout.ts), with the same contract.
+ *
+ * The operation gets a signal of its own. The caller's signal is forwarded to
+ * it, and the deadline aborts it with the labelled `timeoutError` *before* the
+ * operation's fiber is interrupted, so work that honors the signal sees the
+ * same reason the caller does. Either abort fails the effect with that reason:
+ * the caller's, or `timeoutError`. The signal is always aborted on exit, as
+ * withDeadline's `finally` does.
+ *
+ * The error channel is `unknown` because an abort reason is whatever the
+ * caller chose.
+ */
+export function withDeadlineEffect(operation, options) {
+    return Effect.suspend(() => {
+        const controller = new AbortController();
+        const forwardAbort = () => controller.abort(options.signal?.reason);
+        options.signal?.addEventListener("abort", forwardAbort, { once: true });
+        if (options.signal?.aborted)
+            forwardAbort();
+        // One race, not a race nested in a race: every contender is a forked
+        // fiber, and forks are most of what a deadline costs (P1-S02 measured
+        // about 2µs per raceFirst). Fork order is unchanged — operation, abort,
+        // timer — and the timer still aborts the signal before anything is
+        // interrupted, so the abort contender wins with the labelled reason.
+        const contenders = [
+            Effect.suspend(() => operation(controller.signal)),
+            fromSignal(controller.signal),
+        ];
+        if (options.timeoutMs !== undefined) {
+            contenders.push(Effect.sleep(Duration.millis(options.timeoutMs)).pipe(Effect.andThen(Effect.sync(() => controller.abort(options.timeoutError))), Effect.andThen(Effect.never)));
+        }
+        return Effect.raceAllFirst(contenders).pipe(Effect.ensuring(Effect.sync(() => {
+            controller.abort();
+            options.signal?.removeEventListener("abort", forwardAbort);
+        })));
+    });
+}
+/**
+ * The only sanctioned fire-and-forget.
+ *
+ * On Workers the work is handed to `ctx.waitUntil`, so the platform keeps the
+ * invocation alive until it settles rather than freezing it mid-flight. The
+ * returned promise never rejects: the outcome is the effect's own business,
+ * and an unhandled rejection from background work helps nobody.
+ */
+export function detach(effect, ctx) {
+    const settled = runExit(effect).then(() => { }, () => { });
+    ctx?.waitUntil?.(settled);
+    return settled;
+}

package/dist/runtime/services.js

@@ -0,0 +1,130 @@
+// The core's services, as Effect code sees them.
+//
+// createConnecta resolves storage, the vault, activity history, logging, and
+// the rest of its configuration once, at construction. This module gives each
+// of those a service key and assembles them into the layer behind that
+// Connecta's runtime (an EdgeRuntime, src/runtime/run.ts), so an Effect
+// program reads them from its context rather than from arguments threaded
+// through every call. The shells — Registry, CatalogService, and the rest —
+// stay constructible from plain arguments, as the tests construct them. The
+// registry's storage programs read Storage and Logger too, but from their own
+// partition rather than this runtime (see src/runtime/storage.ts for why).
+//
+// Every import from an optional module is type-only. An omitted activity
+// module is a no-op recorder that builds no event and calls nothing, and the
+// UI, vault, and activity implementations stay out of the root import graph
+// (test/purity.test.ts).
+import { Context, Effect, Layer } from "effect";
+import { makeEdgeRuntime } from "./run.js";
+/**
+ * The deployment's KVStorage: `config.storage`, or the memoryStorage() that
+ * stands in for it. `compareAndSet` is present exactly when the adapter
+ * implements it, so a caller that needs atomicity checks for it here.
+ */
+export class Storage extends Context.Service()("connecta/Storage") {
+}
+/**
+ * The credential vault, or undefined when the deployment configures none —
+ * a required service whose value may be absent, not a default, so a program
+ * run without it provided fails to typecheck instead of finding no vault.
+ */
+export class Vault extends Context.Service()("connecta/Vault") {
+}
+/**
+ * Connecta's diagnostic logger, already resolved: the configured Logger, a
+ * no-op for `"silent"`, or console output prefixed `[connecta]`. Effect's
+ * own logger is never used (test/purity.test.ts), because it honors neither
+ * `"silent"` nor the line format a deployment greps for.
+ */
+export class Logger extends Context.Service()("connecta/Logger") {
+}
+/** Payload-free activity history, or a recorder that records nothing. */
+export class ActivityRecorder extends Context.Service()("connecta/ActivityRecorder") {
+}
+/** What createConnecta resolved at construction. */
+export class ResolvedConfig extends Context.Service()("connecta/ResolvedConfig") {
+}
+/**
+ * The request's hook for work that may outlive its response (a Worker's
+ * `ctx.waitUntil`). Per request, not per Connecta, so it is never part of the
+ * runtime: a request provides it with `Effect.provideService`, and a program
+ * outside any request sees undefined and keeps its work in the foreground.
+ */
+export const DeferredWork = Context.Reference("connecta/DeferredWork", { defaultValue: () => undefined });
+/**
+ * Resolve `ConnectaConfig.logger`. `"silent"` discards every line; an omitted
+ * logger writes to the console with the `[connecta]` prefix.
+ */
+export function resolveLogger(logger) {
+    if (logger === "silent") {
+        return { debug() { }, info() { }, warn() { }, error() { } };
+    }
+    return logger ?? {
+        debug: (...a) => console.debug("[connecta]", ...a),
+        info: (...a) => console.info("[connecta]", ...a),
+        warn: (...a) => console.warn("[connecta]", ...a),
+        error: (...a) => console.error("[connecta]", ...a),
+    };
+}
+const NO_ACTIVITY = {
+    enabled: false,
+    recordTool: () => Effect.void,
+    recordDrift: () => Effect.void,
+};
+function activityRecorder(module, serverInfo, logger) {
+    const deployment = module.deploymentId !== undefined
+        ? { deploymentId: module.deploymentId }
+        : {};
+    // A custom module's recorder that throws is logged like a store that
+    // throws: activity never changes the outcome of the work it describes.
+    const bestEffort = (record) => Effect.sync(() => {
+        try {
+            record();
+        }
+        catch (error) {
+            logger.warn("[connecta] activity record failed", error);
+        }
+    });
+    return {
+        enabled: true,
+        recordTool: (request, input) => DeferredWork.use((defer) => bestEffort(() => module.recordTool({
+            sink: module.store,
+            recordTool: module.recordTool,
+            actor: request.actor,
+            requestId: request.requestId,
+            serverInfo,
+            ...deployment,
+            ...(defer ? { defer } : {}),
+            logger,
+        }, input))),
+        recordDrift: (input) => bestEffort(() => module.recordDrift({ sink: module.store, serverInfo, ...deployment, logger }, input)),
+    };
+}
+/**
+ * The layer behind a Connecta's runtime. Every service is a value resolved
+ * before this is called, so building the layer only assembles a context: it
+ * starts no fiber and touches no storage.
+ */
+function coreServices(options) {
+    const activity = options.activity
+        ? activityRecorder(options.activity, options.config.serverInfo, options.logger)
+        : NO_ACTIVITY;
+    return Layer.succeedContext(Context.make(Storage, options.storage).pipe(Context.add(Vault, options.vault), Context.add(Logger, options.logger), Context.add(ActivityRecorder, activity), Context.add(ResolvedConfig, options.config)));
+}
+// Keyed by the root Registry: it is the per-Connecta object every internal
+// caller already holds, and a Registry built directly (as the tests build
+// them) simply has no runtime.
+const runtimes = new WeakMap();
+/**
+ * Create the runtime for the Connecta that owns `registry`. Runs nothing:
+ * the layer is built by the first run that needs it (see EdgeRuntime).
+ */
+export function createCoreRuntime(registry, options) {
+    const runtime = makeEdgeRuntime(coreServices(options));
+    runtimes.set(registry, runtime);
+    return runtime;
+}
+/** The runtime createConnecta made for this root registry, if it made one. */
+export function coreRuntime(registry) {
+    return runtimes.get(registry);
+}

package/dist/runtime/shared-read.js

@@ -0,0 +1,106 @@
+// One read that several readers in one request wait on, each on its own terms.
+//
+// Discovery and the registry both coalesce a connector's catalog read inside
+// one request, so a search, a describe, and the call after them cost one
+// downstream listing. The read used to run under whichever reader asked
+// first: its signal was the read's signal, so a short-deadline call that
+// happened to start the read failed a search that joined it with the call's
+// timeout, and a cancelled search cancelled a read others were still waiting
+// on (#571).
+//
+// So the read owns its signal. Each reader waits under its own cancellation,
+// and the read is cancelled only when no reader is left to want it. Nothing
+// here is shared across requests: a SharedRead lives in one request's map and
+// is waited on only by that request's fibers, which is why a plain count of
+// readers is enough and no edge is needed between them.
+import { Deferred, Effect, Exit } from "effect";
+export class SharedRead {
+    onEnd;
+    controller = new AbortController();
+    outcome = Deferred.makeUnsafe();
+    readers = 0;
+    ended = false;
+    /**
+     * Start `read` at once, under a signal the read owns. `onEnd` runs once:
+     * when the read settles, with whether it succeeded, or when it is cancelled
+     * first, with `false`. It runs before any reader hears the outcome, so an
+     * owner that evicts the read there sends a reader who retries on hearing of
+     * a failure to a fresh read, never back to this one.
+     */
+    constructor(read, onEnd = () => { }) {
+        this.onEnd = onEnd;
+        // The executor turns a synchronous throw from `read` into a rejection.
+        new Promise((resolve) => resolve(read(this.controller.signal))).then((value) => this.settle(Exit.succeed(value)), (cause) => this.settle(Exit.fail(cause)));
+    }
+    settle(exit) {
+        this.end(Exit.isSuccess(exit));
+        Deferred.doneUnsafe(this.outcome, exit);
+    }
+    end(succeeded) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.onEnd(succeeded);
+    }
+    // Cancel the read for good. After this it is no longer joinable: whatever
+    // it eventually settles with still reaches the readers already waiting, but
+    // its owner has evicted it and a newcomer starts afresh.
+    cancel(reason) {
+        if (this.ended)
+            return;
+        this.controller.abort(reason);
+        this.end(false);
+    }
+    /**
+     * Wait for the read under this reader's own cancellation.
+     *
+     * A reader whose signal aborts while others still wait fails at once with
+     * its own reason and leaves the read to them. The last reader's abort is the
+     * read's: it is forwarded to the read's signal and that reader waits for the
+     * read's answer, as a lone reader always has, so a connector that finishes
+     * its listing anyway still hands it over. A reader that is interrupted — its
+     * deadline, as `withDeadlineEffect` ends it — simply leaves, and when it was
+     * the last one the read is cancelled with its reason.
+     */
+    join(signal) {
+        return Effect.suspend(() => {
+            this.readers++;
+            let waiting = true;
+            const leave = Effect.sync(() => {
+                if (!waiting)
+                    return;
+                waiting = false;
+                this.readers--;
+                if (this.readers === 0)
+                    this.cancel(signal?.reason);
+            });
+            const answer = Deferred.await(this.outcome);
+            const own = signal
+                ? Effect.raceFirst(answer, this.leftBy(signal))
+                : answer;
+            return Effect.ensuring(own, leave);
+        });
+    }
+    // Fails with the reader's abort reason when other readers remain; when it is
+    // the last, forwards the abort to the read and never completes, leaving the
+    // read's own answer to win the race.
+    leftBy(signal) {
+        return Effect.callback((resume) => {
+            const onAbort = () => {
+                signal.removeEventListener("abort", onAbort);
+                if (this.readers > 1) {
+                    resume(Effect.fail(signal.reason));
+                }
+                else {
+                    this.cancel(signal.reason);
+                }
+            };
+            if (signal.aborted) {
+                onAbort();
+                return;
+            }
+            signal.addEventListener("abort", onAbort, { once: true });
+            return Effect.sync(() => signal.removeEventListener("abort", onAbort));
+        });
+    }
+}

package/dist/runtime/storage.js

@@ -0,0 +1,66 @@
+// The Storage service, as the registry's programs use it.
+//
+// KVStorage stays Promise-shaped: it is what a deployment author implements,
+// and nobody should need Effect to write a storage adapter. The operations
+// below lift one call each into an effect that reads the adapter from the
+// Storage service and fails with whatever the adapter threw, unwrapped, so a
+// warning built from it reads exactly as it did.
+//
+// Which Storage a program sees is the registry's decision, not the runtime's.
+// The Connecta runtime (src/runtime/services.ts) is keyed by the root
+// Registry, and that is the wrong key here: a personal registry's storage is
+// the root's namespaced to `principal:<key>:`, so handing its programs the
+// runtime's Storage would read and write another partition. Each Registry —
+// root, personal, or one a test built from plain arguments — therefore
+// provides its own storage and logger to the programs it runs
+// (`runOnPartition`). For the root registry those are the very values the
+// runtime holds, because createConnecta passes the same two objects to both.
+// A scoped view holds no storage of its own: it reaches Storage through the
+// registry it delegates to, and the result stash is always the root's,
+// because its capacity is runtime-wide.
+import { Context, Effect } from "effect";
+import { runEdge } from "./run.js";
+import { Logger, Storage } from "./services.js";
+/** Read one key; null when absent. */
+export function storageGet(key) {
+    return Storage.use((storage) => Effect.tryPromise({
+        // Promise.resolve keeps an adapter that answers synchronously working,
+        // as `await` did; a synchronous throw is caught either way.
+        try: () => Promise.resolve(storage.get(key)),
+        catch: (error) => error,
+    }));
+}
+/** Write one key, with the adapter's optional TTL. */
+export function storageSet(key, value, options) {
+    return Storage.use((storage) => Effect.tryPromise({
+        try: () => Promise.resolve(storage.set(key, value, options)),
+        catch: (error) => error,
+    }));
+}
+/** Delete one key. */
+export function storageDelete(key) {
+    return Storage.use((storage) => Effect.tryPromise({
+        try: () => Promise.resolve(storage.delete(key)),
+        catch: (error) => error,
+    }));
+}
+// One context per partition object, built on first use. A registry's options
+// object lives exactly as long as the registry, so the WeakMap never holds a
+// partition past its owner.
+const partitions = new WeakMap();
+function partitionContext(partition) {
+    let context = partitions.get(partition);
+    if (!context) {
+        context = Context.make(Storage, partition.storage).pipe(Context.add(Logger, partition.logger));
+        partitions.set(partition, context);
+    }
+    return context;
+}
+/**
+ * Run a registry program against the registry's own storage and logger, at a
+ * Promise boundary. Resolves and rejects as runEdge does: the original error,
+ * never a wrapper.
+ */
+export function runOnPartition(effect, partition) {
+    return runEdge(Effect.provideContext(effect, partitionContext(partition)));
+}