@sequenceholdings/managed-functions 0.1.1

package/README.md

@@ -0,0 +1,115 @@
+# `@sequenceholdings/managed-functions`
+
+`@sequenceholdings/managed-functions` is the TypeScript SDK for cache-enabled
+Managed Functions. Function code imports its context and cache types; Atlas and
+the local harness use its runtime helpers to construct the optional third
+handler argument. Ordinary two-argument handlers do not need this package.
+
+Managed Functions is a workflow-agnostic platform primitive. The runtime owns
+generic invocation, isolation, secrets, egress, caching, and observability;
+deployed functions own business logic. Primitive code must not identify a
+function consumer or branch on a function ID. See
+[Platform primitive boundaries](../../../docs/platform/platform-primitives.md).
+
+Opt-in caching inside a Managed Function. When the manifest declares a `cache` block, the platform passes a process-reused `context` as the HTTP handler's third argument. Existing two-argument handlers keep working.
+
+```yaml
+cache:
+  enabled: true
+  tier: custom-pico
+  replicas: 0
+  default_ttl_seconds: 30
+```
+
+Each function/environment gets a dedicated private Valkey instance. The baseline is one pico node with no replicas or persistence. Instances incur charges while idle. Only Sequence organization members can change an enabled cache to a nonbaseline tier or replica count; other authors can retain an already-approved configuration or return to baseline. Supported tiers: `custom-pico`, `custom-micro`, `custom-mini`; replicas: 0–5.
+
+```ts
+import type { ManagedFunctionContext } from '@sequenceholdings/managed-functions'
+import type { Request, Response } from '@google-cloud/functions-framework'
+
+export async function handler(req: Request, res: Response, context: ManagedFunctionContext) {
+  // Authenticate and authorize EVERY invocation before accessing shared cached data.
+  // Include tenant, permission scope, arguments, and authoritative data version
+  // in keys whenever they affect the result.
+  const result = await context.cache.getOrCompute('public-catalog:v1', { ttlSeconds: 30 }, async () => {
+    const response = await fetch('https://api.example.com/catalog')
+    if (!response.ok) throw new Error('Catalog unavailable')
+    return response.json()
+  })
+  res.json(result)
+}
+```
+
+## Contract
+
+All methods are asynchronous. Values are lossless JSON, at most 1 MiB; keys are nonempty strings, at most 512 UTF-8 bytes. TTL is an integer from 1 to 86,400 seconds. `CacheOptions` is `{ ttlSeconds?: number }`, defaulting to the manifest TTL. Generic reads assert a type; they do not validate your schema.
+
+| Method | Result |
+| --- | --- |
+| `get<T>(key): Promise<T \| undefined>` | Missing/expired → `undefined`; cached `null` is a hit. Does not extend TTL. |
+| `set(key, value, options?): Promise<void>` | Atomic upsert with a new TTL. |
+| `setIfAbsent(key, value, options?): Promise<boolean>` | Atomic insert+TTL; `false` leaves the existing value and TTL unchanged. |
+| `delete(key): Promise<boolean>` | `true` if removed, otherwise `false`. |
+| `getOrCompute<T>(key, options, loader): Promise<T>` | Hit or computed value; stores successful JSON results. |
+
+Explicit CRUD throws `CacheError` with `DISABLED`, `UNAVAILABLE`, `UNKNOWN_OUTCOME`, `INVALID_ARGUMENT`, or `INVALID_VALUE`. A lost mutation acknowledgement has an unknown outcome and is never replayed automatically. `getOrCompute` bypasses disabled/unavailable caching and failed cache writes; loader errors and invalid inputs/results propagate. A cache failure never retries the loader. Coalescing is bounded and process-local: duplicate computation is possible. This is not an idempotency or exactly-once primitive.
+
+Authors own authorization, read/write choices, and invalidation. A concurrent loader can repopulate a deleted key with old data; use authoritative versioned keys or bypass the cache when freshness is required. Every activation gets a fresh key namespace; old entries expire naturally.
+
+## Local development
+
+Run `seq-studio functions dev --dir . --port 8080` after installing dependencies. Enabled caching without a Valkey connection uses bounded process-local TTL/LRU storage (16 MiB encoded payloads, 10,000 entries); it is reset on restart and not shared across processes. The harness compiles TypeScript with the project's installed compiler. A deployed enabled cache without connection configuration fails startup; it never falls back silently.
+
+For an explicit private Valkey development connection, set `SEQUENCE_FUNCTION_CACHE_CONFIG` to JSON containing `cache` plus `connection: { host, port, serverIdentity, caCertificates, keyPrefix }`. Use ADC with permission on that test instance and network connectivity to its PSC endpoint. `serverIdentity` must match the server certificate. Do not put passwords or tokens in configuration. The deployed runtime always obtains short-lived tokens from its attached service account.
+
+## Runtime bounds
+
+One multiplexed TLS connection per process, at most 128 pending operations, 150 ms command and 1.5 s connection deadlines. Three failures open a five-second circuit breaker. New connections acquire a valid IAM token; live authenticated connections can outlast token expiry. TLS verifies the trusted certificate chain and expected DNS/IP identity. No offline queue, mutation replay, plaintext, or verification bypass.
+
+Cloud Run emits aggregate `managed_function.cache` logs every 30 seconds of active use with operation/error counts and total/maximum operation latency. Keys, values, and credentials are never logged. Cache memory, evictions and hit rate appear beside function metrics; actual compute/cache spend, credits and billing freshness remain in Billing.
+
+Functions without a `cache` manifest block retain their existing two-argument handler. An explicit `cache: { enabled: false }` supplies a disabled `context.cache`, allowing `getOrCompute` to run its loader without caching.
+
+## Runtime tracing
+
+Newly deployed function entrypoints install request-scoped tracing automatically,
+including two-argument handlers without caching. Ordinary global `fetch` calls to
+the current platform propagate the invocation context; ORM and storage delegation
+also retain the original initiator when a function explicitly acts as its service
+account. Normal resource authorization still applies.
+
+Global `fetch` calls to declared external hosts record hostname, method, status
+and duration. Paths, queries, bodies, credentials and arbitrary errors are not
+stored. Other networking transports and redirect hops are outside this capture.
+External requests receive no platform attribution headers from this runtime.
+
+Completed external and nonprimitive Atlas API spans are exported in small batches while the handler keeps
+working (50 ms batching delay, 500 ms per batch including one retry). The final
+batch starts fire-and-forget when the HTTP response ends (or the handler returns
+or throws); the response and errors never wait for export. Calls limited to
+instrumented primitive execution routes send no export. The runtime aborts
+unfinished exports at their deadline or on client disconnect. Callback-style
+handlers remain traced until their response ends.
+
+Delivery remains best effort: a slow or unavailable collector, or CPU throttled
+after the response, can leave spans unacknowledged. Each traced invocation that
+captured egress logs one `traces.function_egress.summary` JSON line once its
+export settles. Every captured span is `acknowledged`, `rejected`, `abandoned`,
+or `unacknowledged`; `dropped` spans were never captured. Only known loss
+(`rejected`, `abandoned`, or `dropped`) logs at `warn`; unacknowledged spans log
+at `info` because the collector may have stored them after the response. A
+refusal on the retry after an uncertain first attempt stays unacknowledged. The runtime
+limits each invocation to 100 spans and 10 batches (20 POST attempts including
+retries), preserving span IDs across a retry. Failures preserve the handler's
+result. The platform allows its own collector hostname through managed egress,
+without making collector availability a readiness dependency. Existing deployed
+revisions need redeployment to pick up the entrypoint. Standalone `functions dev`
+does not mint trusted invocation context.
+
+Same-deployment Atlas API calls outside instrumented primitive execution routes
+are reported as Atlas API dependencies with registered route templates. Query
+strings, dynamic path values and request/response bodies are not persisted.
+Successful reads of a Lattice process or run link to the owning process; direct
+HTTP run starts already use server-recorded spans and preserve the request chain.
+Transport classification is shared with the platform host; function authors
+do not need to import or configure instrumentation.

package/dist/cache.d.ts

@@ -0,0 +1,37 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type CacheOptions = {
+    ttlSeconds?: number;
+};
+export type CacheErrorCode = 'DISABLED' | 'UNAVAILABLE' | 'UNKNOWN_OUTCOME' | 'INVALID_ARGUMENT' | 'INVALID_VALUE';
+export declare class CacheError extends Error {
+    readonly code: CacheErrorCode;
+    constructor(code: CacheErrorCode);
+}
+export interface CacheStore {
+    get(key: string): Promise<string | null>;
+    set(args: {
+        key: string;
+        value: string;
+        ttlSeconds: number;
+        onlyIfAbsent: boolean;
+    }): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    close?(): void;
+}
+export interface CacheManager {
+    get<T extends JsonValue = JsonValue>(key: string): Promise<T | undefined>;
+    set(key: string, value: JsonValue, options?: CacheOptions): Promise<void>;
+    setIfAbsent(key: string, value: JsonValue, options?: CacheOptions): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    getOrCompute<T extends JsonValue>(key: string, options: CacheOptions, loader: () => T | Promise<T>): Promise<T>;
+}
+export declare const CACHE_MAX_VALUE_BYTES: number;
+export declare const CACHE_MAX_KEY_BYTES: 512;
+export declare function serializeCacheValue(value: unknown): string;
+export declare function createCacheManager({ store, defaultTtlSeconds, coalesceWaitMs, }: {
+    store: CacheStore | null;
+    defaultTtlSeconds: number;
+    coalesceWaitMs?: number;
+}): CacheManager;

package/dist/cache.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CACHE_MAX_KEY_BYTES = exports.CACHE_MAX_VALUE_BYTES = exports.CacheError = void 0;
+exports.serializeCacheValue = serializeCacheValue;
+exports.createCacheManager = createCacheManager;
+const config_1 = require("./config");
+class CacheError extends Error {
+    code;
+    constructor(code) {
+        super(`Managed Function cache: ${code}`);
+        this.code = code;
+        this.name = 'CacheError';
+    }
+}
+exports.CacheError = CacheError;
+exports.CACHE_MAX_VALUE_BYTES = config_1.MANAGED_FUNCTION_LIMITS.cache.max_value_bytes.max;
+exports.CACHE_MAX_KEY_BYTES = config_1.MANAGED_FUNCTION_LIMITS.cache.max_key_bytes.max;
+function validateArrayKeys(value, keys) {
+    if (keys.length !== value.length + 1 ||
+        keys.some((key) => key !== 'length' &&
+            (typeof key !== 'string' ||
+                !/^(0|[1-9][0-9]*)$/.test(key) ||
+                Number(key) >= value.length))) {
+        throw new CacheError('INVALID_VALUE');
+    }
+}
+function validateJson(value, ancestors = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number' &&
+        Number.isFinite(value) &&
+        !Object.is(value, -0))
+        return;
+    if (typeof value !== 'object' || ancestors.has(value))
+        throw new CacheError('INVALID_VALUE');
+    if (!Array.isArray(value) &&
+        ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+        throw new CacheError('INVALID_VALUE');
+    ancestors.add(value);
+    const keys = Reflect.ownKeys(value);
+    if (keys.some((key) => typeof key === 'symbol'))
+        throw new CacheError('INVALID_VALUE');
+    if (Array.isArray(value))
+        validateArrayKeys(value, keys);
+    for (const key of keys) {
+        if (Array.isArray(value) && key === 'length')
+            continue;
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor?.enumerable || !('value' in descriptor))
+            throw new CacheError('INVALID_VALUE');
+        validateJson(descriptor.value, ancestors);
+    }
+    ancestors.delete(value);
+}
+function serializeCacheValue(value) {
+    try {
+        validateJson(value);
+        const encoded = JSON.stringify(value);
+        if (Buffer.byteLength(encoded) > exports.CACHE_MAX_VALUE_BYTES)
+            throw new CacheError('INVALID_VALUE');
+        return encoded;
+    }
+    catch {
+        throw new CacheError('INVALID_VALUE');
+    }
+}
+function validateKey(key) {
+    if (typeof key !== 'string' ||
+        key.length === 0 ||
+        Buffer.byteLength(key) > exports.CACHE_MAX_KEY_BYTES)
+        throw new CacheError('INVALID_ARGUMENT');
+}
+function ttl(options, fallback) {
+    if (!options || typeof options !== 'object' || Array.isArray(options))
+        throw new CacheError('INVALID_ARGUMENT');
+    const seconds = options.ttlSeconds ?? fallback;
+    if (!Number.isInteger(seconds) ||
+        seconds < 1 ||
+        seconds > config_1.CACHE_MAX_TTL_SECONDS)
+        throw new CacheError('INVALID_ARGUMENT');
+    return seconds;
+}
+function bypassable(error) {
+    return (error instanceof CacheError &&
+        ['DISABLED', 'UNAVAILABLE', 'UNKNOWN_OUTCOME'].includes(error.code));
+}
+function decode(encoded) {
+    try {
+        if (Buffer.byteLength(encoded) > exports.CACHE_MAX_VALUE_BYTES)
+            throw new CacheError('INVALID_VALUE');
+        const value = JSON.parse(encoded);
+        validateJson(value);
+        return value;
+    }
+    catch {
+        throw new CacheError('INVALID_VALUE');
+    }
+}
+function createCacheManager({ store, defaultTtlSeconds, coalesceWaitMs = 1000, }) {
+    ttl({}, defaultTtlSeconds);
+    const pending = new Map();
+    function backend() {
+        if (!store)
+            throw new CacheError('DISABLED');
+        return store;
+    }
+    const cache = {
+        async get(key) {
+            validateKey(key);
+            const encoded = await backend().get(key);
+            return encoded === null ? undefined : decode(encoded);
+        },
+        async set(key, value, options = {}) {
+            validateKey(key);
+            const seconds = ttl(options, defaultTtlSeconds);
+            const encoded = serializeCacheValue(value);
+            await backend().set({
+                key,
+                value: encoded,
+                ttlSeconds: seconds,
+                onlyIfAbsent: false,
+            });
+        },
+        async setIfAbsent(key, value, options = {}) {
+            validateKey(key);
+            const seconds = ttl(options, defaultTtlSeconds);
+            const encoded = serializeCacheValue(value);
+            return backend().set({
+                key,
+                value: encoded,
+                ttlSeconds: seconds,
+                onlyIfAbsent: true,
+            });
+        },
+        async delete(key) {
+            validateKey(key);
+            return backend().delete(key);
+        },
+        async getOrCompute(key, options, loader) {
+            validateKey(key);
+            ttl(options, defaultTtlSeconds);
+            if (typeof loader !== 'function')
+                throw new CacheError('INVALID_ARGUMENT');
+            try {
+                const hit = await cache.get(key);
+                if (hit !== undefined)
+                    return hit;
+            }
+            catch (error) {
+                if (!bypassable(error))
+                    throw error;
+            }
+            const inFlight = pending.get(key);
+            if (inFlight) {
+                let timer;
+                try {
+                    const result = await Promise.race([
+                        inFlight,
+                        new Promise((resolve) => {
+                            timer = setTimeout(() => resolve(undefined), coalesceWaitMs);
+                        }),
+                    ]);
+                    if (result !== undefined)
+                        return decode(result);
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            }
+            const computation = (async () => {
+                const result = await loader();
+                const encoded = serializeCacheValue(result);
+                try {
+                    await cache.set(key, result, options);
+                }
+                catch (error) {
+                    if (!bypassable(error))
+                        throw error;
+                }
+                return encoded;
+            })();
+            if (pending.size < 1000)
+                pending.set(key, computation);
+            try {
+                return decode(await computation);
+            }
+            finally {
+                if (pending.get(key) === computation)
+                    pending.delete(key);
+            }
+        },
+    };
+    return cache;
+}

package/dist/config.d.ts

@@ -0,0 +1,17 @@
+export { shouldReportAtlasHttp } from './http-tracing';
+import { z } from 'zod';
+export { MANAGED_FUNCTION_LIMITS, MF_LIMITS_CAPS, MF_LIMITS_DEFAULTS, managedFunctionWorkloadLimitsSchema } from './limits';
+export type { ManagedFunctionLimitCatalog } from './limits';
+export declare const CACHE_MAX_TTL_SECONDS: 86400;
+export declare const cacheManifestSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    tier: z.ZodDefault<z.ZodEnum<{
+        "custom-pico": "custom-pico";
+        "custom-micro": "custom-micro";
+        "custom-mini": "custom-mini";
+    }>>;
+    replicas: z.ZodDefault<z.ZodNumber>;
+    default_ttl_seconds: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type CacheConfiguration = z.infer<typeof cacheManifestSchema>;
+export declare function readCacheConfiguration(manifest: unknown): CacheConfiguration;

package/dist/config.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cacheManifestSchema = exports.CACHE_MAX_TTL_SECONDS = exports.managedFunctionWorkloadLimitsSchema = exports.MF_LIMITS_DEFAULTS = exports.MF_LIMITS_CAPS = exports.MANAGED_FUNCTION_LIMITS = exports.shouldReportAtlasHttp = void 0;
+exports.readCacheConfiguration = readCacheConfiguration;
+var http_tracing_1 = require("./http-tracing");
+Object.defineProperty(exports, "shouldReportAtlasHttp", { enumerable: true, get: function () { return http_tracing_1.shouldReportAtlasHttp; } });
+const zod_1 = require("zod");
+const limits_1 = require("./limits");
+var limits_2 = require("./limits");
+Object.defineProperty(exports, "MANAGED_FUNCTION_LIMITS", { enumerable: true, get: function () { return limits_2.MANAGED_FUNCTION_LIMITS; } });
+Object.defineProperty(exports, "MF_LIMITS_CAPS", { enumerable: true, get: function () { return limits_2.MF_LIMITS_CAPS; } });
+Object.defineProperty(exports, "MF_LIMITS_DEFAULTS", { enumerable: true, get: function () { return limits_2.MF_LIMITS_DEFAULTS; } });
+Object.defineProperty(exports, "managedFunctionWorkloadLimitsSchema", { enumerable: true, get: function () { return limits_2.managedFunctionWorkloadLimitsSchema; } });
+const limits = limits_1.MANAGED_FUNCTION_LIMITS.cache;
+exports.CACHE_MAX_TTL_SECONDS = limits.default_ttl_seconds.max;
+exports.cacheManifestSchema = zod_1.z
+    .object({
+    enabled: zod_1.z.boolean().default(limits.enabled.default),
+    tier: zod_1.z
+        .enum(limits.tier.allowed)
+        .default(limits.tier.default),
+    replicas: zod_1.z.number().int().min(limits.replicas.min).max(limits.replicas.max).default(limits.replicas.default),
+    default_ttl_seconds: zod_1.z
+        .number()
+        .int()
+        .min(limits.default_ttl_seconds.min)
+        .max(exports.CACHE_MAX_TTL_SECONDS)
+        .default(limits.default_ttl_seconds.default),
+})
+    .strict();
+function readCacheConfiguration(manifest) {
+    const cache = typeof manifest === 'object' && manifest !== null
+        ? Reflect.get(manifest, 'cache')
+        : undefined;
+    return exports.cacheManifestSchema.parse(cache ?? {});
+}

package/dist/http-tracing.d.ts

@@ -0,0 +1 @@
+export declare function shouldReportAtlasHttp(pathname: string, method: string): boolean;

package/dist/http-tracing.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldReportAtlasHttp = shouldReportAtlasHttp;
+function shouldReportAtlasHttp(pathname, method) {
+    if (!pathname.startsWith('/api/'))
+        return false;
+    if (/^\/api\/(runtime-traces|traces)(\/|$)/.test(pathname))
+        return false;
+    if (pathname === '/api/artifact-studio/trace-context')
+        return false;
+    if (/^\/api\/managed-functions\/[^/]+\/invoke\/?$/.test(pathname))
+        return false;
+    if (/^\/api\/data\/v2\/[^/]+\/?$/.test(pathname))
+        return false;
+    if (method === 'POST' &&
+        /^\/api\/data-pipelines\/stages\/[^/]+\/run\/?$/.test(pathname))
+        return false;
+    if (pathname.startsWith('/api/storage/'))
+        return false;
+    if (method === 'POST' &&
+        /^\/api\/lattice\/(runs|processes\/[^/]+\/runs)\/?$/.test(pathname))
+        return false;
+    return true;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { installFunctionTracing, runWithFunctionTracing } from './tracing';
+export { createFunctionStorageClient } from './storage';
+import { type CacheManager } from "./cache";
+export { CacheError, createCacheManager } from "./cache";
+export type { CacheManager, CacheOptions, CacheErrorCode, JsonValue, } from "./cache";
+export { cacheManifestSchema, readCacheConfiguration } from "./config";
+export type { CacheConfiguration } from "./config";
+export interface ManagedFunctionContext {
+    cache: CacheManager;
+}
+export declare function createManagedFunctionContext({ env, }?: {
+    env?: NodeJS.ProcessEnv;
+}): ManagedFunctionContext;

package/dist/index.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCacheConfiguration = exports.cacheManifestSchema = exports.createCacheManager = exports.CacheError = exports.createFunctionStorageClient = exports.runWithFunctionTracing = exports.installFunctionTracing = void 0;
+exports.createManagedFunctionContext = createManagedFunctionContext;
+var tracing_1 = require("./tracing");
+Object.defineProperty(exports, "installFunctionTracing", { enumerable: true, get: function () { return tracing_1.installFunctionTracing; } });
+Object.defineProperty(exports, "runWithFunctionTracing", { enumerable: true, get: function () { return tracing_1.runWithFunctionTracing; } });
+const zod_1 = require("zod");
+var storage_1 = require("./storage");
+Object.defineProperty(exports, "createFunctionStorageClient", { enumerable: true, get: function () { return storage_1.createFunctionStorageClient; } });
+const config_1 = require("./config");
+const cache_1 = require("./cache");
+const memory_1 = require("./memory");
+var cache_2 = require("./cache");
+Object.defineProperty(exports, "CacheError", { enumerable: true, get: function () { return cache_2.CacheError; } });
+Object.defineProperty(exports, "createCacheManager", { enumerable: true, get: function () { return cache_2.createCacheManager; } });
+var config_2 = require("./config");
+Object.defineProperty(exports, "cacheManifestSchema", { enumerable: true, get: function () { return config_2.cacheManifestSchema; } });
+Object.defineProperty(exports, "readCacheConfiguration", { enumerable: true, get: function () { return config_2.readCacheConfiguration; } });
+const connectionSchema = zod_1.z
+    .object({
+    host: zod_1.z.string().min(1),
+    port: zod_1.z.number().int().min(1).max(65535),
+    serverIdentity: zod_1.z.string().min(1),
+    caCertificates: zod_1.z.array(zod_1.z.string().min(1)).min(1),
+    keyPrefix: zod_1.z.string().min(1),
+})
+    .strict();
+const runtimeSchema = zod_1.z
+    .object({
+    cache: config_1.cacheManifestSchema,
+    connection: connectionSchema.optional(),
+})
+    .strict();
+function createManagedFunctionContext({ env = process.env, } = {}) {
+    const local = env.SEQUENCE_FUNCTION_LOCAL === "1" &&
+        !env.K_SERVICE &&
+        !env.FUNCTION_TARGET;
+    const { cache, connection } = runtimeSchema.parse(env.SEQUENCE_FUNCTION_CACHE_CONFIG
+        ? JSON.parse(env.SEQUENCE_FUNCTION_CACHE_CONFIG)
+        : { cache: { enabled: false } });
+    if (cache.enabled && !connection && !local)
+        throw new Error("Enabled Managed Function cache is missing its private Valkey connection configuration");
+    const store = !cache.enabled
+        ? null
+        : connection
+            ? lazyValkeyStore(connection, local)
+            : new memory_1.MemoryStore();
+    return {
+        cache: (0, cache_1.createCacheManager)({
+            store,
+            defaultTtlSeconds: cache.default_ttl_seconds,
+        }),
+    };
+}
+function lazyValkeyStore(connection, local) {
+    let pending;
+    const client = () => (pending ??= import("./valkey.js").then(({ ValkeyStore }) => new ValkeyStore(connection, local)));
+    return {
+        get: async (key) => (await client()).get(key),
+        set: async (args) => (await client()).set(args),
+        delete: async (key) => (await client()).delete(key),
+    };
+}

package/dist/limits.d.ts

@@ -0,0 +1,153 @@
+import { z } from 'zod';
+export declare const MANAGED_FUNCTION_LIMITS: {
+    readonly environment: {
+        readonly functions: {
+            readonly max: 100;
+            readonly scope: "Non-archived functions across all organizations; undeployed shells count";
+        };
+    };
+    readonly workload: {
+        readonly memory_mb: {
+            readonly min: 128;
+            readonly max: 2048;
+            readonly default: 256;
+            readonly unit: "MiB per instance";
+        };
+        readonly timeout_seconds: {
+            readonly min: 1;
+            readonly max: 540;
+            readonly default: 60;
+            readonly unit: "seconds";
+        };
+        readonly min_instances: {
+            readonly min: 0;
+            readonly max: 10;
+            readonly default: 1;
+            readonly scope: "Cannot exceed max_instances; warm instances incur idle charges";
+        };
+        readonly max_instances: {
+            readonly min: 2;
+            readonly max: 10;
+            readonly default: 3;
+            readonly scope: "Autoscaling ceiling; must allow at least two instances, and GCP may temporarily exceed it";
+        };
+        readonly invoke_rate_per_minute: {
+            readonly min: 1;
+            readonly max: 600;
+            readonly default: 60;
+            readonly window_seconds: 60;
+            readonly scope: "Per function across all Atlas replicas in the environment; Redis-backed fixed window. Redis unavailability rejects invocations (503); key loss resets the window";
+        };
+        readonly max_request_bytes: {
+            readonly max: number;
+            readonly unit: "bytes";
+            readonly configurable: false;
+        };
+        readonly max_response_bytes: {
+            readonly max: number;
+            readonly unit: "bytes";
+            readonly configurable: false;
+        };
+        readonly cpu: {
+            readonly configurable: true;
+            readonly default: "auto";
+            readonly min: 1;
+            readonly max: 2;
+            readonly min_memory_mb_for_multiple_cpus: 512;
+            readonly scope: "auto uses provider memory-derived allocation; explicit CPU must be a whole vCPU. Multiple CPUs require the minimum memory listed here";
+        };
+        readonly concurrency: {
+            readonly configurable: true;
+            readonly min: 1;
+            readonly max: 80;
+            readonly default: 1;
+            readonly scope: "Simultaneous requests per instance; values above 1 require explicit cpu (not auto). Requests share instance CPU and memory";
+        };
+    };
+    readonly cache: {
+        readonly enabled: {
+            readonly default: false;
+        };
+        readonly tier: {
+            readonly allowed: readonly ["custom-pico", "custom-micro", "custom-mini"];
+            readonly default: "custom-pico";
+        };
+        readonly replicas: {
+            readonly min: 0;
+            readonly max: 5;
+            readonly default: 0;
+        };
+        readonly default_ttl_seconds: {
+            readonly min: 1;
+            readonly max: 86400;
+            readonly default: 30;
+            readonly unit: "seconds";
+        };
+        readonly max_key_bytes: {
+            readonly max: 512;
+            readonly unit: "bytes";
+        };
+        readonly max_value_bytes: {
+            readonly max: number;
+            readonly unit: "bytes";
+        };
+    };
+    readonly bundle: {
+        readonly files: {
+            readonly max: 2000;
+        };
+        readonly file_bytes: {
+            readonly max: number;
+            readonly unit: "bytes";
+        };
+        readonly source_bytes: {
+            readonly max: number;
+            readonly unit: "bytes unpacked";
+        };
+        readonly request_bytes: {
+            readonly max: number;
+            readonly unit: "bytes in deploy request";
+        };
+    };
+};
+export type ManagedFunctionLimitCatalog = Record<string, Record<string, {
+    min?: number;
+    max?: number;
+    default?: number | string | boolean;
+    allowed?: readonly string[];
+    unit?: string;
+    configurable?: boolean;
+    min_memory_mb_for_multiple_cpus?: number;
+    window_seconds?: number;
+    scope?: string;
+}>>;
+export declare const managedFunctionWorkloadLimitsSchema: z.ZodPrefault<z.ZodObject<{
+    memory_mb: z.ZodDefault<z.ZodNumber>;
+    cpu: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodNumber]>>;
+    concurrency: z.ZodDefault<z.ZodNumber>;
+    timeout_seconds: z.ZodDefault<z.ZodNumber>;
+    min_instances: z.ZodDefault<z.ZodNumber>;
+    max_instances: z.ZodDefault<z.ZodNumber>;
+    invoke_rate_per_minute: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>>;
+export declare const MF_LIMITS_CAPS: {
+    readonly cpu: 2;
+    readonly concurrency: 80;
+    readonly memoryMb: 2048;
+    readonly timeoutSeconds: 540;
+    readonly maxInstances: 10;
+    readonly invokeRatePerMinute: 600;
+    readonly maxRequestBytes: number;
+    readonly maxResponseBytes: number;
+};
+export declare const MF_LIMITS_DEFAULTS: {
+    readonly cpu: "auto";
+    readonly concurrency: 1;
+    readonly memoryMb: 256;
+    readonly timeoutSeconds: 60;
+    readonly minInstances: 1;
+    readonly maxInstances: 3;
+    readonly invokeRatePerMinute: 60;
+    readonly maxRequestBytes: number;
+    readonly maxResponseBytes: number;
+};