@pulse-compute/provider-fastly 0.0.0 → 1.0.0-beta.1

package/src/compiler/runtime-provider-kv.js

@@ -0,0 +1,237 @@
+'use strict';
+
+const { PACKAGE_VERSION, normalizeArtifact, normalizeDiagnostic } = loadContractsDiagnostics();
+const { validateRuntimeProvider, extractProviderMap, extractKvCapabilities, normalizeRuntimeProvider } = require('./runtime-provider-shape.js');
+const {
+  CONFIG_AUTHORING_SHAPE_VERSION,
+  PLATFORM_STORE_MAP_VERSION,
+  RUNTIME_PROVIDER_KV_PHASE,
+  KV_ADAPTER_INTEGRATION_PHASE,
+  RUNTIME_PROVIDER_CONTRACT_VERSION,
+  RUNTIME_PROVIDER_KV_RESOLUTION_VERSION,
+  KV_CAPABILITY_CONTRACT_VERSION,
+  KV_PROVIDER_MAP_VERSION,
+  RUNTIME_PROVIDER_API_SURFACE_VERSION,
+  RUNTIME_PROVIDER_SMOKE_VERSION,
+  KV_ADAPTER_INTEGRATION_VERSION,
+  KV_PROVIDER_RUNTIME_MAP_VERSION,
+  RUNTIME_PROVIDER_AUTHORING_SHAPE,
+  RUNTIME_PROVIDER_DEFAULT_POLICY,
+  RUNTIME_PROVIDER_KINDS,
+  KV_CAPABILITY_POLICY,
+  RUNTIME_PROVIDER_API_SURFACES
+} = loadContractsRuntimeProviderKv();
+
+
+function loadContractsDiagnostics() {
+  try {
+    return require('@pulse-compute/wasm-contracts/diagnostics');
+  } catch (error) {
+    if (error && error.code === 'MODULE_NOT_FOUND' && String(error.message).includes('@pulse-compute/wasm-contracts')) {
+      return require('../../../../wasm/packages/contracts/src/diagnostics.js');
+    }
+    throw error;
+  }
+}
+
+function loadContractsRuntimeProviderKv() {
+  try {
+    return require('@pulse-compute/wasm-contracts/config/runtime-provider-kv');
+  } catch (error) {
+    if (error && error.code === 'MODULE_NOT_FOUND' && String(error.message).includes('@pulse-compute/wasm-contracts')) {
+      return require('../../../../wasm/packages/contracts/src/config/runtime-provider-kv.js');
+    }
+    throw error;
+  }
+}
+
+function plainObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function makeDiag(raw) {
+  return normalizeDiagnostic({
+    code: raw.code || 'PULSEWASM_RUNTIME_PROVIDER_INVALID',
+    severity: 'error',
+    phase: 'runtime-provider-kv',
+    pass: 'runtime-provider-kv',
+    loc: { file: '<config>' },
+    message: raw.message || 'Invalid runtime provider configuration.',
+    details: raw
+  });
+}
+
+function normalizeResolvedConfig(input = {}) {
+  return input && input.artifact ? input.artifact : input;
+}
+
+function buildRuntimeProviderKv(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const generatedBy = options.generatedBy || PACKAGE_VERSION;
+  const resolvedConfig = normalizeResolvedConfig(options.resolvedConfig || {});
+  const profileName = resolvedConfig.profile || resolvedConfig.selectedProfile || options.profile || 'edge';
+  const profile = { runtime: plainObject(resolvedConfig.runtime) };
+  const provider = normalizeRuntimeProvider(profile.runtime) || {};
+  const rawDiagnostics = validateRuntimeProvider(profileName, profile);
+  const diagnostics = rawDiagnostics.map(makeDiag);
+  const providerMap = extractProviderMap(profileName, profile);
+  const kvCapabilities = extractKvCapabilities(profileName, profile);
+
+  const contract = normalizeArtifact({
+    version: RUNTIME_PROVIDER_CONTRACT_VERSION,
+    generatedBy,
+    phase: RUNTIME_PROVIDER_KV_PHASE,
+    status: diagnostics.length ? 'error' : 'ok',
+    authoringShape: RUNTIME_PROVIDER_AUTHORING_SHAPE,
+    defaultPolicy: RUNTIME_PROVIDER_DEFAULT_POLICY,
+    providerKinds: RUNTIME_PROVIDER_KINDS.slice(),
+    provider,
+    summary: {
+      profile: profileName,
+      provider: provider.kind || null,
+      kvNamespaces: kvCapabilities.length,
+      configStore: provider.configStore || null,
+      secretStore: provider.secretStore || null
+    }
+  }, cwd);
+
+  const resolution = normalizeArtifact({
+    version: RUNTIME_PROVIDER_KV_RESOLUTION_VERSION,
+    generatedBy,
+    phase: RUNTIME_PROVIDER_KV_PHASE,
+    status: diagnostics.length ? 'error' : 'ok',
+    profile: profileName,
+    provider,
+    providerMap,
+    kvCapabilities,
+    summary: contract.summary
+  }, cwd);
+
+  const configAuthoringShape = normalizeArtifact({
+    version: CONFIG_AUTHORING_SHAPE_VERSION,
+    generatedBy,
+    phase: RUNTIME_PROVIDER_KV_PHASE,
+    canonical: RUNTIME_PROVIDER_AUTHORING_SHAPE,
+    rootConfigDefinesTopologyOnly: true,
+    profileRuntimeDefinesBehavior: true,
+    examples: {
+      provider: {
+        kind: 'fastly',
+        configStore: 'pulse_config',
+        secretStore: 'pulse_secrets',
+        kv: { sessions: 'sessions' }
+      }
+    },
+    summary: { canonical: RUNTIME_PROVIDER_AUTHORING_SHAPE }
+  }, cwd);
+
+  const platformStoreMap = normalizeArtifact({
+    version: PLATFORM_STORE_MAP_VERSION,
+    generatedBy,
+    phase: RUNTIME_PROVIDER_KV_PHASE,
+    providerKind: provider.kind || null,
+    stores: providerMap.stores,
+    kv: providerMap.kv,
+    generatedOutputOnly: true,
+    summary: { stores: Object.keys(providerMap.stores || {}).length, kvNamespaces: Object.keys(providerMap.kv || {}).length }
+  }, cwd);
+
+  const kvCapabilityContract = normalizeArtifact({
+    version: KV_CAPABILITY_CONTRACT_VERSION,
+    generatedBy,
+    phase: RUNTIME_PROVIDER_KV_PHASE,
+    handlerSurface: KV_CAPABILITY_POLICY.handlerSurface,
+    compiledHandlerLowering: KV_CAPABILITY_POLICY.compiledHandlerLowering,
+    hostEffectExecution: KV_CAPABILITY_POLICY.hostEffectExecution,
+    localAdapterProof: KV_CAPABILITY_POLICY.localAdapterProof,
+    namespaces: kvCapabilities,
+    summary: { namespaces: kvCapabilities.length, execution: 'reserved-effect' }
+  }, cwd);
+
+  const kvProviderMap = normalizeArtifact({
+    version: KV_PROVIDER_MAP_VERSION,
+    generatedBy,
+    phase: RUNTIME_PROVIDER_KV_PHASE,
+    provider: provider.kind || null,
+    kv: providerMap.kv,
+    summary: { namespaces: Object.keys(providerMap.kv || {}).length }
+  }, cwd);
+
+  const apiSurface = normalizeArtifact({
+    version: RUNTIME_PROVIDER_API_SURFACE_VERSION,
+    generatedBy,
+    phase: RUNTIME_PROVIDER_KV_PHASE,
+    surfaces: RUNTIME_PROVIDER_API_SURFACES.map((surface) => ({ ...surface })),
+    summary: { surfaces: RUNTIME_PROVIDER_API_SURFACES.length }
+  }, cwd);
+
+  const smoke = normalizeArtifact({
+    version: RUNTIME_PROVIDER_SMOKE_VERSION,
+    generatedBy,
+    phase: RUNTIME_PROVIDER_KV_PHASE,
+    status: diagnostics.length ? 'error' : 'ok',
+    checks: [
+      { name: 'provider_kind_valid', status: provider.kind ? 'ok' : 'error' },
+      { name: 'fastly_stores_declared', status: provider.kind === 'fastly' && provider.configStore && provider.secretStore ? 'ok' : 'skipped' },
+      { name: 'kv_namespaces_declared', status: kvCapabilities.length > 0 ? 'ok' : 'skipped' }
+    ],
+    summary: { failedChecks: diagnostics.length, kvNamespaces: kvCapabilities.length }
+  }, cwd);
+
+  const markdown = `# Runtime provider / KV contract\n\n- Canonical authoring shape: \`runtime.provider\`\n- Provider: \`${provider.kind || 'unknown'}\`\n- KV namespaces: ${kvCapabilities.map((entry) => `\`${entry.logicalName}\``).join(', ') || 'none'}\n\nKV execution and compiled-handler lowering remain reserved here; the local runtime/adapter store is validated separately.\n`;
+
+  return {
+    artifact: contract,
+    resolution,
+    configAuthoringShape,
+    platformStoreMap,
+    kvCapabilityContract,
+    kvProviderMap,
+    apiSurface,
+    smoke,
+    files: [{ file: 'generated/host/runtime-provider-kv-contract.md', text: markdown }],
+    diagnostics,
+    summary: contract.summary
+  };
+}
+
+function buildKvAdapterIntegration(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const generatedBy = options.generatedBy || PACKAGE_VERSION;
+  const resolvedConfig = normalizeResolvedConfig(options.resolvedConfig || {});
+  const profileName = resolvedConfig.profile || resolvedConfig.selectedProfile || options.profile || 'edge';
+  const runtime = plainObject(resolvedConfig.runtime);
+  const provider = normalizeRuntimeProvider(runtime) || {};
+  const kv = provider.kv || {};
+  return {
+    integration: normalizeArtifact({
+      version: KV_ADAPTER_INTEGRATION_VERSION,
+      generatedBy,
+      phase: KV_ADAPTER_INTEGRATION_PHASE,
+      status: 'ok',
+      profile: profileName,
+      providerKind: provider.kind || null,
+      hostRuntimeModule: 'src/compiled-wasm-host-runtime-kv.js',
+      nodeAdapterModule: 'src/compiled-wasm-node-adapter-kv.js',
+      kvProviderModule: 'src/kv-provider.js',
+      compiledHandlerLowering: KV_CAPABILITY_POLICY.compiledHandlerLowering,
+      fastlyKvHostcalls: 'reserved',
+      summary: { namespaces: Object.keys(kv).length, localAdapterProof: true }
+    }, cwd),
+    runtimeMap: normalizeArtifact({
+      version: KV_PROVIDER_RUNTIME_MAP_VERSION,
+      generatedBy,
+      phase: KV_ADAPTER_INTEGRATION_PHASE,
+      status: 'ok',
+      provider: provider.kind || null,
+      namespaces: Object.entries(kv).map(([logicalName, physicalName]) => ({ logicalName, physicalName, storage: 'in-memory-local-proof' })),
+      summary: { namespaces: Object.keys(kv).length }
+    }, cwd),
+    files: [{
+      file: 'generated/host/runtime-provider-kv-adapter-proof.md',
+      text: `# Runtime provider KV adapter proof\n\nThis proof wires provider-neutral KV namespaces into the local compiled-Wasm host runtime and Node adapter. It does not lower \`ctx.kv(...)\` inside compiled handlers or bind Fastly KV hostcalls.\n`
+    }]
+  };
+}
+
+module.exports = { buildRuntimeProviderKv, buildKvAdapterIntegration };

