@relkit/app 0.5.0 → 0.5.3

package/dist/app-config.types.d.ts

@@ -0,0 +1,32 @@
+/** API documentation visibility and domain exclusions.
+ * @example const docs: ApiDocsConfig = { enabledInProduction: false };
+ */
+export interface ApiDocsConfig {
+    readonly enabledInProduction?: boolean;
+    readonly excludeDomains?: readonly string[];
+}
+/** HTTP server settings attached to an application descriptor.
+ * @example const server: ServerConfig = { port: 3000, apiDocs: { enabledInProduction: false } };
+ */
+export interface ServerConfig {
+    readonly port?: number;
+    readonly maxBodyBytes?: number;
+    readonly apiDocs?: ApiDocsConfig;
+    readonly clientContract?: boolean;
+    readonly mcp?: boolean;
+}
+/** Inspector settings attached to an application descriptor.
+ * @example const inspector: InspectorConfig = { port: 3210 };
+ */
+export interface InspectorConfig {
+    readonly port?: number;
+    readonly enabledInProduction?: boolean;
+    readonly maxPreviewBytes?: number;
+}
+/** Transitional compatibility switches for application authoring.
+ * @example const compatibility: AppCompatibilityConfig = { legacyJobs: true };
+ */
+export interface AppCompatibilityConfig {
+    readonly legacyJobs?: boolean;
+}
+//# sourceMappingURL=app-config.types.d.ts.map

package/dist/app-config.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-config.types.d.ts","sourceRoot":"","sources":["../src/app-config.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B"}

package/dist/app-config.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=app-config.types.js.map

package/dist/app-config.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-config.types.js","sourceRoot":"","sources":["../src/app-config.types.ts"],"names":[],"mappings":""}

package/dist/app-observability.d.ts

