@volter/twin-postmark 0.1.0

package/src/postmark-conformance.ts

@@ -0,0 +1,282 @@
+// Postmark twin conformance — spec-true validation of the resources the twin serves against
+// per-object JSON Schemas (required fields, types, enums), offline (no key).
+//
+// The schemas below are transcribed from the OFFICIAL `postmark` SDK's own TypeScript models
+// (node_modules/postmark/dist/client/models/**/*.d.ts) — a first-party artifact naming every
+// field and its type. Postmark's API cannot be dual-run against a live sandbox in CI, so
+// those published shapes carry the weight here.
+//
+// For every resource the twin emits, validate its body via the shared specConformance
+// harness: declared TYPES, REQUIRED fields (omission), ENUMS. Twin-internal `_`-prefixed
+// fields are exempt; polymorphic/nested blocks (Triggers, Metadata, MessageEvents, DNS
+// detail) are left untyped to avoid false positives.
+import { twinResources } from '@volter/world-core';
+import { specConformance } from '@volter/world-tooling';
+import type { TwinResource } from '@volter/world-core';
+
+type JsonSchema = specConformance.JsonSchema;
+type KnownDeviation = specConformance.KnownDeviation;
+type SpecViolation = specConformance.SpecViolation;
+
+const SCHEMAS: Record<string, JsonSchema> = {
+  // SDK: models/messages/OutboundMessage.d.ts
+  message: {
+    type: 'object',
+    required: ['MessageID', 'From', 'Recipients', 'ReceivedAt', 'Status', 'MessageStream'],
+    properties: {
+      MessageID: { type: 'string' },
+      From: { type: 'string' },
+      Subject: { type: 'string' },
+      To: { type: 'array' },
+      Cc: { type: 'array' },
+      Bcc: { type: 'array' },
+      Recipients: { type: 'array' },
+      Attachments: { type: 'array' },
+      ReceivedAt: { type: 'string' },
+      Tag: { type: 'string' },
+      Status: { type: 'string', enum: ['Sent', 'Queued', 'Processed'] },
+      TrackOpens: { type: 'boolean' },
+      TrackLinks: { type: 'string', enum: ['None', 'HtmlAndText', 'HtmlOnly', 'TextOnly'] },
+      MessageStream: { type: 'string' },
+      Sandboxed: { type: 'boolean' },
+      MessageEvents: { type: 'array' },
+    },
+  },
+  // SDK: models/bounces/Bounce.d.ts (+ BounceType / BounceTypeCode enums)
+  bounce: {
+    type: 'object',
+    required: ['RecordType', 'ID', 'Type', 'TypeCode', 'Name', 'Email', 'BouncedAt', 'MessageStream'],
+    properties: {
+      RecordType: { type: 'string', enum: ['Bounce'] },
+      ID: { type: 'number' },
+      Type: { type: 'string', enum: ['HardBounce', 'Transient', 'SoftBounce', 'SpamComplaint', 'SpamNotification', 'Unsubscribe', 'AutoResponder', 'DnsError', 'BadEmailAddress', 'Blocked', 'ManuallyDeactivated', 'Unknown'] },
+      TypeCode: { type: 'number' },
+      Name: { type: 'string' },
+      Tag: { type: 'string' },
+      MessageID: { type: 'string' },
+      ServerID: { type: 'number' },
+      Description: { type: 'string' },
+      Details: { type: 'string' },
+      Email: { type: 'string' },
+      From: { type: 'string' },
+      BouncedAt: { type: 'string' },
+      DumpAvailable: { type: 'boolean' },
+      Inactive: { type: 'boolean' },
+      CanActivate: { type: 'boolean' },
+      Subject: { type: 'string' },
+      MessageStream: { type: 'string' },
+    },
+  },
+  // SDK: models/templates/Template.d.ts (+ TemplateTypes enum)
+  template: {
+    type: 'object',
+    required: ['TemplateId', 'Name', 'TemplateType', 'Active'],
+    properties: {
+      TemplateId: { type: 'number' },
+      Name: { type: 'string' },
+      TemplateType: { type: 'string', enum: ['Standard', 'Layout'] },
+      Subject: { type: 'string' },
+      Active: { type: 'boolean' },
+      AssociatedServerId: { type: 'number' },
+    },
+  },
+  // SDK: models/streams/MessageStream.d.ts
+  message_stream: {
+    type: 'object',
+    required: ['ID', 'ServerID', 'Name', 'MessageStreamType', 'CreatedAt'],
+    properties: {
+      ID: { type: 'string' },
+      ServerID: { type: 'number' },
+      Name: { type: 'string' },
+      Description: { type: 'string' },
+      MessageStreamType: { type: 'string', enum: ['Transactional', 'Broadcast', 'Inbound'] },
+      CreatedAt: { type: 'string' },
+    },
+  },
+  // SDK: models/webhooks/Webhook.d.ts
+  webhook: {
+    type: 'object',
+    required: ['ID', 'Url', 'MessageStream'],
+    properties: {
+      ID: { type: 'number' },
+      Url: { type: 'string' },
+      MessageStream: { type: 'string' },
+      HttpHeaders: { type: 'array' },
+    },
+  },
+  // SDK: models/suppressions/Suppression.d.ts (+ SuppressionReason / SuppressionOrigin enums)
+  suppression: {
+    type: 'object',
+    required: ['EmailAddress', 'SuppressionReason', 'Origin', 'CreatedAt'],
+    properties: {
+      EmailAddress: { type: 'string' },
+      SuppressionReason: { type: 'string', enum: ['HardBounce', 'SpamComplaint', 'ManualSuppression'] },
+      Origin: { type: 'string', enum: ['Recipient', 'Customer', 'Admin'] },
+      CreatedAt: { type: 'string' },
+      MessageStream: { type: 'string' },
+    },
+  },
+  // SDK: models/server/Server.d.ts (+ ServerDeliveryTypes enum)
+  server: {
+    type: 'object',
+    required: ['ID', 'Name', 'DeliveryType'],
+    properties: {
+      ID: { type: 'number' },
+      Name: { type: 'string' },
+      ApiTokens: { type: 'array' },
+      ServerLink: { type: 'string' },
+      Color: { type: 'string' },
+      SmtpApiActivated: { type: 'boolean' },
+      RawEmailEnabled: { type: 'boolean' },
+      DeliveryType: { type: 'string', enum: ['Live', 'Sandbox'] },
+      InboundAddress: { type: 'string' },
+      InboundHash: { type: 'string' },
+      InboundSpamThreshold: { type: 'number' },
+      TrackOpens: { type: 'boolean' },
+      TrackLinks: { type: 'string', enum: ['None', 'HtmlAndText', 'HtmlOnly', 'TextOnly'] },
+      PostFirstOpenOnly: { type: 'boolean' },
+    },
+  },
+  // SDK: models/domains/Domain.d.ts (DomainDetails)
+  domain: {
+    type: 'object',
+    required: ['ID', 'Name', 'SPFVerified', 'DKIMVerified', 'ReturnPathDomainVerified'],
+    properties: {
+      ID: { type: 'number' },
+      Name: { type: 'string' },
+      SPFVerified: { type: 'boolean' },
+      DKIMVerified: { type: 'boolean' },
+      WeakDKIM: { type: 'boolean' },
+      ReturnPathDomainVerified: { type: 'boolean' },
+      SPFHost: { type: 'string' },
+      SPFTextValue: { type: 'string' },
+      DKIMHost: { type: 'string' },
+      DKIMTextValue: { type: 'string' },
+      DKIMUpdateStatus: { type: 'string' },
+      ReturnPathDomain: { type: 'string' },
+      ReturnPathDomainCNAMEValue: { type: 'string' },
+    },
+  },
+  // SDK: models/senders/Signature.d.ts (SignatureDetails extends DomainDetails)
+  sender_signature: {
+    type: 'object',
+    required: ['ID', 'Domain', 'EmailAddress', 'Name', 'Confirmed'],
+    properties: {
+      ID: { type: 'number' },
+      Domain: { type: 'string' },
+      EmailAddress: { type: 'string' },
+      ReplyToEmailAddress: { type: 'string' },
+      Name: { type: 'string' },
+      Confirmed: { type: 'boolean' },
+      ConfirmationPersonalNote: { type: 'string' },
+    },
+  },
+  // SDK: models/triggers/InboundRule.d.ts
+  inbound_rule: {
+    type: 'object',
+    required: ['ID', 'Rule'],
+    properties: { ID: { type: 'number' }, Rule: { type: 'string' } },
+  },
+  // SDK: models/messages/InboundMessage.d.ts
+  inbound_message: {
+    type: 'object',
+    required: ['MessageID', 'From', 'To', 'Date', 'Status', 'MessageStream'],
+    properties: {
+      MessageID: { type: 'string' },
+      From: { type: 'string' },
+      FromName: { type: 'string' },
+      To: { type: 'string' },
+      Cc: { type: 'string' },
+      Bcc: { type: 'string' },
+      Subject: { type: 'string' },
+      Date: { type: 'string' },
+      MailboxHash: { type: 'string' },
+      Tag: { type: 'string' },
+      Status: { type: 'string', enum: ['queued', 'sent', 'processed', 'blocked', 'failed', 'scheduled', 'Queued', 'Sent', 'Processed', 'Blocked', 'Failed', 'Scheduled'] },
+      Attachments: { type: 'array' },
+      MessageStream: { type: 'string' },
+    },
+  },
+  // SDK: models/data_removal/DataRemoval.d.ts
+  data_removal: {
+    type: 'object',
+    required: ['ID', 'Status'],
+    properties: {
+      ID: { type: 'number' },
+      Status: { type: 'string', enum: ['Pending', 'Done'] },
+      RequestedBy: { type: 'string' },
+      RequestedFor: { type: 'string' },
+      NotifyWhenCompleted: { type: 'boolean' },
+    },
+  },
+};
+
+// twin resource type → schema key (1:1 here).
+const TYPE_TO_OBJECT: Record<string, string> = Object.fromEntries(Object.keys(SCHEMAS).map((k) => [k, k]));
+
+export type PostmarkViolation = SpecViolation & { object: string; id: string };
+export type PostmarkConformanceReport = {
+  ok: boolean;
+  resourcesChecked: number;
+  fieldsChecked: number;
+  violations: PostmarkViolation[];
+  knownIgnored: number;
+};
+
+const isTwinExtra = (k: string): boolean => k.startsWith('_');
+
+/** The emitted body: drop kernel meta + twin-internal fields. */
+function emitted(r: TwinResource): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(r as unknown as Record<string, unknown>)) {
+    if (k === 'type' || k === 'id' || k === 'updatedAt' || k.startsWith('_')) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+export function loadPostmarkSchemas(): Record<string, JsonSchema> {
+  return SCHEMAS;
+}
+
+/**
+ * Validate every Postmark resource the twin serves (in `root`) against its schema. A wrong
+ * type, an undeclared missing-required field, or an enum violation fails the report.
+ * Soft-deleted rows are skipped — a tombstone is not a served resource.
+ */
+export function checkPostmarkConformance(opts: { root?: string; known?: KnownDeviation[] } = {}): PostmarkConformanceReport {
+  const resources = twinResources('postmark', opts.root)
+    .filter((r) => !r.type.startsWith('_') && (r as unknown as Record<string, unknown>).deleted !== true);
+  const violations: PostmarkViolation[] = [];
+  let fieldsChecked = 0;
+  let knownIgnored = 0;
+  for (const r of resources) {
+    const objectName = TYPE_TO_OBJECT[r.type];
+    if (!objectName) continue;
+    const schema = SCHEMAS[objectName];
+    if (!schema) continue;
+    const rep = specConformance.checkSpecConformance(emitted(r), schema, { exemptKey: isTwinExtra, known: opts.known ?? [], flagExtra: false });
+    fieldsChecked += rep.fieldsChecked;
+    knownIgnored += rep.knownIgnored;
+    for (const v of rep.violations) violations.push({ ...v, object: objectName, id: r.id });
+  }
+  return { ok: violations.length === 0, resourcesChecked: resources.length, fieldsChecked, violations, knownIgnored };
+}
+
+export type PostmarkCoverageReport = specConformance.SpecCoverageReport & { object: string };
+
+/** Per-object coverage: of the fields each Postmark object declares, which does the twin emit? */
+export function postmarkCoverage(opts: { root?: string } = {}): PostmarkCoverageReport[] {
+  const byType = new Map<string, TwinResource>();
+  for (const r of twinResources('postmark', opts.root)) {
+    if (!r.type.startsWith('_') && !byType.has(r.type) && (r as unknown as Record<string, unknown>).deleted !== true) byType.set(r.type, r);
+  }
+  const out: PostmarkCoverageReport[] = [];
+  for (const [type, r] of byType) {
+    const objectName = TYPE_TO_OBJECT[type];
+    const schema = objectName ? SCHEMAS[objectName] : undefined;
+    if (!objectName || !schema) continue;
+    out.push({ object: objectName, ...specConformance.specCoverage(schema, emitted(r), { exemptKey: isTwinExtra }) });
+  }
+  return out;
+}

package/src/postmark-connector.ts

@@ -0,0 +1,312 @@
+// Postmark CONNECTOR — the live-vendor pull/push path that gives the Postmark twin the full
+// "git for SaaS" lifecycle over an INJECTED client (the auth boundary).
+//
+// PULL  (real → twin):  fetch real Postmark objects via the injected client (outbound
+//                       messages, bounces, templates, message streams, webhooks, and the
+//                       server itself), map them to SyncResource[], and fold them into the
+//                       tree through the kernel's observe (its own diff, so a re-pull of identical
+//                       state is a no-op).
+// PUSH  (twin → real):  for every PENDING local action, call the injected client and
+//                       confirmAction on success. The headline push is sending local
+//                       messages to real Postmark; templates/webhooks/streams follow.
+//
+// The vendor I/O is an INJECTED client interface (`PostmarkClient`): a fake in tests, a real
+// `new postmark.ServerClient(token)` in prod. The pack imports NO SDK and holds NO key. The
+// shape below is a structural SUBSET of the real `ServerClient` (method names taken from the
+// SDK's own ServerClient.d.ts), so a real client satisfies it without adaptation.
+import { observeResources } from '@volter/world-core';
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+
+const SERVICE = 'postmark';
+
+/**
+ * The injected real-Postmark boundary — the subset of `postmark`'s `ServerClient` this
+ * connector uses. A real `new ServerClient(token)` is structurally assignable; tests pass a
+ * fake. Only the methods the connector calls are declared, so the surface stays honest.
+ * Unlike Resend's `{data, error}` envelope, the Postmark SDK RESOLVES with the payload and
+ * REJECTS with a typed `PostmarkError` — this interface mirrors that.
+ */
+export interface PostmarkClient {
+  getOutboundMessages(filter?: Record<string, unknown>): Promise<{ TotalCount: number | string; Messages: PostmarkOutboundMessage[] }>;
+  getBounces(filter?: Record<string, unknown>): Promise<{ TotalCount: number; Bounces: PostmarkBounce[] }>;
+  getTemplates(filter?: Record<string, unknown>): Promise<{ TotalCount: number; Templates: PostmarkTemplate[] }>;
+  getMessageStreams(filter?: Record<string, unknown>): Promise<{ TotalCount: number; MessageStreams: PostmarkMessageStream[] }>;
+  getWebhooks(filter?: Record<string, unknown>): Promise<{ Webhooks: PostmarkWebhookConfig[] }>;
+  getServer(): Promise<PostmarkServer>;
+  sendEmail(message: Record<string, unknown>): Promise<{ MessageID: string; ErrorCode: number; Message: string }>;
+  createTemplate(options: Record<string, unknown>): Promise<{ TemplateId: number }>;
+  createWebhook(options: Record<string, unknown>): Promise<{ ID: number }>;
+  createMessageStream(options: Record<string, unknown>): Promise<{ ID: string }>;
+}
+
+export type PostmarkRecipient = { Email?: string; Name?: string };
+export type PostmarkOutboundMessage = {
+  MessageID: string; Tag?: string; To?: PostmarkRecipient[]; Cc?: PostmarkRecipient[]; Bcc?: PostmarkRecipient[];
+  Recipients?: string[]; ReceivedAt?: string; From?: string; Subject?: string; Attachments?: string[];
+  Status?: string; TrackOpens?: boolean; TrackLinks?: string; Metadata?: Record<string, string>;
+  MessageStream?: string; Sandboxed?: boolean;
+};
+export type PostmarkBounce = {
+  ID: number; Type?: string; TypeCode?: number; Name?: string; Tag?: string; MessageID?: string;
+  ServerID?: number; Description?: string; Details?: string; Email?: string; From?: string;
+  BouncedAt?: string; DumpAvailable?: boolean; Inactive?: boolean; CanActivate?: boolean;
+  Subject?: string; MessageStream?: string;
+};
+export type PostmarkTemplate = {
+  TemplateId: number; Name?: string; Alias?: string | null; TemplateType?: string;
+  Active?: boolean; LayoutTemplate?: string | null; Subject?: string; HtmlBody?: string | null; TextBody?: string | null;
+};
+export type PostmarkMessageStream = {
+  ID: string; ServerID?: number; Name?: string; Description?: string; MessageStreamType?: string;
+  CreatedAt?: string; UpdatedAt?: string | null; ArchivedAt?: string | null;
+  SubscriptionManagementConfiguration?: Record<string, unknown>;
+};
+export type PostmarkWebhookConfig = {
+  ID: number; Url?: string; MessageStream?: string; HttpAuth?: Record<string, unknown> | null;
+  HttpHeaders?: Array<Record<string, unknown>>; Triggers?: Record<string, unknown>;
+};
+export type PostmarkServer = {
+  ID: number; Name?: string; Color?: string; DeliveryType?: string; TrackOpens?: boolean;
+  TrackLinks?: string; InboundAddress?: string; ServerLink?: string; SmtpApiActivated?: boolean;
+};
+
+function listOf<T>(value: T[] | undefined): T[] {
+  return Array.isArray(value) ? value : [];
+}
+
+// ── PULL: pure shape mappers (no client, no I/O — trivially unit-testable) ──────────
+export function mapMessage(m: PostmarkOutboundMessage): SyncResource {
+  return {
+    type: 'message',
+    id: String(m.MessageID),
+    fields: {
+      MessageID: String(m.MessageID), Tag: m.Tag ?? '', To: listOf(m.To), Cc: listOf(m.Cc), Bcc: listOf(m.Bcc),
+      Recipients: listOf(m.Recipients), ReceivedAt: m.ReceivedAt ?? null, From: m.From ?? null,
+      Subject: m.Subject ?? '', Attachments: listOf(m.Attachments), Status: m.Status ?? 'Sent',
+      TrackOpens: m.TrackOpens === true, TrackLinks: m.TrackLinks ?? 'None', Metadata: m.Metadata ?? {},
+      MessageStream: m.MessageStream ?? 'outbound', Sandboxed: m.Sandboxed === true,
+      HtmlBody: null, TextBody: null, MessageEvents: [],
+    },
+  };
+}
+export function mapBounce(b: PostmarkBounce): SyncResource {
+  return {
+    type: 'bounce',
+    id: String(b.ID),
+    fields: {
+      RecordType: 'Bounce', ID: b.ID, Type: b.Type ?? 'HardBounce', TypeCode: b.TypeCode ?? 1,
+      Name: b.Name ?? 'Hard bounce', Tag: b.Tag ?? '', MessageID: b.MessageID ?? null,
+      ServerID: b.ServerID ?? 1, Description: b.Description ?? '', Details: b.Details ?? '',
+      Email: b.Email ?? null, From: b.From ?? null, BouncedAt: b.BouncedAt ?? null,
+      DumpAvailable: b.DumpAvailable === true, Inactive: b.Inactive === true,
+      CanActivate: b.CanActivate === true, Subject: b.Subject ?? '', MessageStream: b.MessageStream ?? 'outbound',
+    },
+  };
+}
+export function mapTemplate(t: PostmarkTemplate): SyncResource {
+  return {
+    type: 'template',
+    id: String(t.TemplateId),
+    fields: {
+      TemplateId: t.TemplateId, Name: t.Name ?? null, Alias: t.Alias ?? null,
+      TemplateType: t.TemplateType ?? 'Standard', Active: t.Active !== false,
+      LayoutTemplate: t.LayoutTemplate ?? null, Subject: t.Subject ?? '',
+      HtmlBody: t.HtmlBody ?? null, TextBody: t.TextBody ?? null, AssociatedServerId: 1,
+    },
+  };
+}
+export function mapMessageStream(s: PostmarkMessageStream): SyncResource {
+  return {
+    type: 'message_stream',
+    id: String(s.ID),
+    fields: {
+      ID: String(s.ID), ServerID: s.ServerID ?? 1, Name: s.Name ?? String(s.ID),
+      Description: s.Description ?? '', MessageStreamType: s.MessageStreamType ?? 'Transactional',
+      CreatedAt: s.CreatedAt ?? null, UpdatedAt: s.UpdatedAt ?? null, ArchivedAt: s.ArchivedAt ?? null,
+      SubscriptionManagementConfiguration: s.SubscriptionManagementConfiguration ?? { UnsubscribeHandlingType: 'None' },
+    },
+  };
+}
+export function mapWebhook(w: PostmarkWebhookConfig): SyncResource {
+  return {
+    type: 'webhook',
+    id: String(w.ID),
+    fields: {
+      ID: w.ID, Url: w.Url ?? null, MessageStream: w.MessageStream ?? 'outbound',
+      HttpAuth: w.HttpAuth ?? null, HttpHeaders: listOf(w.HttpHeaders), Triggers: w.Triggers ?? {},
+    },
+  };
+}
+export function mapServer(s: PostmarkServer): SyncResource {
+  return {
+    type: 'server',
+    id: String(s.ID),
+    fields: {
+      ID: s.ID, Name: s.Name ?? null, Color: s.Color ?? 'blue', DeliveryType: s.DeliveryType ?? 'Live',
+      TrackOpens: s.TrackOpens === true, TrackLinks: s.TrackLinks ?? 'None',
+      InboundAddress: s.InboundAddress ?? '', ServerLink: s.ServerLink ?? '',
+      SmtpApiActivated: s.SmtpApiActivated !== false,
+    },
+  };
+}
+
+// ── PULL: the network-touching entry points ────────────────────────────────────────
+export async function pullPostmarkMessages(client: PostmarkClient): Promise<SyncResource[]> {
+  return listOf((await client.getOutboundMessages({ count: 500, offset: 0 })).Messages).map(mapMessage);
+}
+export async function pullPostmarkBounces(client: PostmarkClient): Promise<SyncResource[]> {
+  return listOf((await client.getBounces({ count: 500, offset: 0 })).Bounces).map(mapBounce);
+}
+export async function pullPostmarkTemplates(client: PostmarkClient): Promise<SyncResource[]> {
+  return listOf((await client.getTemplates({ count: 500, offset: 0 })).Templates).map(mapTemplate);
+}
+export async function pullPostmarkMessageStreams(client: PostmarkClient): Promise<SyncResource[]> {
+  return listOf((await client.getMessageStreams()).MessageStreams).map(mapMessageStream);
+}
+export async function pullPostmarkWebhooks(client: PostmarkClient): Promise<SyncResource[]> {
+  return listOf((await client.getWebhooks()).Webhooks).map(mapWebhook);
+}
+export async function pullPostmarkServer(client: PostmarkClient): Promise<SyncResource[]> {
+  return [mapServer(await client.getServer())];
+}
+
+/**
+ * D7 entry point: pull from real Postmark and fold everything into the twin (mirror seeding).
+ * Callers never have to know the per-domain `pull*` mechanics.
+ */
+export async function syncPostmarkFromReal(
+  client: PostmarkClient,
+  opts: { root?: string; occurredAt: string },
+): Promise<{ observed: number; deltasAppended: number }> {
+  const resources: SyncResource[] = [
+    ...(await pullPostmarkMessageStreams(client)),
+    ...(await pullPostmarkServer(client)),
+    ...(await pullPostmarkTemplates(client)),
+    ...(await pullPostmarkMessages(client)),
+    ...(await pullPostmarkBounces(client)),
+    ...(await pullPostmarkWebhooks(client)),
+  ];
+  // protocol 2: the observation lands on the head through the kernel's fold — one batch, one instant
+  const result = observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), { ...(opts.root !== undefined ? { root: opts.root } : {}), at: opts.occurredAt, batch: `obs:${SERVICE}:${opts.occurredAt}` });
+  return { observed: result.observed, deltasAppended: result.appended };
+}
+
+// ── PUSH ────────────────────────────────────────────────────────────────────────────
+// The twin operations this connector knows how to push to real Postmark. Anything not here
+// FAILS LOUDLY rather than being silently dropped.
+const PUSHABLE = new Set(['message.send', 'template.create', 'webhook.create', 'message_stream.create']);
+
+function assertPushable(op: string): void {
+  if (!PUSHABLE.has(op)) {
+    throw new Error(`postmark push: unsupported operation '${op}' — refusing to silently drop a local write`);
+  }
+}
+
+/** Recipients are stored structurally in the twin; Postmark's API takes a comma-joined string. */
+function joinRecipients(v: unknown): string {
+  if (Array.isArray(v)) return v.map((r) => String((r as PostmarkRecipient)?.Email ?? r)).filter(Boolean).join(', ');
+  return typeof v === 'string' ? v : '';
+}
+
+/**
+ * Push ONE pending action to REAL Postmark via the injected client. Returns the real external
+ * id (the Postmark object id from the response). WRITES TO THE REAL ACCOUNT (sends real email).
+ */
+export async function pushPostmarkAction(
+  client: PostmarkClient,
+  action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>,
+): Promise<{ externalId: string }> {
+  const op = action.operation ?? `${action.subject.type}.update`;
+  assertPushable(op);
+  const f = action.fields ?? {};
+  let externalId = action.subject.id;
+  if (op === 'message.send') {
+    const res = await client.sendEmail({
+      From: String(f.From ?? ''),
+      To: joinRecipients(f.To) || joinRecipients(f.Recipients),
+      ...(joinRecipients(f.Cc) ? { Cc: joinRecipients(f.Cc) } : {}),
+      ...(joinRecipients(f.Bcc) ? { Bcc: joinRecipients(f.Bcc) } : {}),
+      Subject: String(f.Subject ?? ''),
+      ...(f.HtmlBody != null ? { HtmlBody: String(f.HtmlBody) } : {}),
+      ...(f.TextBody != null ? { TextBody: String(f.TextBody) } : {}),
+      ...(f.Tag ? { Tag: String(f.Tag) } : {}),
+      ...(f.MessageStream ? { MessageStream: String(f.MessageStream) } : {}),
+      ...(f.TrackOpens === true ? { TrackOpens: true } : {}),
+      ...(f.TrackLinks && f.TrackLinks !== 'None' ? { TrackLinks: String(f.TrackLinks) } : {}),
+    });
+    externalId = String(res.MessageID);
+  } else if (op === 'template.create') {
+    externalId = String((await client.createTemplate({
+      Name: String(f.Name ?? ''),
+      ...(f.Alias != null ? { Alias: String(f.Alias) } : {}),
+      Subject: String(f.Subject ?? ''),
+      ...(f.HtmlBody != null ? { HtmlBody: String(f.HtmlBody) } : {}),
+      ...(f.TextBody != null ? { TextBody: String(f.TextBody) } : {}),
+      TemplateType: String(f.TemplateType ?? 'Standard'),
+    })).TemplateId);
+  } else if (op === 'webhook.create') {
+    externalId = String((await client.createWebhook({
+      Url: String(f.Url ?? ''),
+      MessageStream: String(f.MessageStream ?? 'outbound'),
+      ...(f.HttpAuth ? { HttpAuth: f.HttpAuth } : {}),
+      ...(Array.isArray(f.HttpHeaders) && f.HttpHeaders.length ? { HttpHeaders: f.HttpHeaders } : {}),
+      Triggers: (f.Triggers as Record<string, unknown>) ?? {},
+    })).ID);
+  } else if (op === 'message_stream.create') {
+    externalId = String((await client.createMessageStream({
+      ID: String(f.ID ?? action.subject.id),
+      Name: String(f.Name ?? ''),
+      MessageStreamType: String(f.MessageStreamType ?? 'Transactional'),
+      ...(f.Description ? { Description: String(f.Description) } : {}),
+    })).ID);
+  }
+  return { externalId: externalId || action.subject.id };
+}
+
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/** A PostmarkClient over the kernel's executor. At a REAL boundary the kernel's executor sets the sealed
+ *  credential over these headers (executor.ts); at the twin's own wire any credential is one. */
+export function postmarkClientOver(execute: RemoteExecute): PostmarkClient {
+  const get = async (path: string): Promise<any> => {
+    const res = await execute({ method: 'GET', path, headers: { accept: 'application/json', authorization: 'Bearer twin', 'x-postmark-server-token': 'twin' } });
+    if (res.status < 200 || res.status >= 300) throw new Error(`postmark GET ${path} refused: HTTP ${res.status} ${res.body.slice(0, 200)}`);
+    return JSON.parse(res.body || '{}');
+  };
+  const post = async (path: string, body: Record<string, unknown>): Promise<any> => {
+    const res = await execute({ method: 'POST', path, headers: { accept: 'application/json', 'content-type': 'application/json', 'x-postmark-server-token': 'twin' }, body: JSON.stringify(body) });
+    if (res.status < 200 || res.status >= 300) throw new Error(`postmark POST ${path} refused: HTTP ${res.status} ${res.body.slice(0, 200)}`);
+    return JSON.parse(res.body || '{}');
+  };
+  return {
+    getServer: () => get('/server'),
+    getMessageStreams: () => get('/message-streams'),
+    getOutboundMessages: () => get('/messages/outbound'),
+    getBounces: () => get('/bounces'),
+    getTemplates: () => get('/templates'),
+    getWebhooks: () => get('/webhooks'),
+    sendEmail: (message: Record<string, unknown>) => post('/email', message),
+    createTemplate: (options: Record<string, unknown>) => post('/templates', options),
+    createWebhook: (options: Record<string, unknown>) => post('/webhooks', options),
+    createMessageStream: (options: Record<string, unknown>) => post('/message-streams', options),
+  } as unknown as PostmarkClient;
+}
+/** The refresh adapter: pull the account's state through the executor and fold it into the root. */
+export async function syncPostmarkFromRemote(execute: RemoteExecute, opts: { root?: string; origin?: string; occurredAt?: string } = {}): Promise<ReturnType<typeof syncPostmarkFromReal>> {
+  return syncPostmarkFromReal(postmarkClientOver(execute), {
+    ...(opts.root !== undefined ? { root: opts.root } : {}),
+    occurredAt: opts.occurredAt ?? new Date().toISOString(),
+  } as never);
+}
+/** The perform adapter: a message send crosses; everything else is the twin's own record. */
+export async function performPostmarkAction(execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome> {
+  const op = action.operation ?? `${action.subject.type}.update`;
+  try {
+    return await pushPostmarkAction(postmarkClientOver(execute), { operation: op, subject: action.subject, fields: action.fields ?? {} });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/unsupported operation|not pushable|no push/i.test(message)) {
+      return { externalId: action.subject.id, data: { performed: false, reason: `${op} is the twin's own record — nothing at Postmark to write` } };
+    }
+    throw error;
+  }
+}