@zackbart/connecta 0.37.1 → 0.38.0

package/dist/storage/keys.js

@@ -141,7 +141,7 @@ export const catalogKeys = {
         name: "catalog",
         scope: "root",
         prefixes: ["catalog:"],
-        // Retired v2/v3 listings are inventoried for migration; no runtime reads them.
+        // Retired v2/v3 listings expire on their original TTL; no runtime reads them.
         version: { number: 3, in: "value" },
         codec: textCodec,
         ttl: {
@@ -242,38 +242,6 @@ export const credentialKeys = {
     },
     credential: (connectorId, owner) => `${owner ? scopes.principal(owner) : ""}${scopes.connector(connectorId)}credential:v1`,
 };
-/** Seconds a Workers KV → D1 copy's resume point stays usable. */
-export const KV_COPY_CURSOR_TTL_SECONDS = 7 * 24 * 60 * 60;
-/**
- * Where a one-shot Workers KV → D1 copy (`copyKvToD1` in `src/d1.ts`) resumes,
- * held in D1 under a random token. Workers KV's own list cursor can spell the
- * last key it listed, so the caller holds the token and never the cursor.
- */
-export const kvCopyKeys = {
-    family: {
-        name: "kv-copy",
-        scope: "root",
-        prefixes: ["kv-copy:v1:"],
-        version: { number: 1, in: "key" },
-        codec: textCodec,
-        ttl: { kind: "fixed", seconds: KV_COPY_CURSOR_TTL_SECONDS },
-        durable: false,
-    },
-    cursor: (token) => validateStorageKey(`kv-copy:v1:cursor:${token}`),
-};
-/** Once traffic uses D1, copying stale KV state is refused. */
-export const kvCutoverKeys = {
-    family: {
-        name: "kv-cutover",
-        scope: "root",
-        prefixes: ["kv-cutover:v1:"],
-        version: { number: 1, in: "key" },
-        codec: textCodec,
-        ttl: { kind: "durable" },
-        durable: true,
-    },
-    source: (source) => validateStorageKey(`kv-cutover:v1:${encodeURIComponent(source)}`),
-};
 // --- connector families ---------------------------------------------------
 /** Seconds a consent's flow record stays claimable, the same as its link. */
 export const OAUTH_FLOW_TTL_SECONDS = 15 * 60;
@@ -356,38 +324,6 @@ export const oauthRefreshActiveKeys = {
     prefix: "oauth:refresh-active:",
     holder: (epoch, holder) => validateStorageKey(`oauth:refresh-active:${epoch}:${holder}`),
 };
-/** The values layout 2 stored, each under its historical key. */
-const oauthV2Field = {
-    client: "oauth:client",
-    tokens: "oauth:tokens",
-    pending: "oauth:pending",
-    verifier: "oauth:verifier",
-    state: "oauth:state",
-    discovery: "oauth:discovery",
-};
-/**
- * Layout 2, read once to migrate it into a grant record and then deleted:
- * each value at its field key, suffixed `:epoch:<generation>` once a modern
- * generation owned it; the active generation at `oauth:generation`; a reset's
- * cleanup lineage at `oauth:cleanup:` and `oauth:cleanup-at:`.
- */
-export const oauthV2Keys = {
-    family: {
-        name: "oauth-v2",
-        scope: "connector",
-        prefixes: [...Object.values(oauthV2Field), "oauth:generation", "oauth:cleanup:", "oauth:cleanup-at:"],
-        version: { number: 2, in: "value" },
-        codec: textCodec,
-        ttl: { kind: "durable" },
-        durable: true,
-    },
-    field: oauthV2Field,
-    /** One listing covers every layout 2 key; the reader keeps those above. */
-    scan: "oauth:",
-    /** A value's physical key; `epoch` null is the historical unsuffixed name. */
-    value: (key, epoch) => validateStorageKey(epoch === null ? key : `${key}:epoch:${epoch}`),
-    generation: "oauth:generation",
-};
 /** Single-use browser links (`used`/`started`/`failed`/`closed`) and MRTR rounds. */
 export const oauthConnectKeys = {
     family: {
@@ -430,63 +366,18 @@ export const inputRetryKeys = {
     },
     used: (nonce) => validateStorageKey(`input-retry:v1:${nonce}`),
 };
-/**
- * Every family, for the overlap and coverage checks and for migrations that
- * copy only what a deployment cannot recreate. Keys a custom connector writes
- * through its own `ctx.storage` belong to that connector, inside its
- * namespace, and are not listed here.
- */
-export const KEY_FAMILIES = [
-    continuationKeys.family,
-    operatorViewerKeys.family,
-    resultKeys.family,
-    stashLedgerKeys.family,
-    stashExpiryKeys.family,
-    catalogKeys.family,
-    responseCacheKeys.family,
-    oauthHandoffKeys.family,
-    accessTokenKeys.family,
-    agentObservationKeys.family,
-    credentialKeys.family,
-    oauthGrantKeys.family,
-    oauthFlowKeys.family,
-    oauthRefreshKeys.family,
-    oauthRefreshSpentKeys.family,
-    oauthRefreshActiveKeys.family,
-    oauthV2Keys.family,
-    oauthConnectKeys.family,
-    negotiationKeys.family,
-    inputRetryKeys.family,
-    kvCopyKeys.family,
-    kvCutoverKeys.family,
-];
-// Principal, connector, and subject segments are hex digests and connector
-// ids, so none holds a colon.
-const PRINCIPAL_SCOPE = /^principal:[^:]*:/;
-const CONNECTOR_SCOPE = /^conn:[^:]*:/;
-const PARTITION_SCOPE = /^(?:results:|subject:[^:]*:)/;
-/**
- * The family a physical key belongs to, for reports that count keys without
- * naming them: one-shot migrations report per family, never per key. A key
- * no family claims is `connector-owned` when a custom connector wrote it
- * through its own `ctx.storage`, and `unclassified` otherwise (a key an older release wrote).
- */
-export function familyOfKey(key) {
-    let rest = key.replace(PRINCIPAL_SCOPE, "");
-    let scope = "root";
-    for (const [pattern, nested] of [
-        [CONNECTOR_SCOPE, "connector"],
-        [PARTITION_SCOPE, "partition"],
-    ]) {
-        const match = pattern.exec(rest);
-        if (match) {
-            rest = rest.slice(match[0].length);
-            scope = nested;
-            break;
-        }
-    }
-    const family = KEY_FAMILIES.find((candidate) => candidate.scope === scope && candidate.prefixes.some((prefix) => rest.startsWith(prefix)));
-    if (family)
-        return family.name;
-    return scope === "connector" ? "connector-owned" : "unclassified";
-}
+/** Retired OAuth names are inspected only to report that fresh consent is required. */
+export const retiredOAuthKeys = {
+    scan: "oauth:",
+    prefixes: [
+        "oauth:client",
+        "oauth:tokens",
+        "oauth:pending",
+        "oauth:verifier",
+        "oauth:state",
+        "oauth:discovery",
+        "oauth:generation",
+        "oauth:cleanup:",
+        "oauth:cleanup-at:",
+    ],
+};

package/dist/storage/sql-native.js

@@ -177,107 +177,6 @@ export function nativeSqlStorage(driver) {
         },
     };
 }