package/src/compiler/runtime-provider-shape.js

@@ -0,0 +1,109 @@
+'use strict';
+
+const ALLOWED_PROVIDER_KINDS = new Set(['fastly', 'local', 'node']);
+const DIAGNOSTICS = {
+  PROFILE_RUNTIME_REQUIRED: 'PULSEWASM_PROFILE_RUNTIME_REQUIRED',
+  PROVIDER_REQUIRED: 'PULSEWASM_RUNTIME_PROVIDER_REQUIRED',
+  PROVIDER_KIND_INVALID: 'PULSEWASM_RUNTIME_PROVIDER_KIND_INVALID',
+  FASTLY_CONFIG_STORE_REQUIRED: 'PULSEWASM_FASTLY_CONFIG_STORE_REQUIRED',
+  FASTLY_SECRET_STORE_REQUIRED: 'PULSEWASM_FASTLY_SECRET_STORE_REQUIRED',
+  KV_LINK_INVALID: 'PULSEWASM_KV_LINK_INVALID',
+  KV_NAMESPACE_INVALID: 'PULSEWASM_KV_NAMESPACE_INVALID'
+};
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeRuntimeProvider(runtime = {}) {
+  if (isPlainObject(runtime.provider)) return runtime.provider;
+  const fastly = isPlainObject(runtime.platform) && isPlainObject(runtime.platform.fastly) ? runtime.platform.fastly : undefined;
+  if (fastly) {
+    return {
+      kind: 'fastly',
+      configStore: fastly.configStore,
+      secretStore: fastly.secretStore,
+      kv: fastly.kv || {}
+    };
+  }
+  return undefined;
+}
+
+function validateRuntimeProvider(profileName, profile) {
+  const diagnostics = [];
+  const runtime = profile && profile.runtime;
+  if (!isPlainObject(runtime)) {
+    diagnostics.push({ code: DIAGNOSTICS.PROFILE_RUNTIME_REQUIRED, profile: profileName, message: 'Profile runtime is required.' });
+    return diagnostics;
+  }
+  const provider = normalizeRuntimeProvider(runtime);
+  if (!isPlainObject(provider)) {
+    diagnostics.push({ code: DIAGNOSTICS.PROVIDER_REQUIRED, profile: profileName, message: 'runtime.provider is required.' });
+    return diagnostics;
+  }
+  if (!ALLOWED_PROVIDER_KINDS.has(provider.kind)) {
+    diagnostics.push({ code: DIAGNOSTICS.PROVIDER_KIND_INVALID, profile: profileName, message: 'runtime.provider.kind must be one of fastly, local, node.' });
+  }
+  if (provider.kind === 'fastly') {
+    if (typeof provider.configStore !== 'string' || !provider.configStore) {
+      diagnostics.push({ code: DIAGNOSTICS.FASTLY_CONFIG_STORE_REQUIRED, profile: profileName, message: 'Fastly provider requires configStore.' });
+    }
+    if (typeof provider.secretStore !== 'string' || !provider.secretStore) {
+      diagnostics.push({ code: DIAGNOSTICS.FASTLY_SECRET_STORE_REQUIRED, profile: profileName, message: 'Fastly provider requires secretStore.' });
+    }
+  }
+  if (provider.kv !== undefined) {
+    if (!isPlainObject(provider.kv)) {
+      diagnostics.push({ code: DIAGNOSTICS.KV_NAMESPACE_INVALID, profile: profileName, message: 'runtime.provider.kv must be an object map.' });
+    } else {
+      for (const [logicalName, link] of Object.entries(provider.kv)) {
+        if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(logicalName)) {
+          diagnostics.push({ code: DIAGNOSTICS.KV_NAMESPACE_INVALID, profile: profileName, logicalName, message: 'KV logical names must be alphanumeric with _ or -.' });
+        }
+        if (typeof link !== 'string' || !link) {
+          diagnostics.push({ code: DIAGNOSTICS.KV_LINK_INVALID, profile: profileName, logicalName, message: 'KV links must be non-empty strings.' });
+        }
+      }
+    }
+  }
+  return diagnostics;
+}
+
+function extractProviderMap(profileName, profile) {
+  const runtime = profile.runtime;
+  const provider = normalizeRuntimeProvider(runtime) || {};
+  return {
+    profile: profileName,
+    provider: provider.kind || null,
+    stores: provider.kind === 'fastly' ? {
+      configStore: provider.configStore,
+      secretStore: provider.secretStore
+    } : {},
+    kv: provider.kv || {},
+    authoringShape: 'runtime.provider',
+    legacyPlatformFallback: !isPlainObject(runtime.provider) && isPlainObject(runtime.platform)
+  };
+}
+
+function extractKvCapabilities(profileName, profile) {
+  const runtime = profile.runtime || {};
+  const provider = normalizeRuntimeProvider(runtime) || {};
+  const kv = provider.kv || {};
+  return Object.entries(kv).map(([name, link]) => ({
+    profile: profileName,
+    logicalName: name,
+    link,
+    provider: provider.kind || null,
+    execution: 'reserved-effect',
+    localAdapterProof: 'runtime-owned in-memory provider',
+    handlerSurface: `ctx.kv("${name}")`
+  }));
+}
+
+module.exports = {
+  DIAGNOSTICS,
+  validateRuntimeProvider,
+  extractProviderMap,
+  extractKvCapabilities,
+  normalizeRuntimeProvider
+};

