@useairfoil/connector-kit 0.5.0 → 0.5.1

package/src/manifest/config.ts

@@ -0,0 +1,232 @@
+import { Config, Option, Redacted, Schema, Struct } from "effect";
+
+import { isPlatformRuntimeKey } from "../runtime-config/constants";
+import { makeNumberSchema, type NumberConstraints } from "./number-schema";
+
+type ConfigFieldSpecBase = {
+  readonly runtimeKey: string;
+  readonly required: boolean;
+  readonly description?: string;
+};
+
+type ConfigFieldDefinition = ConfigFieldSpecBase &
+  (
+    | {
+        readonly type: "string";
+        readonly secret: false;
+        readonly default?: string;
+        readonly values?: never;
+      }
+    | {
+        readonly type: "string";
+        readonly secret: true;
+        readonly default?: never;
+        readonly values?: never;
+      }
+    | {
+        readonly type: "number";
+        readonly secret: false;
+        readonly default?: number;
+        readonly values?: never;
+        readonly integer?: boolean;
+        readonly minimum?: number;
+      }
+    | {
+        readonly type: "boolean";
+        readonly secret: false;
+        readonly default?: boolean;
+        readonly values?: never;
+      }
+    | {
+        readonly type: "select";
+        readonly secret: false;
+        readonly default?: string;
+        readonly values: readonly [string, ...Array<string>];
+      }
+  );
+
+/** Serializable, browser-safe metadata for one user-provided connector setting. */
+export type ConfigFieldSpec = ConfigFieldDefinition & { readonly name: string };
+
+/** Pairs an Effect runtime config with the metadata used to generate its form field. */
+export type ConfigField<A> = {
+  readonly config: Config.Config<A>;
+  readonly spec: ConfigFieldDefinition;
+};
+
+type FieldBaseOptions = {
+  readonly runtimeKey: string;
+  readonly description?: string;
+};
+
+type FieldOptions<A extends string | number | boolean = string | number | boolean> =
+  FieldBaseOptions &
+    (
+      | {
+          readonly required?: true;
+          readonly default?: A;
+        }
+      | {
+          readonly required: false;
+          readonly default: A;
+        }
+    );
+
+type NumberFieldOptions = FieldOptions<number> & NumberConstraints;
+
+type FieldsRecord = Record<string, ConfigField<unknown>>;
+
+/** Preserves each field's value type while `Struct.map` extracts its Effect Config. */
+interface ConfigFieldToConfig extends Struct.Lambda {
+  <A>(field: ConfigField<A>): Config.Config<A>;
+  readonly "~lambda.out": this["~lambda.in"] extends ConfigField<infer A>
+    ? Config.Config<A>
+    : never;
+}
+
+const configFieldToConfig = Struct.lambda<ConfigFieldToConfig>((field) => field.config);
+
+type ConfigOf<Fields extends FieldsRecord> = {
+  readonly [Key in keyof Fields]: Fields[Key] extends ConfigField<infer A> ? A : never;
+};
+
+/** Effect config and serializable manifest metadata produced from one field definition. */
+export type ConnectorConfigDef<Fields extends FieldsRecord> = {
+  readonly fields: {
+    readonly [Key in keyof Fields]: Fields[Key] extends ConfigField<infer A>
+      ? Config.Config<A>
+      : never;
+  };
+  readonly config: Config.Config<ConfigOf<Fields>>;
+  readonly spec: ReadonlyArray<ConfigFieldSpec>;
+};
+
+export type ConfigValuesOf<Def extends ConnectorConfigDef<FieldsRecord>> =
+  Def extends ConnectorConfigDef<infer Fields> ? ConfigOf<Fields> : never;
+
+const withDefault = <A extends string | number | boolean>(
+  config: Config.Config<A>,
+  defaultValue: A | undefined,
+) => (defaultValue === undefined ? config : Config.withDefault(config, defaultValue));
+
+/** Defines a required non-empty string, optionally with a default. */
+export const string = (options: FieldOptions<string>): ConfigField<string> => ({
+  config: withDefault(Config.nonEmptyString(options.runtimeKey), options.default),
+  spec: {
+    runtimeKey: options.runtimeKey,
+    type: "string",
+    required: options.required ?? true,
+    secret: false,
+    ...(options.description !== undefined ? { description: options.description } : {}),
+    ...(options.default !== undefined ? { default: options.default } : {}),
+  },
+});
+
+/** Defines a finite number with optional integer, minimum, and default constraints. */
+export const number = (options: NumberFieldOptions): ConfigField<number> => {
+  const schema = makeNumberSchema(options);
+  const defaultValue =
+    options.default === undefined ? undefined : Schema.decodeUnknownSync(schema)(options.default);
+
+  return {
+    config: withDefault(Config.schema(schema, options.runtimeKey), defaultValue),
+    spec: {
+      runtimeKey: options.runtimeKey,
+      type: "number",
+      required: options.required ?? true,
+      secret: false,
+      ...(options.description !== undefined ? { description: options.description } : {}),
+      ...(defaultValue !== undefined ? { default: defaultValue } : {}),
+      ...(options.integer !== undefined ? { integer: options.integer } : {}),
+      ...(options.minimum !== undefined ? { minimum: options.minimum } : {}),
+    },
+  };
+};
+
+/** Defines a boolean, optionally with a default. */
+export const boolean = (options: FieldOptions<boolean>): ConfigField<boolean> => ({
+  config: withDefault(Config.boolean(options.runtimeKey), options.default),
+  spec: {
+    runtimeKey: options.runtimeKey,
+    type: "boolean",
+    required: options.required ?? true,
+    secret: false,
+    ...(options.description !== undefined ? { description: options.description } : {}),
+    ...(options.default !== undefined ? { default: options.default } : {}),
+  },
+});
+
+/** Defines a string literal choice whose values are preserved in the inferred type. */
+export const select = <const Values extends readonly [string, ...Array<string>]>(
+  options: FieldOptions<Values[number]> & { readonly values: Values },
+): ConfigField<Values[number]> => ({
+  config: withDefault(Config.literals(options.values, options.runtimeKey), options.default),
+  spec: {
+    runtimeKey: options.runtimeKey,
+    type: "select",
+    required: options.required ?? true,
+    secret: false,
+    values: options.values,
+    ...(options.description !== undefined ? { description: options.description } : {}),
+    ...(options.default !== undefined ? { default: options.default } : {}),
+  },
+});
+
+/** Defines a required, non-empty secret decoded as `Redacted<string>`. */
+export const secret = (
+  options: FieldBaseOptions & { readonly required?: true },
+): ConfigField<Redacted.Redacted<string>> => ({
+  config: Config.schema(Schema.Redacted(Schema.NonEmptyString), options.runtimeKey),
+  spec: {
+    runtimeKey: options.runtimeKey,
+    type: "string",
+    required: options.required ?? true,
+    secret: true,
+    ...(options.description !== undefined ? { description: options.description } : {}),
+  },
+});
+
+/** Makes an existing field optional and represents a missing value as `Option.none()`. */
+export const optional = <A>(field: ConfigField<A>): ConfigField<Option.Option<A>> => ({
+  config: Config.option(field.config),
+  spec: {
+    ...field.spec,
+    required: false,
+  },
+});
+
+/**
+ * Defines user-facing connector config once for both Effect runtime loading and
+ * frontend form generation. The object keys become logical form/API field names;
+ * `runtimeKey` remains the key read by Effect Config.
+ *
+ * @example
+ * ```ts
+ * const config = define({
+ *   apiUrl: string({ runtimeKey: "API_URL" }),
+ *   token: secret({ runtimeKey: "API_TOKEN" }),
+ * });
+ *
+ * const RuntimeConfig = config.config;
+ * const formFields = config.spec;
+ * ```
+ */
+export const define = <const Fields extends FieldsRecord>(
+  fields: Fields,
+): ConnectorConfigDef<Fields> => {
+  const spec = Object.entries(fields).map(([name, field]) => ({ name, ...field.spec }));
+  const platformField = spec.find((field) => isPlatformRuntimeKey(field.runtimeKey));
+  if (platformField !== undefined) {
+    throw new Error(`Connector runtime key is platform-owned: ${platformField.runtimeKey}`);
+  }
+
+  const configFields = Struct.map(fields, configFieldToConfig);
+
+  return {
+    fields: configFields,
+    // Effect's recursive Config.Wrap cannot reduce this generic mapped type,
+    // although ConfigFieldToConfig preserves the value type of every property.
+    config: Config.unwrap(configFields as Config.Wrap<ConfigOf<Fields>>),
+    spec,
+  };
+};

