@syncular/core 0.0.6-96 → 0.1.0

package/src/schemas/sync.ts

@@ -9,8 +9,11 @@
 
 import { z } from 'zod';
 import {
+  SYNC_SCOPED_SNAPSHOT_ARTIFACT_KIND_SQLITE_V1,
+  SYNC_SCOPED_SNAPSHOT_ARTIFACT_MANIFEST_VERSION,
+  SYNC_SNAPSHOT_ARTIFACT_COMPRESSION_NONE,
   SYNC_SNAPSHOT_CHUNK_COMPRESSION,
-  SYNC_SNAPSHOT_CHUNK_ENCODING,
+  SYNC_SNAPSHOT_CHUNK_ENCODINGS,
 } from '../snapshot-chunks';
 
 // ============================================================================
@@ -37,6 +40,95 @@ export const ScopeValuesSchema = z.record(
   z.union([z.string(), z.array(z.string())])
 );
 
+// ============================================================================
+// Auth Lease Schemas
+// ============================================================================
+
+export const SYNC_AUTH_LEASE_VERSION = 1;
+export const SYNC_AUTH_LEASE_PROTOCOL_VERSION = 1;
+export const SYNC_AUTH_LEASE_ALG_ES256 = 'ES256';
+export const SYNC_AUTH_LEASE_TYP = 'syncular-auth-lease+jws';
+export const SYNC_AUTH_LEASE_CODE_MISSING = 'sync.auth_lease_missing';
+export const SYNC_AUTH_LEASE_CODE_INVALID = 'sync.auth_lease_invalid';
+export const SYNC_AUTH_LEASE_CODE_EXPIRED = 'sync.auth_lease_expired';
+export const SYNC_AUTH_LEASE_CODE_SCHEMA_MISMATCH =
+  'sync.auth_lease_schema_mismatch';
+export const SYNC_AUTH_LEASE_CODE_SCOPE_MISMATCH =
+  'sync.auth_lease_scope_mismatch';
+export const SYNC_AUTH_LEASE_CODE_SCOPE_REVOKED =
+  'sync.auth_lease_scope_revoked';
+export const SYNC_AUTH_LEASE_CODE_BUSINESS_REJECTED =
+  'sync.auth_lease_business_rejected';
+
+export const SyncAuthLeaseProtectedHeaderSchema = z.object({
+  alg: z.literal(SYNC_AUTH_LEASE_ALG_ES256),
+  kid: z.string().min(1),
+  typ: z.literal(SYNC_AUTH_LEASE_TYP),
+});
+
+export type SyncAuthLeaseProtectedHeader = z.infer<
+  typeof SyncAuthLeaseProtectedHeaderSchema
+>;
+
+export const SyncAuthLeaseCapabilitiesSchema = z.object({
+  allowBlobs: z.boolean(),
+  allowCrdt: z.boolean(),
+  allowEncryptedFields: z.boolean(),
+});
+
+export type SyncAuthLeaseCapabilities = z.infer<
+  typeof SyncAuthLeaseCapabilitiesSchema
+>;
+
+export const SyncAuthLeaseScopeSchema = z.object({
+  subscriptionId: z.string().min(1),
+  table: z.string().min(1),
+  values: ScopeValuesSchema,
+  operations: z.array(SyncOpSchema).min(1),
+});
+
+export type SyncAuthLeaseScope = z.infer<typeof SyncAuthLeaseScopeSchema>;
+
+export const SyncAuthLeasePayloadSchema = z.object({
+  version: z.literal(SYNC_AUTH_LEASE_VERSION),
+  leaseId: z.string().min(1),
+  issuer: z.string().min(1),
+  audience: z.string().min(1),
+  actorId: z.string().min(1),
+  subject: z.record(z.string(), z.unknown()).default({}),
+  schemaVersion: z.number().int().min(1),
+  protocolVersion: z.literal(SYNC_AUTH_LEASE_PROTOCOL_VERSION),
+  issuedAtMs: z.number().int(),
+  notBeforeMs: z.number().int(),
+  expiresAtMs: z.number().int(),
+  maxClockSkewMs: z.number().int().min(0),
+  scopes: z.array(SyncAuthLeaseScopeSchema).min(1),
+  capabilities: SyncAuthLeaseCapabilitiesSchema,
+});
+
+export type SyncAuthLeasePayload = z.infer<typeof SyncAuthLeasePayloadSchema>;
+
+export const SyncAuthLeaseIssueRequestSchema = z.object({
+  schemaVersion: z.number().int().min(1),
+  ttlMs: z.number().int().positive().optional(),
+  scopes: z.array(SyncAuthLeaseScopeSchema).min(1),
+});
+
+export type SyncAuthLeaseIssueRequest = z.infer<
+  typeof SyncAuthLeaseIssueRequestSchema
+>;
+
+export const SyncAuthLeaseIssueResponseSchema = z.object({
+  ok: z.literal(true),
+  token: z.string().min(1),
+  protectedHeader: SyncAuthLeaseProtectedHeaderSchema,
+  payload: SyncAuthLeasePayloadSchema,
+});
+
+export type SyncAuthLeaseIssueResponse = z.infer<
+  typeof SyncAuthLeaseIssueResponseSchema
+>;
+
 // ============================================================================
 // Sync Operation Schema
 // ============================================================================
