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

package/src/durable/DurableFailpoint.ts

@@ -0,0 +1,103 @@
+import { Context, Effect, Layer, Schema } from "effect";
+
+/**
+ * Coordinator-owned failpoint locations (plan §Failpoints). Locations normally sit immediately
+ * AFTER one durable mutation of the six-step coordinator flow, so a fault injected there
+ * simulates a crash between two durable steps; the matching BEFORE boundary of each mutation is
+ * owned by the storage adapters (`ledger:*:before`, `append:before`, ...), giving every durable
+ * mutation a failpoint on both sides (change discipline). Run-start append also exposes its
+ * BEFORE boundary here to distinguish a fresh clock from a committed clock in crash tests.
+ *
+ * The `subagent:*` family covers every durable mutation of the S2 establishment/join protocol
+ * including reservation, request append, child admission, child readiness,
+ * start-link append, sibling per-call settles at the suspension seam, the `waitingForChild`
+ * suspension, child abort propagation, the atomic join batch, and both reservation-release
+ * transitions.
+ */
+export const DurableRuntimeFailpointLocation = Schema.Literals([
+  "submit:after-admit",
+  "submit:after-materialize",
+  "claim:after-claim",
+  "input:after-canonical-append",
+  "run:before-start-append",
+  "run:after-start-append",
+  "turn:after-canonical-append",
+  "turn:after-response-append",
+  "turn:after-results-append",
+  "compaction:before-canonical-append",
+  "compaction:after-canonical-append",
+  "checkpoint:before-save",
+  "checkpoint:after-save",
+  "tools:after-prepared-append",
+  "tools:before-prepared-append",
+  "policy:before-reservation-append",
+  "policy:after-reservation-append",
+  "step:after-step-append",
+  "approval:after-request-append",
+  "approval:after-suspend",
+  "join:after-claim",
+  "join:after-canonical-append",
+  "resolve:after-intent",
+  "terminalize:after-reserve",
+  "terminalize:after-canonical-append",
+  "abort:after-intent",
+  "subagent:after-reserve",
+  "subagent:after-request-append",
+  "subagent:after-admit",
+  "subagent:after-child-ready",
+  "subagent:after-start-append",
+  "subagent:after-sibling-settle",
+  "subagent:after-suspend",
+  "subagent:after-child-abort-intent",
+  "subagent:before-join-append",
+  "subagent:after-join-append",
+  "subagent:after-release-pending",
+  "subagent:after-release",
+  "worker:before-source-append",
+  "worker:after-source-append",
+  "worker:before-origin-append",
+  "worker:after-origin-append",
+  "worker:before-completion-append",
+  "worker:after-completion-append",
+  "worker:before-subtree-append",
+  "worker:after-subtree-append",
+  "worker:before-report-append",
+  "worker:after-report-append",
+  "worker:before-report-delivery",
+  "worker:after-report-delivery",
+  "update:before-canonical-append",
+  "update:after-canonical-append",
+  "update:before-delivery-insert",
+  "update:after-delivery-insert",
+]);
+
+export type DurableRuntimeFailpointLocation = typeof DurableRuntimeFailpointLocation.Type;
+
+/** Injected coordinator fault. Reaching the caller means the preceding durable step committed. */
+export class DurableRuntimeFailpointError extends Schema.TaggedError<DurableRuntimeFailpointError>()(
+  "DurableRuntimeFailpointError",
+  {
+    location: DurableRuntimeFailpointLocation,
+  },
+) {}
+
+export type DurableRuntimeFailpointHandler = (
+  location: DurableRuntimeFailpointLocation,
+) => Effect.Effect<void, DurableRuntimeFailpointError>;
+
+const noFailpoint: DurableRuntimeFailpointHandler = () => Effect.void;
+
+/**
+ * Explicit fault-injection authority used at durable coordinator step boundaries. The process
+ * crash harness (WP5) maps a hit to `process.exit`; in-process tests fail the step with the
+ * typed `DurableRuntimeFailpointError` instead.
+ */
+export class DurableRuntimeFailpoint extends Context.Service<
+  DurableRuntimeFailpoint,
+  {
+    readonly hit: DurableRuntimeFailpointHandler;
+  }
+>()("@effect-agent/thread/DurableRuntimeFailpoint") {
+  /** Production default: no fault injection. */
+  static readonly layer = Layer.succeed(this)({ hit: noFailpoint });
+}

