@clivly/core 0.11.0-next.0 → 0.12.0

package/dist/mappings-config.d.cts

@@ -1,4 +1,4 @@
-import { R as ProjectionMapping, S as RelationshipsMap, a as ClivlyEntitiesConfig, h as FilterExpr } from "./entity-config-Ddgukq_E.cjs";
+import { R as ProjectionMapping, S as RelationshipsMap, a as ClivlyEntitiesConfig, h as FilterExpr } from "./entity-config-OhC4Otkz.cjs";
 //#region src/mappings-config.d.ts
 /**
  * Mappings → Entity Config bridge.
@@ -20,7 +20,7 @@ import { R as ProjectionMapping, S as RelationshipsMap, a as ClivlyEntitiesConfi
  * reads. Structurally compatible with the Drizzle row (jsonb columns typed
  * loosely) so the API layer can pass `db.select()` results straight in.
  */
-interface EntityMappingRow {
+export interface EntityMappingRow {
   fieldMap: Record<string, string>;
   filter?: Record<string, unknown> | null;
   /**
@@ -42,7 +42,7 @@ interface EntityMappingRow {
  * unmapped rows are skipped. Returns `{ entities: {} }` when nothing is
  * eligible — a no-op the view compiler and sync engine both tolerate.
  */
-declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
+export declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
 /**
  * Entity Config → Mappings, the inverse of `mappingsToEntitiesConfig`.
  *
@@ -57,7 +57,7 @@ declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntit
  * ("client-accounts" derived from "accounts"). So the key travels explicitly on
  * every row rather than being left for the reverse derivation to guess.
  */
-interface MappingFromConfig {
+export interface MappingFromConfig {
   /**
    * The config entity key this row came from. Not a row column — the caller
    * needs it to resolve a custom object type and to report what it wrote.
@@ -65,6 +65,8 @@ interface MappingFromConfig {
   entityKey: string;
   fieldMap: Record<string, string>;
   filter?: FilterExpr;
+  /** Rows from this entity are their company's point of contact. */
+  isPrimaryContact?: boolean;
   /** Declared custom object, when the config declares one rather than pinning an id. */
   objectType?: {
     iconKey?: string;
@@ -80,6 +82,5 @@ interface MappingFromConfig {
   targetConcept: string;
   targetObjectTypeId?: string;
 }
-declare function entitiesToMappings(config: ClivlyEntitiesConfig): MappingFromConfig[];
-//#endregion
-export { EntityMappingRow, MappingFromConfig, entitiesToMappings, mappingsToEntitiesConfig };
+export declare function entitiesToMappings(config: ClivlyEntitiesConfig): MappingFromConfig[];
+//#endregion

package/dist/mappings-config.d.mts

@@ -1,4 +1,4 @@
-import { R as ProjectionMapping, S as RelationshipsMap, a as ClivlyEntitiesConfig, h as FilterExpr } from "./entity-config-Ddgukq_E.mjs";
+import { R as ProjectionMapping, S as RelationshipsMap, a as ClivlyEntitiesConfig, h as FilterExpr } from "./entity-config-OhC4Otkz.mjs";
 //#region src/mappings-config.d.ts
 /**
  * Mappings → Entity Config bridge.
@@ -20,7 +20,7 @@ import { R as ProjectionMapping, S as RelationshipsMap, a as ClivlyEntitiesConfi
  * reads. Structurally compatible with the Drizzle row (jsonb columns typed
  * loosely) so the API layer can pass `db.select()` results straight in.
  */
-interface EntityMappingRow {
+export interface EntityMappingRow {
   fieldMap: Record<string, string>;
   filter?: Record<string, unknown> | null;
   /**
@@ -42,7 +42,7 @@ interface EntityMappingRow {
  * unmapped rows are skipped. Returns `{ entities: {} }` when nothing is
  * eligible — a no-op the view compiler and sync engine both tolerate.
  */
-declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
+export declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
 /**
  * Entity Config → Mappings, the inverse of `mappingsToEntitiesConfig`.
  *
@@ -57,7 +57,7 @@ declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntit
  * ("client-accounts" derived from "accounts"). So the key travels explicitly on
  * every row rather than being left for the reverse derivation to guess.
  */
-interface MappingFromConfig {
+export interface MappingFromConfig {
   /**
    * The config entity key this row came from. Not a row column — the caller
    * needs it to resolve a custom object type and to report what it wrote.
@@ -65,6 +65,8 @@ interface MappingFromConfig {
   entityKey: string;
   fieldMap: Record<string, string>;
   filter?: FilterExpr;
+  /** Rows from this entity are their company's point of contact. */
+  isPrimaryContact?: boolean;
   /** Declared custom object, when the config declares one rather than pinning an id. */
   objectType?: {
     iconKey?: string;
@@ -80,6 +82,5 @@ interface MappingFromConfig {
   targetConcept: string;
   targetObjectTypeId?: string;
 }
-declare function entitiesToMappings(config: ClivlyEntitiesConfig): MappingFromConfig[];
-//#endregion
-export { EntityMappingRow, MappingFromConfig, entitiesToMappings, mappingsToEntitiesConfig };
+export declare function entitiesToMappings(config: ClivlyEntitiesConfig): MappingFromConfig[];
+//#endregion

package/dist/mappings-config.mjs

@@ -1,4 +1,4 @@
-import { f as projectionFields, t as CANONICAL_FIELDS } from "./entity-config-BTAJe1Zj.mjs";
+import { f as projectionFields, t as CANONICAL_FIELDS } from "./entity-config-C0rtu-K_.mjs";
 //#region src/mappings-config.ts
 const RESERVED_FIELD = "id";
 /**
@@ -119,6 +119,7 @@ function entitiesToMappings(config) {
 			fieldMap: entity.projection ? {} : entity.fields
 		};
 		if (entity.filter) row.filter = entity.filter;
+		if (entity.isPrimaryContact) row.isPrimaryContact = true;
 		if (entity.relationships) row.relationships = entity.relationships;
 		if (entity.projection) row.projection = entity.projection;
 		if (entity.concept === CUSTOM_CONCEPT) {

package/dist/sync-engine.d.cts

@@ -1,4 +1,4 @@
-import { a as ClivlyEntitiesConfig } from "./entity-config-Ddgukq_E.cjs";
+import { a as ClivlyEntitiesConfig } from "./entity-config-OhC4Otkz.cjs";
 import { CompileOptions, CompiledView } from "./view-compiler.cjs";
 //#region src/sync-engine.d.ts
 /**
@@ -19,7 +19,7 @@ import { CompileOptions, CompiledView } from "./view-compiler.cjs";
  * package provides the concrete store.
  */
 /** A row read from a compiled view (what Postgres returns). */
-interface SourceRow {
+export interface SourceRow {
   /** Host-side company key from `<relationship>_ref`; resolved before persist. */
   companyRef?: string | null;
   /** Mapped identity fields (clivly field → value). */
@@ -28,14 +28,14 @@ interface SourceRow {
   sourceRef: string;
 }
 /** An existing mirror row, as far as reconciliation needs to know. */
-interface MirrorRecord {
+export interface MirrorRecord {
   archivedAt: Date | null;
   /** Host-side company key; only consulted in composite (join-table) mode. */
   companyRef: string | null;
   id: string;
   sourceRef: string;
 }
-type SyncAction = {
+export type SyncAction = {
   kind: "create";
   sourceRef: string;
   fields: Record<string, string | null>;
@@ -58,7 +58,7 @@ type SyncAction = {
   sourceRef: string;
 };
 /** A persist action with the company ref resolved to a `crm_companies.id`. */
-type PersistAction = {
+export type PersistAction = {
   kind: "create";
   sourceRef: string;
   fields: Record<string, string | null>;
@@ -99,11 +99,11 @@ type PersistAction = {
  * person in several companies materializes one mirror row per company and a
  * single membership leaving archives only that one row.
  */
-declare function reconcile(source: SourceRow[], mirror: MirrorRecord[], opts?: {
+export declare function reconcile(source: SourceRow[], mirror: MirrorRecord[], opts?: {
   composite?: boolean;
 }): SyncAction[];
 /** DB I/O port. The concrete store lives in the SDK/drizzle package. */
-interface SyncStore {
+export interface SyncStore {
   /** Current mirror rows for a concept + role (including archived). */
   listMirror(input: {
     concept: string;
@@ -129,7 +129,7 @@ interface SyncStore {
   /** Map host-side company refs → `crm_companies.id` (already-synced companies only). */
   resolveCompanyRefs(refs: string[]): Promise<Map<string, string>>;
 }
-interface EntitySyncResult {
+export interface EntitySyncResult {
   archived: number;
   concept: string;
   created: number;
@@ -138,7 +138,7 @@ interface EntitySyncResult {
   role: string;
   updated: number;
 }
-interface SyncResult {
+export interface SyncResult {
   entities: EntitySyncResult[];
   totals: {
     created: number;
@@ -151,12 +151,12 @@ interface SyncResult {
  * Run a full sync: compile the config's views, then reconcile + persist each,
  * companies first. Returns per-entity and total action counts.
  */
-declare function runSync(config: ClivlyEntitiesConfig, store: SyncStore, options?: CompileOptions): Promise<SyncResult>;
-interface PreviewWarning {
+export declare function runSync(config: ClivlyEntitiesConfig, store: SyncStore, options?: CompileOptions): Promise<SyncResult>;
+export interface PreviewWarning {
   field?: string;
   message: string;
 }
-interface PreviewResult {
+export interface PreviewResult {
   rows: SourceRow[];
   sampledCount: number;
   warnings: PreviewWarning[];
@@ -167,7 +167,7 @@ interface PreviewResult {
  * a required field empty in ≥1 row → `K/N` form; an optional field empty in
  * ALL rows → all-empty form; zero source rows → a single table-level warning.
  */
-declare function computeSampleWarnings(rows: SourceRow[], requiredFields: string[], sourceTable: string): PreviewWarning[];
+export declare function computeSampleWarnings(rows: SourceRow[], requiredFields: string[], sourceTable: string): PreviewWarning[];
 /**
  * Zero-write preview: read ≤`limit` rows through the compiled view (a pure
  * SELECT whose SQL already projects each row into its mapped fields) and
@@ -175,10 +175,9 @@ declare function computeSampleWarnings(rows: SourceRow[], requiredFields: string
  * so it can never mutate the mirror. The distinct, write-one-row sibling is
  * `runSync`'s sample mode (T13).
  */
-declare function previewSync(store: SyncStore, view: CompiledView, opts: {
+export declare function previewSync(store: SyncStore, view: CompiledView, opts: {
   limit: number;
   requiredFields: string[];
   sourceTable: string;
 }): Promise<PreviewResult>;
-//#endregion
-export { EntitySyncResult, MirrorRecord, PersistAction, PreviewResult, PreviewWarning, SourceRow, SyncAction, SyncResult, SyncStore, computeSampleWarnings, previewSync, reconcile, runSync };
+//#endregion

package/dist/sync-engine.d.mts

@@ -1,4 +1,4 @@
-import { a as ClivlyEntitiesConfig } from "./entity-config-Ddgukq_E.mjs";
+import { a as ClivlyEntitiesConfig } from "./entity-config-OhC4Otkz.mjs";
 import { CompileOptions, CompiledView } from "./view-compiler.mjs";
 //#region src/sync-engine.d.ts
 /**
@@ -19,7 +19,7 @@ import { CompileOptions, CompiledView } from "./view-compiler.mjs";
  * package provides the concrete store.
  */
 /** A row read from a compiled view (what Postgres returns). */
-interface SourceRow {
+export interface SourceRow {
   /** Host-side company key from `<relationship>_ref`; resolved before persist. */
   companyRef?: string | null;
   /** Mapped identity fields (clivly field → value). */
@@ -28,14 +28,14 @@ interface SourceRow {
   sourceRef: string;
 }
 /** An existing mirror row, as far as reconciliation needs to know. */
-interface MirrorRecord {
+export interface MirrorRecord {
   archivedAt: Date | null;
   /** Host-side company key; only consulted in composite (join-table) mode. */
   companyRef: string | null;
   id: string;
   sourceRef: string;
 }
-type SyncAction = {
+export type SyncAction = {
   kind: "create";
   sourceRef: string;
   fields: Record<string, string | null>;
@@ -58,7 +58,7 @@ type SyncAction = {
   sourceRef: string;
 };
 /** A persist action with the company ref resolved to a `crm_companies.id`. */
-type PersistAction = {
+export type PersistAction = {
   kind: "create";
   sourceRef: string;
   fields: Record<string, string | null>;
@@ -99,11 +99,11 @@ type PersistAction = {
  * person in several companies materializes one mirror row per company and a
  * single membership leaving archives only that one row.
  */
-declare function reconcile(source: SourceRow[], mirror: MirrorRecord[], opts?: {
+export declare function reconcile(source: SourceRow[], mirror: MirrorRecord[], opts?: {
   composite?: boolean;
 }): SyncAction[];
 /** DB I/O port. The concrete store lives in the SDK/drizzle package. */
-interface SyncStore {
+export interface SyncStore {
   /** Current mirror rows for a concept + role (including archived). */
   listMirror(input: {
     concept: string;
@@ -129,7 +129,7 @@ interface SyncStore {
   /** Map host-side company refs → `crm_companies.id` (already-synced companies only). */
   resolveCompanyRefs(refs: string[]): Promise<Map<string, string>>;
 }
-interface EntitySyncResult {
+export interface EntitySyncResult {
   archived: number;
   concept: string;
   created: number;
@@ -138,7 +138,7 @@ interface EntitySyncResult {
   role: string;
   updated: number;
 }
-interface SyncResult {
+export interface SyncResult {
   entities: EntitySyncResult[];
   totals: {
     created: number;
@@ -151,12 +151,12 @@ interface SyncResult {
  * Run a full sync: compile the config's views, then reconcile + persist each,
  * companies first. Returns per-entity and total action counts.
  */
-declare function runSync(config: ClivlyEntitiesConfig, store: SyncStore, options?: CompileOptions): Promise<SyncResult>;
-interface PreviewWarning {
+export declare function runSync(config: ClivlyEntitiesConfig, store: SyncStore, options?: CompileOptions): Promise<SyncResult>;
+export interface PreviewWarning {
   field?: string;
   message: string;
 }
-interface PreviewResult {
+export interface PreviewResult {
   rows: SourceRow[];
   sampledCount: number;
   warnings: PreviewWarning[];
@@ -167,7 +167,7 @@ interface PreviewResult {
  * a required field empty in ≥1 row → `K/N` form; an optional field empty in
  * ALL rows → all-empty form; zero source rows → a single table-level warning.
  */
-declare function computeSampleWarnings(rows: SourceRow[], requiredFields: string[], sourceTable: string): PreviewWarning[];
+export declare function computeSampleWarnings(rows: SourceRow[], requiredFields: string[], sourceTable: string): PreviewWarning[];
 /**
  * Zero-write preview: read ≤`limit` rows through the compiled view (a pure
  * SELECT whose SQL already projects each row into its mapped fields) and
@@ -175,10 +175,9 @@ declare function computeSampleWarnings(rows: SourceRow[], requiredFields: string
  * so it can never mutate the mirror. The distinct, write-one-row sibling is
  * `runSync`'s sample mode (T13).
  */
-declare function previewSync(store: SyncStore, view: CompiledView, opts: {
+export declare function previewSync(store: SyncStore, view: CompiledView, opts: {
   limit: number;
   requiredFields: string[];
   sourceTable: string;
 }): Promise<PreviewResult>;
-//#endregion
-export { EntitySyncResult, MirrorRecord, PersistAction, PreviewResult, PreviewWarning, SourceRow, SyncAction, SyncResult, SyncStore, computeSampleWarnings, previewSync, reconcile, runSync };
+//#endregion

package/dist/types.d.cts

@@ -1,14 +1,14 @@
 //#region src/types.d.ts
-type ContactStatus = "lead" | "active" | "customer" | "churned";
-type DealStage = string;
-type StageType = "open" | "won" | "lost";
-type PipelineKind = "standard" | "recurring";
-type ValueInterval = "one_time" | "monthly" | "annual";
+export type ContactStatus = "lead" | "active" | "customer" | "churned";
+export type DealStage = string;
+export type StageType = "open" | "won" | "lost";
+export type PipelineKind = "standard" | "recurring";
+export type ValueInterval = "one_time" | "monthly" | "annual";
 /** Named once so SQL predicates and UI fallbacks cannot drift apart. */
-declare const OPEN_STAGE_TYPE: "open";
+export declare const OPEN_STAGE_TYPE: "open";
 /** A closed deal is a historical fact: automation never reopens one. */
-declare function isClosedStageType(type: StageType): boolean;
-interface PipelineStageConfig {
+export declare function isClosedStageType(type: StageType): boolean;
+export interface PipelineStageConfig {
   color: string | null;
   id: string;
   key: DealStage;
@@ -17,7 +17,7 @@ interface PipelineStageConfig {
   type: StageType;
   valueFixed: number | null;
 }
-interface PipelineConfig {
+export interface PipelineConfig {
   id: string;
   isDefault: boolean;
   kind: PipelineKind;
@@ -26,12 +26,12 @@ interface PipelineConfig {
   sourceMappingId: string | null;
   stages: PipelineStageConfig[];
 }
-type TaskStatus = "todo" | "in_progress" | "done" | "cancelled";
-type TaskPriority = "low" | "medium" | "high";
-type TaskEntityType = "contact" | "company" | "deal";
-type ActivityType = "note" | "email" | "task" | "deal" | "call";
-type CrmRole = "owner" | "admin" | "member" | "developer" | "support_agent";
-interface Contact {
+export type TaskStatus = "todo" | "in_progress" | "done" | "cancelled";
+export type TaskPriority = "low" | "medium" | "high";
+export type TaskEntityType = "contact" | "company" | "custom" | "deal";
+export type ActivityType = "note" | "email" | "task" | "deal" | "call";
+export type CrmRole = "owner" | "admin" | "member" | "developer" | "support_agent";
+export interface Contact {
   companyId: string | null;
   createdAt: Date;
   email: string;
@@ -40,19 +40,49 @@ interface Contact {
   name: string;
   orgId: string;
   phone: string | null;
+  /**
+   * The host row this contact mirrors, or null when it was created in the CRM.
+   *
+   * Carried on the domain type because it decides whether a user may edit the
+   * identity fields: sync rewrites them from the host view on every run, so an
+   * edit to a sourced row would be silently reverted. See `host-owned-fields`.
+   */
+  sourceRef: string | null;
   status: ContactStatus;
   title: string | null;
 }
-interface Company {
+export interface Company {
+  /**
+   * How many non-archived contacts are attached to this company.
+   *
+   * Derived per read, never stored — distinct from {@link Company.size}, which
+   * is the mappable headcount of the business itself. A provider with 400 staff
+   * and 4 CRM contacts has `size: "400"` and `contactCount: 4`; conflating them
+   * would state a falsehood in the authoritative-looking direction.
+   */
+  contactCount: number;
   createdAt: Date;
   domain: string | null;
+  email: string | null;
   id: string;
   industry: string | null;
   name: string;
   orgId: string;
+  phone: string | null;
+  /**
+   * The one contact to talk to at this company, if chosen.
+   *
+   * Constrained to a contact of this same company, and cleared when that
+   * contact is archived — so a non-null value always names someone live and
+   * attached here. Unlike the other fields it is never host-owned: it is a CRM
+   * judgement, so it stays editable on synced rows.
+   */
+  primaryContactId: string | null;
   size: string | null;
+  /** See {@link Contact.sourceRef}. */
+  sourceRef: string | null;
 }
-interface Deal {
+export interface Deal {
   closeDate: Date | null;
   contactId: string | null;
   createdAt: Date;
@@ -62,9 +92,23 @@ interface Deal {
   owner: string | null;
   position: number | null;
   stage: DealStage;
+  /**
+   * When a human last moved this deal by hand. Non-null means stage derivation
+   * no longer touches it, so a board must be able to mark it as overridden and
+   * offer a way back — otherwise an overridden deal is indistinguishable from
+   * one the rules simply never matched.
+   */
+  stageOverrideAt: Date | null;
   value: number;
+  /**
+   * When a human last set this deal's value by hand. Non-null means value
+   * derivation no longer touches it. Mirrors {@link Deal.stageOverrideAt} — and
+   * needs the same visibility, since an honoured-but-invisible override reads
+   * as a stuck deal rather than a pinned one.
+   */
+  valueOverrideAt: Date | null;
 }
-interface Task {
+export interface Task {
   archivedAt: Date | null;
   assignee: string | null;
   completedAt: Date | null;
@@ -81,7 +125,7 @@ interface Task {
   status: TaskStatus;
   title: string;
 }
-interface Note {
+export interface Note {
   archivedAt: Date | null;
   author: string | null;
   body: string;
@@ -96,7 +140,7 @@ interface Note {
   title: string;
   updatedAt: Date;
 }
-interface Activity {
+export interface Activity {
   actor: string | null;
   contactId: string | null;
   createdAt: Date;
@@ -105,7 +149,7 @@ interface Activity {
   summary: string;
   type: ActivityType;
 }
-interface CreateContactInput {
+export interface CreateContactInput {
   companyId?: string;
   email: string;
   name: string;
@@ -113,7 +157,7 @@ interface CreateContactInput {
   status?: ContactStatus;
   title?: string;
 }
-interface UpdateContactInput {
+export interface UpdateContactInput {
   companyId?: string | null;
   email?: string;
   name?: string;
@@ -121,13 +165,25 @@ interface UpdateContactInput {
   status?: ContactStatus;
   title?: string | null;
 }
-interface CreateCompanyInput {
+export interface CreateCompanyInput {
   domain?: string;
+  email?: string;
   industry?: string;
   name: string;
+  phone?: string;
   size?: string;
 }
-interface CreateDealInput {
+export interface UpdateCompanyInput {
+  domain?: string | null;
+  email?: string | null;
+  industry?: string | null;
+  name?: string;
+  phone?: string | null;
+  /** Null clears the point of contact; see {@link Company.primaryContactId}. */
+  primaryContactId?: string | null;
+  size?: string | null;
+}
+export interface CreateDealInput {
   contactId?: string;
   name: string;
   owner?: string;
@@ -135,7 +191,7 @@ interface CreateDealInput {
   stage?: DealStage;
   value?: number;
 }
-interface UpdateDealInput {
+export interface UpdateDealInput {
   closeDate?: Date | null;
   contactId?: string | null;
   name?: string;
@@ -143,7 +199,7 @@ interface UpdateDealInput {
   stage?: DealStage;
   value?: number;
 }
-interface CreateTaskInput {
+export interface CreateTaskInput {
   assignee?: string;
   createdBy?: string;
   description?: string;
@@ -153,7 +209,7 @@ interface CreateTaskInput {
   priority?: TaskPriority;
   title: string;
 }
-interface UpdateTaskInput {
+export interface UpdateTaskInput {
   assignee?: string | null;
   description?: string | null;
   dueAt?: Date | null;
@@ -162,20 +218,64 @@ interface UpdateTaskInput {
   priority?: TaskPriority;
   title?: string;
 }
-interface CreateActivityInput {
+export interface CreateActivityInput {
   actor?: string;
   contactId?: string;
   summary: string;
   type: ActivityType;
 }
-type RecordSource = "all" | "synced";
-interface ContactFilters {
+export type RecordSource = "all" | "synced";
+export interface ContactFilters {
   companyId?: string;
+  /**
+   * Exclude archived rows. Defaults to false — the adapter returns everything
+   * — because most callers are lookup maps, not user-facing lists:
+   * `importContacts` builds its dedup set from this (hiding archived rows
+   * would resurrect a contact the user archived as a duplicate) and
+   * `deals.list` builds its contact-name map from it (an archived contact on
+   * a live deal would render blank).
+   *
+   * The user-facing `contacts.list` / `companies.list` routes opt in, because
+   * there `archiveContact` is the delete affordance and a row still visible
+   * after archiving reads as a failed delete.
+   *
+   * Independent of `source`: `source: "synced"` already excludes archived
+   * rows, since sync archives a row when it leaves the host view and such a
+   * row is no longer sync-provenanced.
+   */
+  excludeArchived?: boolean;
   search?: string;
   source?: RecordSource;
   status?: ContactStatus;
 }
-interface TaskFilters {
+/**
+ * One page of a keyset-paginated read.
+ *
+ * Keyset, not offset: `LIMIT/OFFSET` re-scans every skipped row, so page 200
+ * costs 200 pages of work, and a row inserted mid-listing shifts everything
+ * after it — the reader sees a record twice or never. A cursor anchored to
+ * `(createdAt, id)` is stable under concurrent writes and costs the same at
+ * page 1 and page 200.
+ *
+ * `audit.list` already does this; these types generalise its shape so the CRM
+ * lists cannot drift into a second convention.
+ */
+export interface PageRequest {
+  /** Opaque `${createdAtISO}|${id}`. Rows strictly older than this. */
+  cursor?: string;
+  limit?: number;
+}
+export interface Page<T> {
+  /** Null when this is the last page. */
+  nextCursor: string | null;
+  rows: T[];
+}
+export interface CompanyFilters {
+  /** See {@link ContactFilters.excludeArchived}. */
+  excludeArchived?: boolean;
+  source?: RecordSource;
+}
+export interface TaskFilters {
   assignee?: string;
   entityId?: string;
   entityType?: TaskEntityType;
@@ -184,5 +284,4 @@ interface TaskFilters {
   priority?: TaskPriority;
   status?: TaskStatus;
 }
-//#endregion
-export { Activity, ActivityType, Company, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, OPEN_STAGE_TYPE, PipelineConfig, PipelineKind, PipelineStageConfig, RecordSource, StageType, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateDealInput, UpdateTaskInput, ValueInterval, isClosedStageType };
+//#endregion