@zackbart/connecta 0.39.0 → 0.41.0

package/dist/url-safety.js

@@ -13,11 +13,11 @@
  * legacy IPv4 spelling (`2130706433`, `0x7f.1`, `0177.0.0.1`) into dotted
  * decimal and every IPv6 literal into compressed hex, so one canonical form is
  * all this module reads. It never resolves a name: that needs DNS, which the
- * Workers-safe core cannot do, and a name that resolves somewhere private — or
- * rebinds after the check — is out of scope. Pure Web API, no `node:` import.
+ * Workers-safe core cannot do. The owned Node transport additionally resolves
+ * and pins learned destinations at connect time. Pure Web API, no `node:` import.
  */
 function classifyIpv4(octets) {
-    const [a = 0, b = 0] = octets;
+    const [a = 0, b = 0, c = 0] = octets;
     if (a === 127)
         return "loopback";
     if (a === 0 ||
@@ -25,7 +25,14 @@ function classifyIpv4(octets) {
         (a === 172 && b >= 16 && b <= 31) ||
         (a === 192 && b === 168) ||
         (a === 169 && b === 254) ||
-        (a === 100 && b >= 64 && b <= 127)) {
+        (a === 100 && b >= 64 && b <= 127) ||
+        (a === 192 && b === 0 && (c === 0 || c === 2)) || // IETF protocol, documentation
+        (a === 192 && b === 88 && c === 99) || // 6to4 relay anycast
+        (a === 198 && (b === 18 || b === 19)) || // benchmarking
+        (a === 198 && b === 51 && c === 100) || // documentation
+        (a === 203 && b === 0 && c === 113) || // documentation
+        a >= 224 // multicast, reserved, broadcast
+    ) {
         return "private";
     }
     return "public";
@@ -61,24 +68,35 @@ function ipv6Pieces(host) {
     return [...head, ...Array.from({ length: missing }, () => 0), ...tail];
 }
 function classifyIpv6(pieces) {
-    const [first = 0] = pieces;
-    const leadingZeros = pieces.slice(0, 5).every((piece) => piece === 0);
-    if (leadingZeros && pieces[5] === 0 && pieces[6] === 0) {
-        if (pieces[7] === 0)
-            return "private"; // ::
-        if (pieces[7] === 1)
-            return "loopback"; // ::1
+    const [p0 = 0, p1 = 0, p2 = 0, p3 = 0, p4 = 0, p5 = 0, p6 = 0, p7 = 0] = pieces;
+    const v4 = (high, low) => classifyIpv4([high >> 8, high & 0xff, low >> 8, low & 0xff]);
+    // A transitional form reaches, at most, the IPv4 address it carries. Only a
+    // mapped address can reach this host, so only it stays `loopback`; every
+    // other non-public carrier is `private`, keeping it out of a loopback
+    // connector's learned URLs.
+    const carried = (high, low) => (v4(high, low) === "public" ? "public" : "private");
+    const zeros = p0 === 0 && p1 === 0 && p2 === 0 && p3 === 0;
+    if (zeros && p4 === 0) {
+        if (p5 === 0xffff)
+            return v4(p6, p7); // ::ffff:a.b.c.d mapped
+        if (p5 === 0) {
+            if (p6 === 0 && p7 === 1)
+                return "loopback"; // ::1
+            return carried(p6, p7); // :: and ::a.b.c.d compatible
+        }
     }
-    // ::ffff:a.b.c.d reaches the mapped IPv4 destination; classify that.
-    if (leadingZeros && pieces[5] === 0xffff) {
-        const high = pieces[6] ?? 0;
-        const low = pieces[7] ?? 0;
-        return classifyIpv4([high >> 8, high & 0xff, low >> 8, low & 0xff]);
+    if (zeros && p4 === 0xffff && p5 === 0)
+        return carried(p6, p7); // ::ffff:0:a.b.c.d translated
+    if (p0 === 0x64 && p1 === 0xff9b && p2 === 0 && p3 === 0 && p4 === 0 && p5 === 0)
+        return carried(p6, p7); // NAT64
+    if (p0 === 0x2002)
+        return carried(p1, p2); // 6to4
+    // Global unicast is 2000::/3. Outside it: unique-local, link-local,
+    // site-local, multicast, local-use NAT64, reserved. Inside it, special-purpose
+    // 2001::/23 and documentation 2001:db8::/32 and 3fff::/20 are not destinations.
+    if ((p0 & 0xe000) !== 0x2000 || (p0 === 0x2001 && (p1 < 0x200 || p1 === 0xdb8)) || (p0 === 0x3fff && p1 < 0x1000)) {
+        return "private";
     }
-    if ((first & 0xfe00) === 0xfc00)
-        return "private"; // fc00::/7
-    if ((first & 0xffc0) === 0xfe80)
-        return "private"; // fe80::/10
     return "public";
 }
 /**

package/dist/utility-recovery.js

@@ -0,0 +1,33 @@
+/** Actions outside the tool namespace never invent a route on a serving surface. */
+export function utilityRecovery(code, message, retryable = false) {
+    return {
+        code,
+        message,
+        retryable,
+        nextAction: {
+            action: ["unsupported_capability", "input_required_unsupported", "invalid_args"].includes(code)
+                ? "inspect_capabilities"
+                : code === "not_found"
+                    ? "recover_result"
+                    : "contact_operator",
+            purpose: ["unsupported_capability", "input_required_unsupported", "invalid_args"].includes(code)
+                ? "Inspect the supported utility input and client capabilities before a fresh call. Never repeat a write whose outcome is unknown."
+                : code === "not_found"
+                    ? "Use a retained result handle if available. Otherwise report the missing output; never repeat a write to recover output."
+                    : "Ask the operator to restore availability. Retry reads only after recovery; reconcile any write whose outcome is unknown.",
+        },
+    };
+}
+/** Missing skill names need local discovery, never service restoration or result recovery. */
+export function skillLookupRecovery(message) {
+    return {
+        code: "not_found",
+        message,
+        retryable: false,
+        nextAction: {
+            tool: "skills",
+            arguments: {},
+            purpose: "List available skills, then fetch an exact name from that list.",
+        },
+    };
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CONNECTA_VERSION = "0.39.0";
+export declare const CONNECTA_VERSION = "0.41.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated from package.json by scripts/generate-version.mjs.
 // Workers-safe: no runtime filesystem read or deployment override.
-export const CONNECTA_VERSION = "0.39.0";
+export const CONNECTA_VERSION = "0.41.0";

package/dist/worker.js

@@ -99,6 +99,20 @@ export function workerExecutor(options) {
         // The SDK prepares its source/dispatchers against this inert loader.
         // Actual Loader and RPC acquisition belongs to the native program below.
         let prepared;
+        // Upstream 0.5.5+ answers every host call that settles after its
+        // evaluate() with a late-call error. Its inert evaluate stays pending
+        // until the native evaluation ends, so the SDK's gate stays open for the
+        // whole run and closes once the run is over or the lease is released.
+        let evaluating;
+        const evaluated = new Promise((resolve) => {
+            evaluating = resolve;
+        });
+        let settleUpstream;
+        const endUpstream = () => {
+            const settle = settleUpstream;
+            settleUpstream = undefined;
+            settle?.();
+        };
         const dispose = (resource) => Effect.sync(() => {
             try {
                 const method = Reflect.get(resource, Symbol.dispose);
@@ -309,7 +323,10 @@ const {
                             getEntrypoint: () => ({
                                 evaluate: (...evaluateArgs) => {
                                     acquisition.args = evaluateArgs;
-                                    return Promise.resolve({ result: undefined });
+                                    return new Promise((resolve) => {
+                                        settleUpstream = () => resolve({ result: undefined });
+                                        evaluating?.();
+                                    });
                                 },
                             }),
                         };
@@ -342,15 +359,21 @@ const {
                 const started = Date.now();
                 const operation = Effect.gen(function* () {
                     const setup = yield* Effect.tryPromise({
-                        try: () => new DynamicWorkerExecutor({
-                            loader,
-                            ...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
-                        }).execute(code, detached),
+                        try: () => {
+                            const upstream = new DynamicWorkerExecutor({
+                                loader,
+                                ...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
+                            }).execute(code, detached);
+                            // The SDK's own result, which settles only after endUpstream(),
+                            // carries nothing; the native evaluation below owns the outcome.
+                            upstream.catch(() => undefined);
+                            return Promise.race([upstream, evaluated.then(() => undefined)]);
+                        },
                         catch: (error) => error,
                     });
                     // Provider validation can return before the SDK reaches its loader.
-                    if (!prepared)
-                        return setup;
+                    if (setup !== undefined || !prepared)
+                        return setup ?? { result: undefined };
                     const load = prepared.load;
                     const args = prepared.args;
                     const open = () => Effect.suspend(() => released || resources.state._tag === "Closed"
@@ -369,7 +392,7 @@ const {
                             try: () => Reflect.apply(Reflect.get(entrypoint, "evaluate"), entrypoint, args ?? []),
                             catch: (error) => error,
                         });
-                    }).pipe(Scope.provide(resources));
+                    }).pipe(Scope.provide(resources), Effect.ensuring(Effect.sync(endUpstream)));
                     const result = yield* evaluation;
                     const outcome = result;
                     if (outcome.failure) {
@@ -407,6 +430,7 @@ const {
                 }));
             }).pipe(Effect.raceFirst(Deferred.await(stopped)), Effect.catchDefect((error) => Effect.fail(error)), Effect.ensuring(Effect.sync(() => {
                 runEnded = true;
+                endUpstream();
                 hostProviders = undefined;
                 prepared = undefined;
                 hostFailures.clear();
@@ -420,6 +444,7 @@ const {
                 if (released)
                     return;
                 released = true;
+                endUpstream();
                 hostProviders = undefined;
                 prepared = undefined;
                 hostFailures.clear();

package/documentation/architecture.md

@@ -340,7 +340,7 @@ without storage reads, decryption or hashing. Catalog invalidation (including
 operator refresh and OAuth connect/disconnect/restart) advances a counter for the
 registry's cache store; built-in vault set/clear advances a counter for that vault.
 These weakly held counters contain no catalogs, credentials or caller identity;
-catalogs and derived views remain request-local. A moved fence replaces the
+registry catalogs and derived views remain request-local. A moved fence replaces the
 retained read and its search views, and prevents joining an older registry flight.
 Changes made through another process/isolate or directly in storage need not be
 observed mid-request; the next request uses the durable generation and auth checks.
@@ -619,6 +619,18 @@ Only complete, intake-redacted tools/list, resources/list and
 resources/templates/list successes are stored. Resource payloads are not cached. SDK default
 in-memory caching is replaced, so raw catalogs never enter it.
 
+A warm isolate retains at most four validated stored JSON catalogs, with a
+combined accounting budget of 8 MiB (twice serialized input bytes, key bytes and
+64 bytes per object property/array slot; larger entries bypass reuse).
+These deeply frozen facts contain no request context, transport, signal,
+callback or promise, and require neither weak references nor cleanup timers.
+Reuse follows the same manifest TTL checks, complete chunk reads, recomputed
+SHA-256 fingerprint and fresh generation/credential acceptance fence as a cold
+read. Its key binds the stored entry, current private owner/deployment partition
+(even for public entries), and chunk fingerprint. Request-specific credential
+redaction and TTL intake still run every time. Eviction affects performance
+only; SQL remains authoritative.
+
 Stored catalog and negotiation keys use deployment-keyed partitions. A remote
 connector's whole cache configuration and negotiation input enter a stored key
 only through HMAC-SHA-256 (`src/storage-digest.ts`) under a key that never
@@ -643,6 +655,28 @@ refresh baselines within 48 hours, verdicts within six hours), so each remote
 connector's partitions refill once after the upgrade with one handshake and
 listing.
 
+Warm remote resolution batches the negotiation verdict and locating generation
+when their physical keys share an observed SQL store. Private and public
+manifest probes share a `getMany` statement; their normal precedence and public
+scope check still apply. These batches contain only reads. Catalog addresses
+use the listing's pinned OAuth identity and locating generation; they authorize
+nothing. After chunk verification, acceptance re-reads the OAuth identity and
+generation separately and refuses a changed epoch or token digest. The invocation
+gate checks disconnect first, then reads tokens separately to refuse absent
+credentials and observe current expiry and the invalidation fingerprint. Token
+removal, expiry, scope and replacement can change without advancing the epoch;
+epoch fences alone cannot protect these values. The SDK's later token read may
+return no tokens and omit Authorization, so it does not replace invocation's
+token-presence refusal. The transport also refuses tokenless MCP requests on
+passive OAuth paths, regardless of provider history; an explicit authorization
+start may probe for the SDK's challenge. A refused tool send binds its private
+failure provenance to the undispatched physical request. Invocation accepts it
+only for the owning boundary and whole logical call; error fields, copied
+connectors, and refusals after a send cannot supply that proof.
+Connection reuse and SDK dispatch retain their fresh
+epoch or token reads; no credential read is prefetched.
+Stores with replaced methods or separate backing stores retain individual reads.
+
 A remote connector's `listTools` without a live connection in its request
 reads this cache before connecting. It derives the same partition a connect
 binds (the admitted principal, the caller's credential digest, or the owner's
@@ -1008,7 +1042,15 @@ run of K = 8 consecutive UTF-16 units of a registered form of a value at least K
 long, in the raw text or any JSON-decoded layer; text cut where the cut can end
 inside a form loses that unfinished tail, however short.** Runs formed from
 placeholder text and kept text or numbers are covered too; the placeholder
-itself is reserved replacement text. Registered forms are
+itself is reserved replacement text. The guarantee excludes an occurrence made
+entirely of reserved replacement text, including a run across the seam between
+adjacent markers, whether or not the registered form contains a complete
+`[redacted]`. For example, register `secretsecret` and `ted][red`, then redact
+`["secretsecret", "secretsecret"]`: the returned leaves may be
+`["[redacted]", "[redacted]"]`. Their joined projection spells the second
+registered value using only reserved replacement text; no original secret
+units survive. An occurrence that includes retained original text stays covered.
+Registered forms are
 the raw value, its URL/form encodings (either percent hex case), base64 and
 base64url, and the `Bearer `/`token ` framings. The framing words are public, so
 no indexed run starts inside them; a run reaching K units of the value is
@@ -3738,6 +3780,16 @@ change. All 88 declarations still exclude Effect and have complete references.
 
 ### Native remote MCP programs (contributor)
 
+Legacy session termination may read a token before rotation and send its DELETE
+on the wire after rotation. This is accepted only for bounded, headers-only
+termination of the old session, never for application traffic (`tools/call`,
+`tools/list`, or other RPCs). Connection scope close retains the same cleanup
+completion after revocation; later connector close joins it so the runtime's
+deferred hook (Workers `waitUntil`) owns the bounded tail. Abandoned leases from
+rotation and failed connects, and authorization exchange transports, retain their
+cleanup in that same request state. Termination and local close keep their
+existing one-second budgets; the caller-facing close window remains 100 ms.
+
 Remote MCP connection joins, credential and epoch checks, catalog intake,
 negotiation, calls, resources, Skills, auth and status compose native programs.
 `connectors/remote-mcp.ts` keeps the published options, the redirect guard and
@@ -3884,3 +3936,32 @@ cache. Exact authored names and complete authored matches precede API pointers;
 ordinary result limits, offsets, catalog failure disclosure and byte bounds apply.
 The published discovery contract states compilation, query and cache bounds.
 No request identity, signal, credential or promise enters a vocabulary cache.
+
+SQL catalog locating snapshots derive at most two manifest candidates from the
+stored generation alongside negotiation and generation rows. These candidates
+are request-local hints with exact config, owner and credential partitions.
+Complete chunk verification and a separate later primary generation and identity
+fence decide acceptance. OAuth invocation and dispatch reads stay separate.
+
+SQL result stashes write at most 64 trailing rows per awaited transaction, with one
+expiry sweep per batch. Header publication follows confirmed trailing writes in a
+separate transaction; uncertain writes retain their ledger charge until expiry.
+Custom storage keeps sequential writes.
+
+Admission observation sampling retains at most 256 scalar deadlines per live
+physical storage identity in an isolate. Only a recent valid stored timestamp
+or confirmed CAS populates it, for at most one minute. This telemetry cache
+never answers token admission; every request still checks current credentials.
+
+### Lexical token reuse (contributor)
+
+Search may retain four complete accepted catalog token indexes, bounded by an
+8 MiB estimate including key text, token strings, postings and structural slots.
+Identity includes complete served content (including schemas, classification and
+order), connector, physical store, owner partition/revisions and the downstream catalog
+generation observed by the current successful listing. The generation marker
+is request-local primitive evidence; it grants no cache acceptance or authority. Only immutable
+strings and numeric positions cross requests. Search views map positions to the
+current request's definitions after owner visibility, classification, redaction
+and endpoint restrictions; no query results are retained. Partial failed
+catalogs cannot enter this cache. Eviction changes cost only, never results.