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

package/src/core/MemoryRevalidation.ts

@@ -0,0 +1,185 @@
+import { Effect, Schema } from "effect";
+
+import { utf8ByteLength } from "./internal/utf8.ts";
+import type * as MemoryNamespace from "./MemoryNamespace.ts";
+import {
+  MemoryLookup,
+  MemoryPassage,
+  MemoryRecallError,
+  MemoryRecallLimits,
+} from "./MemoryReference.ts";
+import {
+  MemoryDocument,
+  MemoryKey,
+  MemoryReader,
+  MemoryScope,
+  MemoryStorageError,
+} from "./MemoryStore.ts";
+
+const RevalidationLimits = Schema.Struct({
+  maxInputBytes: MemoryRecallLimits.fields.maxInputBytes,
+  maxSourceBytes: MemoryRecallLimits.fields.maxInputBytes,
+});
+
+/** Bind these values in host code. Neither is a model-selectable retrieval parameter. */
+class MemoryAccessWire extends Schema.Class<MemoryAccessWire>(
+  "@effect-agent/capabilities/MemoryAccess",
+)({
+  namespace: MemoryKey.Wire.fields.namespace,
+  scope: MemoryScope,
+}) {}
+
+export type MemoryAccess<Namespace extends MemoryNamespace.Any = MemoryNamespace.Any> = Omit<
+  MemoryAccessWire,
+  "namespace"
+> & { readonly namespace: Namespace };
+
+export const MemoryAccess = {
+  Wire: MemoryAccessWire,
+  make: <Namespace extends MemoryNamespace.Any>(
+    fields: MemoryAccess<Namespace>,
+  ): MemoryAccess<Namespace> =>
+    Object.assign(Schema.decodeUnknownSync(MemoryAccessWire)(fields), {
+      namespace: fields.namespace,
+    }),
+};
+
+/**
+ * Resolve derivative candidates against the current authoritative source and host-bound access.
+ * The reader needs no write capability. A same-revision excerpt is kept only if its exact text
+ * occurs in the current source; all attribution and metadata come from that source. Otherwise
+ * the whole current document replaces it. Aggregate output JSON is bounded before retention,
+ * including duplicates, by maxInputBytes, defaulting to 16 MiB with a 64 MiB maximum.
+ * maxSourceBytes optionally bounds aggregate encoded authoritative documents, once per source.
+ * One authoritative document is decoded at a time; reader-side allocations precede these bounds.
+ *
+ * There is no cache. One invocation reads each distinct source once. Checks begun after a
+ * successful withdrawal or access revocation exclude that source; an in-flight snapshot can
+ * finish, including its same-Turn overflow retry. Original history and prior outputs remain.
+ */
+export const revalidateMemoryLookup = Effect.fn("revalidateMemoryLookup")(function* (
+  lookup: MemoryLookup,
+  access: MemoryAccess,
+  limits: Pick<MemoryRecallLimits, "maxInputBytes"> & { readonly maxSourceBytes?: number } = {},
+) {
+  const decodedLimits = yield* Schema.decodeEffect(RevalidationLimits)(limits).pipe(
+    Effect.mapError(() =>
+      MemoryRecallError.make({ reason: "invalid-input", message: "Invalid revalidation limits" }),
+    ),
+  );
+
+  const decodedAccess = yield* Schema.decodeEffect(MemoryAccess.Wire)(access).pipe(
+    Effect.mapError(() =>
+      MemoryRecallError.make({ reason: "invalid-input", message: "Invalid host memory access" }),
+    ),
+  );
+
+  const decoded = yield* Schema.decodeEffect(MemoryLookup)(lookup).pipe(
+    Effect.mapError(() =>
+      MemoryRecallError.make({ reason: "invalid-input", message: "Malformed memory candidates" }),
+    ),
+  );
+
+  if (decoded._tag !== "Found") return decoded;
+  const reader = yield* MemoryReader;
+
+  const groups = new Map<
+    string,
+    Array<{ readonly candidate: MemoryPassage; readonly index: number }>
+  >();
+
+  for (const [index, candidate] of decoded.passages.entries()) {
+    const group = groups.get(candidate.source.id);
+
+    if (group === undefined) groups.set(candidate.source.id, [{ candidate, index }]);
+    else group.push({ candidate, index });
+  }
+  const passages: Array<{ readonly passage: MemoryPassage; readonly index: number }> = [];
+  const maxInputBytes = decodedLimits.maxInputBytes ?? 16_777_216;
+  let inputBytes = 0;
+  let sourceBytes = 0;
+
+  for (const [sourceId, group] of groups) {
+    yield* Effect.yieldNow;
+    const key = MemoryKey.make({ namespace: decodedAccess.namespace, id: sourceId });
+
+    const document = yield* reader
+      .get(key)
+      .pipe(
+        Effect.flatMap((value) =>
+          Schema.decodeEffect(Schema.NullOr(MemoryDocument.Wire))(value).pipe(
+            Effect.mapError(() =>
+              MemoryStorageError.make({ operation: "validate source view", reason: "corrupt" }),
+            ),
+          ),
+        ),
+      );
+
+    if (
+      document !== null &&
+      (document.key.namespace.address !== key.namespace.address ||
+        document.key.id !== key.id ||
+        document.source.id !== key.id)
+    ) {
+      return yield* MemoryStorageError.make({
+        operation: "validate source identity",
+        reason: "corrupt",
+      });
+    }
+    if (
+      document === null ||
+      document._tag === "WithdrawnMemoryDocument" ||
+      !document.scopes.includes(decodedAccess.scope)
+    )
+      continue;
+    if (decodedLimits.maxSourceBytes !== undefined) {
+      sourceBytes += utf8ByteLength(JSON.stringify(document));
+      if (sourceBytes > decodedLimits.maxSourceBytes)
+        return yield* MemoryRecallError.make({
+          reason: "budget",
+          sourceId,
+          message: "Authoritative memory source byte budget exceeded",
+        });
+    }
+    for (const { candidate, index } of group) {
+      const sameExcerpt =
+        document.source.revision === candidate.source.revision &&
+        document.content.text.includes(candidate.content.text);
+
+      const passage = MemoryPassage.make({
+        version: 1,
+        authority: decodedAccess.namespace.address,
+        source: document.source,
+        passageId: sameExcerpt ? candidate.passageId : "document",
+        content: {
+          ...document.content,
+          text: sameExcerpt ? candidate.content.text : document.content.text,
+        },
+      });
+
+      const encoded = JSON.stringify(passage);
+      const remaining = maxInputBytes - inputBytes;
+
+      const encodedBytes = encoded.length <= remaining ? utf8ByteLength(encoded) : undefined;
+
+      if (encodedBytes === undefined || encodedBytes > remaining) {
+        return yield* MemoryRecallError.make({
+          reason: "budget",
+          sourceId,
+          message: "Revalidated memory input encoding budget exceeded",
+        });
+      }
+      inputBytes += encodedBytes;
+      passages.push({ passage, index });
+    }
+  }
+
+  return passages.length === 0
+    ? { _tag: "NoMatch" as const }
+    : {
+        _tag: "Found" as const,
+        passages: passages
+          .sort((left, right) => left.index - right.index)
+          .map(({ passage }) => passage),
+      };
+});

