cfg-api-v3-services

Services (src/services/)

• Pattern: export class EntityService extends Service<typeof Table> { static readonly entityTable = Table; static readonly entityName = "EntityName"; } — see AdapterService.ts and Service.ts.
• New services: export from src/services/index.ts when used outside the service file.
• Logging: use serviceLog (progress, context) and serviceError (failures, bad state) from src/helpers/logger.ts. Any public/static method that does meaningful work (DB, side effects, non-trivial branching) should log at least once; skip trivial pure accessors like read(). Use expandInlineObject for row-shaped payloads where appropriate.
• Batch APIs: prefer insertMany / saveMany on Service when writing many rows; align semantics (onConflictDoNothing vs upsert) with existing callers.
• Extending batch upserts: follow the saveMany / excluded comment in Service.ts (Ponder PG proxy — use sql.raw(\excluded."column"`)for column refs, not brokenexcluded.*` expansions).
• Parameterized raw SQL: only CrosschainPayloadService.refreshPayloadStatusFromAggregates uses context.db.sql.execute. Any new raw SQL must bind dynamic values via bindPg* in sqlSafety.ts; add a test in raw-sql-bindings.test.ts.
• crosschain_payload.status: derive only in crosschainStatusSql.ts — INSERT via payloadStatusForInsertSql, ON CONFLICT via payloadSimpleStatusSetSql, receive via refreshPayloadStatusSql. Never default INSERT status in TS. See docs/1-crosschain-messaging.md § Payload status derivation.
• DB implementation: handlers never call context.db directly; services use the patterns encapsulated in Service (context.db.sql, and context.db.find inside getOrInit only).

Add public methods on the entity service for logic reused by multiple handlers.