@@ -55,15 +147,34 @@ export type SyncOperation = z.infer<typeof SyncOperationSchema>;
 // Push Request/Response Schemas
 // ============================================================================
 
+export const SyncAuthLeaseProvenanceSchema = z.object({
+  leaseId: z.string().min(1),
+  leaseExpiresAtMs: z.number().int(),
+  leaseStatusAtEnqueue: z.string().min(1),
+  leaseScopeSummaryJson: z.string().optional(),
+  leaseToken: z.string().min(1).optional(),
+});
+
+export type SyncAuthLeaseProvenance = z.infer<
+  typeof SyncAuthLeaseProvenanceSchema
+>;
+
 export const SyncPushRequestSchema = z.object({
   clientId: z.string().min(1),
   clientCommitId: z.string().min(1),
   operations: z.array(SyncOperationSchema).min(1),
   schemaVersion: z.number().int().min(1),
+  authLease: SyncAuthLeaseProvenanceSchema.optional(),
 });
 
 export type SyncPushRequest = z.infer<typeof SyncPushRequestSchema>;
 
+export const SyncPushCommitRequestSchema = SyncPushRequestSchema.omit({
+  clientId: true,
+});
+
+export type SyncPushCommitRequest = z.infer<typeof SyncPushCommitRequestSchema>;
+
 const SyncOperationResultAppliedSchema = z.object({
   opIndex: z.number().int(),
   status: z.literal('applied'),
@@ -73,6 +184,7 @@ const SyncOperationResultConflictSchema = z.object({
   opIndex: z.number().int(),
   status: z.literal('conflict'),
   message: z.string(),
+  code: z.string().optional(),
   server_version: z.number().int(),
   server_row: z.unknown(),
 });
@@ -102,6 +214,28 @@ export const SyncPushResponseSchema = z.object({
 
 export type SyncPushResponse = z.infer<typeof SyncPushResponseSchema>;
 
+export const SyncPushBatchCommitResponseSchema = SyncPushResponseSchema.extend({
+  clientCommitId: z.string().min(1),
+});
+
+export type SyncPushBatchCommitResponse = z.infer<
+  typeof SyncPushBatchCommitResponseSchema
+>;
+
+export const SyncPushBatchRequestSchema = z.object({
+  clientId: z.string().min(1),
+  commits: z.array(SyncPushCommitRequestSchema).min(1),
+});
+
+export type SyncPushBatchRequest = z.infer<typeof SyncPushBatchRequestSchema>;
+
+export const SyncPushBatchResponseSchema = z.object({
+  ok: z.literal(true),
+  commits: z.array(SyncPushBatchCommitResponseSchema),
+});
+
+export type SyncPushBatchResponse = z.infer<typeof SyncPushBatchResponseSchema>;
+
 // ============================================================================
 // Bootstrap State Schema
 // ============================================================================
@@ -119,6 +253,19 @@ export type SyncBootstrapState = z.infer<typeof SyncBootstrapStateSchema>;
 // Pull Request/Response Schemas
 // ============================================================================
 
+export const SyncCrdtStateVectorHintSchema = z.object({
+  rowId: z.string().min(1),
+  field: z.string().min(1),
+  stateColumn: z.string().min(1),
+  stateVectorBase64: z.string().min(1),
+  syncMode: z.string().min(1),
+  updatedAt: z.number().int(),
+});
+
+export type SyncCrdtStateVectorHint = z.infer<
+  typeof SyncCrdtStateVectorHintSchema
+>;
+
 export const SyncSubscriptionRequestSchema = z.object({
   id: z.string().min(1),
   table: z.string().min(1),
@@ -126,18 +273,46 @@ export const SyncSubscriptionRequestSchema = z.object({
   params: z.record(z.string(), z.unknown()).optional(),
   cursor: z.number().int(),
   bootstrapState: SyncBootstrapStateSchema.nullable().optional(),
+  verifiedRoot: z.string().optional(),
+  crdtStateVectors: z
+    .array(SyncCrdtStateVectorHintSchema)
+    .optional()
+    .default([]),
 });
 
 export type SyncSubscriptionRequest = z.infer<
   typeof SyncSubscriptionRequestSchema
 >;
 
+export const SyncSnapshotChunkEncodingSchema = z.enum(
+  SYNC_SNAPSHOT_CHUNK_ENCODINGS
+);
+export const SyncScopedSnapshotArtifactKindSchema = z.literal(
+  SYNC_SCOPED_SNAPSHOT_ARTIFACT_KIND_SQLITE_V1
+);
+export const SyncSnapshotArtifactCompressionSchema = z.union([
+  z.literal(SYNC_SNAPSHOT_ARTIFACT_COMPRESSION_NONE),
+  z.literal(SYNC_SNAPSHOT_CHUNK_COMPRESSION),
+]);
+
+export const SyncSnapshotArtifactsRequestSchema = z.object({
+  artifactKinds: z.array(SyncScopedSnapshotArtifactKindSchema).min(1),
+  compressions: z.array(SyncSnapshotArtifactCompressionSchema).optional(),
+  featureSet: z.array(z.string()).optional(),
+});
+
+export type SyncSnapshotArtifactsRequest = z.infer<
+  typeof SyncSnapshotArtifactsRequestSchema
+>;
+
 export const SyncPullRequestSchema = z.object({
   clientId: z.string().min(1),
+  schemaVersion: z.number().int().min(1),
   limitCommits: z.number().int().min(1),
   limitSnapshotRows: z.number().int().min(1).optional(),
   maxSnapshotPages: z.number().int().min(1).optional(),
   dedupeRows: z.boolean().optional(),
+  snapshotArtifacts: SyncSnapshotArtifactsRequestSchema.optional(),
   subscriptions: z.array(SyncSubscriptionRequestSchema),
 });
 
@@ -163,24 +338,137 @@ export const SyncCommitSchema = z.object({
 
 export type SyncCommit = z.infer<typeof SyncCommitSchema>;
 
+export const SyncPullSubscriptionIntegritySchema = z.object({
+  partitionId: z.string(),
+  previousChainRoot: z.string(),
+  commitChainRoot: z.string(),
+  commitSeq: z.number().int(),
+});
+
+export type SyncPullSubscriptionIntegrity = z.infer<
+  typeof SyncPullSubscriptionIntegritySchema
+>;
+
 export const SyncSnapshotChunkRefSchema = z.object({
   id: z.string(),
   byteLength: z.number().int(),
   sha256: z.string(),
-  encoding: z.literal(SYNC_SNAPSHOT_CHUNK_ENCODING),
+  encoding: SyncSnapshotChunkEncodingSchema,
   compression: z.literal(SYNC_SNAPSHOT_CHUNK_COMPRESSION),
 });
 
 export type SyncSnapshotChunkRef = z.infer<typeof SyncSnapshotChunkRefSchema>;
 
-export const SyncSnapshotSchema = z.object({
+export const SyncSnapshotManifestChunkSchema = z.object({
+  id: z.string(),
+  byteLength: z.number().int(),
+  sha256: z.string(),
+  encoding: SyncSnapshotChunkEncodingSchema,
+  compression: z.literal(SYNC_SNAPSHOT_CHUNK_COMPRESSION),
+});
+
+export const SyncSnapshotManifestSchema = z.object({
+  version: z.literal(1),
+  digest: z.string(),
+  table: z.string(),
+  asOfCommitSeq: z.number().int(),
+  scopeDigest: z.string(),
+  rowCursor: z.string().nullable(),
+  rowLimit: z.number().int().min(1),
+  nextRowCursor: z.string().nullable(),
+  isFirstPage: z.boolean(),
+  isLastPage: z.boolean(),
+  chunks: z.array(SyncSnapshotManifestChunkSchema),
+});
+
+export type SyncSnapshotManifest = z.infer<typeof SyncSnapshotManifestSchema>;
+
+export const SyncScopedSnapshotArtifactManifestSchema = z.object({
+  version: z.literal(SYNC_SCOPED_SNAPSHOT_ARTIFACT_MANIFEST_VERSION),
+  artifactKind: z.literal(SYNC_SCOPED_SNAPSHOT_ARTIFACT_KIND_SQLITE_V1),
+  digest: z.string(),
+  partitionId: z.string(),
+  subscriptionId: z.string(),
   table: z.string(),
-  rows: z.array(z.unknown()),
-  chunks: z.array(SyncSnapshotChunkRefSchema).optional(),
+  schemaVersion: z.string(),
+  asOfCommitSeq: z.number().int(),
+  scopeDigest: z.string(),
+  rowCursor: z.string().nullable(),
+  rowLimit: z.number().int().min(1),
+  rowCount: z.number().int().min(0),
+  nextRowCursor: z.string().nullable(),
   isFirstPage: z.boolean(),
   isLastPage: z.boolean(),
+  compression: z.union([
+    z.literal(SYNC_SNAPSHOT_ARTIFACT_COMPRESSION_NONE),
+    z.literal(SYNC_SNAPSHOT_CHUNK_COMPRESSION),
+  ]),
+  byteLength: z.number().int().min(0),
+  sha256: z.string(),
+  featureSet: z.array(z.string()),
+});
+
+export type SyncScopedSnapshotArtifactManifest = z.infer<
+  typeof SyncScopedSnapshotArtifactManifestSchema
+>;
+
+export const SyncSnapshotArtifactRefSchema = z.object({
+  id: z.string(),
+  byteLength: z.number().int().min(0),
+  sha256: z.string(),
+  manifestDigest: z.string(),
+  artifactKind: z.literal(SYNC_SCOPED_SNAPSHOT_ARTIFACT_KIND_SQLITE_V1),
+  compression: z.union([
+    z.literal(SYNC_SNAPSHOT_ARTIFACT_COMPRESSION_NONE),
+    z.literal(SYNC_SNAPSHOT_CHUNK_COMPRESSION),
+  ]),
+  rowCount: z.number().int().min(0),
+  nextRowCursor: z.string().nullable(),
+  isFirstPage: z.boolean(),
+  isLastPage: z.boolean(),
+  manifest: SyncScopedSnapshotArtifactManifestSchema,
 });
 
+export type SyncSnapshotArtifactRef = z.infer<
+  typeof SyncSnapshotArtifactRefSchema
+>;
+
+export const SyncSnapshotSchema = z
+  .object({
+    table: z.string(),
+    rows: z.array(z.unknown()),
+    chunks: z.array(SyncSnapshotChunkRefSchema).optional(),
+    manifest: SyncSnapshotManifestSchema.optional(),
+    artifacts: z.array(SyncSnapshotArtifactRefSchema).optional(),
+    isFirstPage: z.boolean(),
+    isLastPage: z.boolean(),
+    bootstrapStateAfter: SyncBootstrapStateSchema.nullable().optional(),
+  })
+  .superRefine((snapshot, ctx) => {
+    if (!snapshot.artifacts || snapshot.artifacts.length === 0) return;
+    if (snapshot.rows.length > 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['rows'],
+        message: 'Snapshot artifacts cannot be mixed with inline rows',
+      });
+    }
+    if (snapshot.chunks && snapshot.chunks.length > 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['chunks'],
+        message: 'Snapshot artifacts cannot be mixed with chunk refs',
+      });
+    }
+    if (snapshot.manifest) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['manifest'],
+        message: 'Snapshot artifacts cannot be mixed with chunk manifests',
+      });
+    }
+  });
+
 export type SyncSnapshot = z.infer<typeof SyncSnapshotSchema>;
 
 export const SyncPullSubscriptionResponseSchema = z.object({
@@ -190,6 +478,7 @@ export const SyncPullSubscriptionResponseSchema = z.object({
   bootstrap: z.boolean(),
   bootstrapState: SyncBootstrapStateSchema.nullable().optional(),
   nextCursor: z.number().int(),
+  integrity: SyncPullSubscriptionIntegritySchema.optional(),
   commits: z.array(SyncCommitSchema),
   snapshots: z.array(SyncSnapshotSchema).optional(),
 });
@@ -211,7 +500,7 @@ export type SyncPullResponse = z.infer<typeof SyncPullResponseSchema>;
 
 export const SyncCombinedRequestSchema = z.object({
   clientId: z.string().min(1),
-  push: SyncPushRequestSchema.omit({ clientId: true }).optional(),
+  push: SyncPushBatchRequestSchema.omit({ clientId: true }).optional(),
   pull: SyncPullRequestSchema.omit({ clientId: true }).optional(),
 });
 
@@ -219,7 +508,9 @@ export type SyncCombinedRequest = z.infer<typeof SyncCombinedRequestSchema>;
 
 export const SyncCombinedResponseSchema = z.object({
   ok: z.literal(true),
-  push: SyncPushResponseSchema.optional(),
+  requiredSchemaVersion: z.number().int().min(1).optional(),
+  latestSchemaVersion: z.number().int().min(1).optional(),
+  push: SyncPushBatchResponseSchema.optional(),
   pull: SyncPullResponseSchema.optional(),
 });
 

package/src/scopes/index.ts

@@ -179,6 +179,36 @@ export function normalizeScopes(
   return result;
 }
 
+export function createSingleVariableScopeMetadata(
+  scopes: readonly ScopeDefinition[]
+): {
+  scopePatterns: ScopePattern[];
+  scopeColumnsByVariable: Record<string, string>;
+} {
+  const scopeColumnMap = normalizeScopes(scopes);
+  const scopePatterns = Object.keys(scopeColumnMap) as ScopePattern[];
+  const scopeColumnsByVariable: Record<string, string> = {};
+
+  for (const [pattern, columnName] of Object.entries(scopeColumnMap)) {
+    const vars = extractScopeVars(pattern);
+    if (vars.length !== 1) {
+      throw new Error(
+        `Scope pattern "${pattern}" must contain exactly one placeholder (got ${vars.length}).`
+      );
+    }
+    const variableName = vars[0]!;
+    const existingColumn = scopeColumnsByVariable[variableName];
+    if (existingColumn && existingColumn !== columnName) {
+      throw new Error(
+        `Scope variable "${variableName}" is mapped to multiple columns: "${existingColumn}" and "${columnName}".`
+      );
+    }
+    scopeColumnsByVariable[variableName] = columnName;
+  }
+
+  return { scopePatterns, scopeColumnsByVariable };
+}
+
 // ── Value operations (public) ────────────────────────────────────────
 
 /**
@@ -193,3 +223,15 @@ export function extractScopeVars(pattern: ScopePattern): string[] {
   if (!matches) return [];
   return matches.map((m) => m.slice(1, -1));
 }
+
+export function collectScopeVars(
+  scopePatterns: readonly ScopePattern[]
+): Set<string> {
+  const keys = new Set<string>();
+  for (const pattern of scopePatterns) {
+    for (const key of extractScopeVars(pattern)) {
+      keys.add(key);
+    }
+  }
+  return keys;
+}

package/src/sentry.ts

@@ -0,0 +1,200 @@
+import type {
+  SyncMetricOptions,
+  SyncMetrics,
+  SyncSpan,
+  SyncSpanOptions,
+  SyncTelemetry,
+  SyncTelemetryAttributes,
+  SyncTelemetryAttributeValue,
+  SyncTelemetryEvent,
+  SyncTelemetryLevel,
+  SyncTracer,
+} from '@syncular/core';
+
+interface SentryLoggerAdapter {
+  trace?(message: string, attributes?: Record<string, unknown>): void;
+  debug?(message: string, attributes?: Record<string, unknown>): void;
+  info?(message: string, attributes?: Record<string, unknown>): void;
+  warn?(message: string, attributes?: Record<string, unknown>): void;
+  error?(message: string, attributes?: Record<string, unknown>): void;
+  fatal?(message: string, attributes?: Record<string, unknown>): void;
+}
+
+interface SentrySpanAdapter {
+  setAttribute?(name: string, value: SyncTelemetryAttributeValue): void;
+  setAttributes?(attributes: SyncTelemetryAttributes): void;
+  setStatus?(status: 'ok' | 'error' | string): void;
+}
+
+interface SentryMetricsAdapter {
+  count?(name: string, value: number, options?: SyncMetricOptions): void;
+  gauge?(name: string, value: number, options?: SyncMetricOptions): void;
+  distribution?(name: string, value: number, options?: SyncMetricOptions): void;
+}
+
+export interface SentryTelemetryAdapter {
+  logger?: SentryLoggerAdapter;
+  startSpan?<T>(
+    options: SyncSpanOptions,
+    callback: (span: SentrySpanAdapter) => T
+  ): T;
+  metrics?: SentryMetricsAdapter;
+  captureException?(error: unknown): void;
+}
+
+const noopSpan: SyncSpan = {
+  setAttribute() {},
+  setAttributes() {},
+  setStatus() {},
+};
+
+function resolveLogLevel(event: SyncTelemetryEvent): SyncTelemetryLevel {
+  if (event.level) return event.level;
+  return event.error ? 'error' : 'info';
+}
+
+function resolveLogMethod(
+  logger: SentryLoggerAdapter | undefined,
+  level: SyncTelemetryLevel
+): ((message: string, attributes?: Record<string, unknown>) => void) | null {
+  if (!logger) return null;
+  switch (level) {
+    case 'trace':
+      return logger.trace ?? logger.debug ?? logger.info ?? null;
+    case 'debug':
+      return logger.debug ?? logger.info ?? null;
+    case 'info':
+      return logger.info ?? null;
+    case 'warn':
+      return logger.warn ?? logger.info ?? null;
+    case 'error':
+      return logger.error ?? logger.warn ?? logger.info ?? null;
+    case 'fatal':
+      return logger.fatal ?? logger.error ?? logger.warn ?? logger.info ?? null;
+    default:
+      return logger.info ?? null;
+  }
+}
+
+function toSpan(span: SentrySpanAdapter): SyncSpan {
+  return {
+    setAttribute(name, value) {
+      span.setAttribute?.(name, value);
+    },
+    setAttributes(attributes) {
+      if (span.setAttributes) {
+        span.setAttributes(attributes);
+        return;
+      }
+
+      for (const [key, value] of Object.entries(attributes)) {
+        span.setAttribute?.(key, value);
+      }
+    },
+    setStatus(status) {
+      span.setStatus?.(status);
+    },
+  };
+}
+
+function toLogAttributeValue(
+  value: unknown
+): SyncTelemetryAttributeValue | undefined {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : undefined;
+  }
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'bigint') {
+    const asNumber = Number(value);
+    if (Number.isFinite(asNumber)) return asNumber;
+    return value.toString();
+  }
+  if (value instanceof Date) return value.toISOString();
+  if (value === null || value === undefined) return undefined;
+
+  if (Array.isArray(value) || typeof value === 'object') {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  }
+
+  return String(value);
+}
+
+function sanitizeLogAttributes(
+  attributes: Record<string, unknown>
+): Record<string, SyncTelemetryAttributeValue> | null {
+  const sanitized: Record<string, SyncTelemetryAttributeValue> = {};
+  for (const [name, value] of Object.entries(attributes)) {
+    const normalized = toLogAttributeValue(value);
+    if (normalized !== undefined) {
+      sanitized[name] = normalized;
+    }
+  }
+
+  return Object.keys(sanitized).length > 0 ? sanitized : null;
+}
+
+function createTracer(adapter: SentryTelemetryAdapter): SyncTracer {
+  return {
+    startSpan<T>(options: SyncSpanOptions, callback: (span: SyncSpan) => T): T {
+      if (!adapter.startSpan) return callback(noopSpan);
+      return adapter.startSpan(options, (span) => callback(toSpan(span)));
+    },
+  };
+}
+
+function createMetrics(adapter: SentryTelemetryAdapter): SyncMetrics {
+  return {
+    count(name, value, options) {
+      adapter.metrics?.count?.(name, value ?? 1, options);
+    },
+    gauge(name, value, options) {
+      adapter.metrics?.gauge?.(name, value, options);
+    },
+    distribution(name, value, options) {
+      adapter.metrics?.distribution?.(name, value, options);
+    },
+  };
+}
+
+/**
+ * Create a Syncular telemetry adapter backed by Sentry primitives.
+ */
+export function createSentrySyncTelemetry(
+  adapter: SentryTelemetryAdapter
+): SyncTelemetry {
+  return {
+    log(event) {
+      const level = resolveLogLevel(event);
+      const { event: message, ...attributes } = event;
+      const logMethod = resolveLogMethod(adapter.logger, level);
+      if (!logMethod) return;
+      const sanitizedAttributes = sanitizeLogAttributes(attributes);
+      if (!sanitizedAttributes) {
+        logMethod(message);
+        return;
+      }
+      logMethod(message, sanitizedAttributes);
+    },
+    tracer: createTracer(adapter),
+    metrics: createMetrics(adapter),
+    captureException(error, context) {
+      adapter.captureException?.(error);
+      if (!context) return;
+      const logMethod =
+        resolveLogMethod(adapter.logger, 'error') ??
+        resolveLogMethod(adapter.logger, 'info');
+      if (!logMethod) return;
+      const sanitizedContext = sanitizeLogAttributes(context);
+      if (!sanitizedContext) {
+        logMethod('sync.exception.context');
+        return;
+      }
+      logMethod('sync.exception.context', sanitizedContext);
+    },
+  };
+}