effect-agent 0.1.0-beta.85 → 0.1.0-beta.87

package/src/durable/SubmissionStatus.ts

@@ -0,0 +1,14 @@
+import { Schema } from "effect";
+
+import { Settlement } from "./SubmissionLedger.ts";
+
+/** A Submission still owes its canonical Settlement, including while suspended. */
+export class PendingSubmission extends Schema.TaggedClass<PendingSubmission>()("pending", {}) {}
+
+/** The existing durable Settlement is the only authority for completion. */
+export class SettledSubmission extends Schema.TaggedClass<SettledSubmission>()("settled", {
+  settlement: Settlement,
+}) {}
+
+export const SubmissionStatus = Schema.Union([PendingSubmission, SettledSubmission]);
+export type SubmissionStatus = typeof SubmissionStatus.Type;

package/src/durable/Subscription.ts

@@ -0,0 +1,544 @@
+import { Context, Effect, Schema } from "effect";
+
+import { InputMessage } from "../capabilities/Messaging.ts";
+import { AgentId, ThreadId } from "../core/Identifiers.ts";
+import { Receipt } from "../core/Receipt.ts";
+import { DefinitionDigests, Digest, PersistedJson, WorkerAdmission } from "./Records.ts";
+import {
+  ScheduleAuthorizationDecision,
+  ScheduleDestination,
+  ScheduleInstant,
+  ScheduleRetry,
+} from "./Schedule.ts";
+import { AdmissionFence, AdmissionGroup, IdempotencyKey, Principal } from "./SubmissionLedger.ts";
+
+export const SubscriptionName = Schema.NonEmptyString.check(
+  Schema.isMaxLength(256),
+  Schema.isPattern(/^[^\p{Surrogate}]*$/u),
+);
+
+const Positive = Schema.Int.check(Schema.isGreaterThan(0));
+
+/** Stable storage identity. Deployment and payload values must never change its routing. */
+export const SourcePartition = Schema.Struct({
+  tenantId: SubscriptionName,
+  address: SubscriptionName,
+});
+
+export type SourcePartition = typeof SourcePartition.Type;
+
+export const EventSourceVersion = Schema.Struct({
+  name: SubscriptionName,
+  version: SubscriptionName,
+});
+
+export type EventSourceVersion = typeof EventSourceVersion.Type;
+
+export const SubscriptionKey = Schema.Struct({
+  partition: SourcePartition,
+  ownerId: SubscriptionName,
+  subscriptionId: SubscriptionName,
+});
+
+export type SubscriptionKey = typeof SubscriptionKey.Type;
+
+export const SubscriptionScope = Schema.Struct({
+  partition: SourcePartition,
+  ownerId: SubscriptionName,
+  principal: Principal,
+});
+
+export type SubscriptionScope = typeof SubscriptionScope.Type;
+
+export const SubscriptionConfiguration = Schema.Struct({
+  source: EventSourceVersion,
+  matchingKey: SubscriptionName,
+  parameters: PersistedJson,
+  context: PersistedJson,
+  mode: Schema.Literals(["once", "continuous"]),
+  /** Null disables time-based expiry; once selection and cancellation still apply. */
+  expiresAtMillis: Schema.NullOr(ScheduleInstant),
+  destination: ScheduleDestination,
+  deliveryPrincipal: Principal,
+  admissionGroup: Schema.optionalKey(AdmissionGroup),
+  admissionFence: Schema.optionalKey(AdmissionFence),
+  agentId: AgentId,
+  definitions: DefinitionDigests,
+});
+
+export type SubscriptionConfiguration = typeof SubscriptionConfiguration.Type;
+
+export const SourceRecovery = Schema.Struct({
+  attempts: Schema.Natural,
+  /** Null retains a conclusive source failure without continuing provider polling. */
+  nextAttemptAtMillis: Schema.NullOr(ScheduleInstant),
+  lastFailure: Schema.NullOr(SubscriptionName),
+}).check(
+  Schema.makeFilter((value) => value.nextAttemptAtMillis !== null || value.lastFailure !== null),
+);
+
+export const SubscriptionRecord = Schema.Struct({
+  schemaVersion: Schema.Literal(1),
+  key: SubscriptionKey,
+  creationFingerprint: Digest,
+  configurationRevision: Positive,
+  configurationFingerprint: Digest,
+  creationConfiguration: SubscriptionConfiguration,
+  createdBy: Principal,
+  createdAtMillis: ScheduleInstant,
+  /** Assigned atomically in the same order as event eligibility cutoffs. */
+  ordinal: Schema.Natural,
+  configuration: SubscriptionConfiguration,
+  state: Schema.Literals(["active", "paused", "consumed", "cancelled"]),
+  recovery: Schema.NullOr(SourceRecovery),
+}).check(
+  Schema.makeFilter(
+    (value) =>
+      (value.state !== "consumed" || value.configuration.mode === "once") &&
+      (value.recovery === null ||
+        (value.configuration.mode === "once" &&
+          (value.state === "active" || value.state === "paused"))),
+  ),
+);
+
+export type SubscriptionRecord = typeof SubscriptionRecord.Type;
+
+export const AcceptedEvent = Schema.Struct({
+  schemaVersion: Schema.Literal(1),
+  partition: SourcePartition,
+  eventId: SubscriptionName,
+  source: EventSourceVersion,
+  matchingKey: SubscriptionName,
+  payload: PersistedJson,
+  payloadDigest: Digest,
+  acceptedAtMillis: ScheduleInstant,
+  occurredAtMillis: Schema.optionalKey(ScheduleInstant),
+  /** Deduplication evidence after completed payload/delivery retention ends. */
+  tombstone: Schema.optionalKey(Schema.Boolean),
+  cutoff: Schema.Natural,
+  cursor: Schema.Natural,
+  routingComplete: Schema.Boolean,
+  routingFailure: Schema.NullOr(SubscriptionName),
+  nextAttemptAtMillis: ScheduleInstant,
+}).check(
+  Schema.makeFilter(
+    (value) =>
+      value.cursor <= value.cutoff &&
+      (value.tombstone !== true || (value.payload === null && value.routingComplete)),
+  ),
+);
+
+export type AcceptedEvent = typeof AcceptedEvent.Type;
+
+export const EventAcknowledgement = Schema.Struct({
+  partition: SourcePartition,
+  eventId: SubscriptionName,
+  acceptedAtMillis: ScheduleInstant,
+});
+
+export type EventAcknowledgement = typeof EventAcknowledgement.Type;
+
+/** Common admission data; neither a schedule cursor nor a subscription lifecycle lives here. */
+export const PreparedInput = Schema.Struct({
+  schemaVersion: Schema.Literal(1),
+  threadId: ThreadId,
+  deliveryPrincipal: Principal,
+  admissionGroup: Schema.optionalKey(AdmissionGroup),
+  admissionFence: Schema.optionalKey(AdmissionFence),
+  agentId: AgentId,
+  definitions: DefinitionDigests,
+  input: PersistedJson,
+  inputDigest: Digest,
+  admissionKey: IdempotencyKey,
+  authorization: ScheduleAuthorizationDecision,
+  workerAdmission: Schema.optionalKey(WorkerAdmission),
+  messageAdmission: Schema.optionalKey(InputMessage),
+});
+
+export type PreparedInput = typeof PreparedInput.Type;
+
+export const SubscriptionDeliveryKey = Schema.Struct({
+  subscription: SubscriptionKey,
+  eventId: SubscriptionName,
+});
+
+export type SubscriptionDeliveryKey = typeof SubscriptionDeliveryKey.Type;
+
+export const SubscriptionRefusal = Schema.Struct({
+  phase: Schema.Literals(["preparation", "admission"]),
+  code: SubscriptionName,
+});
+
+export const SubscriptionDelivery = Schema.Struct({
+  schemaVersion: Schema.Literal(1),
+  key: SubscriptionDeliveryKey,
+  deliveryId: Digest,
+  subscriptionFingerprint: Digest,
+  configurationRevision: Positive,
+  configuration: SubscriptionConfiguration,
+  eventDigest: Digest,
+  source: EventSourceVersion,
+  threadId: ThreadId,
+  admissionKey: IdempotencyKey,
+  selectedAtMillis: ScheduleInstant,
+  observeSettlement: Schema.optionalKey(Schema.Boolean),
+  settledAtMillis: Schema.optionalKey(ScheduleInstant),
+  completedAtMillis: Schema.optionalKey(ScheduleInstant),
+  state: Schema.Literals(["selected", "prepared", "delivered", "refused"]),
+  envelope: Schema.NullOr(PreparedInput),
+  envelopeDigest: Schema.NullOr(Digest),
+  retry: ScheduleRetry,
+  receipt: Schema.NullOr(Receipt),
+  refusal: Schema.NullOr(SubscriptionRefusal),
+}).check(
+  Schema.makeFilter((value) => {
+    const hasEnvelope = value.envelope !== null && value.envelopeDigest !== null;
+    const noEnvelope = value.envelope === null && value.envelopeDigest === null;
+
+    switch (value.state) {
+      case "selected":
+        return noEnvelope && value.receipt === null && value.refusal === null;
+      case "prepared":
+        return hasEnvelope && value.receipt === null && value.refusal === null;
+      case "delivered":
+        return hasEnvelope && value.receipt !== null && value.refusal === null;
+      case "refused":
+        return (
+          value.receipt === null &&
+          value.refusal !== null &&
+          (value.refusal.phase === "preparation" ? noEnvelope : hasEnvelope)
+        );
+    }
+  }),
+);
+
+export type SubscriptionDelivery = typeof SubscriptionDelivery.Type;
+
+/** Management projections intentionally exclude parameters, context, payload, and input. */
+export const SubscriptionSnapshot = Schema.Struct({
+  key: SubscriptionKey,
+  source: EventSourceVersion,
+  mode: Schema.Literals(["once", "continuous"]),
+  state: Schema.Literals(["active", "paused", "consumed", "cancelled", "expired"]),
+  configurationRevision: Positive,
+  configurationFingerprint: Digest,
+  admissionGroup: SubscriptionConfiguration.fields.admissionGroup,
+  admissionFence: SubscriptionConfiguration.fields.admissionFence,
+  createdAtMillis: ScheduleInstant,
+  /** Null disables time-based expiry; once selection and cancellation still apply. */
+  expiresAtMillis: Schema.NullOr(ScheduleInstant),
+  recovery: Schema.NullOr(SourceRecovery),
+});
+
+export type SubscriptionSnapshot = typeof SubscriptionSnapshot.Type;
+
+export const SubscriptionDeliverySnapshot = Schema.Struct({
+  key: SubscriptionDeliveryKey,
+  state: SubscriptionDelivery.fields.state,
+  configurationRevision: Positive,
+  observeSettlement: Schema.optionalKey(Schema.Boolean),
+  settledAtMillis: Schema.optionalKey(ScheduleInstant),
+  retry: ScheduleRetry,
+  receipt: Schema.NullOr(Receipt),
+  refusal: Schema.NullOr(SubscriptionRefusal),
+});
+
+export class SubscriptionError extends Schema.TaggedError<SubscriptionError>()(
+  "SubscriptionError",
+  {
+    reason: Schema.Literals([
+      "validation",
+      "conflict",
+      "not-found",
+      "capacity",
+      "unauthorized",
+      "unsupported-source",
+      "unsupported-binding",
+      "storage",
+      "corrupt",
+    ]),
+    code: SubscriptionName,
+    cause: Schema.optionalKey(Schema.Defect()),
+    currentRevision: Schema.optionalKey(Positive),
+    currentState: Schema.optionalKey(
+      Schema.Literals(["active", "paused", "consumed", "cancelled"]),
+    ),
+  },
+) {}
+
+/** Host source adapters classify expected failures; raw provider diagnostics are never stored. */
+export class SubscriptionSourceError extends Schema.TaggedError<SubscriptionSourceError>()(
+  "SubscriptionSourceError",
+  {
+    code: SubscriptionName,
+    retryable: Schema.Boolean,
+  },
+) {}
+
+export class SubscriptionFailpointError extends Schema.TaggedError<SubscriptionFailpointError>()(
+  "SubscriptionFailpointError",
+  { point: Schema.String },
+) {}
+
+export type SubscriptionStoreFailure = SubscriptionError | SubscriptionFailpointError;
+
+export const SubscriptionFailpoint = Context.Reference<{
+  readonly hit: (point: string) => Effect.Effect<void, SubscriptionFailpointError>;
+}>("@effect-agent/thread/SubscriptionFailpoint", {
+  defaultValue: () => ({ hit: () => Effect.void }),
+});
+
+export const SubscriptionRetentionPolicy = Schema.Struct({
+  replayHorizonMillis: Positive,
+  completedRetentionMillis: Schema.Natural,
+  maxTombstones: Positive.check(Schema.isLessThanOrEqualTo(100_000)),
+});
+
+export type SubscriptionRetentionPolicy = typeof SubscriptionRetentionPolicy.Type;
+
+export const SubscriptionLimits = Schema.Struct({
+  retention: Schema.optionalKey(SubscriptionRetentionPolicy),
+  maxRegistrations: Positive.check(Schema.isLessThanOrEqualTo(100_000)),
+  maxRegistrationsPerOwner: Positive.check(Schema.isLessThanOrEqualTo(10_000)),
+  maxEvents: Positive.check(Schema.isLessThanOrEqualTo(100_000)),
+  maxDeliveries: Positive.check(Schema.isLessThanOrEqualTo(100_000)),
+  maxDeliveriesPerOwner: Positive.check(Schema.isLessThanOrEqualTo(10_000)),
+  maxPayloadBytes: Positive.check(Schema.isLessThanOrEqualTo(65_536)),
+  maxContextBytes: Positive.check(Schema.isLessThanOrEqualTo(16_384)),
+  maxLifetimeMillis: Positive.check(Schema.isLessThanOrEqualTo(8_640_000_000_000_000)),
+  batchSize: Positive.check(Schema.isLessThanOrEqualTo(100)),
+  concurrency: Positive.check(Schema.isLessThanOrEqualTo(16)),
+  retryMillis: Positive.check(Schema.isLessThanOrEqualTo(86_400_000)),
+  maxAutomaticAttempts: Schema.optionalKey(Positive),
+  operationTimeoutMillis: Positive.check(Schema.isLessThanOrEqualTo(300_000)),
+});
+
+export type SubscriptionLimits = typeof SubscriptionLimits.Type;
+
+export const defaultSubscriptionLimits: SubscriptionLimits = {
+  maxRegistrations: 10_000,
+  maxRegistrationsPerOwner: 1_000,
+  maxEvents: 10_000,
+  maxDeliveries: 10_000,
+  maxDeliveriesPerOwner: 1_000,
+  maxPayloadBytes: 65_536,
+  maxContextBytes: 16_384,
+  maxLifetimeMillis: 30 * 86_400_000,
+  batchSize: 16,
+  concurrency: 4,
+  retryMillis: 30_000,
+  operationTimeoutMillis: 30_000,
+  maxAutomaticAttempts: 8,
+};
+
+export const SubscriptionChange = Schema.Union([
+  Schema.Struct({ _tag: Schema.Literal("Recover"), nowMillis: ScheduleInstant }),
+  Schema.Struct({
+    _tag: Schema.Literal("Update"),
+    configuration: SubscriptionConfiguration,
+    configurationFingerprint: Digest,
+    recovery: Schema.NullOr(SourceRecovery),
+  }),
+  Schema.Struct({ _tag: Schema.Literals(["Pause", "Resume"]) }),
+]);
+
+export type SubscriptionChange = typeof SubscriptionChange.Type;
+
+export const DeliveryChange = Schema.Union([
+  Schema.Struct({
+    _tag: Schema.Literal("ObserveSettlement"),
+    receipt: Receipt,
+    settled: Schema.Boolean,
+    nowMillis: ScheduleInstant,
+    nextAttemptAtMillis: ScheduleInstant,
+  }),
+  Schema.Struct({
+    _tag: Schema.Literal("Recover"),
+    expectedGeneration: Schema.Natural,
+    nowMillis: ScheduleInstant,
+  }),
+  Schema.Struct({
+    _tag: Schema.Literal("Prepare"),
+    envelope: PreparedInput,
+    envelopeDigest: Digest,
+    nowMillis: ScheduleInstant,
+  }),
+  Schema.Struct({ _tag: Schema.Literal("Complete"), receipt: Receipt, nowMillis: ScheduleInstant }),
+  Schema.Struct({
+    _tag: Schema.Literal("Refuse"),
+    refusal: SubscriptionRefusal,
+    nowMillis: ScheduleInstant,
+  }),
+  Schema.Struct({
+    _tag: Schema.Literal("Retry"),
+    retry: ScheduleRetry,
+    nowMillis: ScheduleInstant,
+  }),
+]);
+
+export type DeliveryChange = typeof DeliveryChange.Type;
+
+/** Progress of bounded recovery sweeps, independent of individual work success. */
+export const SubscriptionScanCursors = Schema.Struct({
+  events: Schema.String,
+  deliveries: Schema.String,
+  recovery: Schema.Natural,
+});
+
+export type SubscriptionScanCursors = typeof SubscriptionScanCursors.Type;
+
+/**
+ * One store instance owns exactly one tenant/source partition. Every mutation is local and
+ * atomic, including required Cloudflare wakes. Node has one process owner per database.
+ * Records are retained for the partition lifetime; hard quotas reject new retained work.
+ * No pruning may discard creation replay, deduplication, or unfinished-work evidence.
+ */
+export class SubscriptionStore extends Context.Service<
+  SubscriptionStore,
+  {
+    readonly partition: SourcePartition;
+    readonly compact: (
+      nowMillis: number,
+      policy: SubscriptionRetentionPolicy,
+      limit: number,
+    ) => Effect.Effect<number, SubscriptionStoreFailure>;
+    readonly readScanCursors: Effect.Effect<SubscriptionScanCursors, SubscriptionError>;
+    readonly advanceScanCursors: (
+      cursors: SubscriptionScanCursors,
+    ) => Effect.Effect<void, SubscriptionStoreFailure>;
+    readonly register: (
+      record: SubscriptionRecord,
+      limits: SubscriptionLimits,
+    ) => Effect.Effect<SubscriptionRecord, SubscriptionStoreFailure>;
+    readonly get: (
+      key: SubscriptionKey,
+    ) => Effect.Effect<SubscriptionRecord | null, SubscriptionError>;
+    readonly list: (
+      ownerId: string,
+      after: number,
+      limit: number,
+    ) => Effect.Effect<ReadonlyArray<SubscriptionRecord>, SubscriptionError>;
+    readonly change: (
+      key: SubscriptionKey,
+      expectedRevision: number,
+      change: SubscriptionChange,
+    ) => Effect.Effect<SubscriptionRecord, SubscriptionStoreFailure>;
+    readonly cancel: (
+      key: SubscriptionKey,
+      expectedRevision?: number,
+    ) => Effect.Effect<SubscriptionRecord, SubscriptionStoreFailure>;
+    /** Duplicate identity returns the original cutoff and routing progress; payload/version conflicts fail. */
+    readonly accept: (
+      event: AcceptedEvent,
+      limits: SubscriptionLimits,
+    ) => Effect.Effect<AcceptedEvent, SubscriptionStoreFailure>;
+    readonly event: (eventId: string) => Effect.Effect<AcceptedEvent | null, SubscriptionError>;
+    readonly pendingEvents: (
+      nowMillis: number,
+      after: string,
+      limit: number,
+    ) => Effect.Effect<ReadonlyArray<string>, SubscriptionError>;
+    /** Indexed by partition, source/version, matchingKey, ordinal; never scan arbitrary parameters. */
+    readonly candidates: (
+      event: AcceptedEvent,
+      limit: number,
+    ) => Effect.Effect<ReadonlyArray<SubscriptionRecord>, SubscriptionError>;
+    /** Recheck cursor, eligibility, lifecycle and expiry; consume once + insert obligations + cursor together. */
+    readonly select: (
+      event: AcceptedEvent,
+      deliveries: ReadonlyArray<SubscriptionDelivery>,
+      cursor: number,
+      complete: boolean,
+      nowMillis: number,
+      limits: SubscriptionLimits,
+    ) => Effect.Effect<void, SubscriptionStoreFailure>;
+    /** Only the explicitly reconciled watch may bypass cutoff, never reopen ordinary routing. */
+    readonly catchUp: (
+      event: AcceptedEvent,
+      delivery: SubscriptionDelivery,
+      nowMillis: number,
+      limits: SubscriptionLimits,
+    ) => Effect.Effect<void, SubscriptionStoreFailure>;
+    readonly deferEvent: (
+      eventId: string,
+      nextAttemptAtMillis: number,
+      code?: string,
+    ) => Effect.Effect<void, SubscriptionStoreFailure>;
+    readonly delivery: (
+      key: SubscriptionDeliveryKey,
+    ) => Effect.Effect<SubscriptionDelivery | null, SubscriptionError>;
+    readonly pendingDeliveries: (
+      nowMillis: number,
+      after: string,
+      limit: number,
+    ) => Effect.Effect<ReadonlyArray<SubscriptionDeliveryKey>, SubscriptionError>;
+    readonly listDeliveries: (
+      key: SubscriptionKey,
+      after: string,
+      limit: number,
+    ) => Effect.Effect<ReadonlyArray<SubscriptionDelivery>, SubscriptionError>;
+    /**
+     * A matching deliveryId fences stale outcomes. Prepare rechecks cancellation and expiry atomically.
+     * Retry advances only with a higher attempt count and a nondecreasing next-attempt time.
+     */
+    readonly changeDelivery: (
+      key: SubscriptionDeliveryKey,
+      deliveryId: Digest,
+      change: DeliveryChange,
+    ) => Effect.Effect<SubscriptionDelivery, SubscriptionStoreFailure>;
+    readonly recovering: (
+      nowMillis: number,
+      after: number,
+      limit: number,
+    ) => Effect.Effect<
+      ReadonlyArray<{ readonly key: SubscriptionKey; readonly ordinal: number }>,
+      SubscriptionError
+    >;
+    readonly deferRecovery: (
+      key: SubscriptionKey,
+      expectedRevision: number,
+      recovery: typeof SourceRecovery.Type | null,
+    ) => Effect.Effect<void, SubscriptionStoreFailure>;
+    readonly nextDeadline: Effect.Effect<number | null, SubscriptionError>;
+  }
+>()("@effect-agent/thread/SubscriptionStore") {}
+
+/** Explicit host policy. Management scope is not inferred from handle possession. */
+export class SubscriptionAuthorizer extends Context.Service<
+  SubscriptionAuthorizer,
+  {
+    readonly manage: (
+      operation:
+        | "get"
+        | "subscribe"
+        | "update"
+        | "pause"
+        | "resume"
+        | "recover"
+        | "list"
+        | "cancel"
+        | "deliveries",
+      scope: SubscriptionScope,
+      configuration?: SubscriptionConfiguration,
+    ) => Effect.Effect<void, SubscriptionError>;
+    readonly intake: (
+      partition: SourcePartition,
+      source: EventSourceVersion,
+      principal: Principal,
+    ) => Effect.Effect<void, SubscriptionError>;
+    /** Host recovery authority, independent of the principal who registered the watch. */
+    readonly reconcile: (
+      subscription: SubscriptionRecord,
+    ) => Effect.Effect<void, SubscriptionError>;
+    readonly prepare: (
+      subscription: SubscriptionRecord,
+      event: AcceptedEvent,
+    ) => Effect.Effect<typeof ScheduleAuthorizationDecision.Type, SubscriptionError>;
+  }
+>()("@effect-agent/thread/SubscriptionAuthorizer") {}
+
+export const subscriptionKeyString = (key: SubscriptionKey): string =>
+  JSON.stringify([key.partition.tenantId, key.partition.address, key.ownerId, key.subscriptionId]);
+
+export const subscriptionDeliveryKeyString = (key: SubscriptionDeliveryKey): string =>
+  JSON.stringify([key.subscription.ownerId, key.subscription.subscriptionId, key.eventId]);

