@volter/twin-cloudflare 0.1.0

package/src/cli.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-cloudflare CLI: serve the KERNEL-BACKED Cloudflare API twin, or run conformance. State
+// lives in the @volter/world-core action log (no in-memory side-store). Conformance is dev-only +
+// lazy-imported so the bin runs without @volter/world-tooling (E2).
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createCloudflareTwinServer } from './cloudflare-server.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', String(process.env.PORT ?? '0'))) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+
+if (cmd === 'serve' || cmd === undefined) {
+  const s = await createCloudflareTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`cloudflare twin (accounts, zones, Cloudflare Tunnels, DNS records, Workers, R2, Hyperdrive, Queues)${readOnly ? ' [read-only]' : ''} at ${s.url}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  const { checkCloudflareConformance } = await import('./cloudflare-conformance.ts');
+  const report = await checkCloudflareConformance();
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-cloudflare serve|conformance [--port N] [--root DIR] [--read-only]\n');
+}

package/src/cloudflare-budget.ts

@@ -0,0 +1,61 @@
+// Cloudflare client-side rate budget. The mechanism is shared @volter/world-core RateBudget;
+// only Cloudflare's documented limit and conservative weights live here.
+//
+// Official source, live-fetched 2026-08-21:
+// https://developers.cloudflare.com/fundamentals/api/reference/limits/
+// Cloudflare publishes a global 1,200 requests / five minutes per user/account token.
+// This declaration stays at the kernel fallback's much tighter 60 weighted units/minute.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+
+const VENDOR = 'cloudflare';
+export const CLOUDFLARE_BUDGET_WINDOW_MS = 60_000;
+export const CLOUDFLARE_BUDGET_CEILING = 60;
+export const CLOUDFLARE_BUDGET_MAX_RETRY_AFTER_S = 300;
+export const CLOUDFLARE_CALL_WEIGHTS = { mutation: 3, read: 2 } as const;
+
+export const CLOUDFLARE_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: CLOUDFLARE_BUDGET_WINDOW_MS,
+  ceiling: CLOUDFLARE_BUDGET_CEILING,
+  defaultWeight: CLOUDFLARE_CALL_WEIGHTS.read,
+  maxRetryAfterSeconds: CLOUDFLARE_BUDGET_MAX_RETRY_AFTER_S,
+  rules: [
+    { match: '^(POST|PUT|PATCH|DELETE) ', weight: CLOUDFLARE_CALL_WEIGHTS.mutation },
+  ],
+  reason:
+    'Cloudflare publishes a global Client API limit of 1,200 requests per five minutes per user/account token ' +
+    '(https://developers.cloudflare.com/fundamentals/api/reference/limits/, live-fetched 2026-08-21). ' +
+    'This declaration is deliberately tighter: 60 weighted units per minute; reads cost 2 (30/minute) and ' +
+    'mutations cost 3 (20/minute). It neither exceeds the documented sustained limit nor the kernel fallback burst.',
+};
+
+declareRateBudget(VENDOR, CLOUDFLARE_RATE_BUDGET);
+
+export function cloudflareCallWeight(method: string, path: string): number {
+  return rateBudgetWeight(VENDOR, `${method.toUpperCase()} ${path.split('?')[0] ?? path}`);
+}
+
+export function cloudflareBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  const value = typeof opts === 'string' ? { root: opts } : opts;
+  return rateBudgetPath({ ...value, vendor: VENDOR });
+}
+
+export type CloudflareBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+export class CloudflareBudget extends RateBudget {
+  constructor(opts: CloudflareBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+export type { RateBudgetErrorKind as CloudflareBudgetErrorKind } from '@volter/world-core';
+export { RateBudgetError as CloudflareBudgetError } from '@volter/world-core';
+export type CloudflareBudgetReservation = RateBudgetReservation;
+export type CloudflareBudgetSnapshot = RateBudgetSnapshot;