package/src/config-api.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const { fastlyConfigDefault } = require('./config-schema.js');
+
+const FASTLY_PROVIDER_API_VERSION = 'pulse.provider-fastly-api.v2';
+
+function stringMap(input = {}) {
+  return Object.freeze(Object.fromEntries(Object.entries(input || {}).map(([key, value]) => [String(key), String(value)])));
+}
+
+function gripAuthentication(input) {
+  if (input === undefined) return undefined;
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new TypeError('fastly.grip.authentication must be an object.');
+  }
+  const scheme = String(input.scheme || 'bearer').toLowerCase();
+  if (scheme !== 'bearer') throw new TypeError('fastly.grip.authentication.scheme must be bearer.');
+  return Object.freeze({
+    scheme: 'bearer',
+    secretRef: String(input.secretRef || '')
+  });
+}
+
+function gripBindings(input = {}) {
+  const value = input && typeof input === 'object' && !Array.isArray(input) ? input : {};
+  return Object.freeze({
+    fanoutBackend: value.fanoutBackend === undefined ? undefined : String(value.fanoutBackend),
+    publishEndpoint: value.publishEndpoint === undefined ? undefined : String(value.publishEndpoint),
+    publishUrl: value.publishUrl === undefined ? undefined : String(value.publishUrl),
+    publishBackend: value.publishBackend === undefined ? undefined : String(value.publishBackend),
+    authentication: gripAuthentication(value.authentication),
+    directHold: value.directHold === undefined ? fastlyConfigDefault('fastly.grip.directHold') : value.directHold !== false
+  });
+}
+
+function fastly(options = {}) {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) throw new TypeError('fastly() requires an options object.');
+  const normalizedGrip = options.grip === undefined ? undefined : gripBindings(options.grip);
+  return Object.freeze({
+    kind: 'fastly',
+    version: FASTLY_PROVIDER_API_VERSION,
+    bindings: Object.freeze({
+      configStore: String(options.configStore ?? fastlyConfigDefault('fastly.configStore')),
+      secretStore: String(options.secretStore ?? fastlyConfigDefault('fastly.secretStore')),
+      kv: stringMap(options.kv),
+      backends: stringMap(options.backends),
+      ...(normalizedGrip ? { grip: normalizedGrip } : {}),
+      dynamicBackends: options.dynamicBackends === undefined ? fastlyConfigDefault('fastly.dynamicBackends') : options.dynamicBackends === true
+    }),
+    build: Object.freeze({
+      name: String(options.name ?? fastlyConfigDefault('fastly.name')),
+      description: String(options.description ?? fastlyConfigDefault('fastly.description')),
+      authors: Object.freeze((Array.isArray(options.authors) ? options.authors : fastlyConfigDefault('fastly.authors')).map(String)),
+      language: 'other'
+    }),
+    local: Object.freeze({
+      networkFetch: Boolean(options.local?.networkFetch ?? fastlyConfigDefault('fastly.local.networkFetch'))
+    }),
+    providerSpecificUserland: false
+  });
+}
+
+module.exports = Object.freeze({ FASTLY_PROVIDER_API_VERSION, fastly });