package/src/durable/DurableFailpointTestControl.ts

@@ -0,0 +1,39 @@
+import { Context, Effect, Layer, Ref } from "effect";
+
+import {
+  DurableRuntimeFailpoint,
+  type DurableRuntimeFailpointHandler,
+} from "./DurableFailpoint.ts";
+
+const noFailpoint: DurableRuntimeFailpointHandler = () => Effect.void;
+
+/** Test-only control for replacing the active coordinator failpoint handler. */
+export class DurableRuntimeFailpointTestControl extends Context.Service<
+  DurableRuntimeFailpointTestControl,
+  {
+    readonly clear: Effect.Effect<void>;
+    readonly setHandler: (handler: DurableRuntimeFailpointHandler) => Effect.Effect<void>;
+  }
+>()("@effect-agent/thread/DurableRuntimeFailpointTestControl") {
+  /** Reusable test Layer with a control service backed by the same handler Ref. */
+  static readonly layer = Layer.effectContext(
+    Effect.gen(function* () {
+      const handler = yield* Ref.make<DurableRuntimeFailpointHandler>(noFailpoint);
+
+      return Context.make(
+        DurableRuntimeFailpoint,
+        DurableRuntimeFailpoint.of({
+          hit: (location) => Ref.get(handler).pipe(Effect.flatMap((current) => current(location))),
+        }),
+      ).pipe(
+        Context.add(
+          DurableRuntimeFailpointTestControl,
+          DurableRuntimeFailpointTestControl.of({
+            clear: Ref.set(handler, noFailpoint),
+            setHandler: (next) => Ref.set(handler, next),
+          }),
+        ),
+      );
+    }),
+  );
+}

package/src/durable/EventSource.ts