package/src/manifest/index.ts

@@ -0,0 +1,14 @@
+export {
+  boolean,
+  define as defineConfig,
+  number,
+  optional,
+  secret,
+  select,
+  string,
+} from "./config";
+export type { ConfigField, ConfigFieldSpec, ConfigValuesOf, ConnectorConfigDef } from "./config";
+export { define } from "./manifest";
+export type { ConnectorManifest, ResourceCapability } from "./manifest";
+export { configSchema, decodeConfig, toRuntimeDocument } from "./schema";
+export type { ConnectorConfigSchema, ConnectorConfigValues, RuntimeConfigDocument } from "./schema";

package/src/manifest/manifest.ts

@@ -0,0 +1,31 @@
+import type { ConfigFieldSpec } from "./config";
+
+export type ResourceCapability = "backfill" | "changes" | "webhook";
+
+/** Browser-safe connector metadata consumed by the platform and runtime adapters. */
+export type ConnectorManifest = {
+  readonly name: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly config: ReadonlyArray<ConfigFieldSpec>;
+  readonly resources: ReadonlyArray<{
+    readonly name: string;
+    readonly capabilities: ReadonlyArray<ResourceCapability>;
+  }>;
+};
+
+/**
+ * Defines browser-safe connector metadata while preserving literal names and capabilities.
+ *
+ * @example
+ * ```ts
+ * const manifest = define({
+ *   name: "producer-example",
+ *   title: "Example",
+ *   config: ExampleConfig.spec,
+ *   resources: [{ name: "orders", capabilities: ["backfill"] }],
+ * });
+ * ```
+ */
+export const define = <const Manifest extends ConnectorManifest>(manifest: Manifest): Manifest =>
+  manifest;

