@appport/sdk 1.0.1

package/node_modules/@appport/core/dist/application.d.ts

@@ -0,0 +1,122 @@
+import { type AppEventEnvelope, type AppPortManifest, type AppRequest, type AppResponse, type AppStreamRequest, type ApplicationDescriptor, type Principal, type Session, type TransportDescriptor } from "@appport/protocol";
+import { type Authorizer } from "@appport/authorization";
+import type { AnyCapability, AnyEvent, CapabilityDefinition, EventDefinition } from "./capability.js";
+import { CapabilityRegistry } from "./registry.js";
+import { EventBus, type EventFilter, type EventListener, type Unsubscribe } from "./events.js";
+import { type EmitEventInput, type Logger } from "./context.js";
+import { type SessionStore } from "./sessions.js";
+import { type IdempotencyStore } from "./idempotency.js";
+import { type TelemetrySink } from "./telemetry.js";
+import { type RuntimeMode } from "./sanitize.js";
+import type { VerificationResult } from "./assembly.js";
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export declare const DEFAULT_MAX_TIMEOUT_MS = 120000;
+export interface ApplicationOptions {
+    application: ApplicationDescriptor;
+    capabilities?: ReadonlyArray<AnyCapability>;
+    events?: ReadonlyArray<AnyEvent>;
+    /** Defaults to allow-all, which is only appropriate locally (§37, §38). */
+    authorizer?: Authorizer;
+    sessions?: SessionStore;
+    idempotency?: IdempotencyStore;
+    telemetry?: TelemetrySink;
+    logger?: Logger;
+    /** Controls error sanitization and output validation (§16, §49). */
+    mode?: RuntimeMode;
+    defaultTimeoutMs?: number;
+    maxTimeoutMs?: number;
+    /** Validate handler output. Defaults to true in development, true in production too. */
+    validateOutput?: boolean;
+    /** Application services made available on the handler context. */
+    services?: Record<string, unknown>;
+    /** Optional storage handle surfaced as `context.db` (§10, §66). */
+    db?: unknown;
+    /** Transports advertised in the manifest (§40). */
+    transports?: TransportDescriptor[];
+    extensions?: string[];
+    /**
+     * Registers the reserved `appport.manifest` and `appport.ping` capabilities so
+     * discovery works on transports without URLs. Defaults to true.
+     */
+    builtins?: boolean;
+}
+/** Per-request inputs supplied by the transport layer. */
+export interface DispatchOptions {
+    session?: Session;
+    principal?: Principal;
+    /** Transport kind, recorded for telemetry only — never for trust (§52). */
+    transport?: string;
+    /** External abort (connection closed, client cancelled). */
+    signal?: AbortSignal;
+}
+/** A running stream capability invocation. */
+export interface StreamExecution {
+    readonly streamId: string;
+    readonly requestId: string;
+    /** Validated chunks. Throws {@link AppPortError} on failure. */
+    readonly chunks: AsyncIterable<unknown>;
+    /** Requests best-effort termination of the underlying operation (§21). */
+    cancel(reason?: string): void;
+}
+/**
+ * The AppPort capability runtime.
+ *
+ * It owns the dispatch pipeline described in §48 — receive, validate,
+ * authorize, execute, serialize, respond — and knows nothing about transports.
+ * Servers and transports feed it envelopes and carry the results.
+ */
+export declare class AppPortApplication {
+    #private;
+    readonly registry: CapabilityRegistry;
+    readonly bus: EventBus;
+    readonly descriptor: ApplicationDescriptor;
+    readonly sessions: SessionStore;
+    readonly logger: Logger;
+    readonly mode: RuntimeMode;
+    constructor(options: ApplicationOptions);
+    /** Registers a capability after construction. */
+    capability<Input, Output>(definition: CapabilityDefinition<Input, Output>): this;
+    /** Registers an event definition after construction. */
+    event<Payload>(definition: EventDefinition<Payload>): this;
+    /** Advertises an additional transport in the manifest (§40). */
+    advertiseTransport(descriptor: TransportDescriptor): this;
+    manifest(): AppPortManifest;
+    /**
+     * Verifies the application assembly for coherence and completeness (PR18).
+     *
+     * Checks:
+     * - All capabilities in the registry are structurally valid
+     * - All capabilities have implementations (explicit, definition-bound, or handler)
+     * - No orphan or duplicate implementations
+     *
+     * Returns a VerificationResult with ready state and detailed issues.
+     *
+     * NOTE: This runtime verification accepts both explicit implementations
+     * and legacy handlers (PR17) for backward compatibility.
+     *
+     * CRITICAL: Verification never executes business logic. It is purely structural.
+     */
+    verify(): VerificationResult;
+    /** Subscribes to application events (§18). */
+    subscribe(filter: EventFilter | string, listener: EventListener, subscriptionId?: string): Unsubscribe;
+    /** Publishes an application event outside of a capability handler. */
+    emit(input: EmitEventInput, options?: {
+        traceId?: string;
+    }): Promise<AppEventEnvelope>;
+    /**
+     * Executes a request capability and produces a response envelope.
+     * Never throws for application-level failures: every outcome is an envelope.
+     */
+    handleRequest(request: AppRequest, options?: DispatchOptions): Promise<AppResponse>;
+    /**
+     * Starts a stream capability. Protocol errors that occur before the first
+     * chunk are thrown so the transport can answer with an error response rather
+     * than an empty stream.
+     */
+    handleStreamRequest(request: AppStreamRequest, options?: DispatchOptions): Promise<StreamExecution>;
+    /** Releases every stream and subscription. */
+    close(): Promise<void>;
+}
+/** Creates an {@link AppPortApplication}. */
+export declare function createApplication(options: ApplicationOptions): AppPortApplication;
+//# sourceMappingURL=application.d.ts.map