@@ -0,0 +1,172 @@
+import { Context, Effect, Schema, type Scope } from "effect";
+
+import { PersistedJson } from "./Records.ts";
+import {
+  type AcceptedEvent,
+  type EventSourceVersion,
+  type SubscriptionRecord,
+  SubscriptionSourceError,
+} from "./Subscription.ts";
+
+export interface NormalizedEvent {
+  readonly eventId: string;
+  readonly occurredAtMillis?: number;
+  readonly matchingKey: string;
+  readonly payload: PersistedJson;
+}
+
+/** Runtime-only versioned behavior. Never persist this object or silently replace its version. */
+export interface EventSource {
+  readonly source: EventSourceVersion;
+  readonly continuity: string;
+  readonly parameters: (
+    value: unknown,
+  ) => Effect.Effect<
+    { readonly parameters: PersistedJson; readonly matchingKey: string },
+    SubscriptionSourceError
+  >;
+  readonly normalize: (value: unknown) => Effect.Effect<NormalizedEvent, SubscriptionSourceError>;
+  readonly matches: (
+    event: AcceptedEvent,
+    subscription: SubscriptionRecord,
+  ) => Effect.Effect<boolean, SubscriptionSourceError>;
+  readonly reconcile?: (
+    subscription: SubscriptionRecord,
+  ) => Effect.Effect<NormalizedEvent | null, SubscriptionSourceError>;
+}
+
+export class EventSources extends Context.Service<
+  EventSources,
+  {
+    readonly sources: ReadonlyArray<EventSource>;
+  }
+>()("@effect-agent/thread/EventSources") {}
+
+const invalid = () => SubscriptionSourceError.make({ code: "source-schema", retryable: false });
+
+/**
+ * Capture the source's explicit Effect dependencies at host assembly. Matching and key functions
+ * must be pure and bounded under this exact semantic version.
+ * The returned source accepts Schema-encoded values at intake and management boundaries.
+ * 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 makeEventSource = Effect.fn("Thread.makeEventSource")(function* <
+  Event extends Schema.Top,
+  Parameters extends Schema.Top,
+  R = never,
+>(options: {
+  readonly source: EventSourceVersion;
+  readonly continuity: string;
+  readonly event: Event;
+  readonly parameters: Parameters;
+  readonly identity: (event: Event["Type"]) => string;
+  /** Authenticated source time, stable across delivery retries; required for bounded retention. */
+  readonly occurredAtMillis?: (event: Event["Type"]) => number | undefined;
+  readonly eventKey: (event: Event["Type"]) => string;
+  readonly parameterKey: (parameters: Parameters["Type"]) => string;
+  readonly matches: (event: Event["Type"], parameters: Parameters["Type"]) => boolean;
+  readonly reconcile?: (
+    parameters: Parameters["Type"],
+  ) => Effect.Effect<Event["Type"] | null, SubscriptionSourceError, R>;
+}): Effect.fn.Return<
+  EventSource,
+  never,
+  Exclude<
+    | R
+    | Event["DecodingServices"]
+    | Event["EncodingServices"]
+    | Parameters["DecodingServices"]
+    | Parameters["EncodingServices"],
+    Scope.Scope
+  >
+> {
+  const services =
+    yield* Effect.context<
+      Exclude<
+        | R
+        | Event["DecodingServices"]
+        | Event["EncodingServices"]
+        | Parameters["DecodingServices"]
+        | Parameters["EncodingServices"],
+        Scope.Scope
+      >
+    >();
+
+  const encode = <S extends Schema.Top>(schema: S, value: S["Type"]) =>
+    Schema.encodeEffect(schema)(value).pipe(
+      Effect.flatMap(Schema.decodeUnknownEffect(PersistedJson)),
+      Effect.mapError(invalid),
+    );
+
+  const normalized = Effect.fn("EventSource.normalized")(function* (event: Event["Type"]) {
+    const occurredAtMillis = options.occurredAtMillis?.(event);
+
+    return {
+      eventId: options.identity(event),
+      ...(occurredAtMillis === undefined ? {} : { occurredAtMillis }),
+      matchingKey: options.eventKey(event),
+      payload: yield* encode(options.event, event),
+    };
+  });
+
+  const normalize: EventSource["normalize"] = (value) =>
+    Schema.decodeUnknownEffect(PersistedJson)(value).pipe(
+      Effect.flatMap(Schema.decodeUnknownEffect(options.event)),
+      Effect.mapError(invalid),
+      Effect.flatMap(normalized),
+      Effect.scoped,
+      Effect.provideContext(services),
+    );
+
+  const parameters: EventSource["parameters"] = (value) =>
+    Effect.gen(function* () {
+      yield* Schema.decodeUnknownEffect(PersistedJson)(value).pipe(Effect.mapError(invalid));
+
+      const decoded = yield* Schema.decodeUnknownEffect(options.parameters)(value).pipe(
+        Effect.mapError(invalid),
+      );
+
+      return {
+        parameters: yield* encode(options.parameters, decoded),
+        matchingKey: options.parameterKey(decoded),
+      };
+    }).pipe(Effect.scoped, Effect.provideContext(services));
+
+  const matches: EventSource["matches"] = (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));
+
+      return options.matches(e, p);
+    }).pipe(Effect.scoped, Effect.provideContext(services));
+
+  const reconcile = options.reconcile;
+
+  return {
+    source: options.source,
+    continuity: options.continuity,
+    parameters,
+    normalize,
+    matches,
+    ...(reconcile === undefined
+      ? {}
+      : {
+          reconcile: (subscription: SubscriptionRecord) =>
+            Effect.gen(function* () {
+              const p = yield* Schema.decodeEffect(options.parameters)(
+                subscription.configuration.parameters,
+              ).pipe(Effect.mapError(invalid));
+
+              const event = yield* reconcile(p);
+
+              return event === null ? null : yield* normalized(event);
+            }).pipe(Effect.scoped, Effect.provideContext(services)),
+        }),
+  };
+});