@zackbart/connecta 0.34.0 → 0.35.0

package/dist/d1.js

@@ -4,24 +4,11 @@
 // `KVStorage`, and `d1ActivityStore(db)` its activity history. Both create
 // their tables on first use, so binding the database is the whole setup.
 // `copyKvToD1` moves a 0.28 deployment's Workers KV state into it once.
-import { errorLabel } from "./operator-record.js";
-import { familyOfKey, KEY_FAMILIES, KV_COPY_CURSOR_TTL_SECONDS, kvCopyKeys, kvCutoverKeys } from "./storage/keys.js";
-import { copyIntoSql, sqlActivityStore, sqlStorage, } from "./storage/sql.js";
-function d1Driver(db) {
-    const prepare = (statement) => statement.params.length > 0 ? db.prepare(statement.sql).bind(...statement.params) : db.prepare(statement.sql);
-    return {
-        async all(statement) {
-            return (await prepare(statement).all()).results;
-        },
-        async run(statement) {
-            return (await prepare(statement).run()).meta.changes ?? 0;
-        },
-        async batch(statements) {
-            // D1 runs a batch as one transaction, in order.
-            return (await db.batch(statements.map(prepare))).map((result) => result.meta.changes ?? 0);
-        },
-    };
-}
+import { runEdge } from "./runtime/run.js";
+import { d1Driver } from "./storage/d1-driver.js";
+import { copyKvToD1Effect, markKvToD1LiveEffect } from "./storage/d1-copy.js";
+import { sqlActivityStore, sqlStorage } from "./storage/sql.js";
+import { keepErrorName } from "./redaction-identity.js";
 /**
  * `KVStorage` over a D1 database, with the atomic `compareAndSet` every
  * subsystem relies on. The `connecta_kv` table is created on first use; a
@@ -54,53 +41,10 @@ export class KvToD1CopyError extends Error {
         this.cursor = cursor;
     }
 }
-/** D1 string and row limit, in UTF-8 bytes.
- * https://developers.cloudflare.com/d1/platform/limits/
- */
-const D1_MAX_ROW_BYTES = 2_000_000;
-/** Buffered entries, excluding the single value currently being read. */
-const COPY_BUFFER_BYTES = 4 * 1024 * 1024;
-const COPY_GROUP_KEYS = 50;
-const KV_LIST_LIMIT = 1000;
-const encoder = new TextEncoder();
-// SQLite record header, two TEXT serial types, and an eight-byte expiry.
-// Reserve the worst-case header rather than accepting a row at the boundary.
-const ROW_OVERHEAD_BYTES = 32;
-const emptyCounts = () => ({
-    copied: 0,
-    unchanged: 0,
-    conflicts: 0,
-    overwritten: 0,
-    expired: 0,
-    invalid: 0,
-    verified: 0,
-    mismatches: 0,
-});
-const OUTCOME_COUNT = {
-    copied: "copied",
-    unchanged: "unchanged",
-    conflict: "conflicts",
-    overwritten: "overwritten",
-};
-function errorClass(error) {
-    const label = errorLabel(error);
-    return label ? ` (${label})` : "";
-}
-const valueHash = async (value) => {
-    const hash = await crypto.subtle.digest("SHA-256", encoder.encode(value));
-    return Array.from(new Uint8Array(hash), (byte) => byte.toString(16).padStart(2, "0")).join("");
-};
+keepErrorName(KvToD1CopyError, "KvToD1CopyError");
 /** Mark cutover before reopening traffic. The marker stays in D1 permanently. */