package/src/core/MemoryStore.ts

@@ -0,0 +1,368 @@
+import { Context, Effect, Layer, Schema } from "effect";
+
+import * as MemoryNamespace from "./MemoryNamespace.ts";
+import { MemoryContent, MemorySourceReference } from "./MemoryReference.ts";
+
+const Identity = Schema.NonEmptyString.check(Schema.isMaxLength(1_024));
+const Timestamp = Schema.Finite.check(Schema.isGreaterThanOrEqualTo(0));
+
+/** Host-defined recall visibility label. A scope identifies access policy; it does not grant it. */
+export const MemoryScope = Identity.pipe(Schema.brand("@effect-agent/core/MemoryScope"));
+export type MemoryScope = typeof MemoryScope.Type;
+
+/** A host-selected namespace prevents accidental cross-tenant document lookup. */
+class MemoryKeyWire extends Schema.Class<MemoryKeyWire>("@effect-agent/core/MemoryKey")({
+  namespace: MemoryNamespace.Any,
+  id: MemorySourceReference.fields.id,
+}) {}
+
+export type MemoryKey<Namespace extends MemoryNamespace.Any = MemoryNamespace.Any> = Omit<
+  MemoryKeyWire,
+  "namespace"
+> & { readonly namespace: Namespace };
+
+export const MemoryKey = {
+  Wire: MemoryKeyWire,
+  make: <Namespace extends MemoryNamespace.Any>(
+    fields: MemoryKey<Namespace>,
+  ): MemoryKey<Namespace> =>
+    Object.assign(Schema.decodeUnknownSync(MemoryKeyWire)(fields), { namespace: fields.namespace }),
+};
+
+const KnownSource = Schema.Struct({
+  ...MemorySourceReference.fields,
+  revision: Identity,
+});
+
+const AccessScopes = Schema.Array(MemoryScope).check(
+  Schema.isMaxLength(128),
+  Schema.makeFilter((scopes) => new Set(scopes).size === scopes.length, {
+    expected: "unique access scopes",
+  }),
+);
+
+const DocumentFields = {
+  version: Schema.Literal(1),
+  key: MemoryKey.Wire,
+  source: KnownSource,
+  generation: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER })),
+  predecessor: Schema.NullOr(MemorySourceReference),
+  modifiedAt: Timestamp,
+};
+
+class ActiveMemoryDocumentWire extends Schema.TaggedClass<ActiveMemoryDocumentWire>()(
+  "ActiveMemoryDocument",
+  {
+    ...DocumentFields,
+    content: MemoryContent,
+    /** Explicit application-defined scope names. Empty grants no recall access. */
+    scopes: AccessScopes,
+  },
+) {}
+
+/** Terminal tombstone. Reusing its ID cannot restore the source through delayed work. */
+class WithdrawnMemoryDocumentWire extends Schema.TaggedClass<WithdrawnMemoryDocumentWire>()(
+  "WithdrawnMemoryDocument",
+  {
+    ...DocumentFields,
+    reason: Schema.String.check(Schema.isMaxLength(4_096)),
+  },
+) {}
+
+export type ActiveMemoryDocument<Namespace extends MemoryNamespace.Any = MemoryNamespace.Any> =
+  Omit<ActiveMemoryDocumentWire, "key"> & { readonly key: MemoryKey<Namespace> };
+
+export const ActiveMemoryDocument = {
+  Wire: ActiveMemoryDocumentWire,
+  make: <Namespace extends MemoryNamespace.Any>(
+    fields: Omit<ActiveMemoryDocument<Namespace>, "_tag"> & {
+      readonly _tag?: "ActiveMemoryDocument";
+    },
+  ): ActiveMemoryDocument<Namespace> =>
+    Object.assign(
+      Schema.decodeUnknownSync(ActiveMemoryDocumentWire)({
+        _tag: "ActiveMemoryDocument",
+        ...fields,
+      }),
+      { key: MemoryKey.make(fields.key) },
+    ),
+};
+
+export type WithdrawnMemoryDocument<Namespace extends MemoryNamespace.Any = MemoryNamespace.Any> =
+  Omit<WithdrawnMemoryDocumentWire, "key"> & { readonly key: MemoryKey<Namespace> };
+
+export const WithdrawnMemoryDocument = {
+  Wire: WithdrawnMemoryDocumentWire,
+  make: <Namespace extends MemoryNamespace.Any>(
+    fields: Omit<WithdrawnMemoryDocument<Namespace>, "_tag"> & {
+      readonly _tag?: "WithdrawnMemoryDocument";
+    },
+  ): WithdrawnMemoryDocument<Namespace> =>
+    Object.assign(
+      Schema.decodeUnknownSync(WithdrawnMemoryDocumentWire)({
+        _tag: "WithdrawnMemoryDocument",
+        ...fields,
+      }),
+      { key: MemoryKey.make(fields.key) },
+    ),
+};
+
+export type MemoryDocument<Namespace extends MemoryNamespace.Any = MemoryNamespace.Any> =
+  | ActiveMemoryDocument<Namespace>
+  | WithdrawnMemoryDocument<Namespace>;
+
+export const MemoryDocument = {
+  Wire: Schema.Union([ActiveMemoryDocument.Wire, WithdrawnMemoryDocument.Wire]),
+  restore: Effect.fn("MemoryDocument.restore")(function* <Namespace extends MemoryNamespace.Any>(
+    namespace: Namespace,
+    input: unknown,
+  ): Effect.fn.Return<MemoryDocument<Namespace>, MemoryStorageError> {
+    const document = yield* Schema.decodeUnknownEffect(MemoryDocument.Wire)(input).pipe(
+      Effect.mapError(() =>
+        MemoryStorageError.make({ operation: "restore memory document", reason: "corrupt" }),
+      ),
+    );
+
+    if (!MemoryNamespace.equals(namespace, document.key.namespace))
+      return yield* MemoryStorageError.make({
+        operation: "restore memory namespace",
+        reason: "corrupt",
+      });
+    const key = MemoryKey.make({ ...document.key, namespace });
+
+    return document._tag === "ActiveMemoryDocument"
+      ? ActiveMemoryDocument.make({ ...document, key })
+      : WithdrawnMemoryDocument.make({ ...document, key });
+  }),
+};
+
+const WriteFields = {
+  key: MemoryKey.Wire,
+  /** The same operation ID must always carry exactly the same Schema-encoded command. */
+  operationId: Identity,
+};
+
+const MemoryWriteWire = Schema.Union([
+  Schema.TaggedStruct("Put", {
+    ...WriteFields,
+    expectedRevision: Schema.NullOr(Identity),
+    locator: MemorySourceReference.fields.locator,
+    content: MemoryContent,
+    scopes: AccessScopes,
+  }),
+  Schema.TaggedStruct("Withdraw", {
+    ...WriteFields,
+    expectedRevision: Identity,
+    reason: WithdrawnMemoryDocument.Wire.fields.reason,
+  }),
+]);
+
+export type MemoryWrite<Namespace extends MemoryNamespace.Any = MemoryNamespace.Any> = (
+  | Omit<(typeof MemoryWriteWire.members)[0]["Type"], "key">
+  | Omit<(typeof MemoryWriteWire.members)[1]["Type"], "key">
+) & { readonly key: MemoryKey<Namespace> };
+
+export const MemoryWrite = {
+  Wire: MemoryWriteWire,
+  make: <Namespace extends MemoryNamespace.Any>(
+    fields: MemoryWrite<Namespace>,
+  ): MemoryWrite<Namespace> =>
+    Object.assign(Schema.decodeUnknownSync(MemoryWriteWire)(fields), {
+      key: MemoryKey.make(fields.key),
+    }),
+};
+
+export class MemoryConflict extends Schema.TaggedError<MemoryConflict>()("MemoryConflict", {
+  key: MemoryKey.Wire,
+  expectedRevision: Schema.NullOr(Identity),
+  actualRevision: Schema.NullOr(Identity),
+}) {}
+
+export class MemoryWithdrawn extends Schema.TaggedError<MemoryWithdrawn>()("MemoryWithdrawn", {
+  key: MemoryKey.Wire,
+  revision: Identity,
+}) {}
+
+export class MemoryOperationConflict extends Schema.TaggedError<MemoryOperationConflict>()(
+  "MemoryOperationConflict",
+  {
+    key: MemoryKey.Wire,
+    operationId: Identity,
+  },
+) {}
+
+export class MemoryStorageError extends Schema.TaggedError<MemoryStorageError>()(
+  "MemoryStorageError",
+  {
+    operation: Schema.NonEmptyString,
+    reason: Schema.Literals(["invalid-input", "unavailable", "corrupt", "incompatible"]),
+  },
+) {}
+
+export const MemoryMutationPoint = Schema.Literals([
+  "memory:initialize:before",
+  "memory:initialize:before-accounting",
+  "memory:initialize:after-accounting",
+  "memory:initialize:after",
+  "memory:change:before",
+  "memory:change:after-state",
+  "memory:change:after-receipt",
+  "memory:change:after",
+]);
+
+export type MemoryMutationPoint = typeof MemoryMutationPoint.Type;
+
+export class MemoryMutationFailure extends Schema.TaggedError<MemoryMutationFailure>()(
+  "MemoryMutationFailure",
+  {
+    point: MemoryMutationPoint,
+  },
+) {}
+
+/** Explicit fault-injection seam; production adapters install the no-op Layer. */
+export class MemoryMutationFailpoint extends Context.Service<
+  MemoryMutationFailpoint,
+  {
+    readonly hit: (point: MemoryMutationPoint) => Effect.Effect<void, MemoryMutationFailure>;
+  }
+>()("@effect-agent/core/MemoryMutationFailpoint") {
+  static readonly layer = Layer.succeed(this, { hit: () => Effect.void });
+}
+
+export type MemoryWriteError =
+  | MemoryStorageError
+  | MemoryConflict
+  | MemoryWithdrawn
+  | MemoryOperationConflict
+  | MemoryMutationFailure;
+
+/**
+ * Read capability independent of editing. A get begun after a committed write must observe
+ * that write or a later revision. An adapter unable to provide that view must fail typed.
+ * Host code binds namespace and access scope; cached candidates do not implement this port.
+ */
+export class MemoryReader extends Context.Service<
+  MemoryReader,
+  {
+    readonly get: <Namespace extends MemoryNamespace.Any>(
+      key: MemoryKey<Namespace>,
+    ) => Effect.Effect<MemoryDocument<Namespace> | null, MemoryStorageError>;
+  }
+>()("@effect-agent/core/MemoryReader") {
+  static fromAdapter(adapter: {
+    readonly get: (key: MemoryKey) => Effect.Effect<MemoryDocument | null, MemoryStorageError>;
+  }): MemoryReader["Service"] {
+    return {
+      get: Effect.fn("MemoryReader.get")(function* <Namespace extends MemoryNamespace.Any>(
+        key: MemoryKey<Namespace>,
+      ) {
+        const document = yield* adapter.get(key);
+
+        return document === null ? null : yield* MemoryDocument.restore(key.namespace, document);
+      }),
+    };
+  }
+}
+
+/**
+ * Optional conditional writer. Implement only where atomic expected-revision checks and
+ * durable idempotency receipts can be guaranteed. Apply authorization before calling it.
+ * Reconcile an existing operation receipt before evaluating tombstones or expected revisions:
+ * identical commands return the original result; changed commands fail MemoryOperationConflict.
+ * Original results include content, even for a historical Put replayed after withdrawal;
+ * replay does not change the current head. Revalidate a source before using recalled content.
+ * A failed acknowledgement can hide a committed change: retain and retry the exact command.
+ * Successful withdrawal excludes checks begun afterward; already captured views may finish.
+ * Receipts and original Thread history are separate retention concerns.
+ */
+export class MemoryWriter extends Context.Service<
+  MemoryWriter,
+  {
+    readonly change: <Namespace extends MemoryNamespace.Any>(
+      write: MemoryWrite<Namespace>,
+    ) => Effect.Effect<MemoryDocument<Namespace>, MemoryWriteError>;
+  }
+>()("@effect-agent/core/MemoryWriter") {
+  static fromAdapter(adapter: {
+    readonly change: (write: MemoryWrite) => Effect.Effect<MemoryDocument, MemoryWriteError>;
+  }): MemoryWriter["Service"] {
+    return {
+      change: Effect.fn("MemoryWriter.change")(function* <Namespace extends MemoryNamespace.Any>(
+        write: MemoryWrite<Namespace>,
+      ) {
+        const document = yield* adapter.change(write);
+
+        return yield* MemoryDocument.restore(write.key.namespace, document);
+      }),
+    };
+  }
+}
+
+/**
+ * Transition mechanics for an authoritative document store. Revisions identify this readable
+ * source, not the original activity from which a consumer extracted it. The adapter reconciles
+ * receipts first and owns atomicity and the clock. Original evidence belongs in provenance.
+ */
+export const applyMemoryWrite = Effect.fn("applyMemoryWrite")(function* <
+  Namespace extends MemoryNamespace.Any,
+>(
+  current: MemoryDocument<NoInfer<Namespace>> | null,
+  write: MemoryWrite<Namespace>,
+  modifiedAt: number,
+) {
+  if (
+    current !== null &&
+    (!MemoryNamespace.equals(current.key.namespace, write.key.namespace) ||
+      current.key.id !== write.key.id ||
+      current.source.id !== write.key.id)
+  ) {
+    return yield* MemoryStorageError.make({
+      operation: "memory transition identity",
+      reason: "corrupt",
+    });
+  }
+  if (current?._tag === "WithdrawnMemoryDocument") {
+    return yield* MemoryWithdrawn.make({ key: write.key, revision: current.source.revision });
+  }
+  const actualRevision = current?.source.revision ?? null;
+
+  if (actualRevision !== write.expectedRevision) {
+    return yield* MemoryConflict.make({
+      key: write.key,
+      expectedRevision: write.expectedRevision,
+      actualRevision,
+    });
+  }
+  const generation = (current?.generation ?? 0) + 1;
+
+  const fields = {
+    version: 1 as const,
+    key: write.key,
+    source: {
+      id: write.key.id,
+      locator: write._tag === "Put" ? write.locator : (current?.source.locator ?? ""),
+      revision: String(generation),
+    },
+    generation,
+    predecessor: current?.source ?? null,
+    modifiedAt,
+  };
+
+  const next =
+    write._tag === "Put"
+      ? {
+          _tag: "ActiveMemoryDocument" as const,
+          ...fields,
+          content: write.content,
+          scopes: write.scopes,
+        }
+      : { _tag: "WithdrawnMemoryDocument" as const, ...fields, reason: write.reason };
+
+  const document = yield* Schema.decodeUnknownEffect(MemoryDocument.Wire)(next).pipe(
+    Effect.mapError(() =>
+      MemoryStorageError.make({ operation: "memory transition", reason: "invalid-input" }),
+    ),
+  );
+
+  return yield* MemoryDocument.restore(write.key.namespace, document);
+});