package/src/config-schema.d.ts

@@ -0,0 +1,13 @@
+export interface PulseFastlyConfigSchemaRule {
+  readonly kind: string;
+  readonly default?: unknown;
+}
+
+export interface PulseFastlyConfigSchema {
+  readonly schemaVersion: 'pulse.provider-fastly-config-schema.v1';
+  readonly fields: Readonly<Record<string, PulseFastlyConfigSchemaRule>>;
+}
+
+export const FASTLY_CONFIG_SCHEMA: PulseFastlyConfigSchema;
+export function fastlyConfigRule(path: string): PulseFastlyConfigSchemaRule;
+export function fastlyConfigDefault(path: string): unknown;

package/src/config-schema.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const FASTLY_CONFIG_SCHEMA = require('./config-schema.json');
+
+function clone(value) {
+  if (Array.isArray(value)) return value.map(clone);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, clone(entry)]));
+  return value;
+}
+
+function fastlyConfigRule(path) {
+  const rule = FASTLY_CONFIG_SCHEMA.fields[path];
+  if (!rule) throw new Error(`Unknown Fastly config schema field ${path}`);
+  return rule;
+}
+
+function fastlyConfigDefault(path) {
+  const rule = fastlyConfigRule(path);
+  if (!Object.prototype.hasOwnProperty.call(rule, 'default')) throw new Error(`Fastly config schema field ${path} has no default`);
+  return clone(rule.default);
+}
+
+module.exports = Object.freeze({
+  FASTLY_CONFIG_SCHEMA,
+  fastlyConfigRule,
+  fastlyConfigDefault
+});