package/src/durable/SubscriptionInput.ts

@@ -0,0 +1,144 @@
+import { Context, Effect, Schema, type Scope } from "effect";
+
+import { type AgentId } from "../core/Identifiers.ts";
+import { definitionDigestsEqual } from "./internal/agent-registration.ts";
+import { type DefinitionDigests, PersistedJson } from "./Records.ts";
+import {
+  type AcceptedEvent,
+  type EventSourceVersion,
+  type SubscriptionConfiguration,
+  type SubscriptionRecord,
+  SubscriptionError,
+  SubscriptionSourceError,
+} from "./Subscription.ts";
+
+/** Host-retained preparation code for one source and exact destination Agent definition. */
+export interface SubscriptionInputBinding {
+  readonly source: EventSourceVersion;
+  readonly agentId: AgentId;
+  readonly definitions: DefinitionDigests;
+  readonly context: (value: unknown) => Effect.Effect<PersistedJson, SubscriptionSourceError>;
+  readonly prepare: (
+    event: AcceptedEvent,
+    subscription: SubscriptionRecord,
+  ) => Effect.Effect<PersistedJson, SubscriptionSourceError>;
+}
+
+export class SubscriptionInputBindings extends Context.Service<
+  SubscriptionInputBindings,
+  { readonly bindings: ReadonlyArray<SubscriptionInputBinding> }
+>()("@effect-agent/thread/SubscriptionInputBindings") {}
+
+/** Missing or ambiguous code stays pending. Never substitute a newer destination definition. */
+export const resolveSubscriptionInput = (
+  bindings: ReadonlyArray<SubscriptionInputBinding>,
+  configuration: Pick<SubscriptionConfiguration, "source" | "agentId" | "definitions">,
+): Effect.Effect<SubscriptionInputBinding, SubscriptionError> => {
+  const found = bindings.filter(
+    (binding) =>
+      binding.source.name === configuration.source.name &&
+      binding.source.version === configuration.source.version &&
+      binding.agentId === configuration.agentId &&
+      definitionDigestsEqual(binding.definitions, configuration.definitions),
+  );
+
+  const binding = found[0];
+
+  return found.length === 1 && binding !== undefined
+    ? Effect.succeed(binding)
+    : Effect.fail(SubscriptionError.make({ reason: "unsupported-binding", code: "input-binding" }));
+};
+
+/**
+ * Capture explicit dependencies at host assembly. Pass the destination definition's input Schema.
+ * Include the context Schema and mapper in its retained definition version; changing either
+ * requires new definition digests. Preparation may repeat until its envelope is committed.
+ * Each operation owns a fresh Scope for its callbacks and codecs; captured host services
+ * retain their host lifetime. Operation resources finalize on success, failure, or interruption.
+ */
+export const makeSubscriptionInputBinding = Effect.fn("Thread.makeSubscriptionInputBinding")(
+  function* <
+    Event extends Schema.Top,
+    Parameters extends Schema.Top,
+    Continuation extends Schema.Top,
+    Input extends Schema.Top,
+    R,
+  >(options: {
+    readonly source: EventSourceVersion;
+    readonly agentId: AgentId;
+    readonly definitions: DefinitionDigests;
+    readonly event: Event;
+    readonly parameters: Parameters;
+    readonly context: Continuation;
+    readonly input: Input;
+    readonly prepare: (
+      event: Event["Type"],
+      parameters: Parameters["Type"],
+      context: Continuation["Type"],
+    ) => Effect.Effect<Input["Type"], SubscriptionSourceError, R>;
+  }): Effect.fn.Return<
+    SubscriptionInputBinding,
+    never,
+    Exclude<
+      | R
+      | Event["DecodingServices"]
+      | Parameters["DecodingServices"]
+      | Continuation["DecodingServices"]
+      | Continuation["EncodingServices"]
+      | Input["EncodingServices"],
+      Scope.Scope
+    >
+  > {
+    const services =
+      yield* Effect.context<
+        Exclude<
+          | R
+          | Event["DecodingServices"]
+          | Parameters["DecodingServices"]
+          | Continuation["DecodingServices"]
+          | Continuation["EncodingServices"]
+          | Input["EncodingServices"],
+          Scope.Scope
+        >
+      >();
+
+    const invalid = () =>
+      SubscriptionSourceError.make({ code: "input-binding-schema", retryable: false });
+
+    const encode = <S extends Schema.Top>(schema: S, value: S["Type"]) =>
+      Schema.encodeEffect(schema)(value).pipe(
+        Effect.flatMap(Schema.decodeUnknownEffect(PersistedJson)),
+        Effect.mapError(invalid),
+      );
+
+    return {
+      source: options.source,
+      agentId: options.agentId,
+      definitions: options.definitions,
+      context: (value) =>
+        Schema.decodeUnknownEffect(PersistedJson)(value).pipe(
+          Effect.flatMap(Schema.decodeUnknownEffect(options.context)),
+          Effect.mapError(invalid),
+          Effect.flatMap((decoded) => encode(options.context, decoded)),
+          Effect.scoped,
+          Effect.provideContext(services),
+        ),
+      prepare: (event, subscription) =>
+        Effect.gen(function* () {
+          const e = yield* Schema.decodeEffect(options.event)(event.payload).pipe(
+            Effect.mapError(invalid),
+          );
+
+          const p = yield* Schema.decodeEffect(options.parameters)(
+            subscription.configuration.parameters,
+          ).pipe(Effect.mapError(invalid));
+
+          const c = yield* Schema.decodeEffect(options.context)(
+            subscription.configuration.context,
+          ).pipe(Effect.mapError(invalid));
+
+          return yield* encode(options.input, yield* options.prepare(e, p, c));
+        }).pipe(Effect.scoped, Effect.provideContext(services)),
+    };
+  },
+);