khotan-data 0.1.0 → 0.2.0

package/dist/factory.js

@@ -1,4 +1,4 @@
-import { eq, desc, sql, inArray, count } from 'drizzle-orm';
+import { eq, desc, sql, inArray, count, and } from 'drizzle-orm';
 import { pgTable, timestamp, text, boolean, unique, index, jsonb, integer } from 'drizzle-orm/pg-core';
 
 // src/factory.ts
@@ -162,7 +162,7 @@ var khotanRuns = pgTable(
     )
   ]
 );
-var khotanMappings = pgTable(
+var khotanMappingsTable = pgTable(
   "khotan_mappings",
   {
     id: text("id").primaryKey().$defaultFn(() => crypto.randomUUID()),
@@ -182,6 +182,39 @@ var khotanMappings = pgTable(
     index("khotan_mappings_refs_gin_idx").using("gin", table.refs)
   ]
 );
+var khotanCaches = pgTable(
+  "khotan_caches",
+  {
+    id: text("id").primaryKey().$defaultFn(() => crypto.randomUUID()),
+    name: text("name").notNull().unique(),
+    scope: jsonb("scope").$type(),
+    ttlSeconds: integer("ttl_seconds"),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull()
+  },
+  (table) => [index("khotan_caches_name_idx").on(table.name)]
+);
+var khotanCacheEntries = pgTable(
+  "khotan_cache_entries",
+  {
+    id: text("id").primaryKey().$defaultFn(() => crypto.randomUUID()),
+    cacheId: text("cache_id").notNull(),
+    key: text("key").notNull(),
+    value: jsonb("value").notNull().$type(),
+    expiresAt: timestamp("expires_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull()
+  },
+  (table) => [
+    unique("khotan_cache_entries_cache_id_key_unique").on(
+      table.cacheId,
+      table.key
+    ),
+    index("khotan_cache_entries_cache_id_idx").on(table.cacheId),
+    index("khotan_cache_entries_cache_id_key_idx").on(table.cacheId, table.key),
+    index("khotan_cache_entries_expires_at_idx").on(table.expiresAt)
+  ]
+);
 async function deriveKey(secret) {
   const encoded = new TextEncoder().encode(secret);
   const hash = await crypto.subtle.digest("SHA-256", encoded);
@@ -226,6 +259,104 @@ function hexToBytes(hex) {
 function bytesToHex(bytes) {
   return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
+var CLI_TOKEN_SCHEME = "KhotanCLI";
+var CLI_TOKEN_WINDOW_MS = 6e4;
+async function deriveCliToken(secret, timestamp2) {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    new TextEncoder().encode(`khotan-cli:${timestamp2}`)
+  );
+  return bytesToHex(new Uint8Array(sig));
+}
+function timingSafeEqualHex(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+async function isCliRequestAuthorized(request, secret) {
+  if (process.env["NODE_ENV"] === "production") return false;
+  if (!secret) return false;
+  const header = request.headers.get("authorization");
+  if (!header?.startsWith(`${CLI_TOKEN_SCHEME} `)) return false;
+  const token = header.slice(CLI_TOKEN_SCHEME.length + 1).trim();
+  const dotIdx = token.indexOf(".");
+  if (dotIdx === -1) return false;
+  const timestamp2 = token.slice(0, dotIdx);
+  const provided = token.slice(dotIdx + 1);
+  const ts = Number.parseInt(timestamp2, 10);
+  if (!Number.isFinite(ts)) return false;
+  if (Math.abs(Date.now() - ts) > CLI_TOKEN_WINDOW_MS) return false;
+  const expected = await deriveCliToken(secret, timestamp2);
+  return timingSafeEqualHex(provided, expected);
+}
+function bindPlugWithVars(plug, vars, setVars) {
+  const opts = (extra) => ({
+    ...extra,
+    vars,
+    ...setVars ? { _setVars: setVars } : {}
+  });
+  return {
+    get(path, extra) {
+      return plug.get(path, opts(extra));
+    },
+    post(path, extra) {
+      return plug.post(path, opts(extra));
+    },
+    put(path, extra) {
+      return plug.put(path, opts(extra));
+    },
+    patch(path, extra) {
+      return plug.patch(path, opts(extra));
+    },
+    delete(path, extra) {
+      return plug.delete(path, opts(extra));
+    }
+  };
+}
+function bindWorkflowPlug(plug, ctx, plugName = ctx.flow.plugName) {
+  const vars = plugName === ctx.flow.plugName ? ctx.vars : ctx.plugVarsByName?.[plugName] ?? {};
+  if (plugName !== ctx.flow.plugName) {
+    ctx.plugVarsByName ??= {};
+    ctx.plugVarsByName[plugName] = vars;
+  }
+  return bindPlugWithVars(plug, vars, async (updates) => {
+    Object.assign(vars, updates);
+  });
+}
+var khotanRuntimeRegistry = /* @__PURE__ */ new Map();
+function getWorkflowRuntimeHelpers(ctx) {
+  const helpers = khotanRuntimeRegistry.get(ctx.khotanInstanceId);
+  if (!helpers) {
+    throw new Error(
+      `Khotan runtime helpers for instance "${ctx.khotanInstanceId}" are not registered`
+    );
+  }
+  return helpers;
+}
+function khotanCache(ctx, cacheName) {
+  return getWorkflowRuntimeHelpers(ctx).cache(cacheName);
+}
+function khotanMappings(ctx) {
+  const helpers = getWorkflowRuntimeHelpers(ctx);
+  return {
+    list: helpers.listMappings,
+    lookup: helpers.lookupMapping,
+    upsert: helpers.upsertMapping,
+    update: helpers.updateMapping,
+    delete: helpers.deleteMapping
+  };
+}
 function drizzleAdapter(db) {
   return {
     async upsertPlug(plug) {
@@ -374,27 +505,93 @@ function drizzleAdapter(db) {
     async upsertResource(resource) {
       const rows = await db.insert(khotanResources).values({
         name: resource.name,
-        connectField: resource.connectField,
+        connectField: serializeConnectField(resource.connectField),
         description: resource.description ?? null
       }).onConflictDoUpdate({
         target: khotanResources.name,
         set: {
-          connectField: resource.connectField,
+          connectField: serializeConnectField(resource.connectField),
           description: resource.description ?? null,
           updatedAt: /* @__PURE__ */ new Date()
         }
       }).returning({ id: khotanResources.id });
       return { id: rows[0].id };
     },
+    async upsertCache(cache) {
+      const rows = await db.insert(khotanCaches).values({
+        name: cache.name,
+        scope: cache.scope ?? null,
+        ttlSeconds: cache.ttlSeconds ?? null
+      }).onConflictDoUpdate({
+        target: khotanCaches.name,
+        set: {
+          scope: cache.scope ?? null,
+          ttlSeconds: cache.ttlSeconds ?? null,
+          updatedAt: /* @__PURE__ */ new Date()
+        }
+      }).returning({ id: khotanCaches.id });
+      return { id: rows[0].id };
+    },
+    async getCacheByName(name) {
+      const rows = await db.select().from(khotanCaches).where(eq(khotanCaches.name, name)).limit(1);
+      return rows[0] ?? null;
+    },
+    async getCacheEntry(cacheId, key) {
+      const rows = await db.select({
+        id: khotanCacheEntries.id,
+        cacheId: khotanCacheEntries.cacheId,
+        key: khotanCacheEntries.key,
+        value: khotanCacheEntries.value,
+        expiresAt: khotanCacheEntries.expiresAt,
+        createdAt: khotanCacheEntries.createdAt,
+        updatedAt: khotanCacheEntries.updatedAt
+      }).from(khotanCacheEntries).where(
+        and(
+          eq(khotanCacheEntries.cacheId, cacheId),
+          eq(khotanCacheEntries.key, key)
+        )
+      ).limit(1);
+      return rows[0] ?? null;
+    },
+    async upsertCacheEntry(entry) {
+      const existing = await db.select({ id: khotanCacheEntries.id }).from(khotanCacheEntries).where(
+        and(
+          eq(khotanCacheEntries.cacheId, entry.cacheId),
+          eq(khotanCacheEntries.key, entry.key)
+        )
+      ).limit(1);
+      const rows = await db.insert(khotanCacheEntries).values({
+        cacheId: entry.cacheId,
+        key: entry.key,
+        value: entry.value,
+        expiresAt: entry.expiresAt ?? null
+      }).onConflictDoUpdate({
+        target: [khotanCacheEntries.cacheId, khotanCacheEntries.key],
+        set: {
+          value: entry.value,
+          expiresAt: entry.expiresAt ?? null,
+          updatedAt: /* @__PURE__ */ new Date()
+        }
+      }).returning({ id: khotanCacheEntries.id });
+      return { id: rows[0].id, created: existing.length === 0 };
+    },
+    async deleteCacheEntry(cacheId, key) {
+      await db.delete(khotanCacheEntries).where(
+        and(
+          eq(khotanCacheEntries.cacheId, cacheId),
+          eq(khotanCacheEntries.key, key)
+        )
+      );
+    },
     async listResources() {
       const flowCounts = db.select({
         resourceId: khotanFlows.resourceId,
         flowCount: count(khotanFlows.id).as("flow_count")
       }).from(khotanFlows).where(sql`${khotanFlows.resourceId} is not null`).groupBy(khotanFlows.resourceId).as("flow_counts");
       const mappingCounts = db.select({
-        resourceId: khotanMappings.resourceId,
-        mappingCount: count(khotanMappings.id).as("mapping_count")
-      }).from(khotanMappings).groupBy(khotanMappings.resourceId).as("mapping_counts");
+        resourceId: khotanMappingsTable.resourceId,
+        mappingCount: count(khotanMappingsTable.id).as("mapping_count")
+      }).from(khotanMappingsTable).groupBy(khotanMappingsTable.resourceId).as("mapping_counts");
       const rows = await db.select({
         id: khotanResources.id,
         name: khotanResources.name,
@@ -408,57 +605,79 @@ function drizzleAdapter(db) {
         mappingCounts,
         eq(khotanResources.id, mappingCounts.resourceId)
       );
-      return rows;
+      return rows.map((row) => ({
+        ...row,
+        connectField: deserializeConnectField(row.connectField)
+      }));
     },
     async getResource(id) {
       const rows = await db.select().from(khotanResources).where(eq(khotanResources.id, id)).limit(1);
-      return rows[0] ?? null;
+      if (!rows[0]) return null;
+      return {
+        ...rows[0],
+        connectField: deserializeConnectField(rows[0].connectField)
+      };
     },
     async getResourceFlows(resourceId) {
       return db.select().from(khotanFlows).where(eq(khotanFlows.resourceId, resourceId));
     },
     async upsertMapping(mapping) {
       if (mapping.id) {
-        const rows2 = await db.update(khotanMappings).set({
+        const rows2 = await db.update(khotanMappingsTable).set({
           resourceId: mapping.resourceId,
           connectValue: mapping.connectValue,
           refs: mapping.refs,
           metadata: mapping.metadata ?? null,
           updatedAt: /* @__PURE__ */ new Date()
-        }).where(eq(khotanMappings.id, mapping.id)).returning({ id: khotanMappings.id });
+        }).where(eq(khotanMappingsTable.id, mapping.id)).returning({ id: khotanMappingsTable.id });
         return { id: rows2[0].id, created: false };
       }
-      const existing = await db.select({ id: khotanMappings.id }).from(khotanMappings).where(
-        sql`${khotanMappings.resourceId} = ${mapping.resourceId} and ${khotanMappings.connectValue} = ${mapping.connectValue}`
+      const existing = await db.select({ id: khotanMappingsTable.id }).from(khotanMappingsTable).where(
+        sql`${khotanMappingsTable.resourceId} = ${mapping.resourceId} and ${khotanMappingsTable.connectValue} = ${mapping.connectValue}`
       ).limit(1);
-      const rows = await db.insert(khotanMappings).values({
+      const rows = await db.insert(khotanMappingsTable).values({
         resourceId: mapping.resourceId,
         connectValue: mapping.connectValue,
         refs: mapping.refs,
         metadata: mapping.metadata ?? null
       }).onConflictDoUpdate({
-        target: [khotanMappings.resourceId, khotanMappings.connectValue],
+        target: [khotanMappingsTable.resourceId, khotanMappingsTable.connectValue],
         set: {
-          refs: sql`${khotanMappings.refs} || ${JSON.stringify(mapping.refs)}::jsonb`,
+          refs: sql`${khotanMappingsTable.refs} || ${JSON.stringify(mapping.refs)}::jsonb`,
           metadata: mapping.metadata ?? null,
           updatedAt: /* @__PURE__ */ new Date()
         }
-      }).returning({ id: khotanMappings.id });
+      }).returning({ id: khotanMappingsTable.id });
       return { id: rows[0].id, created: existing.length === 0 };
     },
     async getMapping(id) {
-      const rows = await db.select().from(khotanMappings).where(eq(khotanMappings.id, id)).limit(1);
+      const rows = await db.select().from(khotanMappingsTable).where(eq(khotanMappingsTable.id, id)).limit(1);
       return rows[0] ?? null;
     },
-    async listMappings(resourceId) {
-      return db.select().from(khotanMappings).where(eq(khotanMappings.resourceId, resourceId));
+    async listMappings({ resourceId, limit, offset, search }) {
+      const normalizedSearch = search?.trim();
+      const searchPattern = normalizedSearch ? `%${normalizedSearch.replace(/[%_]/g, "\\$&")}%` : null;
+      const filters = searchPattern ? sql`${khotanMappingsTable.resourceId} = ${resourceId} and (${khotanMappingsTable.connectValue} ilike ${searchPattern} escape '\\' or ${khotanMappingsTable.refs}::text ilike ${searchPattern} escape '\\' or ${khotanMappingsTable.metadata}::text ilike ${searchPattern} escape '\\')` : sql`${khotanMappingsTable.resourceId} = ${resourceId}`;
+      const totalRows = await db.select({ total: count(khotanMappingsTable.id) }).from(khotanMappingsTable).where(filters);
+      const rows = await db.select().from(khotanMappingsTable).where(filters).orderBy(khotanMappingsTable.connectValue, khotanMappingsTable.id).limit(limit + 1).offset(offset);
+      return {
+        items: rows.slice(0, limit),
+        hasMore: rows.length > limit,
+        total: totalRows[0]?.total ?? 0
+      };
     },
     async deleteMapping(id) {
-      await db.delete(khotanMappings).where(eq(khotanMappings.id, id));
+      await db.delete(khotanMappingsTable).where(eq(khotanMappingsTable.id, id));
     },
-    async lookupMapping({ resourceId, plugName, ref }) {
-      const rows = await db.select().from(khotanMappings).where(
-        sql`${khotanMappings.resourceId} = ${resourceId} and ${khotanMappings.refs}->>${plugName} = ${ref}`
+    async lookupMapping(params) {
+      if ("connectValue" in params) {
+        const rows2 = await db.select().from(khotanMappingsTable).where(
+          sql`${khotanMappingsTable.resourceId} = ${params.resourceId} and ${khotanMappingsTable.connectValue} = ${params.connectValue}`
+        ).limit(1);
+        return rows2[0] ?? null;
+      }
+      const rows = await db.select().from(khotanMappingsTable).where(
+        sql`${khotanMappingsTable.resourceId} = ${params.resourceId} and ${khotanMappingsTable.refs}->>${params.plugName} = ${params.ref}`
       ).limit(1);
       return rows[0] ?? null;
     },
@@ -791,6 +1010,149 @@ function getErrorMessage(error) {
   if (error instanceof Error) return error.message;
   return "Unknown error";
 }
+var CRON_MONTH_ALIASES = {
+  jan: 1,
+  feb: 2,
+  mar: 3,
+  apr: 4,
+  may: 5,
+  jun: 6,
+  jul: 7,
+  aug: 8,
+  sep: 9,
+  oct: 10,
+  nov: 11,
+  dec: 12
+};
+var CRON_DAY_ALIASES = {
+  sun: 0,
+  mon: 1,
+  tue: 2,
+  wed: 3,
+  thu: 4,
+  fri: 5,
+  sat: 6
+};
+function parseCronValue(token, spec) {
+  const normalized = token.trim().toLowerCase();
+  if (normalized === "") {
+    throw new Error("Cron token cannot be empty");
+  }
+  if (spec.aliases?.[normalized] !== void 0) {
+    return spec.aliases[normalized];
+  }
+  const parsed = Number.parseInt(normalized, 10);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`Invalid cron token: "${token}"`);
+  }
+  if (spec.aliases === CRON_DAY_ALIASES && parsed === 7) {
+    return 0;
+  }
+  if (parsed < spec.min || parsed > spec.max) {
+    throw new Error(
+      `Cron value "${token}" is out of range ${spec.min}-${spec.max}`
+    );
+  }
+  return parsed;
+}
+function cronFieldIsWildcard(field) {
+  return field.trim() === "*";
+}
+function matchesCronField(field, value, spec) {
+  return field.split(",").map((part) => part.trim()).filter(Boolean).some((part) => {
+    if (part === "*") return true;
+    const [baseRaw, stepRaw] = part.split("/");
+    const base = baseRaw?.trim() ?? "";
+    const step = stepRaw ? Number.parseInt(stepRaw.trim(), 10) : 1;
+    if (!Number.isFinite(step) || step <= 0) {
+      throw new Error(`Invalid cron step: "${part}"`);
+    }
+    let start;
+    let end;
+    if (base === "*" || base === "") {
+      start = spec.min;
+      end = spec.max;
+    } else if (base.includes("-")) {
+      const [startRaw, endRaw] = base.split("-");
+      start = parseCronValue(startRaw ?? "", spec);
+      end = parseCronValue(endRaw ?? "", spec);
+      if (end < start) {
+        throw new Error(`Invalid cron range: "${part}"`);
+      }
+    } else {
+      start = parseCronValue(base, spec);
+      end = stepRaw ? spec.max : start;
+    }
+    if (value < start || value > end) return false;
+    return (value - start) % step === 0;
+  });
+}
+function matchesCronSchedule(schedule, now) {
+  const parts = schedule.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error(`Cron schedule must have 5 fields: "${schedule}"`);
+  }
+  const [minute, hour, dayOfMonth, month, dayOfWeek] = parts;
+  const minuteMatch = matchesCronField(minute, now.getUTCMinutes(), {
+    min: 0,
+    max: 59
+  });
+  const hourMatch = matchesCronField(hour, now.getUTCHours(), {
+    min: 0,
+    max: 23
+  });
+  const monthMatch = matchesCronField(month, now.getUTCMonth() + 1, {
+    min: 1,
+    max: 12,
+    aliases: CRON_MONTH_ALIASES
+  });
+  const dayOfMonthMatch = matchesCronField(dayOfMonth, now.getUTCDate(), {
+    min: 1,
+    max: 31
+  });
+  const dayOfWeekMatch = matchesCronField(dayOfWeek, now.getUTCDay(), {
+    min: 0,
+    max: 6,
+    aliases: CRON_DAY_ALIASES
+  });
+  const dayOfMonthWildcard = cronFieldIsWildcard(dayOfMonth);
+  const dayOfWeekWildcard = cronFieldIsWildcard(dayOfWeek);
+  const dayMatches = dayOfMonthWildcard && dayOfWeekWildcard ? true : dayOfMonthWildcard ? dayOfWeekMatch : dayOfWeekWildcard ? dayOfMonthMatch : dayOfMonthMatch || dayOfWeekMatch;
+  return minuteMatch && hourMatch && monthMatch && dayMatches;
+}
+function startOfUtcMinute(date) {
+  return new Date(
+    Date.UTC(
+      date.getUTCFullYear(),
+      date.getUTCMonth(),
+      date.getUTCDate(),
+      date.getUTCHours(),
+      date.getUTCMinutes(),
+      0,
+      0
+    )
+  );
+}
+function coerceDate(value) {
+  if (value instanceof Date && Number.isFinite(value.getTime())) {
+    return value;
+  }
+  if (typeof value === "string" || typeof value === "number") {
+    const parsed = new Date(value);
+    if (Number.isFinite(parsed.getTime())) return parsed;
+  }
+  return null;
+}
+function isCronRequestAuthorized(request) {
+  const secret = process.env["CRON_SECRET"]?.trim();
+  if (!secret) {
+    return process.env["NODE_ENV"] !== "production";
+  }
+  return request.headers.get("authorization") === `Bearer ${secret}`;
+}
+function isDebugEnabled() {
+  return Boolean(process?.env?.["KHOTAN_DEBUG"]) && process?.env?.["NODE_ENV"] !== "production";
+}
 function isWorkflowCancelledError(error) {
   if (!error || typeof error !== "object") return false;
   const record = error;
@@ -903,31 +1265,263 @@ function serializeEndpoints(endpoints) {
   }
   return result;
 }
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function serializeConnectField(connectField) {
+  return Array.isArray(connectField) ? JSON.stringify(connectField) : connectField;
+}
+function deserializeConnectField(connectField) {
+  if (Array.isArray(connectField)) {
+    return connectField;
+  }
+  if (typeof connectField !== "string") {
+    throw new Error("Resource connectField must be a string or string array");
+  }
+  const trimmed = connectField.trim();
+  if (!trimmed.startsWith("[")) {
+    return connectField;
+  }
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (Array.isArray(parsed) && parsed.length > 0 && parsed.every((value) => typeof value === "string" && value.length > 0)) {
+      return parsed;
+    }
+  } catch {
+  }
+  return connectField;
+}
+function validateConnectField(resourceName, connectField) {
+  if (typeof connectField === "string") {
+    if (!connectField.trim()) {
+      throw new Error(
+        `Resource "${resourceName}" must declare a non-empty connectField`
+      );
+    }
+    return;
+  }
+  if (!Array.isArray(connectField) || connectField.length === 0) {
+    throw new Error(
+      `Resource "${resourceName}" must declare connectField as a string or non-empty ordered string array`
+    );
+  }
+  for (const field of connectField) {
+    if (typeof field !== "string" || !field.trim()) {
+      throw new Error(
+        `Resource "${resourceName}" has an invalid composite connectField entry`
+      );
+    }
+  }
+}
+function validateResourcePlugs(resource, plugNames) {
+  if (resource.mapping.plugs === void 0) {
+    return;
+  }
+  if (!isPlainObject(resource.mapping.plugs)) {
+    throw new Error(
+      `Resource "${resource.name}" must declare mapping.plugs as an object keyed by plug name`
+    );
+  }
+  for (const [plugName, declaration] of Object.entries(resource.mapping.plugs)) {
+    if (!plugNames.has(plugName)) {
+      throw new Error(
+        `Resource "${resource.name}" references unknown plug: "${plugName}"`
+      );
+    }
+    if (!isPlainObject(declaration)) {
+      throw new Error(
+        `Resource "${resource.name}" has an invalid plug declaration for "${plugName}"`
+      );
+    }
+    const keys = Object.keys(declaration);
+    if (keys.length !== 1 || typeof declaration["uniqueIdentifier"] !== "string" || !declaration["uniqueIdentifier"].trim()) {
+      throw new Error(
+        `Resource "${resource.name}" must declare exactly one uniqueIdentifier for plug "${plugName}"`
+      );
+    }
+  }
+}
+function normalizeCacheScope(cacheName, scope) {
+  if (scope === void 0) {
+    return void 0;
+  }
+  if (!isPlainObject(scope)) {
+    throw new Error(`Cache "${cacheName}" must declare scope as an object`);
+  }
+  const normalized = {};
+  for (const key of ["plug", "resource", "flow"]) {
+    const value = scope[key];
+    if (value === void 0) {
+      continue;
+    }
+    if (typeof value !== "string" || !value.trim()) {
+      throw new Error(`Cache "${cacheName}" has an invalid scope.${key} value`);
+    }
+    normalized[key] = value.trim();
+  }
+  return Object.keys(normalized).length > 0 ? normalized : void 0;
+}
+function parseCacheTtlSeconds(cacheName, ttl) {
+  if (ttl === void 0) {
+    return null;
+  }
+  if (typeof ttl === "number") {
+    if (!Number.isFinite(ttl) || ttl <= 0) {
+      throw new Error(`Cache "${cacheName}" must declare a positive ttl`);
+    }
+    return Math.ceil(ttl);
+  }
+  if (typeof ttl !== "string") {
+    throw new Error(`Cache "${cacheName}" must declare ttl as a string or number`);
+  }
+  const normalized = ttl.trim().toLowerCase();
+  const match = /^(\d+)\s*(ms|s|m|h|d)$/.exec(normalized);
+  if (!match) {
+    throw new Error(
+      `Cache "${cacheName}" has an invalid ttl "${ttl}". Use values like "30s", "15m", or "6h"`
+    );
+  }
+  const amount = Number.parseInt(match[1], 10);
+  const unit = match[2];
+  const milliseconds = unit === "ms" ? amount : unit === "s" ? amount * 1e3 : unit === "m" ? amount * 6e4 : unit === "h" ? amount * 36e5 : amount * 864e5;
+  return Math.max(1, Math.ceil(milliseconds / 1e3));
+}
+function validateCacheKey(key) {
+  if (typeof key !== "string" || !key.trim()) {
+    throw new Error("Cache key must be a non-empty string");
+  }
+}
+function coerceCacheEntryRecord(row) {
+  if (typeof row["id"] !== "string" || typeof row["cacheId"] !== "string" || typeof row["key"] !== "string") {
+    return null;
+  }
+  return {
+    id: row["id"],
+    cacheId: row["cacheId"],
+    key: row["key"],
+    value: row["value"],
+    expiresAt: coerceDate(row["expiresAt"]),
+    createdAt: coerceDate(row["createdAt"]) ?? void 0,
+    updatedAt: coerceDate(row["updatedAt"]) ?? void 0
+  };
+}
+function isCacheEntryExpired(entry, now = /* @__PURE__ */ new Date()) {
+  return entry.expiresAt !== null && entry.expiresAt.getTime() <= now.getTime();
+}
+function canonicalizeConnectValue(resource, connectValue) {
+  const { connectField } = resource.mapping;
+  if (Array.isArray(connectField)) {
+    if (typeof connectValue === "string") {
+      return connectValue;
+    }
+    if (!Array.isArray(connectValue)) {
+      throw new Error(
+        `Resource "${resource.name}" expects composite connectValue input matching connectField order`
+      );
+    }
+    if (connectValue.length !== connectField.length) {
+      throw new Error(
+        `Resource "${resource.name}" expects ${String(connectField.length)} connectValue parts in declared order`
+      );
+    }
+    const parts = connectValue.map((part) => {
+      if (typeof part === "string") return part;
+      if (typeof part === "number" || typeof part === "boolean") {
+        return String(part);
+      }
+      throw new Error(
+        `Resource "${resource.name}" connectValue parts must be strings, numbers, or booleans`
+      );
+    });
+    return JSON.stringify(parts);
+  }
+  if (typeof connectValue === "string") {
+    return connectValue;
+  }
+  if (typeof connectValue === "number" || typeof connectValue === "boolean") {
+    return String(connectValue);
+  }
+  throw new Error(
+    `Resource "${resource.name}" expects connectValue to be a string, number, or boolean`
+  );
+}
 function khotan(config) {
-  const { adapter, plugs, resources = [] } = config;
+  const { adapter, plugs, resources = [], caches = [], authorize } = config;
+  const instanceId = crypto.randomUUID();
+  if (!authorize) {
+    console.warn(
+      "[khotan] No `authorize` hook configured: the management API (/api/khotan/*) is publicly accessible. Pass `authorize` to gate it behind your auth layer (e.g. better-auth). This is required for any deployed environment."
+    );
+  }
+  if (!(config.secret ?? process.env["KHOTAN_SECRET"])) {
+    console.warn(
+      "[khotan] No `secret`/`KHOTAN_SECRET` configured: plug credentials and wire metadata will not be encrypted at rest. Set KHOTAN_SECRET to a high-entropy value."
+    );
+  }
+  const plugNames = /* @__PURE__ */ new Set();
+  for (const plug of plugs) {
+    if (plugNames.has(plug.name)) {
+      throw new Error(`Duplicate plug name: "${plug.name}"`);
+    }
+    plugNames.add(plug.name);
+  }
   const resourceNames = /* @__PURE__ */ new Set();
+  const resourceConfigByName = /* @__PURE__ */ new Map();
   for (const resource of resources) {
     if (resourceNames.has(resource.name)) {
       throw new Error(`Duplicate resource name: "${resource.name}"`);
     }
+    validateConnectField(resource.name, resource.mapping.connectField);
+    validateResourcePlugs(resource, plugNames);
     resourceNames.add(resource.name);
+    resourceConfigByName.set(resource.name, resource);
   }
-  const plugNames = /* @__PURE__ */ new Set();
+  const registeredFlowNames = /* @__PURE__ */ new Set();
   for (const plug of plugs) {
-    if (plugNames.has(plug.name)) {
-      throw new Error(`Duplicate plug name: "${plug.name}"`);
-    }
-    plugNames.add(plug.name);
-    if (plug.flows) {
-      for (const flow2 of plug.flows) {
-        if (flow2.resource && !resourceNames.has(flow2.resource)) {
-          throw new Error(
-            `Flow "${flow2.name}" references unknown resource: "${flow2.resource}"`
-          );
-        }
+    if (!plug.flows) continue;
+    for (const flow2 of plug.flows) {
+      registeredFlowNames.add(flow2.name);
+      if (flow2.resource && !resourceNames.has(flow2.resource)) {
+        throw new Error(
+          `Flow "${flow2.name}" references unknown resource: "${flow2.resource}"`
+        );
       }
     }
   }
+  const cacheStateByName = /* @__PURE__ */ new Map();
+  for (const cache of caches) {
+    if (cacheStateByName.has(cache.name)) {
+      throw new Error(`Duplicate cache name: "${cache.name}"`);
+    }
+    if (typeof cache.name !== "string" || !cache.name.trim()) {
+      throw new Error("Cache registrations must declare a non-empty name");
+    }
+    const normalizedScope = normalizeCacheScope(cache.name, cache.scope);
+    if (normalizedScope?.plug && !plugNames.has(normalizedScope.plug)) {
+      throw new Error(
+        `Cache "${cache.name}" references unknown plug: "${normalizedScope.plug}"`
+      );
+    }
+    if (normalizedScope?.resource && !resourceNames.has(normalizedScope.resource)) {
+      throw new Error(
+        `Cache "${cache.name}" references unknown resource: "${normalizedScope.resource}"`
+      );
+    }
+    if (normalizedScope?.flow && !registeredFlowNames.has(normalizedScope.flow)) {
+      throw new Error(
+        `Cache "${cache.name}" references unknown flow: "${normalizedScope.flow}"`
+      );
+    }
+    cacheStateByName.set(cache.name, {
+      id: "",
+      config: {
+        ...cache,
+        name: cache.name.trim(),
+        ...normalizedScope ? { scope: normalizedScope } : {}
+      },
+      ttlSeconds: parseCacheTtlSeconds(cache.name, cache.ttl)
+    });
+  }
   const registeredFlowKeys = new Set(
     plugs.flatMap(
       (plug) => (plug.flows ?? []).map(
@@ -969,16 +1563,31 @@ function khotan(config) {
   }
   let initialized = false;
   let initPromise = null;
+  const resourceIdByName = /* @__PURE__ */ new Map();
+  const resourceConfigById = /* @__PURE__ */ new Map();
   async function doInit() {
     if (initialized) return;
-    const resourceIdMap = /* @__PURE__ */ new Map();
+    resourceIdByName.clear();
+    resourceConfigById.clear();
     for (const resource of resources) {
       const { id } = await adapter.upsertResource({
         name: resource.name,
-        connectField: resource.connectField,
+        connectField: resource.mapping.connectField,
         description: resource.description ?? null
       });
-      resourceIdMap.set(resource.name, id);
+      resourceIdByName.set(resource.name, id);
+      resourceConfigById.set(id, resource);
+    }
+    for (const [cacheName, cacheState] of cacheStateByName) {
+      const { id } = await adapter.upsertCache({
+        name: cacheName,
+        scope: cacheState.config.scope ?? null,
+        ttlSeconds: cacheState.ttlSeconds
+      });
+      cacheStateByName.set(cacheName, {
+        ...cacheState,
+        id
+      });
     }
     for (const plug of plugs) {
       const { id: plugId } = await adapter.upsertPlug({
@@ -996,7 +1605,7 @@ function khotan(config) {
             schedule: flow2.schedule ?? null
           });
           if (flow2.resource) {
-            const resourceId = resourceIdMap.get(flow2.resource);
+            const resourceId = resourceIdByName.get(flow2.resource);
             await adapter.updateFlowResourceId(flowId, resourceId);
           }
         }
@@ -1031,6 +1640,189 @@ function khotan(config) {
     initPromise ??= doInit();
     return initPromise;
   }
+  async function getRegisteredResourceById(resourceId) {
+    await init();
+    return resourceConfigById.get(resourceId) ?? null;
+  }
+  async function resolveCacheState(cacheName) {
+    await init();
+    const cacheState = cacheStateByName.get(cacheName);
+    if (!cacheState || !cacheState.id) {
+      throw new Error(`Cache "${cacheName}" is not registered`);
+    }
+    return cacheState;
+  }
+  function createCacheInstance(cacheName) {
+    return {
+      async get(key) {
+        const entry = await readCacheEntry(cacheName, key);
+        return entry ? entry.value : null;
+      },
+      async set(key, value) {
+        validateCacheKey(key);
+        const cacheState = await resolveCacheState(cacheName);
+        const expiresAt = cacheState.ttlSeconds !== null ? new Date(Date.now() + cacheState.ttlSeconds * 1e3) : null;
+        await adapter.upsertCacheEntry({
+          cacheId: cacheState.id,
+          key,
+          value,
+          expiresAt
+        });
+        return value;
+      },
+      async delete(key) {
+        validateCacheKey(key);
+        const cacheState = await resolveCacheState(cacheName);
+        await adapter.deleteCacheEntry(cacheState.id, key);
+      }
+    };
+  }
+  async function readCacheEntry(cacheName, key) {
+    validateCacheKey(key);
+    const cacheState = await resolveCacheState(cacheName);
+    const row = await adapter.getCacheEntry(cacheState.id, key);
+    if (!row) {
+      return null;
+    }
+    const entry = coerceCacheEntryRecord(row);
+    if (!entry || isCacheEntryExpired(entry)) {
+      return null;
+    }
+    return entry;
+  }
+  function decorateResourceRecord(resource) {
+    const { connectField: storedConnectField, ...rest } = resource;
+    const configResource = typeof resource["name"] === "string" ? resourceConfigByName.get(resource["name"]) : void 0;
+    return {
+      ...rest,
+      mapping: {
+        connectField: configResource?.mapping.connectField ?? deserializeConnectField(storedConnectField),
+        ...configResource?.mapping.plugs ? { plugs: configResource.mapping.plugs } : {}
+      }
+    };
+  }
+  function buildMappingPage(params) {
+    return {
+      items: params.items,
+      page: {
+        limit: params.limit,
+        offset: params.offset,
+        hasMore: params.hasMore,
+        prevOffset: Math.max(params.offset - params.limit, 0),
+        nextOffset: params.offset + params.limit,
+        total: params.total
+      }
+    };
+  }
+  async function validateMappingPayload(params) {
+    if (!isPlainObject(params.refs)) {
+      throw new Error("Mapping refs must be an object keyed by plug name");
+    }
+    for (const [plugName, ref] of Object.entries(params.refs)) {
+      if (typeof ref !== "string") {
+        throw new Error(`Mapping ref "${plugName}" must be a string`);
+      }
+    }
+    if (params.metadata !== void 0 && params.metadata !== null) {
+      if (!isPlainObject(params.metadata)) {
+        throw new Error("Mapping metadata must be an object when provided");
+      }
+    }
+    const resource = await getRegisteredResourceById(params.resourceId);
+    if (!resource) {
+      throw new Error(`Resource "${params.resourceId}" is not registered`);
+    }
+    if (resource.mapping.plugs) {
+      const invalidPlugs = Object.keys(params.refs).filter(
+        (plugName) => !resource.mapping.plugs?.[plugName]
+      );
+      if (invalidPlugs.length > 0) {
+        throw new Error(
+          `Resource "${resource.name}" only allows refs for declared plugs. Invalid refs: ${invalidPlugs.join(", ")}`
+        );
+      }
+    }
+    return resource;
+  }
+  async function listMappings(params) {
+    const resource = await getRegisteredResourceById(params.resourceId);
+    if (!resource) {
+      throw new Error(`Resource "${params.resourceId}" is not registered`);
+    }
+    const limit = Math.min(Math.max(params.limit ?? 20, 1), 100);
+    const offset = Math.max(params.offset ?? 0, 0);
+    const page = await adapter.listMappings({
+      resourceId: params.resourceId,
+      limit,
+      offset,
+      ...params.search?.trim() ? { search: params.search.trim() } : {}
+    });
+    return buildMappingPage({
+      limit,
+      offset,
+      hasMore: page.hasMore,
+      total: page.total,
+      items: page.items
+    });
+  }
+  async function lookupMapping(params) {
+    const resource = await getRegisteredResourceById(params.resourceId);
+    if (!resource) {
+      throw new Error(`Resource "${params.resourceId}" is not registered`);
+    }
+    if ("connectValue" in params) {
+      return adapter.lookupMapping({
+        resourceId: params.resourceId,
+        connectValue: canonicalizeConnectValue(resource, params.connectValue)
+      });
+    }
+    if (resource.mapping.plugs && !resource.mapping.plugs[params.plugName]) {
+      throw new Error(
+        `Resource "${resource.name}" does not declare plug "${params.plugName}"`
+      );
+    }
+    return adapter.lookupMapping(params);
+  }
+  async function upsertMapping(mapping) {
+    const resource = await validateMappingPayload(mapping);
+    const result = await adapter.upsertMapping({
+      resourceId: mapping.resourceId,
+      connectValue: canonicalizeConnectValue(resource, mapping.connectValue),
+      refs: mapping.refs,
+      metadata: mapping.metadata ?? null
+    });
+    const saved = await adapter.getMapping(result.id);
+    if (!saved) {
+      throw new Error("Mapping was saved but could not be reloaded");
+    }
+    return saved;
+  }
+  async function updateMapping(id, mapping) {
+    const existing = await adapter.getMapping(id);
+    if (!existing) {
+      throw new Error(`Mapping "${id}" not found`);
+    }
+    const resource = await validateMappingPayload(mapping);
+    await adapter.upsertMapping({
+      id,
+      resourceId: mapping.resourceId,
+      connectValue: canonicalizeConnectValue(resource, mapping.connectValue),
+      refs: mapping.refs,
+      metadata: mapping.metadata ?? null
+    });
+    const saved = await adapter.getMapping(id);
+    if (!saved) {
+      throw new Error(`Mapping "${id}" disappeared after update`);
+    }
+    return saved;
+  }
+  async function deleteMapping(id) {
+    const existing = await adapter.getMapping(id);
+    if (!existing) {
+      throw new Error(`Mapping "${id}" not found`);
+    }
+    await adapter.deleteMapping(id);
+  }
   function wire(plugName) {
     const plugReg = plugs.find((p) => p.name === plugName);
     if (!plugReg) {
@@ -1041,29 +1833,7 @@ function khotan(config) {
     }
     const wireConfig = plugReg.wires[0];
     function createBoundPlug(vars, _setVars) {
-      const plug = plugReg.plug;
-      const opts = (extra) => ({
-        ...extra,
-        vars,
-        ..._setVars && { _setVars }
-      });
-      return {
-        get(path, extra) {
-          return plug.get(path, opts(extra));
-        },
-        post(path, extra) {
-          return plug.post(path, opts(extra));
-        },
-        put(path, extra) {
-          return plug.put(path, opts(extra));
-        },
-        patch(path, extra) {
-          return plug.patch(path, opts(extra));
-        },
-        delete(path, extra) {
-          return plug.delete(path, opts(extra));
-        }
-      };
+      return bindPlugWithVars(plugReg.plug, vars, _setVars);
     }
     async function getWireVars(wireId) {
       const raw = await adapter.getWireMetadata(wireId);
@@ -1253,31 +2023,21 @@ function khotan(config) {
       const setFlowVars = async (updates) => {
         await setVars(plugName, { ...vars, ...updates });
       };
-      const opts = (extra) => ({
-        ...extra,
+      const boundPlug = bindPlugWithVars(
+        plugReg.plug,
         vars,
-        ...secret ? { _setVars: setFlowVars } : {}
-      });
-      const boundPlug = {
-        get(path, extra) {
-          return plugReg.plug.get(path, opts(extra));
-        },
-        post(path, extra) {
-          return plugReg.plug.post(path, opts(extra));
-        },
-        put(path, extra) {
-          return plugReg.plug.put(path, opts(extra));
-        },
-        patch(path, extra) {
-          return plugReg.plug.patch(path, opts(extra));
-        },
-        delete(path, extra) {
-          return plugReg.plug.delete(path, opts(extra));
-        }
+        secret ? setFlowVars : void 0
+      );
+      const plugVarsByName = {
+        [plugName]: vars
       };
+      if (flowReg.to && plugNames.has(flowReg.to)) {
+        plugVarsByName[flowReg.to] = secret ? await getVars(flowReg.to).catch(() => ({})) : {};
+      }
       const flowContext = {
         id: flowId,
         name: flowReg.name,
+        plugName,
         type: flowReg.type,
         resource: flowReg.resource ?? null,
         to: flowReg.to ?? null
@@ -1290,7 +2050,9 @@ function khotan(config) {
             runType,
             body: requestBody["body"],
             vars,
-            khotanRunId: runId
+            plugVarsByName,
+            khotanRunId: runId,
+            khotanInstanceId: instanceId
           }
         ]);
         const workflowRunId = getWorkflowRunId(result2);
@@ -1315,7 +2077,8 @@ function khotan(config) {
         runType,
         body: requestBody["body"],
         vars,
-        setVars: setFlowVars
+        setVars: setFlowVars,
+        cache: createCacheInstance
       });
       const runResult = toFlowRunResult(result);
       const { counters, status } = await completeRunOk(runResult);
@@ -1336,6 +2099,112 @@ function khotan(config) {
       );
     }
   }
+  async function wasFlowTriggeredInMinuteWindow(flowId, slotStart, slotEnd) {
+    const runs = await adapter.listRuns(flowId);
+    return runs.some((run) => {
+      const startedAt = coerceDate(run["startedAt"]);
+      if (!startedAt) return false;
+      const startedAtMs = startedAt.getTime();
+      return startedAtMs >= slotStart.getTime() && startedAtMs < slotEnd.getTime();
+    });
+  }
+  async function dispatchScheduledFlows(options = {}) {
+    await init();
+    const now = options.now ?? /* @__PURE__ */ new Date();
+    const slotStart = startOfUtcMinute(now);
+    const slotEnd = new Date(slotStart.getTime() + 6e4);
+    const runType = options.runType ?? "full";
+    const registeredFlows = (await adapter.listFlows()).filter(
+      (flow2) => isRegisteredFlowRecord(flow2)
+    );
+    const scheduledFlows = registeredFlows.filter(
+      (flow2) => typeof flow2["schedule"] === "string" && flow2["schedule"].trim()
+    );
+    const triggered = [];
+    const skipped = [];
+    for (const flow2 of scheduledFlows) {
+      const flowId = typeof flow2["id"] === "string" ? flow2["id"] : null;
+      const flowName = typeof flow2["name"] === "string" ? flow2["name"] : null;
+      const plugName = typeof flow2["plugName"] === "string" ? flow2["plugName"] : null;
+      const schedule = typeof flow2["schedule"] === "string" ? flow2["schedule"].trim() : "";
+      if (!flowId || !flowName || !plugName || !schedule) continue;
+      if (flow2["enabled"] === false) {
+        skipped.push({
+          flowId,
+          flowName,
+          plugName,
+          schedule,
+          reason: "disabled"
+        });
+        continue;
+      }
+      let isDue = false;
+      try {
+        isDue = matchesCronSchedule(schedule, now);
+      } catch (error) {
+        skipped.push({
+          flowId,
+          flowName,
+          plugName,
+          schedule,
+          reason: "invalid_schedule",
+          detail: getErrorMessage(error)
+        });
+        continue;
+      }
+      if (!isDue) {
+        skipped.push({
+          flowId,
+          flowName,
+          plugName,
+          schedule,
+          reason: "not_due"
+        });
+        continue;
+      }
+      if (await wasFlowTriggeredInMinuteWindow(flowId, slotStart, slotEnd)) {
+        skipped.push({
+          flowId,
+          flowName,
+          plugName,
+          schedule,
+          reason: "already_triggered"
+        });
+        continue;
+      }
+      const response = await triggerFlowRun(flowId, { runType });
+      const payload = await response.json().catch(() => ({}));
+      if (!response.ok) {
+        skipped.push({
+          flowId,
+          flowName,
+          plugName,
+          schedule,
+          reason: "trigger_failed",
+          status: response.status,
+          detail: typeof payload["error"] === "string" ? payload["error"] : response.statusText
+        });
+        continue;
+      }
+      triggered.push({
+        flowId,
+        flowName,
+        plugName,
+        schedule,
+        runId: payload["id"] ?? null,
+        workflowRunId: payload["workflowRunId"] ?? null,
+        status: typeof payload["status"] === "string" ? payload["status"] : "running"
+      });
+    }
+    return {
+      ok: true,
+      tickAt: slotStart.toISOString(),
+      runType,
+      evaluated: scheduledFlows.length,
+      triggered,
+      skipped
+    };
+  }
   async function resolveFlowId(flowNameOrId, options = {}) {
     await init();
     const byId = await adapter.getFlow(flowNameOrId);
@@ -1407,13 +2276,32 @@ function khotan(config) {
     const plugsIdx = segments.indexOf("plugs");
     const flowsIdx = segments.indexOf("flows");
     const resourcesIdx = segments.indexOf("resources");
+    const cachesIdx = segments.indexOf("caches");
     const mappingsIdx = segments.indexOf("mappings");
     const runsIdx = segments.indexOf("runs");
     const wiresIdx = segments.indexOf("wires");
     const webhookHandlersIdx = segments.indexOf("webhook-handlers");
     const webhookEventsIdx = segments.indexOf("webhook-events");
     const variablesIdx = segments.indexOf("variables");
+    const cronIdx = segments.indexOf("cron");
+    const webhookIdx = segments.indexOf("webhook");
     const debugIdx = segments.indexOf("debug");
+    const isInboundWebhook = webhookIdx !== -1 && webhookIdx === segments.length - 2;
+    const isCronRoute = cronIdx !== -1 && cronIdx === segments.length - 1;
+    const isDebugRoute = debugIdx !== -1;
+    if (authorize && !isInboundWebhook && !isCronRoute && !isDebugRoute) {
+      let allowed = await isCliRequestAuthorized(request, secret);
+      if (!allowed) {
+        try {
+          allowed = await authorize(request);
+        } catch {
+          allowed = false;
+        }
+      }
+      if (!allowed) {
+        return Response.json({ error: "Unauthorized" }, { status: 401 });
+      }
+    }
     const limit = Math.min(
       Math.max(
         Number.parseInt(url.searchParams.get("limit") ?? "20", 10) || 20,
@@ -1425,17 +2313,43 @@ function khotan(config) {
       Number.parseInt(url.searchParams.get("offset") ?? "0", 10) || 0,
       0
     );
+    const search = url.searchParams.get("search")?.trim() || void 0;
+    const wantsMappingPage = url.searchParams.has("limit") || url.searchParams.has("offset") || url.searchParams.has("search");
     if (request.method === "GET") {
+      if (cachesIdx !== -1 && cachesIdx === segments.length - 3) {
+        const cacheName = decodeURIComponent(segments[cachesIdx + 1]);
+        const key = decodeURIComponent(segments[cachesIdx + 2]);
+        try {
+          const entry = await readCacheEntry(cacheName, key);
+          if (!entry) {
+            return Response.json({ error: "Cache entry not found" }, { status: 404 });
+          }
+          return Response.json({
+            cache: cacheName,
+            key: entry.key,
+            value: entry.value,
+            expiresAt: entry.expiresAt
+          });
+        } catch (error) {
+          const message = error instanceof Error ? error.message : "Invalid cache request";
+          return Response.json({ error: message }, { status: 400 });
+        }
+      }
+      if (cronIdx !== -1 && cronIdx === segments.length - 1) {
+        if (!isCronRequestAuthorized(request)) {
+          return Response.json({ error: "Unauthorized" }, { status: 401 });
+        }
+        const result = await dispatchScheduledFlows();
+        return Response.json(result);
+      }
       if (debugIdx !== -1 && debugIdx === segments.length - 1) {
-        const debugActive = process?.env?.["KHOTAN_DEBUG"];
-        if (!debugActive) {
+        if (!isDebugEnabled()) {
           return Response.json({ error: "Not found" }, { status: 404 });
         }
         return Response.json({ enabled: true });
       }
       if (debugIdx !== -1 && debugIdx === segments.length - 2) {
-        const debugActive = process?.env?.["KHOTAN_DEBUG"];
-        if (!debugActive) {
+        if (!isDebugEnabled()) {
           return Response.json({ error: "Not found" }, { status: 404 });
         }
         const plugName = segments[debugIdx + 1];
@@ -1657,12 +2571,27 @@ function khotan(config) {
         const filtered = data.filter(
           (r) => typeof r["name"] === "string" && resourceNames.has(r["name"])
         );
-        return Response.json(filtered);
+        return Response.json(filtered.map(decorateResourceRecord));
       }
       if (resourcesIdx !== -1 && resourcesIdx === segments.length - 3 && segments[resourcesIdx + 2] === "mappings") {
         const resourceId = segments[resourcesIdx + 1];
-        const data = await adapter.listMappings(resourceId);
-        return Response.json(data);
+        const resource = await getRegisteredResourceById(resourceId);
+        if (!resource) {
+          return Response.json(
+            { error: "Resource not found" },
+            { status: 404 }
+          );
+        }
+        const page = await listMappings({
+          resourceId,
+          limit,
+          offset,
+          ...search ? { search } : {}
+        });
+        if (!wantsMappingPage) {
+          return Response.json(page.items);
+        }
+        return Response.json(page);
       }
       if (resourcesIdx !== -1 && resourcesIdx === segments.length - 2) {
         const resourceId = segments[resourcesIdx + 1];
@@ -1674,7 +2603,7 @@ function khotan(config) {
           );
         }
         const flows = await adapter.getResourceFlows(resourceId);
-        return Response.json({ ...resource, flows });
+        return Response.json({ ...decorateResourceRecord(resource), flows });
       }
       if (mappingsIdx !== -1 && mappingsIdx === segments.length - 2) {
         const mappingId = segments[mappingsIdx + 1];
@@ -1686,7 +2615,42 @@ function khotan(config) {
       }
     }
     if (request.method === "POST") {
-      const webhookIdx = segments.indexOf("webhook");
+      if (cachesIdx !== -1 && cachesIdx === segments.length - 3) {
+        const cacheName = decodeURIComponent(segments[cachesIdx + 1]);
+        const key = decodeURIComponent(segments[cachesIdx + 2]);
+        const body = await request.json().catch(() => ({}));
+        if (!("value" in body)) {
+          return Response.json({ error: "Cache writes require a value" }, { status: 400 });
+        }
+        try {
+          const cacheHandle = createCacheInstance(cacheName);
+          await cacheHandle.set(key, body.value);
+          const entry = await readCacheEntry(cacheName, key);
+          return Response.json({
+            cache: cacheName,
+            key,
+            value: body.value,
+            expiresAt: entry?.expiresAt ?? null
+          });
+        } catch (error) {
+          const message = error instanceof Error ? error.message : "Invalid cache payload";
+          return Response.json({ error: message }, { status: 400 });
+        }
+      }
+      if (cronIdx !== -1 && cronIdx === segments.length - 1) {
+        if (!isCronRequestAuthorized(request)) {
+          return Response.json({ error: "Unauthorized" }, { status: 401 });
+        }
+        let body = {};
+        try {
+          body = await request.json();
+        } catch {
+          body = {};
+        }
+        const runType = typeof body["runType"] === "string" ? body["runType"] : "full";
+        const result = await dispatchScheduledFlows({ runType });
+        return Response.json(result);
+      }
       if (webhookIdx !== -1 && webhookIdx === segments.length - 2) {
         const plugName = segments[webhookIdx + 1];
         const plugReg = plugs.find((p) => p.name === plugName);
@@ -1800,7 +2764,13 @@ function khotan(config) {
               }
               try {
                 const result = await startWorkflow(c.workflow, [
-                  { event, eventType, headers, khotanRunId }
+                  {
+                    event,
+                    eventType,
+                    headers,
+                    khotanRunId,
+                    khotanInstanceId: instanceId
+                  }
                 ]);
                 const workflowRunId = result && typeof result === "object" ? "runId" in result ? String(result.runId) : "id" in result ? String(result.id) : null : null;
                 if (workflowRunId) {
@@ -1863,7 +2833,14 @@ function khotan(config) {
               }
               try {
                 const result = await startWorkflow(p.workflow, [
-                  { event, eventType, headers, destVars, khotanRunId }
+                  {
+                    event,
+                    eventType,
+                    headers,
+                    destVars,
+                    khotanRunId,
+                    khotanInstanceId: instanceId
+                  }
                 ]);
                 const workflowRunId = result && typeof result === "object" ? "runId" in result ? String(result.runId) : "id" in result ? String(result.id) : null : null;
                 if (workflowRunId) {
@@ -1890,8 +2867,7 @@ function khotan(config) {
         return Response.json({ received: true }, { status: 202 });
       }
       if (debugIdx !== -1 && debugIdx === segments.length - 2) {
-        const debugActive = process?.env?.["KHOTAN_DEBUG"];
-        if (!debugActive) {
+        if (!isDebugEnabled()) {
           return Response.json({ error: "Not found" }, { status: 404 });
         }
         const plugName = segments[debugIdx + 1];
@@ -2091,7 +3067,38 @@ function khotan(config) {
       }
       if (mappingsIdx !== -1 && mappingsIdx === segments.length - 2 && segments[mappingsIdx + 1] === "lookup") {
         const body = await request.json();
-        const mapping = await adapter.lookupMapping(body);
+        if (!body || typeof body !== "object" || typeof body["resourceId"] !== "string") {
+          return Response.json(
+            {
+              error: "Lookup requires resourceId plus either connectValue or plugName with ref"
+            },
+            { status: 400 }
+          );
+        }
+        const hasConnectValue = "connectValue" in body;
+        const hasPlugRef = "plugName" in body && typeof body.plugName === "string" && "ref" in body && typeof body.ref === "string";
+        if (!hasConnectValue && !hasPlugRef) {
+          return Response.json(
+            {
+              error: "Lookup requires either connectValue or plugName with ref"
+            },
+            { status: 400 }
+          );
+        }
+        let mapping;
+        try {
+          mapping = hasConnectValue ? await lookupMapping({
+            resourceId: body.resourceId,
+            connectValue: body.connectValue
+          }) : await lookupMapping({
+            resourceId: body.resourceId,
+            plugName: body.plugName,
+            ref: body.ref
+          });
+        } catch (error) {
+          const message = error instanceof Error ? error.message : "Invalid lookup request";
+          return Response.json({ error: message }, { status: 400 });
+        }
         if (!mapping) {
           return Response.json({ error: "Mapping not found" }, { status: 404 });
         }
@@ -2099,11 +3106,17 @@ function khotan(config) {
       }
       if (mappingsIdx !== -1 && mappingsIdx === segments.length - 1) {
         const body = await request.json();
-        const result = await adapter.upsertMapping(body);
-        return Response.json(
-          { id: result.id },
-          { status: result.created ? 201 : 200 }
-        );
+        try {
+          const existing = await lookupMapping({
+            resourceId: body.resourceId,
+            connectValue: body.connectValue
+          });
+          const saved = await upsertMapping(body);
+          return Response.json(saved, { status: existing ? 200 : 201 });
+        } catch (error) {
+          const message = error instanceof Error ? error.message : "Invalid mapping payload";
+          return Response.json({ error: message }, { status: 400 });
+        }
       }
     }
     if (request.method === "PATCH") {
@@ -2141,11 +3154,30 @@ function khotan(config) {
       if (mappingsIdx !== -1 && mappingsIdx === segments.length - 2) {
         const mappingId = segments[mappingsIdx + 1];
         const body = await request.json();
-        const result = await adapter.upsertMapping({ ...body, id: mappingId });
-        return Response.json(result);
+        try {
+          const saved = await updateMapping(mappingId, body);
+          return Response.json(saved);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : "Invalid mapping payload";
+          return Response.json(
+            { error: message },
+            { status: message.includes("not found") ? 404 : 400 }
+          );
+        }
       }
     }
     if (request.method === "DELETE") {
+      if (cachesIdx !== -1 && cachesIdx === segments.length - 3) {
+        const cacheName = decodeURIComponent(segments[cachesIdx + 1]);
+        const key = decodeURIComponent(segments[cachesIdx + 2]);
+        try {
+          await createCacheInstance(cacheName).delete(key);
+          return new Response(null, { status: 204 });
+        } catch (error) {
+          const message = error instanceof Error ? error.message : "Invalid cache request";
+          return Response.json({ error: message }, { status: 400 });
+        }
+      }
       if (variablesIdx !== -1 && variablesIdx === segments.length - 2) {
         const plugName = segments[variablesIdx + 1];
         if (!plugNames.has(plugName)) {
@@ -2177,6 +3209,10 @@ function khotan(config) {
       }
       if (mappingsIdx !== -1 && mappingsIdx === segments.length - 2) {
         const mappingId = segments[mappingsIdx + 1];
+        const existing = await adapter.getMapping(mappingId);
+        if (!existing) {
+          return Response.json({ error: "Mapping not found" }, { status: 404 });
+        }
         await adapter.deleteMapping(mappingId);
         return new Response(null, { status: 204 });
       }
@@ -2280,11 +3316,25 @@ function khotan(config) {
     }
     return plugReg.plug;
   }
+  khotanRuntimeRegistry.set(instanceId, {
+    cache: createCacheInstance,
+    listMappings,
+    lookupMapping,
+    upsertMapping,
+    updateMapping,
+    deleteMapping
+  });
   return {
     handler,
     init,
     flow,
     wire,
+    cache: createCacheInstance,
+    listMappings,
+    lookupMapping,
+    upsertMapping,
+    updateMapping,
+    deleteMapping,
     getVars,
     setVars,
     clearVars,
@@ -2306,6 +3356,6 @@ function toNextJsHandler(factoryHandler) {
   };
 }
 
-export { __setWorkflowGetRunForTests, __setWorkflowGetWritableForTests, __setWorkflowStartForTests, drizzleAdapter, khotan, sendUpdate, toNextJsHandler };
+export { __setWorkflowGetRunForTests, __setWorkflowGetWritableForTests, __setWorkflowStartForTests, bindWorkflowPlug, deriveCliToken, drizzleAdapter, khotan, khotanCache, khotanMappings, sendUpdate, toNextJsHandler };
 //# sourceMappingURL=factory.js.map
 //# sourceMappingURL=factory.js.map