package/src/manifest/number-schema.ts

@@ -0,0 +1,17 @@
+import { Schema } from "effect";
+
+export type NumberConstraints = {
+  readonly integer?: boolean;
+  readonly minimum?: number;
+};
+
+export const makeNumberSchema = (constraints: NumberConstraints) => {
+  if (constraints.integer) {
+    return constraints.minimum === undefined
+      ? Schema.Int
+      : Schema.Int.check(Schema.isGreaterThanOrEqualTo(constraints.minimum));
+  }
+  return constraints.minimum === undefined
+    ? Schema.Finite
+    : Schema.Finite.check(Schema.isGreaterThanOrEqualTo(constraints.minimum));
+};

package/src/manifest/schema.ts

@@ -0,0 +1,160 @@
+import { Predicate, Schema, SchemaTransformation, type Types } from "effect";
+
+import type { ConfigFieldSpec } from "./config";
+import type { ConnectorManifest } from "./manifest";
+
+import { makeNumberSchema } from "./number-schema";
+
+type FieldValueOf<Field extends ConfigFieldSpec> = Field["type"] extends "number"
+  ? number
+  : Field["type"] extends "boolean"
+    ? boolean
+    : Field["values"] extends ReadonlyArray<string>
+      ? Field["values"][number]
+      : string;
+
+export type ConnectorConfigValues<Manifest extends ConnectorManifest> = Types.Simplify<
+  {
+    readonly [Field in Manifest["config"][number] as Field["required"] extends true
+      ? Field["name"]
+      : never]: FieldValueOf<Field>;
+  } & {
+    readonly [Field in Manifest["config"][number] as Field["required"] extends true
+      ? never
+      : Field["name"]]?: FieldValueOf<Field> | undefined;
+  }
+> &
+  object;
+
+export type ConnectorConfigSchema<Manifest extends ConnectorManifest> = Schema.Codec<
+  ConnectorConfigValues<Manifest>,
+  unknown
+>;
+
+/** Flat primitive document keyed by the runtime keys consumed by Effect Config. */
+export type RuntimeConfigDocument = Readonly<Record<string, string | number | boolean>>;
+
+// Browser forms submit numbers and booleans as strings, while API callers may
+// already send their canonical JSON representations. These schemas accept both.
+const numberFromForm = (field: Extract<ConfigFieldSpec, { readonly type: "number" }>) => {
+  const numberSchema = makeNumberSchema(field);
+  return Schema.Union([
+    numberSchema,
+    Schema.NonEmptyString.pipe(
+      Schema.decodeTo(numberSchema, SchemaTransformation.numberFromString),
+    ),
+  ]);
+};
+
+const BooleanFromForm = Schema.Union([
+  Schema.Boolean,
+  Schema.Literals(["true", "false"]).pipe(
+    Schema.decodeTo(
+      Schema.Boolean,
+      SchemaTransformation.transform({
+        decode: (value) => value === "true",
+        encode: (value) => (value ? "true" : "false"),
+      }),
+    ),
+  ),
+]);
+
+// An empty optional form control means "not supplied", not an empty config value.
+const EmptyStringAsUndefined = Schema.Literal("").pipe(
+  Schema.decodeTo(
+    Schema.Undefined,
+    SchemaTransformation.transform({ decode: () => undefined, encode: () => "" }),
+  ),
+);
+
+const baseFieldSchema = (field: ConfigFieldSpec): Schema.Codec<unknown, unknown> => {
+  switch (field.type) {
+    case "number":
+      return numberFromForm(field);
+    case "boolean":
+      return BooleanFromForm;
+    case "select":
+      return Schema.Literals(field.values);
+    case "string":
+      return Schema.NonEmptyString;
+  }
+};
+
+const fieldSchema = (field: ConfigFieldSpec) =>
+  field.required
+    ? baseFieldSchema(field)
+    : Schema.optional(Schema.Union([EmptyStringAsUndefined, baseFieldSchema(field)]));
+
+/**
+ * Builds an Effect Schema for logical form/API values from a connector manifest.
+ *
+ * @example
+ * ```ts
+ * const decode = Schema.decodeUnknownEffect(configSchema(manifest));
+ * const values = decode({
+ *   apiUrl: "https://example.com",
+ *   retries: "3",
+ * });
+ * ```
+ */
+export const configSchema = <const Manifest extends ConnectorManifest>(
+  manifest: Manifest,
+): ConnectorConfigSchema<Manifest> => {
+  const fields = Object.fromEntries(
+    manifest.config.map((field) => [field.name, fieldSchema(field)]),
+  );
+  // Object.fromEntries cannot retain keys discovered from the runtime manifest;
+  // the public mapped type restores the same relationship for callers.
+  return Schema.Struct(fields) as unknown as ConnectorConfigSchema<Manifest>;
+};
+
+/** Decodes browser/API config, applies manifest defaults, and rejects undeclared fields. */
+export const decodeConfig = <const Manifest extends ConnectorManifest>(
+  manifest: Manifest,
+  input: unknown,
+) => {
+  const defaults = Object.fromEntries(
+    manifest.config.flatMap((field) =>
+      field.default === undefined ? [] : [[field.name, field.default]],
+    ),
+  );
+  const optionalFields = new Set(
+    manifest.config.flatMap((field) => (field.required ? [] : [field.name])),
+  );
+  const normalizedInput = Predicate.isObject(input)
+    ? Object.fromEntries(
+        Object.entries(input).filter(([name, value]) => value !== "" || !optionalFields.has(name)),
+      )
+    : input;
+  const inputWithDefaults = Predicate.isObject(normalizedInput)
+    ? Object.assign({}, defaults, normalizedInput)
+    : normalizedInput;
+
+  return Schema.decodeUnknownEffect(configSchema(manifest))(inputWithDefaults, {
+    onExcessProperty: "error",
+  });
+};
+
+/**
+ * Maps validated logical values to the flat runtime-key document mounted in a pod.
+ * Missing optional values are omitted.
+ *
+ * @example
+ * ```ts
+ * toRuntimeDocument(manifest, { apiUrl: "https://example.com" });
+ * // { API_URL: "https://example.com" }
+ * ```
+ */
+export const toRuntimeDocument = <const Manifest extends ConnectorManifest>(
+  manifest: Manifest,
+  values: ConnectorConfigValues<Manifest>,
+): RuntimeConfigDocument => {
+  const document: Record<string, string | number | boolean> = {};
+  for (const field of manifest.config) {
+    const value: unknown = Reflect.get(values, field.name);
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      document[field.runtimeKey] = value;
+    }
+  }
+  return document;
+};