package/src/config-schema.json

@@ -0,0 +1,73 @@
+{
+  "schemaVersion": "pulse.provider-fastly-config-schema.v1",
+  "fields": {
+    "fastly.configStore": {
+      "kind": "string",
+      "default": "pulse_config"
+    },
+    "fastly.secretStore": {
+      "kind": "string",
+      "default": "pulse_secrets"
+    },
+    "fastly.kv": {
+      "kind": "string-map",
+      "default": {}
+    },
+    "fastly.backends": {
+      "kind": "string-map",
+      "default": {}
+    },
+    "fastly.dynamicBackends": {
+      "kind": "boolean",
+      "default": false
+    },
+    "fastly.grip": {
+      "kind": "object"
+    },
+    "fastly.grip.fanoutBackend": {
+      "kind": "optional-string"
+    },
+    "fastly.grip.publishEndpoint": {
+      "kind": "optional-string"
+    },
+    "fastly.grip.publishUrl": {
+      "kind": "optional-string"
+    },
+    "fastly.grip.publishBackend": {
+      "kind": "optional-string"
+    },
+    "fastly.grip.authentication": {
+      "kind": "object"
+    },
+    "fastly.grip.authentication.scheme": {
+      "kind": "optional-string"
+    },
+    "fastly.grip.authentication.secretRef": {
+      "kind": "optional-string"
+    },
+    "fastly.grip.directHold": {
+      "kind": "boolean",
+      "default": true
+    },
+    "fastly.name": {
+      "kind": "string",
+      "default": "pulse-app"
+    },
+    "fastly.description": {
+      "kind": "string",
+      "default": "Pulse application"
+    },
+    "fastly.authors": {
+      "kind": "string-array",
+      "default": []
+    },
+    "fastly.local": {
+      "kind": "object",
+      "default": {}
+    },
+    "fastly.local.networkFetch": {
+      "kind": "boolean",
+      "default": false
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./config-api.js');

package/src/index.ts

@@ -0,0 +1,118 @@
+import FASTLY_CONFIG_SCHEMA from './config-schema.json';
+
+type FastlySchemaRule = Readonly<{ kind: string; default?: unknown }>;
+const fastlySchemaFields = FASTLY_CONFIG_SCHEMA.fields as Readonly<Record<string, FastlySchemaRule>>;
+const fastlyDefaults = Object.freeze(Object.fromEntries(Object.entries(fastlySchemaFields).filter(([, rule]) => Object.prototype.hasOwnProperty.call(rule, 'default')).map(([key, rule]) => [key, rule.default]))) as Readonly<Record<string, unknown>>;
+
+export const FASTLY_PROVIDER_API_VERSION = 'pulse.provider-fastly-api.v2' as const;
+
+export interface PulseFastlyGripOptions {
+  readonly fanoutBackend?: string;
+  readonly publishEndpoint?: string;
+  readonly publishUrl?: string;
+  readonly publishBackend?: string;
+  readonly authentication?: {
+    readonly scheme?: 'bearer';
+    readonly secretRef: string;
+  };
+  readonly directHold?: boolean;
+}
+
+export interface PulseFastlyLocalOptions {
+  readonly networkFetch?: boolean;
+}
+
+export interface PulseFastlyProviderOptions {
+  readonly configStore?: string;
+  readonly secretStore?: string;
+  readonly kv?: Readonly<Record<string, string>>;
+  readonly backends?: Readonly<Record<string, string>>;
+  readonly dynamicBackends?: boolean;
+  readonly grip?: PulseFastlyGripOptions;
+  readonly name?: string;
+  readonly description?: string;
+  readonly authors?: readonly string[];
+  readonly local?: PulseFastlyLocalOptions;
+}
+
+export interface PulseFastlyProviderConfig {
+  readonly kind: 'fastly';
+  readonly version: typeof FASTLY_PROVIDER_API_VERSION;
+  readonly bindings: {
+    readonly configStore: string;
+    readonly secretStore: string;
+    readonly kv: Readonly<Record<string, string>>;
+    readonly backends: Readonly<Record<string, string>>;
+    readonly grip?: {
+      readonly fanoutBackend?: string;
+      readonly publishEndpoint?: string;
+      readonly publishUrl?: string;
+      readonly publishBackend?: string;
+      readonly authentication?: {
+        readonly scheme: 'bearer';
+        readonly secretRef: string;
+      };
+      readonly directHold: boolean;
+    };
+    readonly dynamicBackends: boolean;
+  };
+  readonly build: {
+    readonly name: string;
+    readonly description: string;
+    readonly authors: readonly string[];
+    readonly language: 'other';
+  };
+  readonly local: {
+    readonly networkFetch: boolean;
+  };
+  readonly providerSpecificUserland: false;
+}
+
+function stringMap(input: Readonly<Record<string, string>> | undefined): Readonly<Record<string, string>> {
+  return Object.freeze(Object.fromEntries(Object.entries(input ?? {}).map(([key, value]) => [String(key), String(value)])));
+}
+
+function gripAuthentication(input: PulseFastlyGripOptions['authentication'] | undefined): NonNullable<PulseFastlyProviderConfig['bindings']['grip']>['authentication'] {
+  if (input === undefined) return undefined;
+  const scheme = String(input.scheme ?? 'bearer').toLowerCase();
+  if (scheme !== 'bearer') throw new TypeError('fastly.grip.authentication.scheme must be bearer.');
+  return Object.freeze({
+    scheme: 'bearer' as const,
+    secretRef: String(input.secretRef),
+  });
+}
+
+function gripBindings(input: PulseFastlyGripOptions | undefined): NonNullable<PulseFastlyProviderConfig['bindings']['grip']> {
+  return Object.freeze({
+    fanoutBackend: input?.fanoutBackend === undefined ? undefined : String(input.fanoutBackend),
+    publishEndpoint: input?.publishEndpoint === undefined ? undefined : String(input.publishEndpoint),
+    publishUrl: input?.publishUrl === undefined ? undefined : String(input.publishUrl),
+    publishBackend: input?.publishBackend === undefined ? undefined : String(input.publishBackend),
+    authentication: gripAuthentication(input?.authentication),
+    directHold: input?.directHold === undefined ? Boolean(fastlyDefaults['fastly.grip.directHold']) : input.directHold !== false
+  });
+}
+
+export function fastly(options: PulseFastlyProviderOptions = {}): PulseFastlyProviderConfig {
+  const normalizedGrip = options.grip === undefined ? undefined : gripBindings(options.grip);
+  return Object.freeze({
+    kind: 'fastly',
+    version: FASTLY_PROVIDER_API_VERSION,
+    bindings: Object.freeze({
+      configStore: String(options.configStore ?? fastlyDefaults['fastly.configStore']),
+      secretStore: String(options.secretStore ?? fastlyDefaults['fastly.secretStore']),
+      kv: stringMap(options.kv),
+      backends: stringMap(options.backends),
+      ...(normalizedGrip ? { grip: normalizedGrip } : {}),
+      dynamicBackends: options.dynamicBackends === undefined ? Boolean(fastlyDefaults['fastly.dynamicBackends']) : options.dynamicBackends === true
+    }),
+    build: Object.freeze({
+      name: String(options.name ?? fastlyDefaults['fastly.name']),
+      description: String(options.description ?? fastlyDefaults['fastly.description']),
+      authors: Object.freeze((options.authors ?? (Array.isArray(fastlyDefaults['fastly.authors']) ? fastlyDefaults['fastly.authors'] : [])).map(String)),
+      language: 'other'
+    }),
+    local: Object.freeze({ networkFetch: Boolean(options.local?.networkFetch ?? fastlyDefaults['fastly.local.networkFetch']) }),
+    providerSpecificUserland: false
+  });
+}