effect-agent 0.1.0-beta.15 → 0.1.0-beta.151

package/src/durable/MessageDeliveryStoreConformance.ts

@@ -0,0 +1,410 @@
+import { DateTime, Effect, Equal, Result, Schema } from "effect";
+
+import { Update } from "../core/AgentUpdates.ts";
+import {
+  AgentId,
+  ReceiptId,
+  SettlementId,
+  SubmissionId,
+  ThreadId,
+  RunId,
+  DelegationId,
+} from "../core/Identifiers.ts";
+import { WorkerUpdate } from "../core/Worker.ts";
+import { digestJson } from "./Digest.ts";
+import { Receipt } from "./DurableAgentRuntime.ts";
+import {
+  MessageDeliveryStore,
+  readPending,
+  messageDeliveryCapacity,
+  prepareMessageDelivery,
+} from "./MessageDelivery.ts";
+import { DefinitionDigests, Digest } from "./Records.ts";
+import { IdempotencyKey, Principal, QueueSequence, Settlement } from "./SubmissionLedger.ts";
+
+export class MessageDeliveryConformanceViolation extends Schema.TaggedError<MessageDeliveryConformanceViolation>()(
+  "MessageDeliveryConformanceViolation",
+  { message: Schema.String },
+) {}
+
+const verify = (condition: boolean, message: string) =>
+  condition ? Effect.void : Effect.fail(MessageDeliveryConformanceViolation.make({ message }));
+
+/** One valid frozen envelope shared by real storage and restart tests. */
+export const makeMessageDeliveryFixture = Effect.fn("MessageDeliveryConformance.fixture")(
+  function* (messageId = "message", owner = "sender", text = "hello") {
+    const digest = Schema.decodeSync(Digest)("a".repeat(64));
+    const input = { text };
+
+    return yield* prepareMessageDelivery({
+      key: {
+        ownerThreadId: Schema.decodeSync(ThreadId)(owner),
+        messageId: Schema.decodeSync(IdempotencyKey)(messageId),
+      },
+      createdAtMillis: 0,
+      deadlineAtMillis: 1_000,
+      policy: {
+        maxAutomaticAttempts: 3,
+        attemptTimeoutMillis: 100,
+        retryBaseMillis: 10,
+        retryMaxMillis: 20,
+        settlementPollMillis: 5,
+      },
+      envelope: {
+        schemaVersion: 1,
+        threadId: Schema.decodeSync(ThreadId)("receiver"),
+        deliveryPrincipal: Schema.decodeSync(Principal)("principal"),
+        agentId: Schema.decodeSync(AgentId)("agent"),
+        definitions: DefinitionDigests.make({ agent: digest, model: digest, tools: digest }),
+        input,
+        inputDigest: yield* digestJson(input),
+        admissionKey: Schema.decodeSync(IdempotencyKey)(`admit:${owner}:${messageId}`),
+        authorization: { policyId: "policy", decisionId: "decision" },
+      },
+    });
+  },
+);
+
+export const messageDeliveryFixtureReceipt = Receipt.make({
+  threadId: Schema.decodeSync(ThreadId)("receiver"),
+  receiptId: Schema.decodeSync(ReceiptId)("receipt"),
+  submissionId: Schema.decodeSync(SubmissionId)("submission"),
+  queueSequence: Schema.decodeSync(QueueSequence)(0),
+});
+
+export const makeWorkerUpdateDeliveryFixture = Effect.fn(
+  "MessageDeliveryConformance.updateFixture",
+)(function* (id: string) {
+  const base = yield* makeMessageDeliveryFixture(id);
+
+  return yield* prepareMessageDelivery({
+    key: base.key,
+    createdAtMillis: base.createdAtMillis,
+    deadlineAtMillis: base.deadlineAtMillis,
+    policy: base.policy,
+    envelope: {
+      ...base.envelope,
+      messageAdmission: WorkerUpdate.make({
+        _tag: "WorkerUpdate",
+        schemaVersion: 1,
+        worker: {
+          schemaVersion: 1,
+          delegationId: Schema.decodeSync(DelegationId)("worker"),
+          targetAgentId: Schema.decodeSync(AgentId)("child"),
+          threadId: base.key.ownerThreadId,
+        },
+        update: Update.make({
+          schemaVersion: 1,
+          agentId: Schema.decodeSync(AgentId)("child"),
+          threadId: base.key.ownerThreadId,
+          runId: Schema.decodeSync(RunId)("run"),
+          updateId: base.key.messageId,
+          sequence: 1,
+          value: { finding: id },
+        }),
+      }),
+    },
+  });
+});
+
+/** Every case starts with an empty store; all clocks and expected values are explicit. */
+export const messageDeliveryStoreConformanceCases = [
+  {
+    name: "reserves ordinary delivery capacity when worker updates saturate their separate bound",
+    run: Effect.gen(function* () {
+      const store = yield* MessageDeliveryStore;
+      const capacity = messageDeliveryCapacity(store.limits, true);
+
+      for (let index = 0; index < capacity.pending; index++)
+        yield* store.insert(yield* makeWorkerUpdateDeliveryFixture(`update-${index}`));
+
+      const refused = yield* store
+        .insert(yield* makeWorkerUpdateDeliveryFixture("overflow"))
+        .pipe(Effect.result);
+
+      yield* verify(
+        Result.isFailure(refused) &&
+          refused.failure._tag === "MessageDeliveryError" &&
+          refused.failure.reason === "capacity",
+        "Updates must stop at their independent pending bound",
+      );
+      const terminal = yield* makeMessageDeliveryFixture("terminal");
+
+      yield* verify(
+        (yield* store.insert(terminal)).status === "pending",
+        "Update pressure must preserve ordinary terminal capacity",
+      );
+      yield* verify(
+        (yield* store.get({
+          ...terminal.key,
+          messageId: Schema.decodeSync(IdempotencyKey)("overflow"),
+        })) === null,
+        "Rejected update must not mutate delivery storage",
+      );
+    }),
+  },
+  {
+    name: "retains predecessor identity and defers ordering waits without spending attempts",
+    run: Effect.gen(function* () {
+      const store = yield* MessageDeliveryStore;
+
+      const initial = {
+        ...(yield* makeMessageDeliveryFixture("later")),
+        predecessor: Schema.decodeSync(IdempotencyKey)("earlier"),
+      };
+
+      yield* store.insert(initial);
+
+      const deferred = yield* store.change(initial.key, {
+        _tag: "Defer",
+        expectedVersion: 1,
+        nowMillis: 0,
+        untilMillis: 100,
+      });
+
+      yield* verify(
+        deferred.retry.attempts === 0 &&
+          deferred.retry.automaticAttempts === 0 &&
+          deferred.retry.nextAttemptAtMillis === 100,
+        "Ordering waits must remain bounded without exhausting transport retries",
+      );
+      yield* verify(
+        (yield* store.due(99, 10)).length === 0 && (yield* store.due(100, 10)).length === 1,
+        "Deferral must advance the persisted wake deadline",
+      );
+
+      yield* verify(
+        Equal.equals(yield* readPending({ ownerThreadId: initial.key.ownerThreadId, limit: 1 }), [
+          deferred,
+        ]),
+        "Future-due retained work must remain visible before any canonical reservation",
+      );
+
+      const changed = yield* store
+        .insert({ ...initial, predecessor: Schema.decodeSync(IdempotencyKey)("different") })
+        .pipe(Effect.result);
+
+      yield* verify(
+        Result.isFailure(changed) &&
+          changed.failure._tag === "MessageDeliveryError" &&
+          changed.failure.reason === "conflict",
+        "A retry cannot replace its ordering predecessor",
+      );
+    }),
+  },
+  {
+    name: "retains pending, accepted and processed facts with stable duplicate admission",
+    run: Effect.gen(function* () {
+      const store = yield* MessageDeliveryStore;
+      const initial = yield* makeMessageDeliveryFixture();
+
+      yield* store.insert(initial);
+      yield* verify(
+        Equal.equals(yield* store.due(0, 10), [initial.key]),
+        "Pending work must be independently discoverable",
+      );
+
+      const claim = yield* store.change(initial.key, {
+        _tag: "Claim",
+        nowMillis: 0,
+        expectedVersion: 1,
+      });
+
+      const accepted = yield* store.change(initial.key, {
+        _tag: "Accept",
+        nowMillis: 1,
+        expectedVersion: claim.version,
+        receipt: messageDeliveryFixtureReceipt,
+      });
+
+      yield* verify(
+        accepted.status === "accepted" && accepted.settlement === null,
+        "Acceptance must not claim processing",
+      );
+
+      yield* verify(
+        Equal.equals(yield* readPending({ ownerThreadId: initial.key.ownerThreadId, limit: 1 }), [
+          accepted,
+        ]),
+        "Accepted work must retain its exact receipt and envelope in the pending read",
+      );
+
+      const secondClaim = yield* store.change(initial.key, {
+        _tag: "Claim",
+        nowMillis: 6,
+        expectedVersion: accepted.version,
+      });
+
+      const settlement = Settlement.make({
+        receiptId: messageDeliveryFixtureReceipt.receiptId,
+        submissionId: messageDeliveryFixtureReceipt.submissionId,
+        settlementId: Schema.decodeSync(SettlementId)("settlement"),
+        outcome: "completed",
+        settledAt: DateTime.makeUnsafe(7),
+      });
+
+      const processed = yield* store.change(initial.key, {
+        _tag: "Process",
+        nowMillis: 7,
+        expectedVersion: secondClaim.version,
+        settlement,
+      });
+
+      yield* verify(
+        processed.status === "processed",
+        "Canonical settlement must finish processing",
+      );
+      yield* verify(
+        Equal.equals(yield* store.insert(initial), processed),
+        "Replay must preserve terminal evidence",
+      );
+      yield* verify(
+        (yield* store.nextDeadline()) === null,
+        "Processed work must release its wake deadline",
+      );
+      yield* verify(
+        (yield* readPending({ ownerThreadId: initial.key.ownerThreadId, limit: 1 })).length === 0,
+        "Processed history must not enter pending authorization reads",
+      );
+    }),
+  },
+  {
+    name: "rejects conflicting identity and scopes cursors and discovery to the source owner",
+    run: Effect.gen(function* () {
+      const store = yield* MessageDeliveryStore;
+      const a = yield* makeMessageDeliveryFixture("a");
+      const b = yield* makeMessageDeliveryFixture("b");
+      const other = yield* makeMessageDeliveryFixture("a", "other");
+
+      yield* store.insert(a);
+      yield* store.insert(b);
+      yield* store.insert(other);
+
+      const conflict = yield* store
+        .insert(yield* makeMessageDeliveryFixture("a", "sender", "changed"))
+        .pipe(Effect.result);
+
+      yield* verify(
+        Result.isFailure(conflict) &&
+          conflict.failure._tag === "MessageDeliveryError" &&
+          conflict.failure.reason === "conflict",
+        "Conflicting replay must be refused",
+      );
+      yield* verify(
+        Equal.equals(yield* store.get(a.key), a),
+        "Refusal must preserve original input",
+      );
+
+      const overflow = yield* readPending({ ownerThreadId: a.key.ownerThreadId, limit: 1 }).pipe(
+        Effect.result,
+      );
+
+      yield* verify(
+        Result.isFailure(overflow) && overflow.failure.reason === "capacity",
+        "Overflow must fail without a partial inventory",
+      );
+      yield* verify(
+        Equal.equals(yield* readPending({ ownerThreadId: other.key.ownerThreadId, limit: 1 }), [
+          other,
+        ]),
+        "Pending reads must use the source owner",
+      );
+
+      const page = yield* store.list({
+        ownerThreadId: a.key.ownerThreadId,
+        limit: 1,
+        pendingOnly: true,
+      });
+
+      yield* verify(
+        page.items.length === 1 && page.items[0]?.key.messageId === "a" && page.next === "a",
+        "First page must remain owner scoped",
+      );
+
+      const next = yield* store.list({
+        ownerThreadId: a.key.ownerThreadId,
+        limit: 1,
+        after: a.key.messageId,
+        pendingOnly: true,
+      });
+
+      yield* verify(
+        next.items.length === 1 && next.items[0]?.key.messageId === "b" && next.next === null,
+        "Cursor must be stable",
+      );
+      yield* verify(
+        Equal.equals(yield* store.due(0, 10, other.key.ownerThreadId), [other.key]),
+        "Owner-scoped scans must not expose another source",
+      );
+    }),
+  },
+  {
+    name: "fences stale completion and preserves parked work for explicit recovery",
+    run: Effect.gen(function* () {
+      const store = yield* MessageDeliveryStore;
+      const initial = yield* makeMessageDeliveryFixture();
+
+      yield* store.insert(initial);
+
+      const old = yield* store.change(initial.key, {
+        _tag: "Claim",
+        nowMillis: 0,
+        expectedVersion: 1,
+      });
+
+      const current = yield* store.change(initial.key, {
+        _tag: "Claim",
+        nowMillis: 101,
+        expectedVersion: old.version,
+      });
+
+      const stale = yield* store
+        .change(initial.key, {
+          _tag: "Accept",
+          nowMillis: 102,
+          expectedVersion: old.version,
+          receipt: messageDeliveryFixtureReceipt,
+        })
+        .pipe(Effect.result);
+
+      yield* verify(
+        Result.isFailure(stale) &&
+          stale.failure._tag === "MessageDeliveryError" &&
+          stale.failure.reason === "conflict",
+        "Old claims cannot commit",
+      );
+
+      const parked = yield* store.change(initial.key, {
+        _tag: "Park",
+        nowMillis: 102,
+        expectedVersion: current.version,
+        reason: "exhausted",
+      });
+
+      yield* verify(
+        (yield* store.nextDeadline()) === null && parked.status === "parked",
+        "Parked work must remain inspectable without busy polling",
+      );
+
+      yield* verify(
+        Equal.equals(yield* readPending({ ownerThreadId: initial.key.ownerThreadId, limit: 1 }), [
+          parked,
+        ]),
+        "Parked uncertainty must remain visible without a wake deadline",
+      );
+
+      const recovered = yield* store.change(initial.key, {
+        _tag: "Recover",
+        nowMillis: 103,
+        expectedVersion: parked.version,
+        deadlineAtMillis: 2_000,
+      });
+
+      yield* verify(
+        recovered.retry.generation === 1 && Equal.equals(recovered.envelope, initial.envelope),
+        "Explicit retry must preserve the frozen envelope",
+      );
+      yield* verify((yield* store.nextDeadline()) === 103, "Recovered work must be discoverable");
+    }),
+  },
+] as const;