package/src/metrics.ts

@@ -0,0 +1,128 @@
+import { DateTime, Effect, Metric, Option } from "effect";
+
+import type { SyncState } from "./core/types";
+
+export type BatchSource = "backfill" | "changes" | "webhook";
+export type BatchOutcome = "accepted" | "rejected" | "error";
+export type ApiRetryReason = "transport" | "timeout" | "rate_limit" | "server_error";
+export type WebhookOutcome =
+  | "ok"
+  | "read_error"
+  | "invalid_json"
+  | "invalid_payload"
+  | "rejected"
+  | "handler_error";
+
+export type ResourceMetricAttrs = {
+  readonly connector: string;
+  readonly resource: string;
+  readonly source: BatchSource;
+};
+
+export type WebhookMetricAttrs = {
+  readonly connector: string;
+  readonly path: string;
+  readonly outcome: WebhookOutcome;
+};
+
+export type SyncStateAttrs = {
+  readonly connector: string;
+  readonly resource: string;
+};
+
+export type LastSuccessMetricAttrs = {
+  readonly connector: string;
+  readonly resource: string;
+  readonly source: "backfill" | "changes";
+};
+
+export type ApiRetryMetricAttrs = {
+  readonly connector: string;
+  readonly reason: ApiRetryReason;
+};
+
+export const entitiesUpsertedTotal = Metric.counter("airfoil_connector_entities_upserted_total", {
+  description: "Total entity upsert mutations published by connector sources",
+  incremental: true,
+});
+
+export const entitiesDeletedTotal = Metric.counter("airfoil_connector_entities_deleted_total", {
+  description: "Total entity delete mutations published by connector sources",
+  incremental: true,
+});
+
+export const batchesTotal = Metric.counter("airfoil_connector_batches_total", {
+  description: "Total resource batches published by connector sources",
+  incremental: true,
+});
+
+export const batchSize = Metric.histogram("airfoil_connector_batch_size", {
+  description: "Distribution of resource mutation batch sizes",
+  boundaries: [1, 5, 10, 25, 50, 100, 250, 500, 1000],
+});
+
+export const publishDuration = Metric.timer("airfoil_connector_publish_duration_ms", {
+  description: "Publisher call duration in milliseconds",
+  boundaries: [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000],
+});
+
+export const webhookRequestsTotal = Metric.counter("airfoil_connector_webhook_requests_total", {
+  description: "Total webhook HTTP requests handled by connector routes",
+  incremental: true,
+});
+
+export const webhookQueueDepth = Metric.gauge("airfoil_connector_webhook_queue_depth", {
+  description: "Current queued webhook batches waiting for publish",
+});
+
+export const syncState = Metric.gauge("airfoil_connector_sync_state", {
+  description: "Connector resource sync state as a Prometheus state-set gauge",
+});
+
+export const lastSuccessTimestamp = Metric.gauge(
+  "airfoil_connector_last_success_timestamp_seconds",
+  {
+    description: "Unix timestamp of the last successful durable source checkpoint",
+  },
+);
+
+export const apiRetriesTotal = Metric.counter("airfoil_connector_api_retries_total", {
+  description: "Total provider API retries performed by the connector",
+  incremental: true,
+});
+
+export const recordWebhookRequest = (attrs: WebhookMetricAttrs) =>
+  Metric.update(Metric.withAttributes(webhookRequestsTotal, attrs), 1);
+
+export const setWebhookQueueDepth = (connector: string, depth: number) =>
+  Metric.update(Metric.withAttributes(webhookQueueDepth, { connector }), depth);
+
+export const setLastSuccessTimestamp = (attrs: LastSuccessMetricAttrs, lastSuccessAt?: string) => {
+  const timestamp =
+    lastSuccessAt === undefined
+      ? 0
+      : DateTime.make(lastSuccessAt).pipe(
+          Option.map((dateTime) => DateTime.toEpochMillis(dateTime) / 1000),
+          Option.getOrElse(() => 0),
+        );
+  return Metric.update(Metric.withAttributes(lastSuccessTimestamp, attrs), timestamp);
+};
+
+export const recordApiRetry = (attrs: ApiRetryMetricAttrs) =>
+  Metric.update(Metric.withAttributes(apiRetriesTotal, attrs), 1);
+
+const syncStates = ["pending", "backfilling", "live", "error"] as const;
+
+export const setSyncState = (attrs: SyncStateAttrs, current: SyncState) =>
+  Effect.forEach(
+    syncStates,
+    (state) =>
+      Metric.update(
+        Metric.withAttributes(syncState, {
+          ...attrs,
+          state,
+        }),
+        state === current ? 1 : 0,
+      ),
+    { discard: true },
+  );

