takos-control 1.0.0

package/package.json

@@ -0,0 +1,169 @@
+{
+  "name": "takos-control",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@aws-sdk/client-dynamodb": "^3.700.0",
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@aws-sdk/client-sqs": "^3.700.0",
+    "@google-cloud/firestore": "^7.11.0",
+    "@google-cloud/pubsub": "^4.9.0",
+    "@google-cloud/storage": "^7.14.0",
+    "@langchain/core": "^1.1.8",
+    "@langchain/langgraph": "^1.0.7",
+    "@langchain/langgraph-checkpoint": "^1.0.0",
+    "@langchain/openai": "^1.2.0",
+    "@libsql/client": "^0.17.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "takos-actions-engine": "workspace:*",
+    "takos-common": "workspace:*",
+    "@cloudflare/workers-types": "^4.20260118.0",
+    "drizzle-orm": "^0.45.1",
+    "hono": "^4.12.4",
+    "jose": "^5.9.0",
+    "pg": "^8.20.0",
+    "redis": "^5.11.0",
+    "yaml": "^2.8.2",
+    "zod": "^3.25.32"
+  },
+  "devDependencies": {
+    "miniflare": "^4.20260124.0",
+    "typescript": "^5.7.0"
+  },
+  "exports": {
+    "./agent": "./src/application/services/agent/index.ts",
+    "./agent/public-runner": "./src/application/services/agent/runner.ts",
+
+    "./bindings/dynamo-kv-store": "./src/adapters/dynamo-kv-store.ts",
+    "./bindings/firestore-kv-store": "./src/adapters/firestore-kv-store.ts",
+    "./bindings/gcs-object-store": "./src/adapters/gcs-object-store.ts",
+    "./bindings/openai-binding": "./src/adapters/openai-binding.ts",
+    "./bindings/pgvector-store": "./src/adapters/pgvector-store.ts",
+    "./bindings/pubsub-queue": "./src/adapters/pubsub-queue.ts",
+    "./bindings/s3-object-store": "./src/adapters/s3-object-store.ts",
+    "./bindings/sqs-queue": "./src/adapters/sqs-queue.ts",
+    "./bindings/redis-durable-object": "./src/worker-emulation/redis-durable-object.ts",
+    "./bindings/sse-notifier": "./src/worker-emulation/sse-notifier.ts",
+
+    "./core": "./src/index.ts",
+    "./core/application/services/cloudflare/api-client": "./src/application/services/cloudflare/api-client.ts",
+    "./core/application/services/wfp/client": "./src/application/services/wfp/client.ts",
+    "./core/web": "./src/web.ts",
+    "./core/dispatch": "./src/dispatch.ts",
+    "./core/worker": "./src/runtime/worker/index.ts",
+    "./core/platform": "./src/platform/index.ts",
+
+    "./git/smart": "./src/application/services/git-smart/index.ts",
+    "./git/smart/client": "./src/application/services/git-smart/client/index.ts",
+    "./git/smart/operations": "./src/application/services/git-smart/operations.ts",
+    "./git/source/apps": "./src/application/services/source/apps.ts",
+    "./git/source/explore": "./src/application/services/source/explore.ts",
+    "./git/source/repos": "./src/application/services/source/repos.ts",
+    "./git/source/search": "./src/application/services/source/search.ts",
+    "./git/source/skills": "./src/application/services/source/skills.ts",
+    "./git/source/skill-search": "./src/application/services/source/skill-search.ts",
+    "./git/source/fork": "./src/application/services/source/fork.ts",
+    "./git/source/git": "./src/application/services/source/git.ts",
+    "./git/source/external-import": "./src/application/services/source/external-import.ts",
+    "./git/source/app-manifest": "./src/application/services/source/app-manifest.ts",
+    "./git/source/space-storage": "./src/application/services/source/space-storage.ts",
+
+    "./platform": "./src/platform/index.ts",
+    "./platform/accessors": "./src/platform/accessors.ts",
+    "./platform/context": "./src/platform/context.ts",
+    "./platform/types": "./src/platform/types.ts",
+    "./platform/adapters/node": "./src/platform/adapters/node.ts",
+    "./platform/adapters/shared": "./src/platform/adapters/shared.ts",
+    "./platform/adapters/workers": "./src/platform/adapters/workers.ts",
+    "./platform/providers/cloudflare/pdf-render": "./src/platform/providers/cloudflare/pdf-render.ts",
+    "./platform/providers/cloudflare/resources": "./src/platform/providers/cloudflare/resources.ts",
+    "./platform/providers/cloudflare/wfp": "./src/platform/providers/cloudflare/wfp.ts",
+    "./platform/providers/node/pdf-render": "./src/platform/providers/node/pdf-render.ts",
+
+    "./runtime/worker": "./src/runtime/worker/index.ts",
+    "./runtime/worker/env": "./src/runtime/worker/env.ts",
+    "./runtime/worker/egress": "./src/runtime/worker/egress.ts",
+    "./runtime/runner": "./src/runtime/runner/index.ts",
+    "./runtime/runner/queue-handler": "./src/runtime/runner/queue-handler.ts",
+    "./runtime/runner/cron-handler": "./src/runtime/runner/cron-handler.ts",
+    "./runtime/indexer": "./src/runtime/indexer/index.ts",
+    "./runtime/executor-proxy-api": "./src/runtime/executor-proxy-api.ts",
+    "./runtime/durable-objects/git-push-lock": "./src/runtime/durable-objects/git-push-lock.ts",
+    "./runtime/durable-objects/notification-notifier": "./src/runtime/durable-objects/notification-notifier.ts",
+    "./runtime/durable-objects/rate-limiter": "./src/runtime/durable-objects/rate-limiter.ts",
+    "./runtime/durable-objects/routing": "./src/runtime/durable-objects/routing.ts",
+    "./runtime/durable-objects/run-notifier": "./src/runtime/durable-objects/run-notifier.ts",
+    "./runtime/durable-objects/session": "./src/runtime/durable-objects/session.ts",
+    "./runtime/durable-objects/shared": "./src/runtime/durable-objects/shared.ts",
+    "./runtime/queues/deploy-jobs": "./src/runtime/queues/deploy-jobs.ts",
+    "./runtime/queues/parallel-steps": "./src/runtime/queues/parallel-steps.ts",
+    "./runtime/queues/workflow-dlq": "./src/runtime/queues/workflow-dlq.ts",
+    "./runtime/queues/workflow-events": "./src/runtime/queues/workflow-events.ts",
+    "./runtime/queues/workflow-expressions": "./src/runtime/queues/workflow-expressions.ts",
+    "./runtime/queues/workflow-job-handler": "./src/runtime/queues/workflow-job-handler.ts",
+    "./runtime/queues/workflow-job-phases": "./src/runtime/queues/workflow-job-phases.ts",
+    "./runtime/queues/workflow-jobs": "./src/runtime/queues/workflow-jobs.ts",
+    "./runtime/queues/workflow-runner": "./src/runtime/queues/workflow-runner.ts",
+    "./runtime/queues/workflow-runtime-client": "./src/runtime/queues/workflow-runtime-client.ts",
+    "./runtime/queues/workflow-secrets": "./src/runtime/queues/workflow-secrets.ts",
+    "./runtime/queues/workflow-steps": "./src/runtime/queues/workflow-steps.ts",
+    "./runtime/queues/workflow-types": "./src/runtime/queues/workflow-types.ts",
+    "./runtime/container-hosts/browser-session-host": "./src/runtime/container-hosts/browser-session-host.ts",
+    "./runtime/container-hosts/browser-session-types": "./src/runtime/container-hosts/browser-session-types.ts",
+    "./runtime/container-hosts/container-runtime": "./src/runtime/container-hosts/container-runtime.ts",
+    "./runtime/container-hosts/d1-raw": "./src/runtime/container-hosts/d1-raw.ts",
+    "./runtime/container-hosts/executor-auth": "./src/runtime/container-hosts/executor-auth.ts",
+    "./runtime/container-hosts/executor-control-rpc": "./src/runtime/container-hosts/executor-control-rpc.ts",
+    "./runtime/container-hosts/executor-dispatch": "./src/runtime/container-hosts/executor-dispatch.ts",
+    "./runtime/container-hosts/executor-host": "./src/runtime/container-hosts/executor-host.ts",
+    "./runtime/container-hosts/executor-proxy-config": "./src/runtime/container-hosts/executor-proxy-config.ts",
+    "./runtime/container-hosts/executor-proxy-handlers": "./src/runtime/container-hosts/executor-proxy-handlers.ts",
+    "./runtime/container-hosts/executor-run-state": "./src/runtime/container-hosts/executor-run-state.ts",
+    "./runtime/container-hosts/executor-utils": "./src/runtime/container-hosts/executor-utils.ts",
+    "./runtime/container-hosts/proxy-token-manager": "./src/runtime/container-hosts/proxy-token-manager.ts",
+    "./runtime/container-hosts/runtime-host": "./src/runtime/container-hosts/runtime-host.ts",
+
+    "./server/routes/api": "./src/server/routes/api.ts",
+    "./server/routes/auth/cli": "./src/server/routes/auth/cli.ts",
+    "./server/routes/auth/external": "./src/server/routes/auth/external.ts",
+    "./server/routes/auth/link": "./src/server/routes/auth/link.ts",
+    "./server/routes/auth/provisioning": "./src/server/routes/auth/provisioning.ts",
+    "./server/routes/auth/session": "./src/server/routes/auth/session.ts",
+    "./server/routes/auth-api": "./src/server/routes/auth-api.ts",
+    "./server/routes/oauth": "./src/server/routes/oauth/routes.ts",
+    "./server/routes/well-known": "./src/server/routes/well-known.ts",
+    "./server/routes/smart-http": "./src/server/routes/smart-http.ts",
+    "./server/routes/setup": "./src/server/routes/setup.ts",
+    "./server/routes/rpc-types": "./src/server/routes/rpc-types.ts",
+    "./server/middleware/auth": "./src/server/middleware/auth.ts",
+    "./server/middleware/billing": "./src/server/middleware/billing.ts",
+    "./server/middleware/body-size": "./src/server/middleware/body-size.ts",
+    "./server/middleware/cache": "./src/server/middleware/cache.ts",
+    "./server/middleware/content-type": "./src/server/middleware/content-type.ts",
+    "./server/middleware/git-auth": "./src/server/middleware/git-auth.ts",
+    "./server/middleware/oauth-auth": "./src/server/middleware/oauth-auth.ts",
+    "./server/middleware/param-validation": "./src/server/middleware/param-validation.ts",
+    "./server/middleware/plan-gates": "./src/server/middleware/plan-gates.ts",
+    "./server/middleware/space-access": "./src/server/middleware/space-access.ts",
+    "./server/middleware/static-assets": "./src/server/middleware/static-assets.ts",
+    "./server/middleware/trust-tier": "./src/server/middleware/trust-tier.ts",
+    "./server/middleware/turnstile": "./src/server/middleware/turnstile.ts",
+    "./server/utils/spa-fallback": "./src/server/utils/spa-fallback.ts",
+
+    "./shared/utils": "./src/shared/utils/index.ts",
+    "./shared/types": "./src/shared/types/index.ts",
+    "./shared/config": "./src/shared/config/index.ts",
+    "./shared/constants": "./src/shared/constants/index.ts",
+
+    "./deployment/group-deploy-types": "./src/application/services/deployment/group-deploy-types.ts",
+
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "package.json"
+  ]
+}

