Replicator Operations

Security checklist

• Scope CONVEX_REPLICATOR_TOKEN to the workspace and rotate regularly.
• Protect replicator.config.json and state files; they contain secrets.
• Route inbound mutations through the provided helpers to reuse canonical validation.
• Enforce rate limits on applyExternalMutation (baseline 100 writes/minute with burst allowance).
• Keep transport encrypted end-to-end (Convex HTTPS/WSS).

Monitoring hooks

• Subscribe to onHeartbeat for lag and status metrics.
• Stream structured logs via logPath into your logging stack.
• Watch .entitycli/bridge/state/<node>.json for heartbeat timestamps and PID updates.
• Alert on heartbeat staleness (>60 seconds) or growing lag between processed and latest versions.

Failure recovery

• Restart crashes using the persisted state; offsets resume automatically.
• Implement retry/backoff within adapters; halt on irrecoverable errors to avoid data divergence.
• On Convex action rejection, revert local state to the last confirmed version and surface the error.
• For large backlogs, reduce eventsPerBatch or run parallel replicas; events support replay from any version.

Maintenance

• Snapshot local databases periodically; the event log can rebuild from version 0.
• Purge .entitycli/bridge/state entries when decommissioning workspaces.
• Stay current with @entityauth/replicator releases to pick up adapter fixes.
• Run pnpm build:packs before publishing CLI shims to bundle the latest templates.

Troubleshooting

• bridge status reveals entry path, env, heartbeat, and logs path.
• Use the memory demo template to validate connectivity without touching production.
• Set LOG_LEVEL=debug (template support) for verbose processing traces.
• If cursors stall, inspect the offset store and file permissions.