package/src/durable/OperationAuthorizer.ts

@@ -0,0 +1,85 @@
+import { Context, Effect, Layer, Schema } from "effect";
+
+import { ThreadId, SubmissionId } from "../core/Identifiers.ts";
+import { Principal } from "./SubmissionLedger.ts";
+
+/**
+ * Administrative/observation operations submitted to authorization (P7 WP1; SEC-003/SEC-011,
+ * DUR-017 "authenticated per-read authorization"). The union covers every operation the durable
+ * runtime consults the authorizer for: canonical observation, settlement waits, aborts,
+ * administration, and the two durable resolution paths.
+ */
+export const AuthorizedOperation = Schema.Literals([
+  "observe",
+  "awaitSettlement",
+  "abort",
+  "explain",
+  "verify",
+  "retry",
+  "wake",
+  "scanObligations",
+  "resolveUnknown",
+  "resolveApproval",
+]);
+
+export type AuthorizedOperation = typeof AuthorizedOperation.Type;
+
+/**
+ * One authorization question. `principal` is present only when the host authenticated a caller
+ * identity and threaded it through — the framework never parses bearer tokens (SEC-001); absent
+ * identity under the default authorizer keeps the pre-P7 service-possession behavior.
+ */
+export class OperationAuthorizationRequest extends Schema.Class<OperationAuthorizationRequest>(
+  "@effect-agent/thread/OperationAuthorizationRequest",
+)({
+  operation: AuthorizedOperation,
+  threadId: Schema.optionalKey(ThreadId),
+  submissionId: Schema.optionalKey(SubmissionId),
+  principal: Schema.optionalKey(Principal),
+}) {}
+
+/** A typed, fail-closed authorization denial (never a defect, never silent). */
+export class OperationDenied extends Schema.TaggedError<OperationDenied>()("OperationDenied", {
+  operation: AuthorizedOperation,
+  reason: Schema.String.check(Schema.isMaxLength(4_096)),
+  threadId: Schema.optionalKey(ThreadId),
+  submissionId: Schema.optionalKey(SubmissionId),
+}) {}
+
+/**
+ * The minimal authorization port consulted by `observe`, `awaitSettlement`, `abort`, administration, and the
+ * `resolveUnknown`/`resolveApproval` resolution paths. `authorize` either succeeds (allow) or
+ * fails with the typed `OperationDenied` (deny) — the runtime propagates the denial fail-closed
+ * and performs no reads or writes for the denied operation.
+ */
+export interface OperationAuthorizerService {
+  readonly authorize: (
+    request: OperationAuthorizationRequest,
+  ) => Effect.Effect<void, OperationDenied>;
+}
+
+/**
+ * The default possession-behavior authorizer: possession of the `DurableAgentRuntime` service
+ * (plus each mutating command's mandatory author/reason audit fields) IS the authorization —
+ * exactly the pre-P7 boundary, unchanged. Hosts that authenticate callers substitute a real
+ * decision procedure through `operationAuthorizerLayer`; the framework enforces the decision
+ * fail-closed without inventing an identity system (D10/DUR-017 stance, plan §3).
+ */
+export const possessionOperationAuthorizer: OperationAuthorizerService = {
+  authorize: () => Effect.void,
+};
+
+/**
+ * Context reference with the possession default, mirroring `DurableApprovalResolver`: the
+ * coordinator consults it unconditionally, and only a host-supplied non-default Layer changes
+ * the answer. References resolve at Layer construction, so provide the override when building
+ * `DurableAgentRuntime.layer` (e.g. `Layer.provide(operationAuthorizerLayer(...))`).
+ */
+export const OperationAuthorizer: Context.Reference<OperationAuthorizerService> =
+  Context.Reference<OperationAuthorizerService>("@effect-agent/thread/OperationAuthorizer", {
+    defaultValue: () => possessionOperationAuthorizer,
+  });
+
+/** Layer carrying a host-supplied authorization decision procedure. */
+export const operationAuthorizerLayer = (service: OperationAuthorizerService): Layer.Layer<never> =>
+  Layer.succeedContext(Context.make(OperationAuthorizer, service));