package/src/core/Messaging.ts

@@ -0,0 +1,90 @@
+import { Schema } from "effect";
+
+import { AgentId, SettlementId, ThreadId } from "./Identifiers.ts";
+import { IdempotencyKey, Receipt } from "./Receipt.ts";
+import { FrameworkMessage } from "./Worker.ts";
+
+/** Application-chosen fixed route name; it never authorizes a destination by itself. */
+export const PeerName = Schema.NonEmptyString.check(
+  Schema.isMaxLength(64),
+  Schema.isPattern(/^[a-zA-Z0-9_-]+$/u),
+);
+
+export type PeerName = typeof PeerName.Type;
+
+/** A retained outbound delivery identity, not a destination Receipt or access grant. */
+export const MessageRef = Schema.Struct({ ownerThreadId: ThreadId, messageId: IdempotencyKey });
+export type MessageRef = typeof MessageRef.Type;
+
+export const MessageAddress = Schema.Struct({ threadId: ThreadId, agentId: AgentId });
+export type MessageAddress = typeof MessageAddress.Type;
+
+/** Host-authenticated provenance stored separately from destination-owned application input. */
+export const MessageAdmission = Schema.Struct({
+  schemaVersion: Schema.Literal(1),
+  message: MessageRef,
+  peerName: PeerName,
+  sender: MessageAddress,
+  returnAddress: MessageAddress,
+  inReplyTo: Schema.optionalKey(MessageRef),
+}).check(
+  Schema.makeFilter(
+    (value) =>
+      value.message.ownerThreadId === value.sender.threadId &&
+      value.sender.threadId === value.returnAddress.threadId &&
+      value.sender.agentId === value.returnAddress.agentId,
+  ),
+);
+
+export type MessageAdmission = typeof MessageAdmission.Type;
+
+/** Bounded public projection of delivery state; the frozen envelope remains host-private. */
+export const MessageStatus = Schema.Struct({
+  message: MessageRef,
+  status: Schema.Literals(["pending", "accepted", "processed", "refused", "parked"]),
+  receipt: Schema.NullOr(Receipt),
+  settlement: Schema.NullOr(
+    Schema.Struct({
+      settlementId: SettlementId,
+      outcome: Schema.Literals(["completed", "failed", "aborted"]),
+    }),
+  ),
+  reason: Schema.NullOr(Schema.String.check(Schema.isMaxLength(256))),
+});
+
+export type MessageStatus = typeof MessageStatus.Type;
+
+export const InboxEntry = Schema.Struct({
+  sequence: Schema.Natural.check(Schema.isGreaterThan(0)),
+  admission: MessageAdmission,
+});
+
+export type InboxEntry = typeof InboxEntry.Type;
+
+export const InboxPage = Schema.Struct({
+  items: Schema.Array(InboxEntry).check(Schema.isMaxLength(100)),
+  next: Schema.NullOr(Schema.Natural),
+});
+
+export type InboxPage = typeof InboxPage.Type;
+
+export class MessagingError extends Schema.TaggedError<MessagingError>()("MessagingError", {
+  operation: Schema.Literals(["context", "send", "reply", "inbox", "inspect", "retry"]),
+  reason: Schema.Literals([
+    "denied",
+    "unavailable",
+    "route-unavailable",
+    "binding-mismatch",
+    "invalid-input",
+    "invalid-reference",
+    "conflict",
+    "capacity",
+    "not-found",
+    "storage",
+    "corrupt",
+  ]),
+}) {}
+
+/** Canonical input provenance: peer input or a framework-owned completion message. */
+export const InputMessage = Schema.Union([MessageAdmission, FrameworkMessage]);
+export type InputMessage = typeof InputMessage.Type;

package/src/core/Receipt.ts

@@ -0,0 +1,42 @@
+import { Schema } from "effect";
+
+import { ReceiptId, SubmissionId, ThreadId } from "./Identifiers.ts";
+
+// Keep the established brand and Schema identities when sharing these values inward.
+/** Caller-supplied deduplication key, scoped to one Thread and authenticated principal. */
+export const IdempotencyKey = Schema.NonEmptyString.check(Schema.isMaxLength(256)).pipe(
+  Schema.brand("@effect-agent/thread/IdempotencyKey"),
+);
+
+export type IdempotencyKey = typeof IdempotencyKey.Type;
+
+/** Stable host-authenticated admission principal; the established durable brand is preserved. */
+export const Principal = Schema.NonEmptyString.check(Schema.isMaxLength(256)).pipe(
+  Schema.brand("@effect-agent/thread/Principal"),
+);
+
+export type Principal = typeof Principal.Type;
+
+/** Thread-local FIFO position allocated once at admission. */
+export const QueueSequence = Schema.Natural.pipe(
+  Schema.brand("@effect-agent/thread/QueueSequence"),
+);
+
+export type QueueSequence = typeof QueueSequence.Type;
+
+/**
+ * One accepted input whose admission, Thread materialization and readiness are committed.
+ * A Receipt identifies an observation target; possession grants no authorization.
+ */
+export class Receipt extends Schema.Class<Receipt>("@effect-agent/thread/Receipt")({
+  receiptId: ReceiptId,
+  submissionId: SubmissionId,
+  threadId: ThreadId,
+  queueSequence: QueueSequence,
+}) {}
+
+/** The input joined this host Submission; cancelling it must never silently cancel the host. */
+export class JoinedToHost extends Schema.TaggedError<JoinedToHost>()("JoinedToHost", {
+  submissionId: SubmissionId,
+  hostSubmissionId: SubmissionId,
+}) {}