-export async function markKvToD1Live(db, source) {
-    if (typeof source !== "string" || !source || source.includes("\0")) {
-        throw new TypeError("copyKvToD1 source must be a namespace id");
-    }
-    try {
-        await d1Storage(db).set(kvCutoverKeys.source(source), "live");
-    }
-    catch (error) {
-        throw new KvToD1CopyError(`Workers KV to D1 copy stopped: recording cutover failed${errorClass(error)}`, undefined);
-    }
+export function markKvToD1Live(db, source) {
+    return runEdge(markKvToD1LiveEffect(db, source));
 }
 /**
  * Copy live KV entries verbatim while all writers and traffic are stopped.
@@ -108,183 +52,6 @@ export async function markKvToD1Live(db, source) {
  * `verify` reads hashes and absolute expiries without changing copied entries.
  * Results contain counts only. Resume tokens are source-bound atomic claims.
  */
-export async function copyKvToD1(kv, db, options) {
-    if (!options?.source || typeof options.source !== "string" || options.source.includes("\0")) {
-        throw new TypeError("copyKvToD1 source must be a namespace id");
-    }
-    const maxKeys = options.maxKeys ?? 500;
-    if (!Number.isSafeInteger(maxKeys) || maxKeys < 1) {
-        throw new TypeError("copyKvToD1 maxKeys must be a positive integer");
-    }
-    const allowed = new Set([...KEY_FAMILIES.map((family) => family.name), "connector-owned", "unclassified"]);
-    if (options.overwriteFamilies?.some((family) => !allowed.has(family))) {
-        throw new TypeError("copyKvToD1 overwriteFamilies contains an unknown family");
-    }
-    const overwrite = new Set(options.overwriteFamilies ?? []);
-    const driver = d1Driver(db);
-    const storage = sqlStorage(driver, "d1");
-    const remember = async (kvCursor) => {
-        const token = crypto.randomUUID();
-        await storage.set(kvCopyKeys.cursor(token), JSON.stringify({ source: options.source, cursor: kvCursor }), {
-            ttlSeconds: KV_COPY_CURSOR_TTL_SECONDS,
-        });
-        return token;
-    };
-    let cursor;
-    let pageCursor;
-    const families = {};
-    const count = (key, field) => {
-        (families[familyOfKey(key)] ??= emptyCounts())[field] += 1;
-    };
-    const unknown = new TypeError("copyKvToD1 cursor is unknown, expired, spent, or belongs to another source; restart under maintenance");
-    const stale = new TypeError("copyKvToD1 refuses stale KV after cutover");
-    // Validate before any D1 access so a failing binding cannot return raw input
-    // as an error's resume point.
-    if (options.cursor !== undefined &&
-        !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(options.cursor)) {
-        throw unknown;
-    }
-    const failures = new WeakSet();
-    const failure = (message) => {
-        const error = new KvToD1CopyError(message, undefined);
-        failures.add(error);
-        return error;
-    };
-    try {
-        if (!options.allowStale && (await storage.get(kvCutoverKeys.source(options.source))) !== null) {
-            throw stale;
-        }
-        if (options.cursor !== undefined) {
-            const key = kvCopyKeys.cursor(options.cursor);
-            const stored = await storage.get(key);
-            let record = null;
-            try {
-                record = stored === null ? null : JSON.parse(stored);
-            }
-            catch {
-                /* refused below */
-            }
-            if (!record || record.source !== options.source || typeof record.cursor !== "string") {
-                throw unknown;
-            }
-            // Delete only the exact record read: concurrent consumers cannot both win.
-            if (!(await storage.compareAndSet(key, stored, null)))
-                throw unknown;
-            cursor = record.cursor;
-        }
-    }
-    catch (error) {
-        if (error === unknown || error === stale)
-            throw error;
-        throw new KvToD1CopyError(`Workers KV to D1 copy stopped: claiming the resume point in D1 failed${errorClass(error)}`, options.cursor);
-    }
-    const flush = async (buffer) => {
-        const entries = buffer.filter((entry) => {
-            if (entry.expiresAtMs !== null && entry.expiresAtMs <= Date.now()) {
-                count(entry.key, "expired");
-                return false;
-            }
-            return true;
-        });
-        if (!entries.length)
-            return;
-        try {
-            if (options.verify) {
-                for (const entry of entries) {
-                    const [row] = await driver.all({
-                        // Read bytes, including NUL, and hash in JS. D1 has no SHA-256 function.
-                        sql: "SELECT CAST(value AS BLOB) AS value_bytes, expires_at_ms FROM connecta_kv WHERE key = ?",
-                        params: [entry.key],
-                    });
-                    const bytes = row ? Uint8Array.from(row.value_bytes) : undefined;
-                    const hash = bytes ? await crypto.subtle.digest("SHA-256", bytes) : undefined;
-                    const hex = hash
-                        ? Array.from(new Uint8Array(hash), (byte) => byte.toString(16).padStart(2, "0")).join("")
-                        : undefined;
-                    count(entry.key, row && row.expires_at_ms === entry.expiresAtMs && hex === (await valueHash(entry.value))
-                        ? "verified"
-                        : "mismatches");
-                }
-            }
-            else {
-                // Partition only this bounded buffer by overwrite permission.
-                for (const replace of [false, true]) {
-                    const group = entries.filter((entry) => overwrite.has(familyOfKey(entry.key)) === replace);
-                    if (!group.length)
-                        continue;
-                    const outcomes = await copyIntoSql(driver, group, { overwrite: replace, now: Date.now() });
-                    for (const [index, outcome] of outcomes.entries())
-                        count(group[index].key, OUTCOME_COUNT[outcome]);
-                }
-            }
-        }
-        catch (error) {
-            throw failure(`Workers KV to D1 copy stopped: ${options.verify ? "verifying" : "writing to"} D1 failed${errorClass(error)}`);
-        }
-    };
-    let read = 0;
-    try {
-        for (;;) {
-            pageCursor = cursor;
-            let page;
-            try {
-                page = await kv.list({ limit: Math.min(KV_LIST_LIMIT, maxKeys - read), ...(cursor ? { cursor } : {}) });
-            }
-            catch (error) {
-                throw failure(`Workers KV to D1 copy stopped: listing Workers KV failed${errorClass(error)}`);
-            }
-            read += page.keys.length;
-            let entries = [];
-            let bufferedBytes = 0;
-            for (const key of page.keys) {
-                const keyBytes = encoder.encode(key.name).byteLength;
-                if (key.name.includes("\0") || keyBytes + ROW_OVERHEAD_BYTES > D1_MAX_ROW_BYTES) {
-                    count(key.name, "invalid");
-                    continue;
-                }
-                const expiresAtMs = key.expiration === undefined ? null : key.expiration * 1000;
-                if (expiresAtMs !== null && expiresAtMs <= Date.now()) {
-                    count(key.name, "expired");
-                    continue;
-                }
-                let value;
-                try {
-                    value = await kv.get(key.name, "text");
-                }
-                catch (error) {
-                    throw failure(`Workers KV to D1 copy stopped: reading an entry of the ${familyOfKey(key.name)} family from Workers KV failed${errorClass(error)}`);
-                }
-                if (value === null || (expiresAtMs !== null && expiresAtMs <= Date.now())) {
-                    count(key.name, "expired");
-                    continue;
-                }
-                const valueBytes = encoder.encode(value).byteLength;
-                const bytes = keyBytes + valueBytes + ROW_OVERHEAD_BYTES;
-                if (valueBytes > D1_MAX_ROW_BYTES || bytes > D1_MAX_ROW_BYTES) {
-                    count(key.name, "invalid");
-                    continue;
-                }
-                if (entries.length >= COPY_GROUP_KEYS || bufferedBytes + bytes > COPY_BUFFER_BYTES) {
-                    await flush(entries);
-                    entries = [];
-                    bufferedBytes = 0;
-                }
-                entries.push({ key: key.name, value, expiresAtMs });
-                bufferedBytes += bytes;
-            }
-            await flush(entries);
-            if (page.list_complete || !page.cursor)
-                return { done: true, families };
-            cursor = page.cursor;
-            if (read >= maxKeys)
-                return { done: false, cursor: await remember(cursor), families };
-        }
-    }
-    catch (error) {
-        // The old token was claimed atomically. Replace it on failure, if D1 works.
-        const resume = pageCursor === undefined ? undefined : await remember(pageCursor).catch(() => undefined);
-        throw new KvToD1CopyError(error instanceof KvToD1CopyError && failures.has(error)
-            ? error.message
-            : `Workers KV to D1 copy stopped: recording the resume point in D1 failed${errorClass(error)}`, resume);
-    }
+export function copyKvToD1(kv, db, options) {
+    return runEdge(copyKvToD1Effect(kv, db, options));
 }

package/dist/derived-context.js

@@ -0,0 +1,5 @@
+// The Promise bridge shares its service entry only through explicit derivation.
+import { deriveView } from "./runtime/call.js";
+export function deriveContext(ctx, overrides) {
+    return deriveView(ctx, overrides);
+}

package/dist/describe-config.d.ts

@@ -20,6 +20,8 @@ export type DescribedMember = {
 };
 /** One connector as `describeConfig()` reports it. */
 export interface DescribedConnector {
+    /** Connector policy, independent of endpoint policy; omitted when false. */
+    readOnly?: boolean;
     id: string;
     title?: string;
     description?: string;
@@ -103,7 +105,7 @@ export interface ConnectaConfigDescription {
         namespace: string;
         id: string;
     }>;
-    classification: Record<string, Record<string, "read" | "write">>;
+    classification: Record<string, Record<string, "read" | "write" | "hidden">>;
     /** Inbound auth providers in the order they are tried. */
     auth: Array<{
         kind: string;
@@ -124,6 +126,8 @@ export interface ConnectaConfigDescription {
         tools: string[];
         members: DescribedMember[];
         readOnly: boolean;
+        surface: "meta" | "native";
+        executeCode: boolean;
         owner: string | null;
         description: string | null;
     }>;

package/dist/describe-config.js

@@ -133,6 +133,7 @@ function describeConnector(connector, deploymentCap, registry) {
     const guideSummary = connectorGuideSummary(connector);
     const guided = connector.usageGuide !== undefined;
     return {
+        ...(connector.readOnly === true ? { readOnly: true } : {}),
         id: connector.id,
         ...(str(connector.title) !== undefined ? { title: connector.title } : {}),
         ...(str(connector.description) !== undefined ? { description: connector.description } : {}),
@@ -243,6 +244,8 @@ export function describeConfig(input) {
         agents: [...config.agents],
         pools: Object.entries(config.pools ?? {}).map(([name, pool]) => ({
             readOnly: pool.readOnly ?? config.readOnly,
+            surface: pool.surface ?? "meta",
+            executeCode: pool.executeCode !== false,
             name,
             path: `/mcp/${name}`,
             tools: pool.tools.map(String),