-/** Keys one read compares: D1 binds at most 100 parameters, one is `now`. */
-const COPY_READ_KEYS = 99;
-/** Writes one transaction carries, by count and by UTF-8 bytes. */
-const COPY_BATCH_STATEMENTS = 50;
-const COPY_BATCH_BYTES = 4 * 1024 * 1024;
-/**
- * Copy entries into the key-value table, verbatim: same key, same value,
- * same absolute expiry. A live row holding a different value is kept unless
- * `overwrite` is set, so a second copy of the same entries writes nothing.
- * Writes go out in bounded transactions; the outcomes follow `entries`.
- */
-export function copyIntoSqlEffect(driver, entries, options) {
-    return Effect.gen(function* () {
-        const { overwrite, now } = options;
-        for (const entry of entries)
-            validateStorageKey(entry.key);
-        yield* driver.batch(KV_SCHEMA.map((statement) => sql(statement)));
-        const live = "(expires_at_ms IS NULL OR expires_at_ms > ?)";
-        const currentValues = (keys) => Effect.gen(function* () {
-            const values = new Map();
-            for (let start = 0; start < keys.length; start += COPY_READ_KEYS) {
-                const chunk = keys.slice(start, start + COPY_READ_KEYS);
-                const rows = yield* driver.all(sql(`SELECT key, ${textColumn("value")}, expires_at_ms FROM connecta_kv
-         WHERE key IN (${chunk.map(() => "?").join(", ")}) AND ${live}`, ...chunk, now));
-                // The message names no key: a copy's errors reach operator output.
-                for (const row of rows) {
-                    values.set(row.key, {
-                        value: textOf(row.value, row.value_bytes, "a stored value") ?? "",
-                        expiresAtMs: row.expires_at_ms,
-                    });
-                }
-            }
-            return values;
-        });
-        const outcomes = Array.from({ length: entries.length });
-        const writes = [];
-        const existing = yield* currentValues(entries.map((entry) => entry.key));
-        for (const [index, entry] of entries.entries()) {
-            const current = existing.get(entry.key);
-            if (current?.value === entry.value && current.expiresAtMs === entry.expiresAtMs) {
-                outcomes[index] = "unchanged";
-            }
-            else if (current !== undefined && !overwrite) {
-                outcomes[index] = "conflict";
-            }
-            else {
-                outcomes[index] = current === undefined ? "copied" : "overwritten";
-                writes.push({
-                    index,
-                    bytes: new TextEncoder().encode(entry.key).byteLength + new TextEncoder().encode(entry.value).byteLength + 32,
-                    statement: overwrite
-                        ? sql(`INSERT INTO connecta_kv (key, value, expires_at_ms)
-               VALUES (?, ?, ?)
-               ON CONFLICT (key) DO UPDATE SET
-                 value = excluded.value, expires_at_ms = excluded.expires_at_ms`, entry.key, entry.value, entry.expiresAtMs)
-                        : // Absent when read; a live row written since is kept, not replaced.
-                            sql(`INSERT INTO connecta_kv (key, value, expires_at_ms)
-               VALUES (?, ?, ?)
-               ON CONFLICT (key) DO UPDATE SET
-                 value = excluded.value, expires_at_ms = excluded.expires_at_ms
-               WHERE connecta_kv.expires_at_ms IS NOT NULL
-                 AND connecta_kv.expires_at_ms <= ?`, entry.key, entry.value, entry.expiresAtMs, now),
-                });
-            }
-        }
-        const raced = [];
-        let batch = [];
-        let batchBytes = 0;
-        const flush = () => Effect.gen(function* () {
-            if (batch.length === 0)
-                return;
-            const changes = yield* driver.batch(batch.map((write) => write.statement));
-            for (const [position, write] of batch.entries()) {
-                if (!(changes[position] > 0))
-                    raced.push(write.index);
-            }
-            batch = [];
-            batchBytes = 0;
-        });
-        for (const write of writes) {
-            if (batch.length > 0 && (batch.length >= COPY_BATCH_STATEMENTS || batchBytes + write.bytes > COPY_BATCH_BYTES)) {
-                yield* flush();
-            }
-            batch.push(write);
-            batchBytes += write.bytes;
-        }
-        yield* flush();
-        // A row another writer added between the read and the write: report what
-        // it holds, and leave it.
-        if (raced.length > 0) {
-            const after = yield* currentValues(raced.map((index) => entries[index].key));
-            for (const index of raced) {
-                const entry = entries[index];
-                const current = after.get(entry.key);
-                outcomes[index] =
-                    current?.value === entry.value && current.expiresAtMs === entry.expiresAtMs ? "unchanged" : "conflict";
-            }
-        }
-        return outcomes;
-    });
-}
 // --- activity -----------------------------------------------------------
 /**
  * The activity table, with keyset paging on `(occurred_at_ms, id)`. Its shape

package/dist/storage/sql.d.ts

@@ -1,7 +1,5 @@
 import type { ActivityStore } from "../activity.js";
 import type { KVStorage } from "../types.js";
-/** The 0.28-compatible key-value table and expiry index. */
-export { KV_SCHEMA } from "./sql-schema.js";
 type SqlValue = string | number | null;
 export interface SqlStatement {
     readonly sql: string;
@@ -21,18 +19,6 @@ export interface SqlDriver {
 }
 /** The two drivers, as `describe()` names them. */
 export type SqlKind = "d1" | "sqlite";
-export interface SqlCopyEntry {
-    readonly key: string;
-    readonly value: string;
-    /** Epoch milliseconds; null never expires. */
-    readonly expiresAtMs: number | null;
-}
-/**
- * What a copy did with one entry: written where no live row was, left alone
- * because the live row already held the value, refused because it held
- * another (`conflict`), or replaced under `overwrite` (`overwritten`).
- */
-export type SqlCopyOutcome = "copied" | "unchanged" | "conflict" | "overwritten";
 export interface SqlActivityOptions {
     /**
      * Days of history kept. Each write removes a bounded batch of older rows,
@@ -48,13 +34,4 @@ export declare function sqlStorage(driver: SqlDriver, kind: SqlKind): KVStorage;
  * payload to leak.
  */
 export declare function sqlActivityStore(driver: SqlDriver, kind: SqlKind, options?: SqlActivityOptions): ActivityStore;
-/**
- * Copy entries into the key-value table, verbatim: same key, same value,
- * same absolute expiry. A live row holding a different value is kept unless
- * `overwrite` is set, so a second copy of the same entries writes nothing.
- * Writes go out in bounded transactions; the outcomes follow `entries`.
- */
-export declare function copyIntoSql(driver: SqlDriver, entries: readonly SqlCopyEntry[], options: {
-    overwrite: boolean;
-    now: number;
-}): Promise<SqlCopyOutcome[]>;
+export {};

package/dist/storage/sql.js

@@ -1,9 +1,7 @@
 import { runEdge } from "../runtime/run.js";
 import { registerNativeStorage, registerNativeActivity } from "../runtime/native-storage.js";
 import { nativeSqlDriver } from "./sql-driver.js";
-import { nativeSqlStorage, nativeSqlActivityStore, copyIntoSqlEffect } from "./sql-native.js";
-/** The 0.28-compatible key-value table and expiry index. */
-export { KV_SCHEMA } from "./sql-schema.js";
+import { nativeSqlStorage, nativeSqlActivityStore } from "./sql-native.js";
 /** `KVStorage` over one `connecta_kv` table. */
 export function sqlStorage(driver, kind) {
     const native = nativeSqlStorage(nativeSqlDriver(driver));
@@ -30,12 +28,3 @@ export function sqlActivityStore(driver, kind, options = {}) {
         list: (options) => runEdge(native.list(options)),
     }, native);
 }
-/**
- * Copy entries into the key-value table, verbatim: same key, same value,
- * same absolute expiry. A live row holding a different value is kept unless
- * `overwrite` is set, so a second copy of the same entries writes nothing.
- * Writes go out in bounded transactions; the outcomes follow `entries`.
- */
-export function copyIntoSql(driver, entries, options) {
-    return runEdge(copyIntoSqlEffect(nativeSqlDriver(driver), entries, options));
-}

package/dist/tool-error.js

@@ -0,0 +1,4 @@
+export function toolError(error, fields = {}) {
+    const structuredContent = { ...fields, error };
+    return { content: [{ type: "text", text: JSON.stringify(structuredContent) }], structuredContent, isError: true };
+}

package/dist/url-safety.js

@@ -117,10 +117,6 @@ export function classifyHost(hostname) {
         return "loopback";
     return "public";
 }
-/** True for loopback and private hosts alike. */
-export function isPrivateHost(hostname) {
-    return classifyHost(hostname) !== "public";
-}
 /**
  * Why connecta must not fetch `target`, a URL the downstream advertised, for a
  * connector configured at `configured` — or undefined when it may.

package/dist/usage-guide.js

@@ -84,8 +84,8 @@ Split remaining reads. Never replay writes for their output.
 
 ## Per-connector guides
 
-Fetch a listed guide with skills by its exact name, or \`connecta.skill(name)\`
-inside a program; it returns \`{ name, text, format: "text" }\`.
+Fetch a listed guide by its exact name with the skills tool, or
+\`connecta.skill(name)\` inside a program; it returns \`{ name, text, format: "text" }\`.
 \`guideRequired: true\` is a hard stop. connector_required and approval_required
 remain after schema expansion; schema_truncated clears after exact describe.
 Otherwise fetch for units, pagination, aliases, or sequences.

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CONNECTA_VERSION = "0.37.1";
+export declare const CONNECTA_VERSION = "0.38.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.37.1";
+export const CONNECTA_VERSION = "0.38.0";

package/dist/worker.js

@@ -47,7 +47,7 @@ function routeGuestImports(source) {
 export function workerExecutor(options) {
     // One pool per executor, so per isolate. A queued run may wait out one
     // default guest deadline: programs spend it awaiting host calls, and a
-    // five-second wait refused nearly every run queued behind one (#1106).
+    // five-second wait refused nearly every run queued behind one.
     const admission = new AdmissionController(options.admission ?? {
         concurrency: 2,
         maxQueueSize: 8,

package/documentation/README.md

@@ -36,20 +36,8 @@ The separate `@zackbart/connecta-eve` helper is available from 0.35.0. Its
 [package guide](https://github.com/zackbart/connecta/blob/main/packages/connecta-eve/README.md)
 owns installation, supported Node/Eve versions, and token-source setup.
 
-## Audience rule
-
-`documentation/`, `templates/`, and `examples/worker/` are written first for an
-agent operating a deployment from the installed package. The root `README.md`
-and `guides/` explain the product for people and also ship in the package;
-they own no operator contracts. Operator conventions must be self-contained rules plus a
-neutral example. Decision records and issues explain why; no operator task
-requires them, `spec/`, `.claude/`, or the Connecta source checkout. Those
-three directories do not ship. Contributor source maps, INV citations, and
-implementation/test evidence belong under clearly labeled contributor
-headings and are optional for operators. Use `assistant`, `alice`, `bob`,
-`crm`, `tickets`, `notes_alice`, and `alice@example.com` in examples; never
-real deployment, client, person, or organization names. Maintained provider
-product names stay.
+For pre-0.29 storage or OAuth grants, complete the [retired layout migrations](./migration-retired-layouts.md)
+on 0.37.1 before upgrading past that bridge release.
 
 ## Contract reference
 
@@ -61,6 +49,7 @@ product names stay.
 | [Architecture (contributor reference)](./architecture.md)        | Request lifetimes, routes, storage, configuration, import boundaries, and Effect implementation               |
 | [Operator UI](./operator-ui.md)                                  | Optional UI setup, scoped configuration and live-data contract, activity disclosure, and UI implementation    |
 | [Operator UI tests (contributor reference)](./operator-tests.md) | Browser state matrix, real-server flows, and snapshot maintenance                                             |
+| [Retired layout migrations](./migration-retired-layouts.md)      | Required 0.37.1 bridge for KV, JSON state, and OAuth layout-2 grants                                          |
 | [Migration to 0.33](./migration-0.33.md)                         | Upgrade actions from 0.32 options to maintainers, members, agents, agent endpoints, and pool owners           |
 | [Provider migration for 0.29](./provider-migration-0.29.md)      | Upgrade actions for Notion, Vercel, and Cloudflare; provider reconciliation tables supply exact name mappings |
 | [Provider migration for 0.35](./provider-migration-0.35.md)      | Provider upgrade actions for 0.35.0                                                                           |
@@ -72,34 +61,9 @@ implementation evidence.
 
 ## Contributor reference
 
-### Documentation ownership
-
-The root [README](../README.md) explains the product for people. It owns what
-Connecta offers and the setup handoff. The human guides explain
-[how it works](../guides/how-it-works.md), [connecting agents](../guides/connecting-agents.md),
-and [safety and trust](../guides/safety-and-trust.md). Keep their examples small
-and consistent with these contracts. Configuration references, complete setup
-procedures, migrations, and internal module maps belong here in agent documentation.
-
-[AGENTS.md](https://github.com/zackbart/connecta/blob/main/AGENTS.md) is the
-canonical repository policy, with `CLAUDE.md` as its symlink. Do not copy its
-verification, review, or release rules into another policy document.
-
-Deployment-local READMEs and agent instructions own runnable platform setup:
-[Node and Docker](../templates/node/README.md), [Workers](../examples/worker/README.md).
-Keep those aligned with their configuration and with this task router.
-Repository [skills](https://github.com/zackbart/connecta/tree/main/.claude/skills)
-own scoped change procedures. Each [provider folder](https://github.com/zackbart/connecta/tree/main/src/providers)
-owns its maintained `SKILL.md`, options, tests, fixtures, and review data.
-Use those details instead of copying provider catalogs into general guides.
-The provider list in the human README is generated; preserve its marker pair
-and run `pnpm run check:providers-generated` after edits.
-
-When changing behavior, update its owning contract and task guide in the same
-change. Check examples against current source and point to the tests that
-defend the contract. Published Markdown links to repo-only files must use
-canonical `https://github.com/zackbart/connecta/blob/main/…` or `tree/main/…`
-links. Keep `documentation/` flat, with Markdown files only.
+For source changes, follow [AGENTS.md](https://github.com/zackbart/connecta/blob/main/AGENTS.md).
+Contributor references describe implementation and test evidence; deployment
+operators can use the task procedures above without a source checkout.
 
 The [changelog](../CHANGELOG.md) records shipped releases.
 [Decisions](https://github.com/zackbart/connecta/tree/main/decisions) explain