package/node_modules/@appport/core/dist/application.d.ts.map

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

package/node_modules/@appport/core/dist/application.js

@@ -0,0 +1,515 @@
+import { AppPortError, createErrorResponse, createEvent, createSuccessResponse, errors, isValidName, newEventId, newStreamId, newTraceId } from "@appport/protocol";
+import { allowAllAuthorizer, createAuthorizationContext, decisionToError } from "@appport/authorization";
+import { formatIssues, issuesToDetails } from "@appport/schema";
+import { CapabilityRegistry } from "./registry.js";
+import { EventBus } from "./events.js";
+import { consoleLogger, silentLogger } from "./context.js";
+import { createStreamContext, toAsyncIterable } from "./streams.js";
+import { MemorySessionStore } from "./sessions.js";
+import { DEFAULT_IDEMPOTENCY_TTL_MS, idempotencyStorageKey, MemoryIdempotencyStore } from "./idempotency.js";
+import { ConcurrencyGate } from "./concurrency.js";
+import { createBuiltinCapabilities } from "./builtins.js";
+import { noopTelemetry } from "./telemetry.js";
+import { toWireError } from "./sanitize.js";
+import { verifyApplication, verifyApplicationWithHandlers } from "./assembly.js";
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const DEFAULT_MAX_TIMEOUT_MS = 120_000;
+/**
+ * The AppPort capability runtime.
+ *
+ * It owns the dispatch pipeline described in §48 — receive, validate,
+ * authorize, execute, serialize, respond — and knows nothing about transports.
+ * Servers and transports feed it envelopes and carry the results.
+ */
+export class AppPortApplication {
+    registry;
+    bus;
+    descriptor;
+    sessions;
+    logger;
+    mode;
+    #authorizer;
+    #idempotency;
+    #telemetry;
+    #concurrency = new ConcurrencyGate();
+    #inflightIdempotent = new Map();
+    #defaultTimeoutMs;
+    #maxTimeoutMs;
+    #validateOutput;
+    #services;
+    #db;
+    #transports;
+    #extensions;
+    #openStreams = new Set();
+    #closed = false;
+    constructor(options) {
+        this.descriptor = options.application;
+        this.mode = options.mode ?? (process.env["NODE_ENV"] === "production" ? "production" : "development");
+        this.logger = options.logger ?? (this.mode === "development" ? consoleLogger() : silentLogger);
+        this.registry = new CapabilityRegistry();
+        this.bus = new EventBus(this.logger);
+        this.sessions = options.sessions ?? new MemorySessionStore();
+        this.#authorizer = options.authorizer ?? allowAllAuthorizer();
+        this.#idempotency = options.idempotency ?? new MemoryIdempotencyStore();
+        this.#telemetry = options.telemetry ?? noopTelemetry;
+        this.#defaultTimeoutMs = options.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.#maxTimeoutMs = options.maxTimeoutMs ?? DEFAULT_MAX_TIMEOUT_MS;
+        this.#validateOutput = options.validateOutput ?? true;
+        this.#services = options.services ?? {};
+        this.#db = options.db;
+        this.#transports = options.transports ?? [];
+        this.#extensions = options.extensions ?? [];
+        for (const capability of options.capabilities ?? [])
+            this.registry.register(capability);
+        for (const event of options.events ?? [])
+            this.registry.registerEvent(event);
+        if (options.builtins !== false) {
+            for (const capability of createBuiltinCapabilities({ manifest: () => this.manifest() })) {
+                this.registry.register(capability);
+            }
+        }
+    }
+    /** Registers a capability after construction. */
+    capability(definition) {
+        this.registry.register(definition);
+        return this;
+    }
+    /** Registers an event definition after construction. */
+    event(definition) {
+        this.registry.registerEvent(definition);
+        return this;
+    }
+    /** Advertises an additional transport in the manifest (§40). */
+    advertiseTransport(descriptor) {
+        const existing = this.#transports.findIndex((entry) => entry.kind === descriptor.kind && entry.endpoint === descriptor.endpoint);
+        if (existing === -1)
+            this.#transports.push(descriptor);
+        else
+            this.#transports[existing] = descriptor;
+        return this;
+    }
+    manifest() {
+        return this.registry.manifest({
+            application: this.descriptor,
+            transports: [...this.#transports],
+            extensions: [...this.#extensions]
+        });
+    }
+    /**
+     * Verifies the application assembly for coherence and completeness (PR18).
+     *
+     * Checks:
+     * - All capabilities in the registry are structurally valid
+     * - All capabilities have implementations (explicit, definition-bound, or handler)
+     * - No orphan or duplicate implementations
+     *
+     * Returns a VerificationResult with ready state and detailed issues.
+     *
+     * NOTE: This runtime verification accepts both explicit implementations
+     * and legacy handlers (PR17) for backward compatibility.
+     *
+     * CRITICAL: Verification never executes business logic. It is purely structural.
+     */
+    verify() {
+        // Build an ApplicationAssembly from the current registry state
+        const capabilities = this.registry.capabilities();
+        const implementations = new Map();
+        // Collect all explicit implementations from the registry
+        // Note: We don't collect implementations from capability definitions here;
+        // the verifyApplicationWithHandlers function will check capability.implementation
+        for (const capability of capabilities) {
+            if (capability.implementation) {
+                implementations.set(`${capability.name}@${capability.version}`, capability.implementation);
+            }
+        }
+        const assembly = {
+            identity: {
+                id: this.descriptor.id,
+                name: this.descriptor.name,
+                version: this.descriptor.version
+            },
+            provides: capabilities,
+            requires: [],
+            implementations
+        };
+        // Use the handler-aware verification for runtime
+        return verifyApplicationWithHandlers(assembly);
+    }
+    /** Subscribes to application events (§18). */
+    subscribe(filter, listener, subscriptionId) {
+        return this.bus.subscribe(filter, listener, subscriptionId);
+    }
+    /** Publishes an application event outside of a capability handler. */
+    async emit(input, options = {}) {
+        return this.#emit(input, options.traceId);
+    }
+    async #emit(input, traceId) {
+        if (!isValidName(input.name)) {
+            throw errors.internal(`Invalid event name: ${input.name}`);
+        }
+        const definition = this.registry.getEvent(input.name, input.version);
+        if (!definition) {
+            if (this.registry.getEvent(input.name)) {
+                throw errors.internal(`Event ${input.name}@${input.version ?? "?"} is not registered`);
+            }
+            this.logger.warn("emitting an event that is not declared in the manifest", { event: input.name });
+        }
+        else {
+            const result = definition.payload.validate(input.payload);
+            if (!result.ok) {
+                throw new AppPortError("INTERNAL_ERROR", "Event payload failed validation", {
+                    internal: `${input.name}: ${formatIssues(result.issues)}`
+                });
+            }
+        }
+        const envelope = createEvent({
+            name: input.name,
+            version: input.version ?? definition?.version ?? 1,
+            eventId: newEventId(),
+            payload: input.payload,
+            ...(traceId ? { traceId } : {})
+        });
+        await this.bus.publish(envelope);
+        return envelope;
+    }
+    /**
+     * Executes a request capability and produces a response envelope.
+     * Never throws for application-level failures: every outcome is an envelope.
+     */
+    async handleRequest(request, options = {}) {
+        const started = Date.now();
+        const traceId = request.traceId ?? newTraceId();
+        let capabilityRef = request.capability;
+        let outcome;
+        let idempotentReplay = false;
+        try {
+            const definition = this.registry.resolve(request.capability.name, request.capability.version);
+            capabilityRef = { name: definition.name, version: definition.version };
+            if (definition.kind === "stream") {
+                throw errors.invalidRequest(`Capability ${definition.name}@${definition.version} is a stream capability; use a stream request`);
+            }
+            const input = this.#validateInput(definition, request.input);
+            const authorization = await this.#authorize(definition, input, options);
+            const replayKey = definition.idempotency === "supported" && request.idempotencyKey
+                ? idempotencyStorageKey({
+                    key: request.idempotencyKey,
+                    capability: definition.name,
+                    version: definition.version,
+                    sessionId: options.session?.id
+                })
+                : undefined;
+            if (replayKey) {
+                const stored = await this.#idempotency.get(replayKey);
+                if (stored) {
+                    idempotentReplay = true;
+                    outcome = { response: replayResponse(stored.response, request.requestId, traceId) };
+                    this.#recordTelemetry(request, capabilityRef, "request", options, started, outcome, {
+                        traceId,
+                        idempotentReplay
+                    });
+                    return outcome.response;
+                }
+                const inflight = this.#inflightIdempotent.get(replayKey);
+                if (inflight) {
+                    const response = replayResponse(await inflight, request.requestId, traceId);
+                    this.#recordTelemetry(request, capabilityRef, "request", options, started, { response }, { traceId, idempotentReplay: true });
+                    return response;
+                }
+            }
+            const execute = async () => {
+                const output = await this.#execute(definition, input, request, options, authorization, traceId);
+                return createSuccessResponse(request.requestId, output, { traceId });
+            };
+            let responsePromise;
+            if (replayKey) {
+                responsePromise = execute();
+                this.#inflightIdempotent.set(replayKey, responsePromise);
+                responsePromise.catch(() => undefined).finally(() => this.#inflightIdempotent.delete(replayKey));
+            }
+            else {
+                responsePromise = execute();
+            }
+            const response = await responsePromise;
+            if (replayKey) {
+                const now = Date.now();
+                await this.#idempotency.set({
+                    key: replayKey,
+                    capability: definition.name,
+                    version: definition.version,
+                    requestId: request.requestId,
+                    response,
+                    storedAt: now,
+                    expiresAt: now + DEFAULT_IDEMPOTENCY_TTL_MS
+                });
+            }
+            outcome = { response };
+        }
+        catch (error) {
+            const wire = toWireError(error, this.mode);
+            outcome = { response: createErrorResponse(request.requestId, wire, { traceId }), errorCode: wire.code };
+            if (!AppPortError.is(error)) {
+                this.logger.error("capability handler threw a non-protocol error", {
+                    capability: capabilityRef.name,
+                    requestId: request.requestId
+                });
+            }
+        }
+        this.#recordTelemetry(request, capabilityRef, "request", options, started, outcome, {
+            traceId,
+            idempotentReplay
+        });
+        return outcome.response;
+    }
+    /**
+     * Starts a stream capability. Protocol errors that occur before the first
+     * chunk are thrown so the transport can answer with an error response rather
+     * than an empty stream.
+     */
+    async handleStreamRequest(request, options = {}) {
+        const started = Date.now();
+        const traceId = request.traceId ?? newTraceId();
+        const definition = this.registry.resolve(request.capability.name, request.capability.version);
+        if (definition.kind !== "stream") {
+            throw errors.invalidRequest(`Capability ${definition.name}@${definition.version} is not a stream capability`);
+        }
+        const input = this.#validateInput(definition, request.input);
+        const authorization = await this.#authorize(definition, input, options);
+        const controller = new AbortController();
+        const timeoutMs = this.#resolveTimeout(definition.timeoutMs, request.timeoutMs);
+        const timer = setTimeout(() => controller.abort(errors.timeout()), timeoutMs);
+        if (timer.unref)
+            timer.unref();
+        const abortParent = () => controller.abort(errors.cancelled());
+        options.signal?.addEventListener("abort", abortParent, { once: true });
+        if (options.signal?.aborted)
+            controller.abort(errors.cancelled());
+        const release = () => {
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", abortParent);
+            this.#openStreams.delete(release);
+        };
+        this.#openStreams.add(release);
+        const context = this.#createContext({
+            request,
+            definition,
+            options,
+            authorization,
+            traceId,
+            signal: controller.signal,
+            deadline: started + timeoutMs
+        });
+        const self = this;
+        let chunkCount = 0;
+        async function* iterate() {
+            let failure;
+            try {
+                // If an implementation is bound, execute it; otherwise use the handler directly.
+                // This supports PR17: Capability Implementation Binding & Runtime Enforcement
+                const source = definition.implementation
+                    ? await definition.implementation.execute(input, context)
+                    : await definition.handler(input, context);
+                for await (const chunk of toAsyncIterable(source)) {
+                    if (controller.signal.aborted) {
+                        throw controller.signal.reason instanceof AppPortError ? controller.signal.reason : errors.cancelled();
+                    }
+                    chunkCount += 1;
+                    yield self.#validateChunk(definition, chunk);
+                }
+            }
+            catch (error) {
+                failure = error;
+                throw error;
+            }
+            finally {
+                release();
+                // Telemetry reports what actually happened to the stream, including a
+                // cancellation or a failed chunk (§20).
+                const outcome = failure === undefined
+                    ? { response: createSuccessResponse(request.requestId, null, { traceId }) }
+                    : {
+                        response: createErrorResponse(request.requestId, toWireError(failure, self.mode), { traceId })
+                    };
+                self.#recordTelemetry(request, { name: definition.name, version: definition.version }, "stream", options, started, outcome, { traceId, chunks: chunkCount });
+            }
+        }
+        return {
+            streamId: newStreamId(),
+            requestId: request.requestId,
+            chunks: iterate(),
+            cancel: (reason) => controller.abort(errors.cancelled(reason ?? "Cancelled by client"))
+        };
+    }
+    /** Releases every stream and subscription. */
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        for (const release of [...this.#openStreams])
+            release();
+        this.bus.clear();
+    }
+    // -------------------------------------------------------------------------
+    // Pipeline steps
+    // -------------------------------------------------------------------------
+    #validateInput(definition, raw) {
+        const result = definition.input.validate(raw);
+        if (!result.ok) {
+            throw errors.invalidInput(`Input for ${definition.name}@${definition.version} is invalid: ${formatIssues(result.issues)}`, issuesToDetails(result.issues));
+        }
+        return result.value;
+    }
+    #validateChunk(definition, chunk) {
+        if (!this.#validateOutput)
+            return chunk;
+        const result = definition.output.validate(chunk);
+        if (!result.ok) {
+            throw new AppPortError("STREAM_ERROR", "Stream chunk failed output validation", {
+                internal: `${definition.name}: ${formatIssues(result.issues)}`
+            });
+        }
+        return result.value;
+    }
+    async #authorize(definition, input, options) {
+        const decision = await this.#authorizer.authorize({
+            capability: { name: definition.name, version: definition.version },
+            required: definition.authorization,
+            ...(options.session ? { session: options.session } : {}),
+            ...(options.principal ?? options.session?.principal
+                ? { principal: (options.principal ?? options.session?.principal) }
+                : {}),
+            input,
+            ...(options.transport ? { transport: options.transport } : {})
+        });
+        if (!decision.allowed)
+            throw decisionToError(decision);
+        return decision.permissions ?? options.session?.permissions ?? [];
+    }
+    #resolveTimeout(capabilityTimeout, requested) {
+        const base = capabilityTimeout ?? this.#defaultTimeoutMs;
+        const desired = requested ?? base;
+        return Math.min(desired, capabilityTimeout ?? this.#maxTimeoutMs, this.#maxTimeoutMs);
+    }
+    async #execute(definition, input, request, options, authorization, traceId) {
+        const controller = new AbortController();
+        const timeoutMs = this.#resolveTimeout(definition.timeoutMs, request.timeoutMs);
+        const deadline = Date.now() + timeoutMs;
+        const abortParent = () => controller.abort(errors.cancelled());
+        if (options.signal?.aborted)
+            controller.abort(errors.cancelled());
+        else
+            options.signal?.addEventListener("abort", abortParent, { once: true });
+        const context = this.#createContext({
+            request,
+            definition,
+            options,
+            authorization,
+            traceId,
+            signal: controller.signal,
+            deadline
+        });
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                const error = errors.timeout(`Capability ${definition.name}@${definition.version} exceeded ${timeoutMs}ms`);
+                controller.abort(error);
+                reject(error);
+            }, timeoutMs);
+            if (timer.unref)
+                timer.unref();
+        });
+        try {
+            const work = this.#concurrency.run(definition.concurrency, `${definition.name}@${definition.version}`, input, async () => {
+                // If an implementation is bound, execute it; otherwise use the handler directly.
+                // This supports PR17: Capability Implementation Binding & Runtime Enforcement
+                if (definition.implementation) {
+                    return await definition.implementation.execute(input, context);
+                }
+                return definition.handler(input, context);
+            });
+            const output = await Promise.race([work, timeout]);
+            if (!this.#validateOutput)
+                return output;
+            const result = definition.output.validate(output);
+            if (!result.ok) {
+                throw new AppPortError("INTERNAL_ERROR", "Capability produced an invalid response", {
+                    internal: `${definition.name}: ${formatIssues(result.issues)}`
+                });
+            }
+            return result.value;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            options.signal?.removeEventListener("abort", abortParent);
+        }
+    }
+    #createContext(args) {
+        const { request, definition, options, authorization, traceId, signal, deadline } = args;
+        const metadata = {
+            ...(request.metadata ?? {}),
+            ...(options.transport ? { transport: options.transport } : {}),
+            receivedAt: request.metadata?.receivedAt ?? new Date().toISOString()
+        };
+        const principal = options.principal ?? options.session?.principal;
+        return {
+            requestId: request.requestId,
+            traceId,
+            capability: { name: definition.name, version: definition.version },
+            ...(options.session ? { session: options.session } : {}),
+            ...(principal ? { principal } : {}),
+            authorization: createAuthorizationContext({
+                ...(options.session ? { session: options.session } : {}),
+                ...(principal ? { principal } : {}),
+                permissions: authorization
+            }),
+            metadata,
+            signal,
+            deadline,
+            ...(request.idempotencyKey ? { idempotencyKey: request.idempotencyKey } : {}),
+            logger: this.logger,
+            extensions: request.extensions ?? {},
+            emit: async (event) => {
+                await this.#emit(event, traceId);
+            },
+            createStream: (highWaterMark) => createStreamContext(signal, highWaterMark),
+            ...(this.#db !== undefined ? { db: this.#db } : {}),
+            services: this.#services
+        };
+    }
+    #recordTelemetry(request, capability, kind, options, started, outcome, extra) {
+        const principal = options.principal ?? options.session?.principal;
+        const record = {
+            requestId: request.requestId,
+            traceId: extra.traceId,
+            applicationId: this.descriptor.id,
+            capability: capability.name,
+            version: capability.version,
+            kind,
+            transport: options.transport ?? "unknown",
+            ...(principal ? { principal: principal.id } : {}),
+            ...(options.session ? { sessionId: options.session.id } : {}),
+            startTime: started,
+            durationMs: Date.now() - started,
+            success: outcome.response.ok,
+            ...(outcome.response.ok ? {} : { errorCode: outcome.response.error.code }),
+            ...(extra.chunks !== undefined ? { chunks: extra.chunks } : {}),
+            ...(extra.idempotentReplay ? { idempotentReplay: true } : {})
+        };
+        try {
+            this.#telemetry.record(record);
+        }
+        catch {
+            // Telemetry must never break a request.
+        }
+    }
+}
+function replayResponse(stored, requestId, traceId) {
+    return stored.ok
+        ? createSuccessResponse(requestId, stored.output, { traceId })
+        : createErrorResponse(requestId, stored.error, { traceId });
+}
+/** Creates an {@link AppPortApplication}. */
+export function createApplication(options) {
+    return new AppPortApplication(options);
+}
+//# sourceMappingURL=application.js.map