package/src/__tests__/db-runtime-contracts.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const srcRoot = resolve(import.meta.dirname, '..');
+
+const bannedPatterns = [
+  { label: 'legacy spaces.kind column', regex: /\bspaces\.kind\b/ },
+  { label: 'legacy spaces kind SQL alias', regex: /\b(?:s|sp|w)\.kind\b/ },
+  { label: 'legacy spaces.owner_principal_id column', regex: /\bspaces\.owner_principal_id\b/ },
+  { label: 'legacy spaces.owner_id column', regex: /\bspaces\.owner_id\b/ },
+  { label: 'legacy managed_takos_tokens.subject_principal_id column', regex: /\bsubject_principal_id\b/ },
+  { label: 'legacy threads.project_id column', regex: /\bthreads\.project_id\b/ },
+  { label: 'legacy shared Tenant type', regex: /\bexport interface Tenant\b/ },
+  { label: 'legacy shared Project type', regex: /\bexport interface Project\b/ },
+  { label: 'legacy project_id placeholder field', regex: /\bproject_id\b/ },
+  { label: 'legacy user.id principal fallback', regex: /\bprincipal_id\s*\|\|\s*user\.id\b/ },
+  { label: 'legacy targetUser.id principal fallback', regex: /\bprincipal_id\s*\|\|\s*targetUser\.id\b/ },
+];
+
+function collectSourceFiles(dir: string): string[] {
+  const entries = readdirSync(dir).sort();
+  const files: string[] = [];
+
+  for (const entry of entries) {
+    const fullPath = resolve(dir, entry);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory()) {
+      files.push(...collectSourceFiles(fullPath));
+      continue;
+    }
+    if (!fullPath.endsWith('.ts') || fullPath.endsWith('.test.ts')) {
+      continue;
+    }
+    files.push(fullPath);
+  }
+
+  return files;
+}
+
+describe('DB runtime contract guard', () => {
+  it('does not reference removed legacy schema columns in runtime source', () => {
+    const files = collectSourceFiles(srcRoot);
+    const offenders: string[] = [];
+
+    for (const file of files) {
+      const source = readFileSync(file, 'utf8');
+      for (const { label, regex } of bannedPatterns) {
+        if (regex.test(source)) {
+          offenders.push(`${label}: ${file}`);
+        }
+      }
+    }
+
+    expect(offenders).toEqual([]);
+  });
+});

package/src/adapters/analytics-engine-binding.ts

@@ -0,0 +1,104 @@
+/**
+ * Non-Cloudflare implementation of the AnalyticsEngine binding.
+ *
+ * Supports three backends controlled by configuration:
+ * - **otel**: Sends data points to an OpenTelemetry collector endpoint
+ * - **buffer**: Accumulates data points in-memory (for local dev / debugging)
+ * - **noop**: Silently discards data points (default)
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface AnalyticsEngineDataPoint {
+  blobs?: string[];
+  doubles?: number[];
+  indexes?: string[];
+}
+
+export interface AnalyticsEngineDataset {
+  writeDataPoint(event: AnalyticsEngineDataPoint): void;
+}
+
+export type AnalyticsEngineConfig = {
+  dataset: string;
+  /** OTEL collector endpoint (e.g., http://localhost:4318/v1/logs). */
+  otelEndpoint?: string;
+  /** Backend mode. Defaults to 'noop'. */
+  mode?: 'otel' | 'buffer' | 'noop';
+};
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+export function createAnalyticsEngineBinding(config: AnalyticsEngineConfig): AnalyticsEngineDataset & { getBuffer(): AnalyticsEngineDataPoint[] } {
+  const mode = config.mode ?? (config.otelEndpoint ? 'otel' : 'noop');
+  const buffer: AnalyticsEngineDataPoint[] = [];
+
+  // Batched OTEL flush
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+  const pendingBatch: AnalyticsEngineDataPoint[] = [];
+
+  function flushToOtel() {
+    if (pendingBatch.length === 0 || !config.otelEndpoint) return;
+
+    const batch = pendingBatch.splice(0);
+    const body = JSON.stringify({
+      resourceLogs: [{
+        resource: { attributes: [{ key: 'service.name', value: { stringValue: `takos-analytics:${config.dataset}` } }] },
+        scopeLogs: [{
+          scope: { name: config.dataset },
+          logRecords: batch.map((dp) => ({
+            timeUnixNano: String(Date.now() * 1_000_000),
+            body: { stringValue: JSON.stringify(dp) },
+            attributes: [
+              ...(dp.indexes ?? []).map((idx, i) => ({
+                key: `index.${i}`,
+                value: { stringValue: idx },
+              })),
+            ],
+          })),
+        }],
+      }],
+    });
+
+    // Fire-and-forget POST to OTEL collector
+    fetch(config.otelEndpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body,
+    }).catch(() => { /* fire-and-forget: OTEL collector POST failure is non-critical */ });
+  }
+
+  return {
+    writeDataPoint(event: AnalyticsEngineDataPoint): void {
+      switch (mode) {
+        case 'buffer':
+          buffer.push(event);
+          break;
+        case 'otel':
+          pendingBatch.push(event);
+          // Batch flush: 100 data points or 1 second, whichever comes first
+          if (pendingBatch.length >= 100) {
+            flushToOtel();
+          } else if (!flushTimer) {
+            flushTimer = setTimeout(() => {
+              flushTimer = null;
+              flushToOtel();
+            }, 1000);
+          }
+          break;
+        case 'noop':
+        default:
+          break;
+      }
+    },
+
+    /** Access the in-memory buffer (only useful in 'buffer' mode). */
+    getBuffer(): AnalyticsEngineDataPoint[] {
+      return buffer;
+    },
+  };
+}