package/src/publisher/instrumented.ts

@@ -0,0 +1,68 @@
+import { Effect, Metric } from "effect";
+
+import type { ResourceBatch } from "../core/types";
+
+import { ConnectorError } from "../errors";
+import * as Metrics from "../metrics";
+import { Attr, EventAttr, EventName, addCurrentSpanEvent } from "../telemetry";
+import { Publisher, type PublishSource } from "./service";
+
+export const publishBatch = Effect.fnUntraced(function* (options: {
+  readonly connector?: string;
+  readonly resource: string;
+  readonly source: PublishSource;
+  readonly batch: ResourceBatch;
+}) {
+  const metric = {
+    connector: options.connector ?? "unknown",
+    resource: options.resource,
+    source: options.source,
+  };
+  const upserts = options.batch.mutations.filter((mutation) => mutation.op === "upsert").length;
+  const deletes = options.batch.mutations.length - upserts;
+
+  const publisher = yield* Publisher;
+  const [duration, ack] = yield* Effect.timed(
+    publisher.publish({
+      resource: options.resource,
+      source: options.source,
+      batch: options.batch,
+    }),
+  ).pipe(
+    Effect.catchCause((cause) =>
+      Metric.update(
+        Metric.withAttributes(Metrics.batchesTotal, { ...metric, outcome: "error" }),
+        1,
+      ).pipe(Effect.andThen(Effect.failCause(cause))),
+    ),
+  );
+
+  yield* Metric.update(Metric.withAttributes(Metrics.publishDuration, metric), duration);
+  yield* Metric.update(
+    Metric.withAttributes(Metrics.batchesTotal, { ...metric, outcome: ack.status }),
+    1,
+  );
+
+  yield* Effect.annotateCurrentSpan({ [Attr.publisherSuccess]: ack.status === "accepted" });
+  if (ack.status === "rejected") {
+    yield* Effect.annotateCurrentSpan({ [Attr.errorPhase]: "publish" });
+    return yield* Effect.fail(
+      new ConnectorError({
+        message: `Publisher rejected batch for ${options.resource}: ${ack.reason}`,
+      }),
+    );
+  }
+
+  yield* Metric.update(Metric.withAttributes(Metrics.entitiesUpsertedTotal, metric), upserts);
+  yield* Metric.update(Metric.withAttributes(Metrics.entitiesDeletedTotal, metric), deletes);
+  yield* Metric.update(
+    Metric.withAttributes(Metrics.batchSize, metric),
+    options.batch.mutations.length,
+  );
+
+  if (options.batch.cursor !== undefined) {
+    yield* addCurrentSpanEvent(EventName.batchCheckpoint, {
+      [EventAttr.batchCursor]: options.batch.cursor,
+    });
+  }
+});