@@ -0,0 +1,21 @@
+import { Context, Effect, Layer } from "effect";
+import type { AppOperation, AppTelemetryService } from "./app-observability.types.js";
+declare const AppTelemetry_base: Context.ServiceClass<AppTelemetry, "relkit/app/AppTelemetry", AppTelemetryService>;
+/** Injectable observer for application authoring operations.
+ * @example Effect.provide(defineAppEffect(options), AppTelemetryLive);
+ */
+export declare class AppTelemetry extends AppTelemetry_base {
+}
+/** Live spans, counts, failures, and durations for application operations.
+ * @example Effect.provide(defineAppEffect(options), AppTelemetryLive);
+ */
+export declare const AppTelemetryLive: Layer.Layer<AppTelemetry, never, never>;
+/** Applies an injected observer or the live observer to one operation.
+ * @param operation - Fixed operation label.
+ * @param effect - Operation to measure.
+ * @returns The observed Effect, retaining success, error, and requirements.
+ * @example observeApp("define", Effect.succeed(app));
+ */
+export declare function observeApp<A, E, R>(operation: AppOperation, effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>;
+export {};
+//# sourceMappingURL=app-observability.d.ts.map

package/dist/app-observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-observability.d.ts","sourceRoot":"","sources":["../src/app-observability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,OAAO,EAAE,MAAM,EAAQ,KAAK,EAAkB,MAAM,QAAQ,CAAC;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;;AAEtF;;GAEG;AACH,qBAAa,YAAa,SAAQ,iBAEjC;CAAG;AAEJ;;GAEG;AACH,eAAO,MAAM,gBAAgB,yCAAwD,CAAC;AAQtF;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAChC,SAAS,EAAE,YAAY,EACvB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAMxB"}

package/dist/app-observability.js

@@ -0,0 +1,41 @@
+import { Clock, Context, Effect, Exit, Layer, Metric, Option } from "effect";
+/** Injectable observer for application authoring operations.
+ * @example Effect.provide(defineAppEffect(options), AppTelemetryLive);
+ */
+export class AppTelemetry extends Context.Service()("relkit/app/AppTelemetry") {
+}
+/** Live spans, counts, failures, and durations for application operations.
+ * @example Effect.provide(defineAppEffect(options), AppTelemetryLive);
+ */
+export const AppTelemetryLive = Layer.succeed(AppTelemetry, { observe: observeLive });
+const calls = Metric.counter("relkit_app_operations_total", { incremental: true });
+const failures = Metric.counter("relkit_app_failures_total", { incremental: true });
+const duration = Metric.histogram("relkit_app_duration_ms", {
+    boundaries: [0.01, 0.1, 1, 5, 10, 50, 100],
+});
+/** Applies an injected observer or the live observer to one operation.
+ * @param operation - Fixed operation label.
+ * @param effect - Operation to measure.
+ * @returns The observed Effect, retaining success, error, and requirements.
+ * @example observeApp("define", Effect.succeed(app));
+ */
+export function observeApp(operation, effect) {
+    return Effect.flatMap(Effect.serviceOption(AppTelemetry), (service) => Option.isSome(service)
+        ? service.value.observe(operation, effect)
+        : observeLive(operation, effect));
+}
+/** Records one duration on every exit, including interruption and defects. */
+function observeLive(operation, effect) {
+    const attributes = { operation };
+    return Effect.withSpan(Effect.gen(function* () {
+        const started = yield* Clock.monotonicTimeNanos;
+        yield* Metric.update(Metric.withAttributes(calls, attributes), 1);
+        return yield* Effect.onExit(effect, (exit) => Effect.gen(function* () {
+            const elapsed = Number((yield* Clock.monotonicTimeNanos) - started) / 1_000_000;
+            yield* Metric.update(Metric.withAttributes(duration, attributes), Math.max(0, elapsed));
+            if (Exit.isFailure(exit))
+                yield* Metric.update(Metric.withAttributes(failures, attributes), 1);
+        }));
+    }), `app.${operation}`);
+}
+//# sourceMappingURL=app-observability.js.map

package/dist/app-observability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-observability.js","sourceRoot":"","sources":["../src/app-observability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAG7E;;GAEG;AACH,MAAM,OAAO,YAAa,SAAQ,OAAO,CAAC,OAAO,EAAqC,CACpF,yBAAyB,CAC1B;CAAG;AAEJ;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;AAEtF,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,6BAA6B,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;AACnF,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,2BAA2B,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;AACpF,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,wBAAwB,EAAE;IAC1D,UAAU,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC;CAC3C,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CACxB,SAAuB,EACvB,MAA8B;IAE9B,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CACpE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC;QACpB,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC;QAC1C,CAAC,CAAC,WAAW,CAAC,SAAS,EAAE,MAAM,CAAC,CACnC,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,SAAS,WAAW,CAClB,SAAuB,EACvB,MAA8B;IAE9B,MAAM,UAAU,GAAG,EAAE,SAAS,EAAE,CAAC;IACjC,OAAO,MAAM,CAAC,QAAQ,CACpB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QAClB,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC;QAChD,KAAK,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;QAClE,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAC3C,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;YAClB,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC,GAAG,OAAO,CAAC,GAAG,SAAS,CAAC;YAChF,KAAK,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;YACxF,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;gBACtB,KAAK,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;QACzE,CAAC,CAAC,CACH,CAAC;IACJ,CAAC,CAAC,EACF,OAAO,SAAS,EAAE,CACnB,CAAC;AACJ,CAAC"}

package/dist/app-observability.types.d.ts

@@ -0,0 +1,18 @@
+import type { Effect } from "effect";
+/** Fixed operation labels used for application authoring telemetry.
+ * @example const operation: AppOperation = "define";
+ */
+export type AppOperation = "define" | "env.isDefinition" | "id.derive" | "compatibility.normalize" | "alias.assertExclusive" | "constants.define" | "prompt.define" | "context.create" | "context.resolve";
+/** A replaceable observer for application authoring operations.
+ * @example const observer: AppTelemetryService = { observe: (_name, effect) => effect };
+ */
+export interface AppTelemetryService {
+    /** Surrounds one operation without changing its result.
+     * @param operation - A fixed operation label.
+     * @param effect - The operation to observe.
+     * @returns The observed Effect with its success and error channels intact.
+     * @example observer.observe("define", Effect.succeed(app));
+     */
+    readonly observe: <A, E, R>(operation: AppOperation, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+}
+//# sourceMappingURL=app-observability.types.d.ts.map

package/dist/app-observability.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-observability.types.d.ts","sourceRoot":"","sources":["../src/app-observability.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAErC;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,kBAAkB,GAClB,WAAW,GACX,yBAAyB,GACzB,uBAAuB,GACvB,kBAAkB,GAClB,eAAe,GACf,gBAAgB,GAChB,iBAAiB,CAAC;AAEtB;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACxB,SAAS,EAAE,YAAY,EACvB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC3B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAC7B"}

package/dist/app-observability.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=app-observability.types.js.map

package/dist/app-observability.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-observability.types.js","sourceRoot":"","sources":["../src/app-observability.types.ts"],"names":[],"mappings":""}

package/dist/app-provider-capabilities.d.ts

@@ -0,0 +1,3 @@
+/** Provider capabilities accepted by application descriptors. */
+export declare const APP_PROVIDER_CAPABILITIES: readonly ["bucket", "cache", "job", "event", "model", "realtime", "agent-state"];
+//# sourceMappingURL=app-provider-capabilities.d.ts.map

package/dist/app-provider-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-provider-capabilities.d.ts","sourceRoot":"","sources":["../src/app-provider-capabilities.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,eAAO,MAAM,yBAAyB,kFAQ5B,CAAC"}

package/dist/{define-app-types.js → app-provider-capabilities.js}

@@ -1,3 +1,4 @@
+/** Provider capabilities accepted by application descriptors. */
 export const APP_PROVIDER_CAPABILITIES = [
     "bucket",
     "cache",
@@ -7,4 +8,4 @@ export const APP_PROVIDER_CAPABILITIES = [
     "realtime",
     "agent-state",
 ];
-//# sourceMappingURL=define-app-types.js.map
+//# sourceMappingURL=app-provider-capabilities.js.map

package/dist/app-provider-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-provider-capabilities.js","sourceRoot":"","sources":["../src/app-provider-capabilities.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,QAAQ;IACR,OAAO;IACP,KAAK;IACL,OAAO;IACP,OAAO;IACP,UAAU;IACV,aAAa;CACL,CAAC"}

package/dist/app-provider-normalization.d.ts

@@ -0,0 +1,32 @@
+import { Effect } from "effect";
+import { AppValidationFailure } from "./app-validation.js";
+import type { AppProviderDefaults, AppProviderInputs } from "./define-app.types.js";
+import type { NormalizedProviderProfiles, ProviderSourceInput } from "@relkit/provider";
+/** Normalizes configured provider profiles in capability order.
+ * @param options - Authored provider bindings.
+ * @returns Normalized profiles or AppValidationFailure.
+ * @example Effect.runSync(normalizeProvidersEffect({}));
+ */
+export declare const normalizeProvidersEffect: (options: AppProviderInputs) => Effect.Effect<Partial<Record<"model" | "event" | "bucket" | "cache" | "job" | "realtime" | "agent-state", NormalizedProviderProfiles<import("@relkit/provider").ProviderAdapter>>>, AppValidationFailure, never>;
+/** Checks default profile selections and returns an immutable copy.
+ * @param providers - Normalized available provider profiles.
+ * @param defaults - Optional selected profile names.
+ * @returns Frozen defaults or AppValidationFailure.
+ * @example Effect.runSync(normalizeDefaultsEffect({}, undefined));
+ */
+export declare const normalizeDefaultsEffect: <Providers extends AppProviderInputs>(providers: Partial<Record<"model" | "event" | "bucket" | "cache" | "job" | "realtime" | "agent-state", NormalizedProviderProfiles<import("@relkit/provider").ProviderAdapter>>>, defaults: AppProviderDefaults<Providers> | undefined) => Effect.Effect<Readonly<{
+    model?: ["model" extends infer T ? T extends "model" ? T extends keyof Providers ? NonNullable<Providers[T]> : never : never : never] extends [never] ? never : ("model" extends infer T_1 ? T_1 extends "model" ? T_1 extends keyof Providers ? NonNullable<Providers[T_1]> : never : never : never) extends infer T_2 ? T_2 extends ("model" extends infer T_3 ? T_3 extends "model" ? T_3 extends keyof Providers ? NonNullable<Providers[T_3]> : never : never : never) ? T_2 extends ProviderSourceInput ? "default" : Extract<keyof T_2, string> : never : never;
+    event?: ["event" extends infer T_4 ? T_4 extends "event" ? T_4 extends keyof Providers ? NonNullable<Providers[T_4]> : never : never : never] extends [never] ? never : ("event" extends infer T_5 ? T_5 extends "event" ? T_5 extends keyof Providers ? NonNullable<Providers[T_5]> : never : never : never) extends infer T_6 ? T_6 extends ("event" extends infer T_7 ? T_7 extends "event" ? T_7 extends keyof Providers ? NonNullable<Providers[T_7]> : never : never : never) ? T_6 extends ProviderSourceInput ? "default" : Extract<keyof T_6, string> : never : never;
+    bucket?: ["bucket" extends infer T_8 ? T_8 extends "bucket" ? T_8 extends keyof Providers ? NonNullable<Providers[T_8]> : never : never : never] extends [never] ? never : ("bucket" extends infer T_9 ? T_9 extends "bucket" ? T_9 extends keyof Providers ? NonNullable<Providers[T_9]> : never : never : never) extends infer T_10 ? T_10 extends ("bucket" extends infer T_11 ? T_11 extends "bucket" ? T_11 extends keyof Providers ? NonNullable<Providers[T_11]> : never : never : never) ? T_10 extends ProviderSourceInput ? "default" : Extract<keyof T_10, string> : never : never;
+    cache?: ["cache" extends infer T_12 ? T_12 extends "cache" ? T_12 extends keyof Providers ? NonNullable<Providers[T_12]> : never : never : never] extends [never] ? never : ("cache" extends infer T_13 ? T_13 extends "cache" ? T_13 extends keyof Providers ? NonNullable<Providers[T_13]> : never : never : never) extends infer T_14 ? T_14 extends ("cache" extends infer T_15 ? T_15 extends "cache" ? T_15 extends keyof Providers ? NonNullable<Providers[T_15]> : never : never : never) ? T_14 extends ProviderSourceInput ? "default" : Extract<keyof T_14, string> : never : never;
+    job?: ["jobs" extends keyof Providers ? NonNullable<Providers[keyof Providers & "jobs"]> : "job" extends keyof Providers ? NonNullable<Providers[keyof Providers & "job"]> : never] extends [never] ? never : ("jobs" extends keyof Providers ? NonNullable<Providers[keyof Providers & "jobs"]> : "job" extends keyof Providers ? NonNullable<Providers[keyof Providers & "job"]> : never) extends infer T_16 ? T_16 extends ("jobs" extends keyof Providers ? NonNullable<Providers[keyof Providers & "jobs"]> : "job" extends keyof Providers ? NonNullable<Providers[keyof Providers & "job"]> : never) ? T_16 extends ProviderSourceInput ? "default" : Extract<keyof T_16, string> : never : never;
+    realtime?: ["realtime" extends infer T_17 ? T_17 extends "realtime" ? T_17 extends keyof Providers ? NonNullable<Providers[T_17]> : never : never : never] extends [never] ? never : ("realtime" extends infer T_18 ? T_18 extends "realtime" ? T_18 extends keyof Providers ? NonNullable<Providers[T_18]> : never : never : never) extends infer T_19 ? T_19 extends ("realtime" extends infer T_20 ? T_20 extends "realtime" ? T_20 extends keyof Providers ? NonNullable<Providers[T_20]> : never : never : never) ? T_19 extends ProviderSourceInput ? "default" : Extract<keyof T_19, string> : never : never;
+    "agent-state"?: ["agent-state" extends infer T_21 ? T_21 extends "agent-state" ? T_21 extends keyof Providers ? NonNullable<Providers[T_21]> : never : never : never] extends [never] ? never : ("agent-state" extends infer T_22 ? T_22 extends "agent-state" ? T_22 extends keyof Providers ? NonNullable<Providers[T_22]> : never : never : never) extends infer T_23 ? T_23 extends ("agent-state" extends infer T_24 ? T_24 extends "agent-state" ? T_24 extends keyof Providers ? NonNullable<Providers[T_24]> : never : never : never) ? T_23 extends ProviderSourceInput ? "default" : Extract<keyof T_23, string> : never : never;
+}>, AppValidationFailure, never>;
+/** Copies a serializable configuration value through RELKIT's serializer.
+ * @param value - Configuration value to copy.
+ * @returns A JSON copy or AppValidationFailure.
+ * @example Effect.runSync(copyEffect({ port: 3000 }));
+ */
+export declare const copyEffect: <Value>(value: Value) => Effect.Effect<Value, AppValidationFailure, never>;
+//# sourceMappingURL=app-provider-normalization.d.ts.map

package/dist/app-provider-normalization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-provider-normalization.d.ts","sourceRoot":"","sources":["../src/app-provider-normalization.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGhC,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAEV,mBAAmB,EACnB,iBAAiB,EAElB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAExF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,kPAkBpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GACjC,SAAS,SAAS,iBAAiB;;;;;;;;gCAqBrC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAA0B,KAAK,oEAKrD,CAAC"}

package/dist/app-provider-normalization.js

@@ -0,0 +1,58 @@
+import { serializeJson } from "@relkit/contracts";
+import { Effect } from "effect";
+import { defineProviderCapability, normalizeProviderProfiles } from "@relkit/provider";
+import { APP_PROVIDER_CAPABILITIES } from "./app-provider-capabilities.js";
+import { AppValidationFailure } from "./app-validation.js";
+/** Normalizes configured provider profiles in capability order.
+ * @param options - Authored provider bindings.
+ * @returns Normalized profiles or AppValidationFailure.
+ * @example Effect.runSync(normalizeProvidersEffect({}));
+ */
+export const normalizeProvidersEffect = Effect.fn("App.normalizeProviders")((options) => Effect.gen(function* () {
+    const result = {};
+    for (const capability of APP_PROVIDER_CAPABILITIES) {
+        const input = capability === "job" ? (options.jobs ?? options.job) : options[capability];
+        if (input !== undefined)
+            result[capability] = yield* Effect.try({
+                try: () => normalizeProviderProfiles(defineProviderCapability(capability), input),
+                catch: failure,
+            });
+    }
+    return result;
+}));
+/** Checks default profile selections and returns an immutable copy.
+ * @param providers - Normalized available provider profiles.
+ * @param defaults - Optional selected profile names.
+ * @returns Frozen defaults or AppValidationFailure.
+ * @example Effect.runSync(normalizeDefaultsEffect({}, undefined));
+ */
+export const normalizeDefaultsEffect = Effect.fn("App.normalizeDefaults")((providers, defaults) => Effect.gen(function* () {
+    const result = {};
+    for (const [rawCapability, selected] of Object.entries(defaults ?? {})) {
+        const capability = rawCapability === "jobs" ? "job" : rawCapability;
+        if (!APP_PROVIDER_CAPABILITIES.includes(capability))
+            return yield* Effect.fail(failure(new TypeError(`Unknown default capability "${capability}"`)));
+        const profiles = providers[capability]?.profiles;
+        if (typeof selected !== "string" || profiles?.[selected] === undefined)
+            return yield* Effect.fail(failure(new TypeError(`defaults.${capability} must reference a configured profile`)));
+        result[capability] = selected;
+    }
+    return (yield* copyEffect(result));
+}));
+/** Copies a serializable configuration value through RELKIT's serializer.
+ * @param value - Configuration value to copy.
+ * @returns A JSON copy or AppValidationFailure.
+ * @example Effect.runSync(copyEffect({ port: 3000 }));
+ */
+export const copyEffect = Effect.fn("App.copy")((value) => Effect.try({
+    try: () => JSON.parse(serializeJson(value)),
+    catch: failure,
+}));
+/** Keeps original errors available to compatibility adapters. */
+function failure(cause) {
+    return new AppValidationFailure({
+        message: cause instanceof Error ? cause.message : String(cause),
+        cause,
+    });
+}
+//# sourceMappingURL=app-provider-normalization.js.map

package/dist/app-provider-normalization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-provider-normalization.js","sourceRoot":"","sources":["../src/app-provider-normalization.ts"],"names":[],"mappings":"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"}

package/dist/{define-app-types.d.ts → app-provider.types.d.ts}

@@ -1,29 +1,13 @@
-import type { EnvDefinition, EnvShape } from "@relkit/config";
-import type { DescriptorBase, DescriptorMetadata, JsonValue } from "@relkit/contracts";
-import type { TelemetryConfiguration, TelemetryExporterMap } from "@relkit/observability/telemetry";
 import type { NormalizedProviderProfiles, ProviderAdapter, ProviderCapability, ProviderInput, ProviderSourceInput } from "@relkit/provider";
-export interface ApiDocsConfig {
-    readonly enabledInProduction?: boolean;
-    readonly excludeDomains?: readonly string[];
-}
-export interface ServerConfig {
-    readonly port?: number;
-    readonly maxBodyBytes?: number;
-    readonly apiDocs?: ApiDocsConfig;
-    readonly clientContract?: boolean;
-    readonly mcp?: boolean;
-}
-export interface InspectorConfig {
-    readonly port?: number;
-    readonly enabledInProduction?: boolean;
-    readonly maxPreviewBytes?: number;
-}
-export interface AppCompatibilityConfig {
-    readonly legacyJobs?: boolean;
-}
-export declare const APP_PROVIDER_CAPABILITIES: readonly ["bucket", "cache", "job", "event", "model", "realtime", "agent-state"];
+import type { APP_PROVIDER_CAPABILITIES } from "./app-provider-capabilities.js";
+/** Provider capabilities accepted by the application descriptor.
+ * @example const capability: AppProviderCapability = "cache";
+ */
 export type AppProviderCapability = (typeof APP_PROVIDER_CAPABILITIES)[number];
 type CapabilityInput<Capability extends AppProviderCapability> = ProviderInput<ProviderSourceInput<ProviderAdapter<ProviderCapability<Capability>>>>;
+/** Optional provider bindings for every supported capability.
+ * @example const providers: AppProviderInputs = { cache: redisAdapter };
+ */
 export interface AppProviderInputs {
     readonly bucket?: CapabilityInput<"bucket">;
     readonly cache?: CapabilityInput<"cache">;
@@ -41,7 +25,9 @@ type ProviderInputFor<Providers extends AppProviderInputs, Capability extends Ap
 type ProfileFor<Providers extends AppProviderInputs, Capability extends AppProviderCapability> = [
     ProviderInputFor<Providers, Capability>
 ] extends [never] ? never : Profile<ProviderInputFor<Providers, Capability>>;
-/** Public provider-default spellings. The normalized descriptor uses `job`. */
+/** Public default-profile spellings; normalized descriptors use `job`.
+ * @example const defaults: AppProviderDefaults<typeof providers> = { cache: "default" };
+ */
 export type AppProviderDefaults<Providers extends AppProviderInputs> = Readonly<{
     [Capability in Exclude<AppProviderCapability, "job">]?: ProfileFor<Providers, Capability>;
 }> & {
@@ -49,35 +35,18 @@ export type AppProviderDefaults<Providers extends AppProviderInputs> = Readonly<
     /** @deprecated Use `jobs`. */
     readonly job?: ProfileFor<Providers, "job">;
 };
+/** Validated default profiles keyed by normalized capability names.
+ * @example const defaults: NormalizedAppProviderDefaults<typeof providers> = { cache: "default" };
+ */
 export type NormalizedAppProviderDefaults<Providers extends AppProviderInputs> = Readonly<{
     [Capability in AppProviderCapability]?: ProfileFor<Providers, Capability>;
 }>;
-export type AppTelemetryConfig<Exporters extends TelemetryExporterMap = TelemetryExporterMap> = TelemetryConfiguration<Exporters>;
-export type AppDeploymentConfig = Readonly<Record<string, JsonValue>>;
-export type DefineAppOptions<Shape extends EnvShape, Providers extends AppProviderInputs, Exporters extends TelemetryExporterMap = TelemetryExporterMap> = DescriptorMetadata & Providers & {
-    readonly id?: string;
-    readonly env: EnvDefinition<Shape>;
-    readonly defaults?: AppProviderDefaults<Providers>;
-    readonly compatibility?: AppCompatibilityConfig;
-    readonly telemetry?: AppTelemetryConfig<Exporters>;
-    readonly server?: ServerConfig;
-    readonly inspector?: InspectorConfig;
-    readonly deployment?: AppDeploymentConfig;
-};
-type AdapterOf<Input> = Input extends ProviderSourceInput<infer Adapter> ? Adapter : Input extends Readonly<Record<string, infer Binding>> ? Binding extends ProviderSourceInput<infer Adapter> ? Adapter : never : never;
-type NormalizedProviders<Providers extends AppProviderInputs> = {
+/** Provider profiles inferred from the authored provider bindings.
+ * @example type Profiles = NormalizedProviders<typeof providers>;
+ */
+export type NormalizedProviders<Providers extends AppProviderInputs> = {
     readonly [Capability in AppProviderCapability as [ProviderInputFor<Providers, Capability>] extends [never] ? never : Capability]: NormalizedProviderProfiles<AdapterOf<ProviderInputFor<Providers, Capability>>>;
 };
-export type ApplicationDescriptor<Shape extends EnvShape = EnvShape, Providers extends AppProviderInputs = AppProviderInputs, Exporters extends TelemetryExporterMap = TelemetryExporterMap> = DescriptorBase<"app", string> & NormalizedProviders<Providers> & {
-    readonly env: EnvDefinition<Shape>;
-    readonly defaults: NormalizedAppProviderDefaults<Providers>;
-    readonly compatibility: {
-        readonly legacyJobs: boolean;
-    };
-    readonly telemetry?: AppTelemetryConfig<Exporters>;
-    readonly server?: ServerConfig;
-    readonly inspector?: InspectorConfig;
-    readonly deployment?: AppDeploymentConfig;
-};
+type AdapterOf<Input> = Input extends ProviderSourceInput<infer Adapter> ? Adapter : Input extends Readonly<Record<string, infer Binding>> ? Binding extends ProviderSourceInput<infer Adapter> ? Adapter : never : never;
 export {};
-//# sourceMappingURL=define-app-types.d.ts.map
+//# sourceMappingURL=app-provider.types.d.ts.map

package/dist/app-provider.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-provider.types.d.ts","sourceRoot":"","sources":["../src/app-provider.types.ts"],"names":[],"mappings":"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"}

package/dist/app-provider.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=app-provider.types.js.map

package/dist/app-provider.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-provider.types.js","sourceRoot":"","sources":["../src/app-provider.types.ts"],"names":[],"mappings":""}

package/dist/app-validation.d.ts

@@ -1,9 +1,75 @@
 import { type EnvDefinition, type EnvShape } from "@relkit/config";
-import type { AppCompatibilityConfig } from "./define-app-types.js";
+import { Effect, Schema } from "effect";
+import type { AppCompatibilityConfig } from "./define-app.types.js";
+declare const AppValidationFailure_base: Schema.Class<AppValidationFailure, Schema.TaggedStruct<"AppValidationFailure", {
+    readonly message: Schema.String;
+    readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/** Expected invalid application input with the original cause preserved.
+ * @example if (error._tag === "AppValidationFailure") console.error(error.message);
+ */
+export declare class AppValidationFailure extends AppValidationFailure_base {
+}
+/** Checks the complete environment descriptor shape in Effect.
+ * @param value - Candidate environment descriptor.
+ * @returns True for a valid environment definition; no expected failure.
+ * @example Effect.runSync(isEnvDefinitionEffect(value));
+ */
+export declare const isEnvDefinitionEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
+/** Synchronous environment descriptor guard.
+ * @param value - Candidate environment descriptor.
+ * @returns True for a valid environment definition.
+ * @example if (isEnvDefinition(value)) console.log(value.shape);
+ */
 export declare function isEnvDefinition(value: unknown): value is EnvDefinition<EnvShape>;
+/** Derives an application ID from a package name in Effect.
+ * @param packageName - Scoped or unscoped package name.
+ * @returns A normalized ID or AppValidationFailure.
+ * @example Effect.runSync(deriveApplicationIdEffect("@acme/orders"));
+ */
+export declare const deriveApplicationIdEffect: (packageName: string) => Effect.Effect<import("@relkit/contracts").StableId, AppValidationFailure, never>;
+/** Synchronous package-name ID adapter.
+ * @param packageName - Scoped or unscoped package name.
+ * @returns A normalized application ID.
+ * @throws The original normalization error for invalid input.
+ * @example deriveApplicationId("@acme/orders");
+ */
 export declare function deriveApplicationId(packageName: string): string;
+/** Normalizes the legacy jobs compatibility flag in Effect.
+ * @param value - Optional compatibility configuration.
+ * @returns A frozen flag object or AppValidationFailure.
+ * @example Effect.runSync(normalizeCompatibilityEffect({ legacyJobs: true }));
+ */
+export declare const normalizeCompatibilityEffect: (value: AppCompatibilityConfig | undefined) => Effect.Effect<Readonly<{
+    legacyJobs: boolean;
+}>, AppValidationFailure, never>;
+/** Synchronous compatibility normalizer.
+ * @param value - Optional compatibility configuration.
+ * @returns A frozen legacy-jobs flag object.
+ * @throws TypeError for an invalid compatibility flag.
+ * @example normalizeCompatibility({ legacyJobs: true });
+ */
 export declare function normalizeCompatibility(value: AppCompatibilityConfig | undefined): {
     readonly legacyJobs: boolean;
 };
+/** Rejects simultaneous current and legacy aliases in Effect.
+ * @param value - Record containing optional aliases.
+ * @param primary - Current alias name.
+ * @param legacy - Legacy alias name.
+ * @param label - Diagnostic context.
+ * @returns Void or AppValidationFailure.
+ * @example Effect.runSync(assertExclusiveAliasEffect(options, "jobs", "job", "defineApp"));
+ */
+export declare const assertExclusiveAliasEffect: (value: Record<string, unknown>, primary: string, legacy: string, label: string) => Effect.Effect<void, AppValidationFailure, never>;
+/** Synchronous alias exclusivity adapter.
+ * @param value - Record containing optional aliases.
+ * @param primary - Current alias name.
+ * @param legacy - Legacy alias name.
+ * @param label - Diagnostic context.
+ * @returns Nothing when aliases are exclusive.
+ * @throws TypeError when both aliases are present.
+ * @example assertExclusiveAlias(options, "jobs", "job", "defineApp");
+ */
 export declare function assertExclusiveAlias(value: Record<string, unknown>, primary: string, legacy: string, label: string): void;
+export {};
 //# sourceMappingURL=app-validation.d.ts.map

package/dist/app-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-validation.d.ts","sourceRoot":"","sources":["../src/app-validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE7E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAEpE,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAAC,QAAQ,CAAC,CAahF;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAG/D;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,sBAAsB,GAAG,SAAS,GAAG;IACjF,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B,CASA;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,IAAI,CAIN"}
+{"version":3,"file":"app-validation.d.ts","sourceRoot":"","sources":["../src/app-validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE7E,OAAO,EAAE,MAAM,EAAU,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;;;;;AAEpE;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,yBAGzC;CAAG;AAEJ;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,0DAmBjC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAAC,QAAQ,CAAC,CAEhF;AAED;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,2GAYrC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;GAIG;AACH,eAAO,MAAM,4BAA4B;;gCAiBxC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,sBAAsB,GAAG,SAAS,GAAG;IACjF,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B,CAEA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,sIAYtC,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,IAAI,CAEN"}

package/dist/app-validation.js

@@ -1,6 +1,18 @@
 import { isEnvRef } from "@relkit/config";
 import { normalizeId } from "@relkit/contracts";
-export function isEnvDefinition(value) {
+import { Effect, Result, Schema } from "effect";
+import { observeApp } from "./app-observability.js";
+/** Expected invalid application input with the original cause preserved.
+ * @example if (error._tag === "AppValidationFailure") console.error(error.message);
+ */
+export class AppValidationFailure extends Schema.TaggedError()("AppValidationFailure", { message: Schema.String, cause: Schema.Defect() }) {
+}
+/** Checks the complete environment descriptor shape in Effect.
+ * @param value - Candidate environment descriptor.
+ * @returns True for a valid environment definition; no expected failure.
+ * @example Effect.runSync(isEnvDefinitionEffect(value));
+ */
+export const isEnvDefinitionEffect = Effect.fn("App.isEnvDefinition")((value) => observeApp("env.isDefinition", Effect.sync(() => {
     if (!isRecord(value) || value.kind !== "env-definition" || !isRecord(value.shape))
         return false;
     return Object.entries(value.shape).every(([name, builder]) => {
@@ -12,25 +24,100 @@ export function isEnvDefinition(value) {
             isEnvRef(reference) &&
             reference.name === name);
     });
+})));
+/** Synchronous environment descriptor guard.
+ * @param value - Candidate environment descriptor.
+ * @returns True for a valid environment definition.
+ * @example if (isEnvDefinition(value)) console.log(value.shape);
+ */
+export function isEnvDefinition(value) {
+    return Effect.runSync(isEnvDefinitionEffect(value));
 }
+/** Derives an application ID from a package name in Effect.
+ * @param packageName - Scoped or unscoped package name.
+ * @returns A normalized ID or AppValidationFailure.
+ * @example Effect.runSync(deriveApplicationIdEffect("@acme/orders"));
+ */
+export const deriveApplicationIdEffect = Effect.fn("App.deriveApplicationId")((packageName) => observeApp("id.derive", Effect.try({
+    try: () => normalizeId((packageName.startsWith("@") ? packageName.slice(1) : packageName).replaceAll("/", ".")),
+    catch: validationFailure,
+})));
+/** Synchronous package-name ID adapter.
+ * @param packageName - Scoped or unscoped package name.
+ * @returns A normalized application ID.
+ * @throws The original normalization error for invalid input.
+ * @example deriveApplicationId("@acme/orders");
+ */
 export function deriveApplicationId(packageName) {
-    const normalized = packageName.startsWith("@") ? packageName.slice(1) : packageName;
-    return normalizeId(normalized.replaceAll("/", "."));
+    return runValidation(deriveApplicationIdEffect(packageName));
 }
+/** Normalizes the legacy jobs compatibility flag in Effect.
+ * @param value - Optional compatibility configuration.
+ * @returns A frozen flag object or AppValidationFailure.
+ * @example Effect.runSync(normalizeCompatibilityEffect({ legacyJobs: true }));
+ */
+export const normalizeCompatibilityEffect = Effect.fn("App.normalizeCompatibility")((value) => observeApp("compatibility.normalize", Effect.try({
+    try: () => {
+        if (value === undefined)
+            return Object.freeze({ legacyJobs: false });
+        if (!isRecord(value) ||
+            (value.legacyJobs !== undefined && typeof value.legacyJobs !== "boolean"))
+            throw new TypeError("defineApp compatibility.legacyJobs must be a boolean");
+        return Object.freeze({ legacyJobs: value.legacyJobs === true });
+    },
+    catch: validationFailure,
+})));
+/** Synchronous compatibility normalizer.
+ * @param value - Optional compatibility configuration.
+ * @returns A frozen legacy-jobs flag object.
+ * @throws TypeError for an invalid compatibility flag.
+ * @example normalizeCompatibility({ legacyJobs: true });
+ */
 export function normalizeCompatibility(value) {
-    if (value === undefined)
-        return Object.freeze({ legacyJobs: false });
-    if (!isRecord(value) ||
-        (value.legacyJobs !== undefined && typeof value.legacyJobs !== "boolean")) {
-        throw new TypeError("defineApp compatibility.legacyJobs must be a boolean");
-    }
-    return Object.freeze({ legacyJobs: value.legacyJobs === true });
+    return runValidation(normalizeCompatibilityEffect(value));
 }
+/** Rejects simultaneous current and legacy aliases in Effect.
+ * @param value - Record containing optional aliases.
+ * @param primary - Current alias name.
+ * @param legacy - Legacy alias name.
+ * @param label - Diagnostic context.
+ * @returns Void or AppValidationFailure.
+ * @example Effect.runSync(assertExclusiveAliasEffect(options, "jobs", "job", "defineApp"));
+ */
+export const assertExclusiveAliasEffect = Effect.fn("App.assertExclusiveAlias")((value, primary, legacy, label) => observeApp("alias.assertExclusive", Effect.try({
+    try: () => {
+        if (value[primary] !== undefined && value[legacy] !== undefined)
+            throw new TypeError(`${label} cannot specify both "${primary}" and "${legacy}"`);
+    },
+    catch: validationFailure,
+})));
+/** Synchronous alias exclusivity adapter.
+ * @param value - Record containing optional aliases.
+ * @param primary - Current alias name.
+ * @param legacy - Legacy alias name.
+ * @param label - Diagnostic context.
+ * @returns Nothing when aliases are exclusive.
+ * @throws TypeError when both aliases are present.
+ * @example assertExclusiveAlias(options, "jobs", "job", "defineApp");
+ */
 export function assertExclusiveAlias(value, primary, legacy, label) {
-    if (value[primary] !== undefined && value[legacy] !== undefined) {
-        throw new TypeError(`${label} cannot specify both "${primary}" and "${legacy}"`);
-    }
+    runValidation(assertExclusiveAliasEffect(value, primary, legacy, label));
+}
+/** Maps known synchronous validation errors into the typed channel. */
+function validationFailure(cause) {
+    return new AppValidationFailure({
+        message: cause instanceof Error ? cause.message : String(cause),
+        cause,
+    });
+}
+/** Runs a pure validation Effect while preserving old thrown errors. */
+function runValidation(effect) {
+    const result = Effect.runSync(Effect.result(effect));
+    if (Result.isFailure(result))
+        throw result.failure.cause;
+    return result.success;
 }
+/** Tests for a non-array object record. */
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }