@echovisionlab/geul-event 0.1.0

package/src/pgmq.ts

@@ -0,0 +1,216 @@
+export const PGMQ_ENVELOPE_SCHEMA_VERSION = 1 as const;
+
+export type PgmqEnvelope = {
+  message_id: string;
+  message_type: string;
+  schema_version: typeof PGMQ_ENVELOPE_SCHEMA_VERSION;
+  created_at: string;
+  correlation_id?: string;
+  causation_id?: string;
+  payload_base64: string;
+};
+
+export type PgmqHeaders = Record<string, string>;
+
+type QueryResult<Row> = { rows: Row[] };
+
+export interface PgmqExecutor {
+  query<Row extends Record<string, unknown>>(
+    text: string,
+    values?: readonly unknown[],
+  ): Promise<QueryResult<Row>>;
+}
+
+export type PgmqMessage = {
+  transportId: bigint;
+  readCount: number;
+  enqueuedAt: Date;
+  visibleAt: Date;
+  envelope?: PgmqEnvelope;
+  headers: PgmqHeaders;
+  /** Present when the row was read but violates the shared transport contract. */
+  contractError?: string;
+};
+
+function encodeBase64(payload: Uint8Array): string {
+  return Buffer.from(payload).toString("base64");
+}
+
+function decodeBase64(payload: string): Uint8Array {
+  return new Uint8Array(Buffer.from(payload, "base64"));
+}
+
+export function createPgmqEnvelope(input: {
+  messageId: string;
+  messageType: string;
+  payload: Uint8Array;
+  correlationId?: string;
+  causationId?: string;
+  createdAt?: Date;
+}): PgmqEnvelope {
+  const envelope: PgmqEnvelope = {
+    message_id: input.messageId,
+    message_type: input.messageType,
+    schema_version: PGMQ_ENVELOPE_SCHEMA_VERSION,
+    created_at: (input.createdAt ?? new Date()).toISOString(),
+    payload_base64: encodeBase64(input.payload),
+    ...(input.correlationId ? { correlation_id: input.correlationId } : {}),
+    ...(input.causationId ? { causation_id: input.causationId } : {}),
+  };
+  assertPgmqEnvelope(envelope);
+  return envelope;
+}
+
+export function assertPgmqEnvelope(
+  value: unknown,
+): asserts value is PgmqEnvelope {
+  if (!value || typeof value !== "object") {
+    throw new Error("PGMQ envelope must be an object");
+  }
+  const envelope = value as Partial<PgmqEnvelope>;
+  if (!envelope.message_id || typeof envelope.message_id !== "string") {
+    throw new Error("PGMQ envelope message_id is required");
+  }
+  if (!envelope.message_type || typeof envelope.message_type !== "string") {
+    throw new Error("PGMQ envelope message_type is required");
+  }
+  if (envelope.schema_version !== PGMQ_ENVELOPE_SCHEMA_VERSION) {
+    throw new Error(
+      `Unsupported PGMQ envelope schema ${envelope.schema_version}`,
+    );
+  }
+  if (
+    typeof envelope.created_at !== "string" ||
+    Number.isNaN(Date.parse(envelope.created_at))
+  ) {
+    throw new Error("PGMQ envelope created_at must be an ISO timestamp");
+  }
+  if (typeof envelope.payload_base64 !== "string") {
+    throw new Error("PGMQ envelope payload_base64 is required");
+  }
+  const normalized = Buffer.from(envelope.payload_base64, "base64").toString(
+    "base64",
+  );
+  if (normalized !== envelope.payload_base64) {
+    throw new Error("PGMQ envelope payload_base64 is invalid");
+  }
+}
+
+export function pgmqEnvelopePayload(envelope: PgmqEnvelope): Uint8Array {
+  assertPgmqEnvelope(envelope);
+  return decodeBase64(envelope.payload_base64);
+}
+
+export class PgmqClient {
+  async enqueue(
+    executor: PgmqExecutor,
+    queue: string,
+    envelope: PgmqEnvelope,
+    options: { headers?: PgmqHeaders; delaySeconds?: number } = {},
+  ): Promise<bigint> {
+    assertPgmqEnvelope(envelope);
+    if (!queue) throw new Error("PGMQ queue is required");
+    const delaySeconds = Math.max(0, Math.trunc(options.delaySeconds ?? 0));
+    const result = await executor.query<{ msg_id: string | number | bigint }>(
+      "SELECT pgmq.send($1, $2::jsonb, $3::jsonb, $4::integer) AS msg_id",
+      [queue, envelope, options.headers ?? {}, delaySeconds],
+    );
+    const row = result.rows[0];
+    if (!row) throw new Error(`PGMQ send returned no message for ${queue}`);
+    return BigInt(row.msg_id);
+  }
+
+  async read(
+    executor: PgmqExecutor,
+    queue: string,
+    options: { visibilityTimeoutSeconds: number; batch?: number },
+  ): Promise<PgmqMessage[]> {
+    if (!queue) throw new Error("PGMQ queue is required");
+    const visibilityTimeoutSeconds = Math.trunc(
+      options.visibilityTimeoutSeconds,
+    );
+    const batch = Math.trunc(options.batch ?? 1);
+    if (visibilityTimeoutSeconds <= 0) {
+      throw new Error("PGMQ visibility timeout must be positive");
+    }
+    if (batch <= 0) throw new Error("PGMQ batch must be positive");
+    const result = await executor.query<{
+      msg_id: string | number | bigint;
+      read_ct: number;
+      enqueued_at: Date | string;
+      vt: Date | string;
+      message: unknown;
+      headers: PgmqHeaders | null;
+    }>(
+      "SELECT msg_id, read_ct, enqueued_at, vt, message, headers FROM pgmq.read($1, $2::integer, $3::integer, '{}'::jsonb)",
+      [queue, visibilityTimeoutSeconds, batch],
+    );
+    return result.rows.map((row) => {
+      const message = {
+        transportId: BigInt(row.msg_id),
+        readCount: row.read_ct,
+        enqueuedAt: new Date(row.enqueued_at),
+        visibleAt: new Date(row.vt),
+        headers: row.headers ?? {},
+      };
+      try {
+        assertPgmqEnvelope(row.message);
+        return { ...message, envelope: row.message };
+      } catch (error) {
+        return {
+          ...message,
+          contractError:
+            error instanceof Error ? error.message : "Invalid PGMQ envelope",
+        };
+      }
+    });
+  }
+
+  async complete(
+    executor: PgmqExecutor,
+    queue: string,
+    transportId: bigint,
+  ): Promise<void> {
+    await this.booleanOperation(executor, "delete", queue, transportId);
+  }
+
+  async retry(
+    executor: PgmqExecutor,
+    queue: string,
+    transportId: bigint,
+    delaySeconds: number,
+  ): Promise<void> {
+    const result = await executor.query<{ msg_id: string | number | bigint }>(
+      "SELECT msg_id FROM pgmq.set_vt($1, $2::bigint, $3::integer)",
+      [queue, transportId.toString(), Math.max(0, Math.trunc(delaySeconds))],
+    );
+    if (BigInt(result.rows[0]?.msg_id ?? -1) !== transportId) {
+      throw new Error(`PGMQ retry did not update ${queue}/${transportId}`);
+    }
+  }
+
+  async deadLetter(
+    executor: PgmqExecutor,
+    queue: string,
+    transportId: bigint,
+  ): Promise<void> {
+    await this.booleanOperation(executor, "archive", queue, transportId);
+  }
+
+  private async booleanOperation(
+    executor: PgmqExecutor,
+    operation: "delete" | "archive",
+    queue: string,
+    transportId: bigint,
+  ): Promise<void> {
+    const result = await executor.query<{ succeeded: boolean }>(
+      `SELECT pgmq.${operation}($1, $2::bigint) AS succeeded`,
+      [queue, transportId.toString()],
+    );
+    if (result.rows[0]?.succeeded !== true) {
+      throw new Error(
+        `PGMQ ${operation} did not update ${queue}/${transportId}`,
+      );
+    }
+  }
+}

package/src/proto-helpers.test.ts

@@ -0,0 +1,103 @@
+import { create, toBinary } from "@bufbuild/protobuf";
+import { describe, expect, it } from "vitest";
+import {
+  OgGenerationLifecycleEventSchema,
+  UserDeleteIdentityCommandSchema,
+} from "@echovisionlab/geul-proto/secure/events_pb.ts";
+import {
+  deserializeProto,
+  FileIngestAttachedEventSchema,
+  FileIngestIdentitySchema,
+  FileIngestMediaKind,
+  TranscodeEntityType,
+} from "./proto-helpers.ts";
+
+describe("deserializeProto", () => {
+  it("decodes a generated protobuf message", () => {
+    const source = create(OgGenerationLifecycleEventSchema, {
+      generationId: "generation-1",
+      runId: "run-1",
+    });
+
+    expect(
+      deserializeProto(
+        OgGenerationLifecycleEventSchema,
+        toBinary(OgGenerationLifecycleEventSchema, source),
+      ),
+    ).toEqual(source);
+  });
+
+  it("preserves Track first-attach absence and replacement CAS identity", () => {
+    const firstAttach = create(FileIngestIdentitySchema, {
+      entityType: TranscodeEntityType.TRACK,
+      entityId: "track-1",
+      fileId: "file-new",
+      mediaKind: FileIngestMediaKind.TRACK_AUDIO,
+    });
+    const firstDecoded = deserializeProto(
+      FileIngestIdentitySchema,
+      toBinary(FileIngestIdentitySchema, firstAttach),
+    );
+    expect(firstDecoded.expectedCurrentFileId).toBeUndefined();
+
+    const replacement = create(FileIngestIdentitySchema, {
+      entityType: TranscodeEntityType.TRACK,
+      entityId: "track-1",
+      fileId: "file-new",
+      mediaKind: FileIngestMediaKind.TRACK_AUDIO,
+      expectedCurrentFileId: "file-current",
+    });
+    const replacementDecoded = deserializeProto(
+      FileIngestIdentitySchema,
+      toBinary(FileIngestIdentitySchema, replacement),
+    );
+    expect(replacementDecoded.expectedCurrentFileId).toBe("file-current");
+  });
+
+  it.each([
+    { name: "first attach", expectedCurrentFileId: undefined },
+    { name: "replacement", expectedCurrentFileId: "file-current" },
+  ])("round-trips a $name attached event", ({ expectedCurrentFileId }) => {
+    const source = create(FileIngestAttachedEventSchema, {
+      correlationId: `correlation-${expectedCurrentFileId ?? "first"}`,
+      identity: {
+        entityType: TranscodeEntityType.TRACK,
+        entityId: "track-1",
+        fileId: "file-new",
+        mediaKind: FileIngestMediaKind.TRACK_AUDIO,
+        expectedCurrentFileId,
+      },
+      sequenceNumber: 1n,
+      timestampMs: 1782864000000n,
+      fileName: "field-recording.wav",
+      mimeType: "audio/wav",
+      fileSize: 1024n,
+    });
+
+    const decoded = deserializeProto(
+      FileIngestAttachedEventSchema,
+      toBinary(FileIngestAttachedEventSchema, source),
+    );
+
+    expect(decoded).toEqual(source);
+    expect(decoded.identity?.expectedCurrentFileId).toBe(expectedCurrentFileId);
+  });
+
+  it("preserves the immutable account-deletion identity/member pair", () => {
+    const source = create(UserDeleteIdentityCommandSchema, {
+      memberId: "14600000-0000-0000-0000-000000000001",
+      identityId: "14600000-0000-0000-0000-000000000003",
+      avatarAssetId: "14600000-0000-0000-0000-000000000002",
+      notificationEmail: "member@example.test",
+      notificationName: "Member",
+      notificationLocale: "ko",
+    });
+
+    expect(
+      deserializeProto(
+        UserDeleteIdentityCommandSchema,
+        toBinary(UserDeleteIdentityCommandSchema, source),
+      ),
+    ).toEqual(source);
+  });
+});

package/src/proto-helpers.ts

@@ -0,0 +1,62 @@
+import { fromBinary, type Message } from "@bufbuild/protobuf";
+import type { GenMessage } from "@bufbuild/protobuf/codegenv2";
+
+export type {
+  AssetRef,
+  AssetWriteResult,
+  AssetWriteTarget,
+} from "@echovisionlab/geul-proto/common/media_pb.ts";
+
+export {
+  AssetDisposition,
+  MediaProcessingStatus,
+} from "@echovisionlab/geul-proto/common/media_pb.ts";
+
+export type {
+  FileIngestAttachedEvent,
+  FileIngestDownloadEvent,
+  FileIngestFailedEvent,
+  FileIngestFinalizedEvent,
+  FileIngestIdentity,
+  FileIngestProgress,
+  FileIngestUploadEvent,
+  MediaProcessingLifecycleEvent,
+  MediaProcessingLifecycleOutputs,
+  MeshOptimizationResultEvent,
+  OgGenerationJob,
+  OgGenerationLifecycleEvent,
+  OgGenerationTarget,
+  TranscodeCompleteEvent,
+  TranslationLifecycleEvent,
+  WaveformResultEvent,
+} from "@echovisionlab/geul-proto/secure/events_pb.ts";
+
+export {
+  FileIngestAttachedEventSchema,
+  FileIngestDownloadEventSchema,
+  FileIngestFailedEventSchema,
+  FileIngestFailureReason,
+  FileIngestFinalizedEventSchema,
+  FileIngestIdentitySchema,
+  FileIngestMediaKind,
+  FileIngestSource,
+  FileIngestUploadEventSchema,
+  MediaProcessingLifecycleEventSchema,
+  MeshOptimizationResultEventSchema,
+  OgEntityType,
+  OgGenerationJobSchema,
+  OgGenerationLifecycleEventSchema,
+  OgGenerationStatus,
+  OgGenerationTargetSchema,
+  TranscodeCompleteEventSchema,
+  TranscodeEntityType,
+  TranslationLifecycleEventSchema,
+  WaveformResultEventSchema,
+} from "@echovisionlab/geul-proto/secure/events_pb.ts";
+
+export function deserializeProto<T extends Message>(
+  schema: GenMessage<T>,
+  data: Uint8Array,
+): T {
+  return fromBinary(schema, data);
+}

package/src/spicedb-policy.test.ts

@@ -0,0 +1,226 @@
+import { describe, expect, it } from "vitest";
+
+import { Artist } from "@echovisionlab/geul-proto/policy/spicedb/artist.ts";
+import {
+  EmailEventMapping,
+  EmailLayout,
+} from "@echovisionlab/geul-proto/policy/spicedb/email_authoring.ts";
+import {
+  EmailSuppression,
+  MailAdapter,
+} from "@echovisionlab/geul-proto/policy/spicedb/email_delivery.ts";
+import { File } from "@echovisionlab/geul-proto/policy/spicedb/file.ts";
+import {
+  DelegationKind,
+  DirectSession,
+  MCPOAuth,
+  NewAccountIdentityActor,
+  NewAuthorizationDecision,
+  Platform,
+  RelationshipOperation,
+  spiceDbCatalogFingerprint,
+} from "@echovisionlab/geul-proto/policy/spicedb/core.ts";
+import type {
+  Can,
+  RelationshipMutation,
+  Resource,
+  ResourceLookup,
+  SubjectLookup,
+} from "@echovisionlab/geul-proto/policy/spicedb/core.ts";
+import { Label } from "@echovisionlab/geul-proto/policy/spicedb/label.ts";
+import { Post } from "@echovisionlab/geul-proto/policy/spicedb/post.ts";
+import { ProgramEvent } from "@echovisionlab/geul-proto/policy/spicedb/program_event.ts";
+import {
+  TranslationProvider,
+  TranslationSettings,
+} from "@echovisionlab/geul-proto/policy/spicedb/translation.ts";
+
+function compileTimeInvalidSurfaceMustStayUnrepresentable(): void {
+  const actor = NewAccountIdentityActor("identity-id");
+
+  // @ts-expect-error Resource keys cannot be caller-authored.
+  const rawResource: Resource = { type: "post", id: "post-id" };
+  // @ts-expect-error Action and permission keys cannot be caller-authored.
+  const rawCan: Can = {};
+  // @ts-expect-error Lookup resource and permission keys cannot be caller-authored.
+  const rawLookup: ResourceLookup = {
+    resourceType: "post",
+    permission: "view",
+  };
+  // @ts-expect-error Subject lookup resource, permission, and subject keys cannot be caller-authored.
+  const rawSubjectLookup: SubjectLookup = {
+    resourceType: "platform",
+    resourceId: "global",
+    permission: "is_admin",
+    subjectType: "account_identity",
+  };
+  // @ts-expect-error Relation and operation combinations require a domain constructor.
+  const rawRelationship: RelationshipMutation = {};
+
+  const validCan = Post.Edit("post-id");
+  const spreadCan = {
+    ...validCan,
+    action: { ...validCan.action, permission: "delete" },
+  };
+  // @ts-expect-error Spreading a valid descriptor does not copy its private nominal key.
+  const forgedCan: Can = spreadCan;
+  const spreadResource = { ...Post.Resource("post-id"), type: "artist" };
+  // @ts-expect-error Spreading a valid resource does not copy its private nominal key.
+  const forgedResource: Resource = spreadResource;
+  const spreadLookup = {
+    ...Post.LookupView(),
+    permission: "delete",
+  };
+  // @ts-expect-error Spreading a lookup does not copy its private nominal key.
+  const forgedLookup: ResourceLookup = spreadLookup;
+
+  // @ts-expect-error Post has no Owner relation.
+  Post.TouchOwner("post-id", actor);
+  // @ts-expect-error Artist has no Collaborator relation.
+  Artist.TouchCollaborator("artist-id", actor);
+  // @ts-expect-error platform_admin is a schema helper, not a Post action.
+  Post.PlatformAdmin("post-id");
+  // @ts-expect-error ManageParticipants requires a Post id.
+  Post.ManageParticipants();
+  // @ts-expect-error Artist owns only the manage resource lookup.
+  Artist.LookupView();
+
+  void rawResource;
+  void rawCan;
+  void rawRelationship;
+  void rawLookup;
+  void rawSubjectLookup;
+  void forgedCan;
+  void forgedResource;
+  void forgedLookup;
+}
+
+void compileTimeInvalidSurfaceMustStayUnrepresentable;
+
+describe("domain-shaped SpiceDB policy descriptors", () => {
+  it("keeps direct-session and MCP engine checks byte-identical", () => {
+    expect(spiceDbCatalogFingerprint).toBe(
+      "b1c92baf58538b463ae2a94d9b26c3c7e920b22bf92ca71841196b017592a2fe",
+    );
+    const actor = NewAccountIdentityActor("identity-id");
+    const can = Post.Edit("post-id");
+    const direct = NewAuthorizationDecision(
+      actor,
+      DirectSession("session-id"),
+      can,
+    );
+    const oauth = NewAuthorizationDecision(
+      actor,
+      MCPOAuth("oauth-grant-id", "Example Member · Example Client"),
+      can,
+    );
+    expect(new TextEncoder().encode(oauth.engineKey)).toEqual(
+      new TextEncoder().encode(direct.engineKey),
+    );
+    expect(oauth.engineKey).toBe("post\0post-id\0edit");
+    expect(oauth.delegation.kind).toBe(DelegationKind.MCPOAuth);
+    expect(oauth.delegation.delegationId).toBe("oauth-grant-id");
+    expect(oauth.delegation.delegationDisplayName).toBe(
+      "Example Member · Example Client",
+    );
+    expect(Object.keys(oauth.delegation)).toEqual([
+      "kind",
+      "sessionId",
+      "delegationId",
+      "delegationDisplayName",
+    ]);
+    expect(Object.isFrozen(oauth)).toBe(true);
+  });
+
+  it("keeps exact global admin actions in their owning domains", () => {
+    const actions = {
+      "file.manage_library": File.ManageLibrary(),
+      "program_event.update_type": ProgramEvent.UpdateType(),
+      "program_event.delete_type": ProgramEvent.DeleteType(),
+      "email_event_mapping.update": EmailEventMapping.Update(),
+      "email_layout.preview_content": EmailLayout.PreviewContent(),
+      "translation_settings.view": TranslationSettings.View(),
+      "translation_settings.update": TranslationSettings.Update(),
+      "translation_provider.list": TranslationProvider.List(),
+      "translation_provider.create": TranslationProvider.Create(),
+      "translation_provider.update": TranslationProvider.Update(),
+      "translation_provider.delete": TranslationProvider.Delete(),
+      "mail_adapter.list": MailAdapter.List(),
+      "mail_adapter.create": MailAdapter.Create(),
+      "mail_adapter.update": MailAdapter.Update(),
+      "mail_adapter.delete": MailAdapter.Delete(),
+      "mail_adapter.test": MailAdapter.Test(),
+      "email_suppression.release": EmailSuppression.Release(),
+    };
+    for (const [name, can] of Object.entries(actions)) {
+      expect(can).toMatchObject({
+        resource: { type: "platform", id: "global" },
+        action: { name, permission: "is_admin" },
+      });
+    }
+  });
+
+  it("exposes business aliases without schema helper actions", () => {
+    expect(Post.RemoveAuthor("post-id").action).toMatchObject({
+      name: "remove_author",
+      permission: "platform_admin",
+    });
+    expect(Artist.RemoveOwner("artist-id").action.permission).toBe(
+      "platform_admin",
+    );
+    expect(Label.RemoveOwner("label-id").action.permission).toBe(
+      "platform_admin",
+    );
+    expect(Post.Create()).toMatchObject({
+      resource: { type: "platform", id: "global" },
+      action: { name: "post.create", permission: "is_author" },
+    });
+    expect(Post).not.toHaveProperty("PlatformAdmin");
+    expect(Post).not.toHaveProperty("AuthorManage");
+    expect(Artist).not.toHaveProperty("OwnerManage");
+    expect(Label).not.toHaveProperty("ManagerManage");
+  });
+
+  it("constructs exact object-ID-less resource lookups", () => {
+    const lookup = Post.LookupPlatformAdmin();
+    expect(lookup).toEqual({
+      resourceType: "post",
+      permission: "platform_admin",
+    });
+    expect(Object.isFrozen(lookup)).toBe(true);
+    expect(Post).not.toHaveProperty("PlatformAdmin");
+    expect(Artist).not.toHaveProperty("LookupView");
+  });
+
+  it("constructs only the closed platform account-identity subject lookups", () => {
+    expect(Platform.LookupAdminSubjects()).toEqual({
+      resourceType: "platform",
+      resourceId: "global",
+      permission: "is_admin",
+      subjectType: "account_identity",
+    });
+    expect(Platform.LookupAuthorSubjects().permission).toBe("is_author");
+    expect(Platform.LookupUserSubjects().permission).toBe("is_user");
+    expect(Object.isFrozen(Platform.LookupAdminSubjects())).toBe(true);
+  });
+
+  it("binds valid relation subjects and operations in domain constructors", () => {
+    const actor = NewAccountIdentityActor("identity-id");
+    expect(Post.TouchAuthor("post-id", actor)).toMatchObject({
+      resource: { type: "post", id: "post-id" },
+      relation: "author",
+      subject: { type: "account_identity", id: "identity-id", relation: "" },
+      operation: RelationshipOperation.Touch,
+    });
+    expect(Post.DeleteCollaborator("post-id", actor).operation).toBe(
+      RelationshipOperation.Delete,
+    );
+    expect(Artist.TouchParent("artist-id", "parent-id").subject).toEqual({
+      type: "artist",
+      id: "parent-id",
+      relation: "",
+    });
+    expect(Post).not.toHaveProperty("TouchOwner");
+    expect(Artist).not.toHaveProperty("TouchCollaborator");
+  });
+});

package/src/translation-source.test.ts

@@ -0,0 +1,28 @@
+import { create } from "@bufbuild/protobuf";
+import { describe, expect, it } from "vitest";
+import {
+  TranslationEntityType,
+  TranslationJobSchema,
+} from "@echovisionlab/geul-proto/secure/translation_pb.ts";
+import { assertTranslationJobRequestArtifact } from "./translation-source.ts";
+
+describe("translation request artifact", () => {
+  it("requires one target and canonical request artifact digest", () => {
+    const job = create(TranslationJobSchema);
+    expect(() => assertTranslationJobRequestArtifact(job)).toThrow(
+      "translation job target is required",
+    );
+
+    job.target = {
+      $typeName: "api.manage.v1.TranslationTarget",
+      entityType: TranslationEntityType.PAGE,
+      entityId: "entity-1",
+    };
+    expect(() => assertTranslationJobRequestArtifact(job)).toThrow(
+      "translation job request artifact digest is required",
+    );
+
+    job.requestArtifactDigest = "artifact-digest";
+    expect(() => assertTranslationJobRequestArtifact(job)).not.toThrow();
+  });
+});

package/src/translation-source.ts

@@ -0,0 +1,15 @@
+import type { TranslationJob } from "@echovisionlab/geul-proto/secure/translation_pb.ts";
+
+/**
+ * Validates the one request identity shared by every translation-capable
+ * domain. Domain-specific source epochs, hashes, and revision counters are
+ * intentionally absent from this boundary.
+ */
+export function assertTranslationJobRequestArtifact(job: TranslationJob): void {
+  if (job.target === undefined) {
+    throw new Error("translation job target is required");
+  }
+  if (job.requestArtifactDigest.trim().length === 0) {
+    throw new Error("translation job request artifact digest is required");
+  }
+}

package/src/user-delete-identity-mode.test.ts

@@ -0,0 +1,34 @@
+import { create } from "@bufbuild/protobuf";
+import { describe, expect, it } from "vitest";
+import {
+  UserDeleteIdentityCommandSchema,
+  UserDeleteIdentityMode,
+} from "@echovisionlab/geul-proto/secure/events_pb.ts";
+
+describe("UserDeleteIdentityCommand mode", () => {
+  it("keeps the zero value invalid instead of selecting a cleanup mode", () => {
+    const command = create(UserDeleteIdentityCommandSchema, {
+      memberId: "member-1",
+      identityId: "identity-1",
+    });
+
+    expect(command.mode).toBe(UserDeleteIdentityMode.UNSPECIFIED);
+    expect(command.mode).not.toBe(UserDeleteIdentityMode.TOMBSTONE);
+    expect(command.mode).not.toBe(
+      UserDeleteIdentityMode.UNONBOARDED_HARD_DELETE,
+    );
+  });
+
+  it.each([
+    UserDeleteIdentityMode.TOMBSTONE,
+    UserDeleteIdentityMode.UNONBOARDED_HARD_DELETE,
+  ])("round-trips explicit mode %s", (mode) => {
+    const command = create(UserDeleteIdentityCommandSchema, {
+      mode,
+      memberId: "member-1",
+      identityId: "identity-1",
+    });
+
+    expect(command.mode).toBe(mode);
+  });
+});