package/src/runtime-config/constants.ts

@@ -0,0 +1,27 @@
+import { HashSet } from "effect";
+
+/** Shared runtime keys owned by Airfoil rather than an individual connector. */
+export const PlatformRuntimeKey = {
+  configPath: "AIRFOIL_CONFIG_PATH",
+  connectorInstanceId: "AIRFOIL_CONNECTOR_INSTANCE_ID",
+  stateTable: "AIRFOIL_STATE_TABLE",
+  postgresConnectionString: "POSTGRES_CONNECTION_STRING",
+  wingsHost: "WINGS_HOST",
+  wingsNamespace: "WINGS_NAMESPACE",
+  otelEnabled: "OTEL_ENABLED",
+  otelExporterOtlpEndpoint: "OTEL_EXPORTER_OTLP_ENDPOINT",
+  otelExporterOtlpHeaders: "OTEL_EXPORTER_OTLP_HEADERS",
+  otelServiceName: "OTEL_SERVICE_NAME",
+  otelServiceVersion: "OTEL_SERVICE_VERSION",
+  otelResourceAttributes: "OTEL_RESOURCE_ATTRIBUTES",
+} as const;
+
+/** Defaults for optional platform-owned runtime configuration. */
+export const PlatformRuntimeDefault = {
+  stateTable: "_airfoil_connectors_state",
+} as const;
+
+const platformRuntimeKeys = HashSet.fromIterable(Object.values(PlatformRuntimeKey));
+
+/** @internal */
+export const isPlatformRuntimeKey = (key: string): boolean => HashSet.has(platformRuntimeKeys, key);

package/src/runtime-config/error.ts

@@ -0,0 +1,13 @@
+import { Data } from "effect";
+
+export type RuntimeConfigErrorCode =
+  | "CONFIG_PATH_MISSING"
+  | "CONFIG_FILE_UNREADABLE"
+  | "CONFIG_JSON_INVALID";
+
+/** Expected hosted-config failure with a stable code and diagnostic cause. */
+export class RuntimeConfigError extends Data.TaggedError("RuntimeConfigError")<{
+  readonly code: RuntimeConfigErrorCode;
+  readonly message: string;
+  readonly cause: Error;
+}> {}