package/src/adapters/dynamo-kv-store.ts

@@ -0,0 +1,284 @@
+import {
+  DynamoDBClient,
+  GetItemCommand,
+  PutItemCommand,
+  DeleteItemCommand,
+  ScanCommand,
+} from '@aws-sdk/client-dynamodb';
+import type { KVNamespace } from '../../shared/types/bindings.ts';
+
+export type DynamoKvStoreConfig = {
+  region: string;
+  tableName: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+};
+
+export function createDynamoKvStore(config: DynamoKvStoreConfig): KVNamespace {
+  let client: DynamoDBClient | undefined;
+
+  function getClient(): DynamoDBClient {
+    if (!client) {
+      client = new DynamoDBClient({
+        region: config.region,
+        ...(config.accessKeyId && config.secretAccessKey
+          ? {
+              credentials: {
+                accessKeyId: config.accessKeyId,
+                secretAccessKey: config.secretAccessKey,
+              },
+            }
+          : {}),
+      });
+    }
+    return client;
+  }
+
+  function nowEpoch(): number {
+    return Math.floor(Date.now() / 1000);
+  }
+
+  function isExpired(expirationValue: string | undefined): boolean {
+    if (expirationValue === undefined) return false;
+    const exp = Number(expirationValue);
+    return exp > 0 && exp <= nowEpoch();
+  }
+
+  return {
+    async get(
+      key: string,
+      type?: 'text' | 'json' | 'arrayBuffer' | 'stream',
+    ): Promise<string | null> {
+      const command = new GetItemCommand({
+        TableName: config.tableName,
+        Key: { pk: { S: key } },
+      });
+      const result = await getClient().send(command);
+      const item = result.Item;
+      if (!item || !item.value?.S) return null;
+
+      if (isExpired(item.expiration?.N)) return null;
+
+      const raw = item.value.S;
+
+      // Return type is declared as `string | null` to match the default
+      // KVNamespace.get() overload.  When `type` is 'json', 'arrayBuffer',
+      // or 'stream' the actual runtime value differs — this mirrors the
+      // overloaded behaviour of the Cloudflare KVNamespace interface.
+      switch (type) {
+        case 'json':
+          return JSON.parse(raw) as string;
+        case 'arrayBuffer': {
+          const encoder = new TextEncoder();
+          return encoder.encode(raw).buffer as unknown as string;
+        }
+        case 'stream': {
+          const encoder = new TextEncoder();
+          const bytes = encoder.encode(raw);
+          return new ReadableStream({
+            start(controller) {
+              controller.enqueue(bytes);
+              controller.close();
+            },
+          }) as unknown as string;
+        }
+        case 'text':
+        default:
+          return raw;
+      }
+    },
+
+    async getWithMetadata(
+      key: string,
+      type?: 'text' | 'json' | 'arrayBuffer' | 'stream',
+    ): Promise<{ value: unknown; metadata: Record<string, string> | null; cacheStatus: null }> {
+      const command = new GetItemCommand({
+        TableName: config.tableName,
+        Key: { pk: { S: key } },
+      });
+      const result = await getClient().send(command);
+      const item = result.Item;
+
+      if (!item || !item.value?.S || isExpired(item.expiration?.N)) {
+        return { value: null, metadata: null, cacheStatus: null };
+      }
+
+      const raw = item.value.S;
+      let value: unknown;
+
+      switch (type) {
+        case 'json':
+          value = JSON.parse(raw);
+          break;
+        case 'arrayBuffer': {
+          const encoder = new TextEncoder();
+          value = encoder.encode(raw).buffer;
+          break;
+        }
+        case 'stream': {
+          const encoder = new TextEncoder();
+          const bytes = encoder.encode(raw);
+          value = new ReadableStream({
+            start(controller) {
+              controller.enqueue(bytes);
+              controller.close();
+            },
+          });
+          break;
+        }
+        case 'text':
+        default:
+          value = raw;
+          break;
+      }
+
+      const metadata: Record<string, string> | null = item.metadata?.S
+        ? (JSON.parse(item.metadata.S) as Record<string, string>)
+        : null;
+
+      return { value, metadata, cacheStatus: null };
+    },
+
+    async put(
+      key: string,
+      value: string | ArrayBuffer | ReadableStream,
+      options?: {
+        expirationTtl?: number;
+        expiration?: number;
+        metadata?: Record<string, string>;
+      },
+    ): Promise<void> {
+      let serialized: string;
+
+      if (typeof value === 'string') {
+        serialized = value;
+      } else if (value instanceof ArrayBuffer) {
+        const decoder = new TextDecoder();
+        serialized = decoder.decode(value);
+      } else {
+        // ReadableStream
+        const reader = (value as ReadableStream).getReader();
+        const chunks: Uint8Array[] = [];
+        for (;;) {
+          const { done, value: chunk } = await reader.read();
+          if (done) break;
+          chunks.push(chunk);
+        }
+        const totalLength = chunks.reduce((acc, c) => acc + c.length, 0);
+        const combined = new Uint8Array(totalLength);
+        let offset = 0;
+        for (const chunk of chunks) {
+          combined.set(chunk, offset);
+          offset += chunk.length;
+        }
+        const decoder = new TextDecoder();
+        serialized = decoder.decode(combined);
+      }
+
+      const item: Record<string, { S?: string; N?: string }> = {
+        pk: { S: key },
+        value: { S: serialized },
+      };
+
+      if (options?.metadata) {
+        item.metadata = { S: JSON.stringify(options.metadata) };
+      }
+
+      if (options?.expiration !== undefined) {
+        item.expiration = { N: String(options.expiration) };
+      } else if (options?.expirationTtl !== undefined) {
+        item.expiration = { N: String(nowEpoch() + options.expirationTtl) };
+      }
+
+      const command = new PutItemCommand({
+        TableName: config.tableName,
+        Item: item as Record<string, import('@aws-sdk/client-dynamodb').AttributeValue>,
+      });
+      await getClient().send(command);
+    },
+
+    async delete(key: string): Promise<void> {
+      const command = new DeleteItemCommand({
+        TableName: config.tableName,
+        Key: { pk: { S: key } },
+      });
+      await getClient().send(command);
+    },
+
+    async list(
+      options?: { prefix?: string; limit?: number; cursor?: string },
+    ): Promise<{
+      keys: Array<{ name: string; expiration?: number; metadata?: Record<string, string> }>;
+      list_complete: boolean;
+      cursor?: string;
+    }> {
+      const limit = options?.limit ?? 1000;
+
+      const expressionAttributeValues: Record<string, import('@aws-sdk/client-dynamodb').AttributeValue> = {};
+      let filterExpression: string | undefined;
+
+      if (options?.prefix) {
+        filterExpression = 'begins_with(pk, :prefix)';
+        expressionAttributeValues[':prefix'] = { S: options.prefix };
+      }
+
+      let exclusiveStartKey: Record<string, import('@aws-sdk/client-dynamodb').AttributeValue> | undefined;
+      if (options?.cursor) {
+        exclusiveStartKey = JSON.parse(
+          Buffer.from(options.cursor, 'base64').toString('utf-8'),
+        );
+      }
+
+      const command = new ScanCommand({
+        TableName: config.tableName,
+        Limit: limit,
+        ...(filterExpression ? { FilterExpression: filterExpression } : {}),
+        ...(Object.keys(expressionAttributeValues).length > 0
+          ? { ExpressionAttributeValues: expressionAttributeValues }
+          : {}),
+        ...(exclusiveStartKey
+          ? { ExclusiveStartKey: exclusiveStartKey }
+          : {}),
+      });
+
+      const result = await getClient().send(command);
+      const now = nowEpoch();
+
+      const keys = (result.Items ?? [])
+        .filter((item) => {
+          if (!item.pk?.S) return false;
+          const exp = item.expiration?.N ? Number(item.expiration.N) : 0;
+          return exp === 0 || exp > now;
+        })
+        .map((item) => {
+          const entry: { name: string; expiration?: number; metadata?: Record<string, string> } = {
+            name: item.pk!.S!,
+          };
+          if (item.expiration?.N) {
+            entry.expiration = Number(item.expiration.N);
+          }
+          if (item.metadata?.S) {
+            entry.metadata = JSON.parse(item.metadata.S) as Record<string, string>;
+          }
+          return entry;
+        });
+
+      const listComplete = !result.LastEvaluatedKey;
+      let cursor: string | undefined;
+      if (result.LastEvaluatedKey) {
+        cursor = Buffer.from(
+          JSON.stringify(result.LastEvaluatedKey),
+        ).toString('base64');
+      }
+
+      return {
+        keys,
+        list_complete: listComplete,
+        ...(cursor ? { cursor } : {}),
+      };
+    },
+  // Cast required: this object structurally implements the KVNamespace
+  // interface, but TypeScript cannot verify compatibility with the
+  // Cloudflare Workers type definitions without the runtime environment.
+  } as unknown as KVNamespace;
+}