@clivly/core 0.13.0 → 0.15.0

package/README.md

@@ -48,7 +48,7 @@ client.
 | Entry | Contents |
 | --- | --- |
 | `@clivly/core` | The re-exported surface: contracts, entity config, mapping form, sync engine, view compiler, projections, shared types |
-| `@clivly/core/adapter` | `CRMAdapter` — the interface every ORM implementation fulfils (org-scoped; contacts, companies, deals, tasks, activities) |
+| `@clivly/core/adapter` | `CRMAdapter` — the interface every ORM implementation fulfils (org-scoped; contacts, companies, deals, tasks, activities). List reads are keyset-paged: `listContactsPage`, `listCompaniesPage`, `listDealsPage` and `listTasksPage` take a `PageRequest` and return a `Page`; `countContacts` returns how many contacts match the same `ContactFilters` |
 | `@clivly/core/auth-adapter` | `ClivlyAuthAdapter`, `ClivlyUser`, `authCustom()`, `MembershipResolver`, `CrmMembership` — pluggable host-app identity + the `crm_members` authorization layer |
 | `@clivly/core/entity-config` | `defineClivlyConfig`, `validateEntitiesConfig`, `entitiesConfigSchema`, `CANONICAL_FIELDS`, `CRM_CONCEPTS`, `ClivlyConfigError`, and the config types |
 | `@clivly/core/types` | Shared domain types (`Contact`, `Company`, `Deal`, `Task`, `Note`, `Activity`, inputs, filters, `CrmRole`) |
@@ -58,7 +58,7 @@ client.
 | `@clivly/core/mapping-form` | `buildFilterFromDiscriminator`, `buildRelationships`, `relationshipViaSignature` — mapping-UI helpers |
 | `@clivly/core/mapping-score` | Scoring helpers for ranking candidate mappings |
 | `@clivly/core/entity-heuristics` | Table-name heuristics that guess which table holds contacts/companies |
-| `@clivly/core/sync-engine` | `reconcile`, `runSync`, `SyncStore` and friends — the mirror reconciliation engine |
+| `@clivly/core/sync-engine` | `reconcile`, `runSync`, `resolveActions`, `isRemovalAction`, `SyncStore` and friends — the mirror reconciliation engine. Identity is the source primary key; with `reconcile(..., { memberships: true })` (contacts) a person's join-table rows collapse into one action carrying every tenant ref, and a tenant they left yields an `endMembership` action. Apply removals (`archive`, `endMembership`) only for a complete source set |
 | `@clivly/core/integration-state` | `INSTALL_COMMAND` and the shared onboarding state machine |
 | `@clivly/core/env-file` | `envFileFor(framework)` — the conventional env filename per framework |
 

package/dist/adapter.d.cts

@@ -19,6 +19,20 @@ export interface CRMAdapter {
   archiveContact(orgId: string, id: string): Promise<Contact>;
   archiveTask(orgId: string, id: string): Promise<Task>;
   completeTask(orgId: string, id: string): Promise<Task>;
+  /**
+   * How many contacts match `filters`, ignoring pagination entirely.
+   *
+   * Exists so a caller can state the size of a selection before acting on it —
+   * a bulk send has to say "this will go to N contacts", and the paged read
+   * cannot answer that: it knows only whether *another* page exists, never how
+   * many rows are behind it.
+   *
+   * Takes the same `ContactFilters` as {@link CRMAdapter.listContactsPage} and
+   * applies exactly the same predicates, so the count and the list can never
+   * disagree about what matches. It returns a number rather than rows, so it
+   * stays bounded however large the match is.
+   */
+  countContacts(orgId: string, filters?: ContactFilters): Promise<number>;
   createActivity(orgId: string, data: CreateActivityInput): Promise<Activity>;
   createCompany(orgId: string, data: CreateCompanyInput): Promise<Company>;
   createContact(orgId: string, data: CreateContactInput): Promise<Contact>;
@@ -76,6 +90,19 @@ export interface CRMAdapter {
   listDealsPage(orgId: string, filters?: {
     source?: RecordSource;
   }, page?: PageRequest): Promise<Page<Deal>>;
+  /**
+   * One page of tasks, newest-created first. See
+   * {@link CRMAdapter.listCompaniesPage}.
+   *
+   * `filters.entityType`/`entityId` match the task's own polymorphic-link
+   * columns. `filters.additionalIds`, when given, extends that match with an
+   * explicit id allowlist — `services/tasks.ts`'s `listTasks` uses it to fold
+   * in tasks linked only via `crm_record_links` (the multi-link table),
+   * without falling back to an unbounded read.
+   */
+  listTasksPage(orgId: string, filters?: TaskFilters & {
+    additionalIds?: string[];
+  }, page?: PageRequest): Promise<Page<Task>>;
   /**
    * Move a deal to `stage` and reorder it directly after `afterId` (null = top
    * of the column). The adapter computes the fractional `position` from the

package/dist/adapter.d.mts

@@ -19,6 +19,20 @@ export interface CRMAdapter {
   archiveContact(orgId: string, id: string): Promise<Contact>;
   archiveTask(orgId: string, id: string): Promise<Task>;
   completeTask(orgId: string, id: string): Promise<Task>;
+  /**
+   * How many contacts match `filters`, ignoring pagination entirely.
+   *
+   * Exists so a caller can state the size of a selection before acting on it —
+   * a bulk send has to say "this will go to N contacts", and the paged read
+   * cannot answer that: it knows only whether *another* page exists, never how
+   * many rows are behind it.
+   *
+   * Takes the same `ContactFilters` as {@link CRMAdapter.listContactsPage} and
+   * applies exactly the same predicates, so the count and the list can never
+   * disagree about what matches. It returns a number rather than rows, so it
+   * stays bounded however large the match is.
+   */
+  countContacts(orgId: string, filters?: ContactFilters): Promise<number>;
   createActivity(orgId: string, data: CreateActivityInput): Promise<Activity>;
   createCompany(orgId: string, data: CreateCompanyInput): Promise<Company>;
   createContact(orgId: string, data: CreateContactInput): Promise<Contact>;
@@ -76,6 +90,19 @@ export interface CRMAdapter {
   listDealsPage(orgId: string, filters?: {
     source?: RecordSource;
   }, page?: PageRequest): Promise<Page<Deal>>;
+  /**
+   * One page of tasks, newest-created first. See
+   * {@link CRMAdapter.listCompaniesPage}.
+   *
+   * `filters.entityType`/`entityId` match the task's own polymorphic-link
+   * columns. `filters.additionalIds`, when given, extends that match with an
+   * explicit id allowlist — `services/tasks.ts`'s `listTasks` uses it to fold
+   * in tasks linked only via `crm_record_links` (the multi-link table),
+   * without falling back to an unbounded read.
+   */
+  listTasksPage(orgId: string, filters?: TaskFilters & {
+    additionalIds?: string[];
+  }, page?: PageRequest): Promise<Page<Task>>;
   /**
    * Move a deal to `stage` and reorder it directly after `afterId` (null = top
    * of the column). The adapter computes the fractional `position` from the

package/dist/index.cjs

@@ -33,6 +33,18 @@ function computeDealValue(source, fields, mappedFields, stageType) {
 	const seats = Number(rawSeats);
 	if (!Number.isSafeInteger(seats)) return null;
 	const monthly = (source.baseFeeCents ?? 0) + seats * unitPriceCents;
+	if (!Number.isSafeInteger(monthly) || monthly < 0) return null;
+	return normalizePrice(monthly, source, fields, mappedFields);
+}
+/** Preserve old configurations while making new price bases explicit. */
+function normalizePrice(monthly, source, fields, mappedFields) {
+	if (source.priceBasis === "monthly") return monthly;
+	if (source.priceBasis === "billing_interval") {
+		const interval = source.intervalField && mappedFields.has(source.intervalField) ? fields[source.intervalField]?.trim().toLowerCase() : null;
+		if (interval === "month" || interval === "monthly") return monthly;
+		if (interval === "year" || interval === "annual" || interval === "annually" || interval === "yearly") return Math.round(monthly / MONTHS_PER_YEAR);
+		return null;
+	}
 	return source.intervalField !== void 0 && mappedFields.has(source.intervalField) && fields[source.intervalField] === "year" ? Math.round(monthly / MONTHS_PER_YEAR) : monthly;
 }
 //#endregion
@@ -291,6 +303,7 @@ exports.hostOwnedFieldMessage = hostOwnedFieldMessage;
 exports.identityRefs = require_projection.identityRefs;
 exports.isClosedStageType = require_types.isClosedStageType;
 exports.isHostOwned = isHostOwned;
+exports.isRemovalAction = require_sync_engine.isRemovalAction;
 exports.joinFansOut = require_entity_config.joinFansOut;
 exports.mappingsToEntitiesConfig = require_mappings_config.mappingsToEntitiesConfig;
 exports.matchesCondition = matchesCondition;
@@ -306,6 +319,7 @@ exports.relationshipSchema = require_entity_config.relationshipSchema;
 exports.relationshipViaSignature = require_mapping_form.relationshipViaSignature;
 exports.relationshipsSchema = require_entity_config.relationshipsSchema;
 exports.requiredFieldsFor = require_entity_config.requiredFieldsFor;
+exports.resolveActions = require_sync_engine.resolveActions;
 exports.runSync = require_sync_engine.runSync;
 exports.slugify = slugify;
 exports.toObjectTypeSlug = toObjectTypeSlug;

package/dist/index.d.cts

@@ -6,7 +6,7 @@ import { ConnectionLiveness, IntegrationFacts, IntegrationState, IntegrationStat
 import { RelationshipCandidate, buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.cjs";
 import { EntityMappingRow, mappingsToEntitiesConfig } from "./mappings-config.cjs";
 import { CompileOptions, CompiledView, DEFAULT_VIEW_PREFIX, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig } from "./view-compiler.cjs";
-import { EntitySyncResult, MirrorRecord, PersistAction, SourceRow, SyncAction, SyncResult, SyncStore, reconcile, runSync } from "./sync-engine.cjs";
+import { EntitySyncResult, MirrorRecord, PersistAction, ResolvedMembership, SourceRow, SyncAction, SyncResult, SyncStore, isRemovalAction, reconcile, resolveActions, runSync } from "./sync-engine.cjs";
 //#region src/deal-value.d.ts
 /**
  * Value derived as a flat fee plus a per-seat price that depends on the plan.
@@ -17,7 +17,7 @@ import { EntitySyncResult, MirrorRecord, PersistAction, SourceRow, SyncAction, S
  * D8 made for stage-rule conditions.
  */
 interface PerSeatValueSource {
-  /** Flat monthly fee in cents, added before the interval is normalised. */
+  /** Flat fee in cents, using the same price basis as the plan prices. */
   baseFeeCents?: number;
   /** Mapped column holding "month" or "year". Absent means always monthly. */
   intervalField?: string;
@@ -26,6 +26,8 @@ interface PerSeatValueSource {
   planField: string;
   /** Unit price in cents, keyed by the value found in `planField`. */
   plans: Record<string, number>;
+  /** Monthly rates or amounts charged each billing period. Omitted preserves legacy behaviour. */
+  priceBasis?: "monthly" | "billing_interval";
   /** Mapped column holding the seat count. */
   seatField: string;
   /** Stage types whose deals are worth nothing (usually `["lost"]`). */
@@ -333,4 +335,4 @@ export declare function matchesCondition(condition: Condition, fields: Record<st
  */
 export declare function evaluateStage(rules: EvaluableRule[], fields: Record<string, string | null>, mappedFields: Set<string>): string | null;
 //#endregion
-export { type Activity, type ActivityType, BASE_REF, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, type Company, type CompanyFilters, type CompileOptions, type CompiledView, type Condition, type ConditionOp, type ConfigValidationError, type ConfigValidationResult, type ConnectionLiveness, type Contact, type ContactFilters, type ContactStatus, type CreateActivityInput, type CreateCompanyInput, type CreateContactInput, type CreateDealInput, type CreateTaskInput, type CrmConcept, type CrmMembership, type CrmRole, DEFAULT_VIEW_PREFIX, type Deal, type DealStage, type DiscoveredColumnMeta, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type EvaluableRule, type ExplainResult, type FilterExpr, type FilterValue, type HostOwnedCompanyField, type HostOwnedContactField, type IntegrationFacts, type IntegrationState, type IntegrationStatus, type IntegrationStep, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type NextAction, type Note, OPEN_STAGE_TYPE, PROJECTION_KEY_PATTERN, type Page, type PageRequest, type PerSeatValueSource, type PersistAction, type PipelineConfig, type PipelineKind, type PipelineStageConfig, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, REQUIRED_FIELDS, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type SourcedRecord, type StageType, type StepId, type StepProblem, type StepState, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateCompanyInput, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, type ValueInterval, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, explainEntitiesConfig, filterSchema, identityRefs, isClosedStageType, mappingsToEntitiesConfig, missingRequiredFields, projectionFields, projectionSchema, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, requiredFieldsFor, runSync, validateEntitiesConfig };
+export { type Activity, type ActivityType, BASE_REF, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, type Company, type CompanyFilters, type CompileOptions, type CompiledView, type Condition, type ConditionOp, type ConfigValidationError, type ConfigValidationResult, type ConnectionLiveness, type Contact, type ContactFilters, type ContactStatus, type CreateActivityInput, type CreateCompanyInput, type CreateContactInput, type CreateDealInput, type CreateTaskInput, type CrmConcept, type CrmMembership, type CrmRole, DEFAULT_VIEW_PREFIX, type Deal, type DealStage, type DiscoveredColumnMeta, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type EvaluableRule, type ExplainResult, type FilterExpr, type FilterValue, type HostOwnedCompanyField, type HostOwnedContactField, type IntegrationFacts, type IntegrationState, type IntegrationStatus, type IntegrationStep, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type NextAction, type Note, OPEN_STAGE_TYPE, PROJECTION_KEY_PATTERN, type Page, type PageRequest, type PerSeatValueSource, type PersistAction, type PipelineConfig, type PipelineKind, type PipelineStageConfig, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, REQUIRED_FIELDS, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type ResolvedMembership, type SourceRow, type SourcedRecord, type StageType, type StepId, type StepProblem, type StepState, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateCompanyInput, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, type ValueInterval, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, explainEntitiesConfig, filterSchema, identityRefs, isClosedStageType, isRemovalAction, mappingsToEntitiesConfig, missingRequiredFields, projectionFields, projectionSchema, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, requiredFieldsFor, resolveActions, runSync, validateEntitiesConfig };

package/dist/index.d.mts

@@ -6,7 +6,7 @@ import { ConnectionLiveness, IntegrationFacts, IntegrationState, IntegrationStat
 import { RelationshipCandidate, buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.mjs";
 import { EntityMappingRow, mappingsToEntitiesConfig } from "./mappings-config.mjs";
 import { CompileOptions, CompiledView, DEFAULT_VIEW_PREFIX, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig } from "./view-compiler.mjs";
-import { EntitySyncResult, MirrorRecord, PersistAction, SourceRow, SyncAction, SyncResult, SyncStore, reconcile, runSync } from "./sync-engine.mjs";
+import { EntitySyncResult, MirrorRecord, PersistAction, ResolvedMembership, SourceRow, SyncAction, SyncResult, SyncStore, isRemovalAction, reconcile, resolveActions, runSync } from "./sync-engine.mjs";
 //#region src/deal-value.d.ts
 /**
  * Value derived as a flat fee plus a per-seat price that depends on the plan.
@@ -17,7 +17,7 @@ import { EntitySyncResult, MirrorRecord, PersistAction, SourceRow, SyncAction, S
  * D8 made for stage-rule conditions.
  */
 interface PerSeatValueSource {
-  /** Flat monthly fee in cents, added before the interval is normalised. */
+  /** Flat fee in cents, using the same price basis as the plan prices. */
   baseFeeCents?: number;
   /** Mapped column holding "month" or "year". Absent means always monthly. */
   intervalField?: string;
@@ -26,6 +26,8 @@ interface PerSeatValueSource {
   planField: string;
   /** Unit price in cents, keyed by the value found in `planField`. */
   plans: Record<string, number>;
+  /** Monthly rates or amounts charged each billing period. Omitted preserves legacy behaviour. */
+  priceBasis?: "monthly" | "billing_interval";
   /** Mapped column holding the seat count. */
   seatField: string;
   /** Stage types whose deals are worth nothing (usually `["lost"]`). */
@@ -333,4 +335,4 @@ export declare function matchesCondition(condition: Condition, fields: Record<st
  */
 export declare function evaluateStage(rules: EvaluableRule[], fields: Record<string, string | null>, mappedFields: Set<string>): string | null;
 //#endregion
-export { type Activity, type ActivityType, BASE_REF, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, type Company, type CompanyFilters, type CompileOptions, type CompiledView, type Condition, type ConditionOp, type ConfigValidationError, type ConfigValidationResult, type ConnectionLiveness, type Contact, type ContactFilters, type ContactStatus, type CreateActivityInput, type CreateCompanyInput, type CreateContactInput, type CreateDealInput, type CreateTaskInput, type CrmConcept, type CrmMembership, type CrmRole, DEFAULT_VIEW_PREFIX, type Deal, type DealStage, type DiscoveredColumnMeta, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type EvaluableRule, type ExplainResult, type FilterExpr, type FilterValue, type HostOwnedCompanyField, type HostOwnedContactField, type IntegrationFacts, type IntegrationState, type IntegrationStatus, type IntegrationStep, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type NextAction, type Note, OPEN_STAGE_TYPE, PROJECTION_KEY_PATTERN, type Page, type PageRequest, type PerSeatValueSource, type PersistAction, type PipelineConfig, type PipelineKind, type PipelineStageConfig, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, REQUIRED_FIELDS, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type SourcedRecord, type StageType, type StepId, type StepProblem, type StepState, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateCompanyInput, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, type ValueInterval, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, explainEntitiesConfig, filterSchema, identityRefs, isClosedStageType, mappingsToEntitiesConfig, missingRequiredFields, projectionFields, projectionSchema, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, requiredFieldsFor, runSync, validateEntitiesConfig };
+export { type Activity, type ActivityType, BASE_REF, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, type Company, type CompanyFilters, type CompileOptions, type CompiledView, type Condition, type ConditionOp, type ConfigValidationError, type ConfigValidationResult, type ConnectionLiveness, type Contact, type ContactFilters, type ContactStatus, type CreateActivityInput, type CreateCompanyInput, type CreateContactInput, type CreateDealInput, type CreateTaskInput, type CrmConcept, type CrmMembership, type CrmRole, DEFAULT_VIEW_PREFIX, type Deal, type DealStage, type DiscoveredColumnMeta, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type EvaluableRule, type ExplainResult, type FilterExpr, type FilterValue, type HostOwnedCompanyField, type HostOwnedContactField, type IntegrationFacts, type IntegrationState, type IntegrationStatus, type IntegrationStep, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type NextAction, type Note, OPEN_STAGE_TYPE, PROJECTION_KEY_PATTERN, type Page, type PageRequest, type PerSeatValueSource, type PersistAction, type PipelineConfig, type PipelineKind, type PipelineStageConfig, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, REQUIRED_FIELDS, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type ResolvedMembership, type SourceRow, type SourcedRecord, type StageType, type StepId, type StepProblem, type StepState, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateCompanyInput, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, type ValueInterval, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, explainEntitiesConfig, filterSchema, identityRefs, isClosedStageType, isRemovalAction, mappingsToEntitiesConfig, missingRequiredFields, projectionFields, projectionSchema, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, requiredFieldsFor, resolveActions, runSync, validateEntitiesConfig };

package/dist/index.mjs

@@ -5,7 +5,7 @@ import { _ as validateProjection, a as MATERIALIZING_CONCEPTS, b as joinFansOut,
 import { buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.mjs";
 import { mappingsToEntitiesConfig } from "./mappings-config.mjs";
 import { c as compileProjectionIdentity, d as compileProjectionSelect, f as quoteIdent, i as explainEntitiesConfig, l as compileProjectionJoins, n as compileEntityView, o as PREVIEW_MAX_ROWS, r as compileEntityViews, s as compileProjectionFrom, t as DEFAULT_VIEW_PREFIX, u as compileProjectionPreview } from "./view-compiler-CLvZ0wJW.mjs";
-import { reconcile, runSync } from "./sync-engine.mjs";
+import { isRemovalAction, reconcile, resolveActions, runSync } from "./sync-engine.mjs";
 import { OPEN_STAGE_TYPE, isClosedStageType } from "./types.mjs";
 //#region src/deal-value.ts
 const MONTHS_PER_YEAR = 12;
@@ -32,6 +32,18 @@ function computeDealValue(source, fields, mappedFields, stageType) {
 	const seats = Number(rawSeats);
 	if (!Number.isSafeInteger(seats)) return null;
 	const monthly = (source.baseFeeCents ?? 0) + seats * unitPriceCents;
+	if (!Number.isSafeInteger(monthly) || monthly < 0) return null;
+	return normalizePrice(monthly, source, fields, mappedFields);
+}
+/** Preserve old configurations while making new price bases explicit. */
+function normalizePrice(monthly, source, fields, mappedFields) {
+	if (source.priceBasis === "monthly") return monthly;
+	if (source.priceBasis === "billing_interval") {
+		const interval = source.intervalField && mappedFields.has(source.intervalField) ? fields[source.intervalField]?.trim().toLowerCase() : null;
+		if (interval === "month" || interval === "monthly") return monthly;
+		if (interval === "year" || interval === "annual" || interval === "annually" || interval === "yearly") return Math.round(monthly / MONTHS_PER_YEAR);
+		return null;
+	}
 	return source.intervalField !== void 0 && mappedFields.has(source.intervalField) && fields[source.intervalField] === "year" ? Math.round(monthly / MONTHS_PER_YEAR) : monthly;
 }
 //#endregion
@@ -256,4 +268,4 @@ function evaluateStage(rules, fields, mappedFields) {
 	return null;
 }
 //#endregion
-export { BASE_REF, CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, DEFAULT_VIEW_PREFIX, MATERIALIZING_CONCEPTS, OPEN_STAGE_TYPE, PREVIEW_MAX_ROWS, PROJECTION_KEY_PATTERN, REQUIRED_FIELDS, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, compileProjectionPreview, compileProjectionSelect, computeDealValue, coversUniqueKey, defineClivlyConfig, entitiesConfigSchema, evaluateStage, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, hostOwnedFieldMessage, identityRefs, isClosedStageType, isHostOwned, joinFansOut, mappingsToEntitiesConfig, matchesCondition, missingRequiredFields, primaryKeyColumns, projectionFields, projectionSchema, quoteIdent, reconcile, rejectedCompanyFields, rejectedContactFields, relationshipSchema, relationshipViaSignature, relationshipsSchema, requiredFieldsFor, runSync, slugify, toObjectTypeSlug, validateEntitiesConfig, validateProjection, validateProjectionFilter };
+export { BASE_REF, CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, DEFAULT_VIEW_PREFIX, MATERIALIZING_CONCEPTS, OPEN_STAGE_TYPE, PREVIEW_MAX_ROWS, PROJECTION_KEY_PATTERN, REQUIRED_FIELDS, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, compileProjectionPreview, compileProjectionSelect, computeDealValue, coversUniqueKey, defineClivlyConfig, entitiesConfigSchema, evaluateStage, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, hostOwnedFieldMessage, identityRefs, isClosedStageType, isHostOwned, isRemovalAction, joinFansOut, mappingsToEntitiesConfig, matchesCondition, missingRequiredFields, primaryKeyColumns, projectionFields, projectionSchema, quoteIdent, reconcile, rejectedCompanyFields, rejectedContactFields, relationshipSchema, relationshipViaSignature, relationshipsSchema, requiredFieldsFor, resolveActions, runSync, slugify, toObjectTypeSlug, validateEntitiesConfig, validateProjection, validateProjectionFilter };

package/dist/integration-state.cjs

@@ -346,6 +346,7 @@ exports.DEFAULT_HEARTBEAT_INTERVAL_MS = DEFAULT_HEARTBEAT_INTERVAL_MS;
 exports.INSTALL_COMMAND = INSTALL_COMMAND;
 exports.INTEGRATION_STEPS = INTEGRATION_STEPS;
 exports.INTEGRATION_STEP_LABELS = INTEGRATION_STEP_LABELS;
+exports.LIVE_INTERVALS = LIVE_INTERVALS;
 exports.STEP_PREREQUISITES = STEP_PREREQUISITES;
 exports.computeIntegrationState = computeIntegrationState;
 exports.deriveLiveness = deriveLiveness;

package/dist/integration-state.d.cts

@@ -111,6 +111,7 @@ export interface IntegrationStep {
 export declare function formatAge(ms: number): string;
 /** The cadence `createClivlySDK` uses when the host app configures none. */
 export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 60000;
+export declare const LIVE_INTERVALS = 2.5;
 export type ConnectionHealth = "live" | "live_with_issues" | "stale" | "offline";
 /**
  * Clivly's own answer to "is this app up", obtained by asking it rather than

package/dist/integration-state.d.mts

@@ -111,6 +111,7 @@ export interface IntegrationStep {
 export declare function formatAge(ms: number): string;
 /** The cadence `createClivlySDK` uses when the host app configures none. */
 export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 60000;
+export declare const LIVE_INTERVALS = 2.5;
 export type ConnectionHealth = "live" | "live_with_issues" | "stale" | "offline";
 /**
  * Clivly's own answer to "is this app up", obtained by asking it rather than

package/dist/integration-state.mjs

@@ -341,4 +341,4 @@ function computeIntegrationState(facts) {
 	};
 }
 //#endregion
-export { DEFAULT_HEARTBEAT_INTERVAL_MS, INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, STEP_PREREQUISITES, computeIntegrationState, deriveLiveness, deriveStatus, formatAge, livenessWindows, nextAction, resolveSteps, stepIndex };
+export { DEFAULT_HEARTBEAT_INTERVAL_MS, INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, LIVE_INTERVALS, STEP_PREREQUISITES, computeIntegrationState, deriveLiveness, deriveStatus, formatAge, livenessWindows, nextAction, resolveSteps, stepIndex };

package/dist/sync-engine.cjs

@@ -1,68 +1,104 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_view_compiler = require("./view-compiler-DP4Fbj7-.cjs");
 //#region src/sync-engine.ts
+/** Actions that remove something — only safe when the source set is complete. */
+function isRemovalAction(action) {
+	return action.kind === "archive" || action.kind === "endMembership";
+}
+/** Every distinct non-null company ref in a person's rows, in arrival order. */
+function collectCompanyRefs(rows) {
+	const refs = [];
+	for (const row of rows) {
+		const ref = row.companyRef ?? null;
+		if (ref !== null && !refs.includes(ref)) refs.push(ref);
+	}
+	return refs;
+}
+/**
+* The primary company for a person: the one they already have while it is
+* still one of theirs — so the displayed organisation never flips between
+* syncs — otherwise the lowest ref, which is deterministic for a new person.
+*/
+function pickPrimaryRef(refs, current) {
+	if (current !== null && refs.includes(current)) return current;
+	return [...refs].sort()[0] ?? null;
+}
+/**
+* The mirror row that represents a source identity. Normally there is exactly
+* one; before contact consolidation has run there can be several (one per
+* tenant), and the live, earliest-listed one stands for the person while the
+* rest are left alone for the consolidation script to fold in.
+*/
+function canonicalMirror(rows) {
+	return rows.find((row) => !row.archivedAt) ?? rows[0];
+}
 /**
 * Diff a view's rows against the current mirror population for one entity.
 *
-* - source row with no mirror row      → create
-* - source row with a live mirror row  → update (overwrite identity fields)
-* - source row with an archived mirror → restore (re-activate + update)
-* - live mirror row absent from source → archive (soft delete, keep history)
-* - archived mirror row absent from source → no-op
+* - source identity with no mirror row      → create
+* - source identity with a live mirror row  → update (overwrite identity fields)
+* - source identity with an archived mirror → restore (re-activate + update)
+* - live mirror row absent from source      → archive (soft delete, keep history)
+* - archived mirror row absent from source  → no-op
 *
-* Source rows are de-duplicated by the reconciliation key (first wins). In
-* simple mode (default) the key is `sourceRef`. In composite mode — used for
-* `through` (join-table) entities, where the compiled view fans a person out
-* into one row per membership — the key is `(sourceRef, companyRef)`, so a
-* person in several companies materializes one mirror row per company and a
-* single membership leaving archives only that one row.
+* Identity is always the source primary key. A `through` (join-table) view
+* fans one person out into a row per tenant; those rows are ONE person, so they
+* collapse into one action. With `memberships` on (contacts), that action also
+* carries every tenant ref the person was seen with, and each tenant the mirror
+* still has as active but the source no longer lists yields `endMembership` —
+* a person leaving one tenant ends that membership and keeps the others.
 */
 function reconcile(source, mirror, opts = {}) {
-	const keyOf = (sourceRef, companyRef) => opts.composite ? `${sourceRef}\0${companyRef ?? ""}` : sourceRef;
-	const seen = /* @__PURE__ */ new Set();
-	const rows = [];
-	for (const row of source) {
-		const key = keyOf(row.sourceRef, row.companyRef ?? null);
-		if (!seen.has(key)) {
-			seen.add(key);
-			rows.push(row);
-		}
-	}
-	const byKey = new Map(mirror.map((m) => [keyOf(m.sourceRef, m.companyRef), m]));
-	const liveKeys = /* @__PURE__ */ new Set();
+	const rowsByRef = groupBySourceRef(source);
+	const mirrorByRef = groupBySourceRef(mirror);
 	const actions = [];
-	for (const row of rows) {
-		const companyRef = row.companyRef ?? null;
-		const key = keyOf(row.sourceRef, companyRef);
-		liveKeys.add(key);
-		const existing = byKey.get(key);
-		if (!existing) actions.push({
-			kind: "create",
-			sourceRef: row.sourceRef,
-			fields: row.fields,
-			companyRef
-		});
-		else if (existing.archivedAt) actions.push({
-			kind: "restore",
-			id: existing.id,
-			sourceRef: row.sourceRef,
-			fields: row.fields,
-			companyRef
-		});
-		else actions.push({
-			kind: "update",
-			id: existing.id,
-			sourceRef: row.sourceRef,
-			fields: row.fields,
-			companyRef
-		});
+	for (const [sourceRef, rows] of rowsByRef) {
+		const existing = canonicalMirror(mirrorByRef.get(sourceRef) ?? []);
+		actions.push(...personActions(sourceRef, rows, existing, opts));
+	}
+	for (const m of mirror) if (!(rowsByRef.has(m.sourceRef) || m.archivedAt)) actions.push({
+		kind: "archive",
+		id: m.id,
+		sourceRef: m.sourceRef
+	});
+	return actions;
+}
+function groupBySourceRef(items) {
+	const out = /* @__PURE__ */ new Map();
+	for (const item of items) {
+		const list = out.get(item.sourceRef);
+		if (list) list.push(item);
+		else out.set(item.sourceRef, [item]);
 	}
-	for (const m of mirror) {
-		const key = keyOf(m.sourceRef, m.companyRef);
-		if (!(liveKeys.has(key) || m.archivedAt)) actions.push({
-			kind: "archive",
-			id: m.id,
-			sourceRef: m.sourceRef
+	return out;
+}
+/** The create/update/restore for one present person, plus any ended tenants. */
+function personActions(sourceRef, rows, existing, opts) {
+	const first = rows[0];
+	const refs = collectCompanyRefs(rows);
+	const companyRef = opts.memberships ? pickPrimaryRef(refs, existing?.companyRef ?? null) : first.companyRef ?? null;
+	const membershipSet = opts.memberships ? { companyRefs: refs } : {};
+	if (!existing) return [{
+		kind: "create",
+		sourceRef,
+		fields: first.fields,
+		companyRef,
+		...membershipSet
+	}];
+	const actions = [{
+		kind: existing.archivedAt ? "restore" : "update",
+		id: existing.id,
+		sourceRef,
+		fields: first.fields,
+		companyRef,
+		...membershipSet
+	}];
+	if (opts.memberships) {
+		for (const held of existing.companyRefs ?? []) if (!refs.includes(held)) actions.push({
+			kind: "endMembership",
+			id: existing.id,
+			sourceRef,
+			companyRef: held
 		});
 	}
 	return actions;
@@ -75,20 +111,40 @@ const CONCEPT_ORDER = {
 function syncOrder(a, b) {
 	return (CONCEPT_ORDER[a.concept] ?? 99) - (CONCEPT_ORDER[b.concept] ?? 99);
 }
+/**
+* Resolve each action's host-side company refs — the primary one and, for
+* contacts, every membership — to `crm_companies.id`s in one lookup. Shared by
+* `runSync` and the cloud push receiver so both persist identical actions.
+*/
 async function resolveActions(store, actions) {
 	const refs = /* @__PURE__ */ new Set();
-	for (const action of actions) if (action.kind !== "archive" && action.companyRef) refs.add(action.companyRef);
+	for (const action of actions) {
+		if (isRemovalAction(action) || !("fields" in action)) continue;
+		if (action.companyRef) refs.add(action.companyRef);
+		for (const ref of action.companyRefs ?? []) refs.add(ref);
+	}
 	const resolved = refs.size ? await store.resolveCompanyRefs([...refs]) : /* @__PURE__ */ new Map();
 	return actions.map((action) => {
-		if (action.kind === "archive") return action;
+		if (action.kind === "archive" || action.kind === "endMembership") return action;
 		const companyId = action.companyRef ? resolved.get(action.companyRef) ?? null : null;
-		return {
-			kind: action.kind,
-			id: "id" in action ? action.id : "",
+		const memberships = action.companyRefs?.map((companyRef) => ({
+			companyRef,
+			companyId: resolved.get(companyRef) ?? null
+		}));
+		const base = {
 			sourceRef: action.sourceRef,
 			fields: action.fields,
 			companyId,
-			companySourceRef: action.companyRef ?? null
+			companySourceRef: action.companyRef ?? null,
+			...memberships ? { memberships } : {}
+		};
+		return action.kind === "create" ? {
+			kind: "create",
+			...base
+		} : {
+			kind: action.kind,
+			id: action.id,
+			...base
 		};
 	});
 }
@@ -97,19 +153,11 @@ function emptyTally() {
 		create: 0,
 		update: 0,
 		restore: 0,
-		archive: 0
+		archive: 0,
+		endMembership: 0
 	};
 }
 /**
-* An entity whose company relationship is a `through` (join-table) join fans out
-* into one source row per membership, so its mirror must be keyed compositely.
-*/
-function isCompositeEntity(config, entityKey) {
-	const entity = config.entities[entityKey];
-	if (!entity?.relationships) return false;
-	return Object.values(entity.relationships).some((rel) => "through" in rel.via);
-}
-/**
 * Run a full sync: compile the config's views, then reconcile + persist each,
 * companies first. Returns per-entity and total action counts.
 */
@@ -130,7 +178,7 @@ async function runSync(config, store, options = {}) {
 			role: view.role,
 			objectTypeId
 		})]);
-		const actions = reconcile(source, mirror, { composite: isCompositeEntity(config, view.entityKey) }).filter((a) => !(options.sample && a.kind === "archive"));
+		const actions = reconcile(source, mirror, { memberships: view.concept === "contact" }).filter((a) => !(options.sample && isRemovalAction(a)));
 		const persistActions = await resolveActions(store, actions);
 		await store.persist({
 			concept: view.concept,
@@ -213,6 +261,8 @@ async function previewSync(store, view, opts) {
 }
 //#endregion
 exports.computeSampleWarnings = computeSampleWarnings;
+exports.isRemovalAction = isRemovalAction;
 exports.previewSync = previewSync;
 exports.reconcile = reconcile;
+exports.resolveActions = resolveActions;
 exports.runSync = runSync;

package/dist/sync-engine.d.cts

@@ -30,77 +30,112 @@ export interface SourceRow {
 /** An existing mirror row, as far as reconciliation needs to know. */
 export interface MirrorRecord {
   archivedAt: Date | null;
-  /** Host-side company key; only consulted in composite (join-table) mode. */
+  /** Host-side key of the row's primary company (its `company_source_ref`). */
   companyRef: string | null;
+  /**
+   * Host-side keys of the person's ACTIVE memberships. Only listed for
+   * contacts; reconciliation ends any membership absent from a full sync.
+   */
+  companyRefs?: string[];
   id: string;
   sourceRef: string;
 }
-export type SyncAction = {
+/**
+ * The tenants a person belongs to, as seen in this batch. Present on contact
+ * actions only (the `memberships` reconcile option); `companyRef` alongside it
+ * is the one picked as primary.
+ */
+interface MembershipSet {
+  companyRefs?: string[];
+}
+export type SyncAction = ({
   kind: "create";
   sourceRef: string;
   fields: Record<string, string | null>;
   companyRef: string | null;
-} | {
+} & MembershipSet) | ({
   kind: "update";
   id: string;
   sourceRef: string;
   fields: Record<string, string | null>;
   companyRef: string | null;
-} | {
+} & MembershipSet) | ({
   kind: "restore";
   id: string;
   sourceRef: string;
   fields: Record<string, string | null>;
   companyRef: string | null;
-} | {
+} & MembershipSet) | {
   kind: "archive";
   id: string;
   sourceRef: string;
+} | {
+  kind: "endMembership";
+  id: string;
+  sourceRef: string;
+  companyRef: string;
 };
+/** A membership with its host tenant key resolved to a `crm_companies.id`. */
+export interface ResolvedMembership {
+  companyId: string | null;
+  companyRef: string;
+}
+interface ResolvedMembershipSet {
+  memberships?: ResolvedMembership[];
+}
 /** A persist action with the company ref resolved to a `crm_companies.id`. */
-export type PersistAction = {
+export type PersistAction = ({
   kind: "create";
   sourceRef: string;
   fields: Record<string, string | null>;
   companyId: string | null;
   companySourceRef: string | null;
-} | {
+} & ResolvedMembershipSet) | ({
   kind: "update";
   id: string;
   sourceRef: string;
   fields: Record<string, string | null>;
   companyId: string | null;
   companySourceRef: string | null;
-} | {
+} & ResolvedMembershipSet) | ({
   kind: "restore";
   id: string;
   sourceRef: string;
   fields: Record<string, string | null>;
   companyId: string | null;
   companySourceRef: string | null;
-} | {
+} & ResolvedMembershipSet) | {
   kind: "archive";
   id: string;
   sourceRef: string;
+} | {
+  kind: "endMembership";
+  id: string;
+  sourceRef: string;
+  companyRef: string;
 };
+/** Actions that remove something — only safe when the source set is complete. */
+export declare function isRemovalAction(action: {
+  kind: string;
+}): boolean;
 /**
  * Diff a view's rows against the current mirror population for one entity.
  *
- * - source row with no mirror row      → create
- * - source row with a live mirror row  → update (overwrite identity fields)
- * - source row with an archived mirror → restore (re-activate + update)
- * - live mirror row absent from source → archive (soft delete, keep history)
- * - archived mirror row absent from source → no-op
+ * - source identity with no mirror row      → create
+ * - source identity with a live mirror row  → update (overwrite identity fields)
+ * - source identity with an archived mirror → restore (re-activate + update)
+ * - live mirror row absent from source      → archive (soft delete, keep history)
+ * - archived mirror row absent from source  → no-op
  *
- * Source rows are de-duplicated by the reconciliation key (first wins). In
- * simple mode (default) the key is `sourceRef`. In composite mode — used for
- * `through` (join-table) entities, where the compiled view fans a person out
- * into one row per membership — the key is `(sourceRef, companyRef)`, so a
- * person in several companies materializes one mirror row per company and a
- * single membership leaving archives only that one row.
+ * Identity is always the source primary key. A `through` (join-table) view
+ * fans one person out into a row per tenant; those rows are ONE person, so they
+ * collapse into one action. With `memberships` on (contacts), that action also
+ * carries every tenant ref the person was seen with, and each tenant the mirror
+ * still has as active but the source no longer lists yields `endMembership` —
+ * a person leaving one tenant ends that membership and keeps the others.
  */
 export declare function reconcile(source: SourceRow[], mirror: MirrorRecord[], opts?: {
-  composite?: boolean;
+  memberships?: boolean;
 }): SyncAction[];
 /** DB I/O port. The concrete store lives in the SDK/drizzle package. */
 export interface SyncStore {
@@ -147,6 +182,12 @@ export interface SyncResult {
     archived: number;
   };
 }
+/**
+ * Resolve each action's host-side company refs — the primary one and, for
+ * contacts, every membership — to `crm_companies.id`s in one lookup. Shared by
+ * `runSync` and the cloud push receiver so both persist identical actions.
+ */
+export declare function resolveActions(store: SyncStore, actions: SyncAction[]): Promise<PersistAction[]>;
 /**
  * Run a full sync: compile the config's views, then reconcile + persist each,
  * companies first. Returns per-entity and total action counts.

package/dist/sync-engine.d.mts

@@ -30,77 +30,112 @@ export interface SourceRow {
 /** An existing mirror row, as far as reconciliation needs to know. */
 export interface MirrorRecord {
   archivedAt: Date | null;
-  /** Host-side company key; only consulted in composite (join-table) mode. */
+  /** Host-side key of the row's primary company (its `company_source_ref`). */
   companyRef: string | null;
+  /**
+   * Host-side keys of the person's ACTIVE memberships. Only listed for
+   * contacts; reconciliation ends any membership absent from a full sync.
+   */
+  companyRefs?: string[];
   id: string;
   sourceRef: string;
 }
-export type SyncAction = {
+/**
+ * The tenants a person belongs to, as seen in this batch. Present on contact
+ * actions only (the `memberships` reconcile option); `companyRef` alongside it
+ * is the one picked as primary.
+ */
+interface MembershipSet {
+  companyRefs?: string[];
+}
+export type SyncAction = ({
   kind: "create";
   sourceRef: string;
   fields: Record<string, string | null>;
   companyRef: string | null;
-} | {
+} & MembershipSet) | ({
   kind: "update";
   id: string;
   sourceRef: string;
   fields: Record<string, string | null>;
   companyRef: string | null;
-} | {
+} & MembershipSet) | ({
   kind: "restore";
   id: string;
   sourceRef: string;
   fields: Record<string, string | null>;
   companyRef: string | null;
-} | {
+} & MembershipSet) | {
   kind: "archive";
   id: string;
   sourceRef: string;
+} | {
+  kind: "endMembership";
+  id: string;
+  sourceRef: string;
+  companyRef: string;
 };
+/** A membership with its host tenant key resolved to a `crm_companies.id`. */
+export interface ResolvedMembership {
+  companyId: string | null;
+  companyRef: string;
+}
+interface ResolvedMembershipSet {
+  memberships?: ResolvedMembership[];
+}
 /** A persist action with the company ref resolved to a `crm_companies.id`. */
-export type PersistAction = {
+export type PersistAction = ({
   kind: "create";
   sourceRef: string;
   fields: Record<string, string | null>;
   companyId: string | null;
   companySourceRef: string | null;
-} | {
+} & ResolvedMembershipSet) | ({
   kind: "update";
   id: string;
   sourceRef: string;
   fields: Record<string, string | null>;
   companyId: string | null;
   companySourceRef: string | null;
-} | {
+} & ResolvedMembershipSet) | ({
   kind: "restore";
   id: string;
   sourceRef: string;
   fields: Record<string, string | null>;
   companyId: string | null;
   companySourceRef: string | null;
-} | {
+} & ResolvedMembershipSet) | {
   kind: "archive";
   id: string;
   sourceRef: string;
+} | {
+  kind: "endMembership";
+  id: string;
+  sourceRef: string;
+  companyRef: string;
 };
+/** Actions that remove something — only safe when the source set is complete. */
+export declare function isRemovalAction(action: {
+  kind: string;
+}): boolean;
 /**
  * Diff a view's rows against the current mirror population for one entity.
  *
- * - source row with no mirror row      → create
- * - source row with a live mirror row  → update (overwrite identity fields)
- * - source row with an archived mirror → restore (re-activate + update)
- * - live mirror row absent from source → archive (soft delete, keep history)
- * - archived mirror row absent from source → no-op
+ * - source identity with no mirror row      → create
+ * - source identity with a live mirror row  → update (overwrite identity fields)
+ * - source identity with an archived mirror → restore (re-activate + update)
+ * - live mirror row absent from source      → archive (soft delete, keep history)
+ * - archived mirror row absent from source  → no-op
  *
- * Source rows are de-duplicated by the reconciliation key (first wins). In
- * simple mode (default) the key is `sourceRef`. In composite mode — used for
- * `through` (join-table) entities, where the compiled view fans a person out
- * into one row per membership — the key is `(sourceRef, companyRef)`, so a
- * person in several companies materializes one mirror row per company and a
- * single membership leaving archives only that one row.
+ * Identity is always the source primary key. A `through` (join-table) view
+ * fans one person out into a row per tenant; those rows are ONE person, so they
+ * collapse into one action. With `memberships` on (contacts), that action also
+ * carries every tenant ref the person was seen with, and each tenant the mirror
+ * still has as active but the source no longer lists yields `endMembership` —
+ * a person leaving one tenant ends that membership and keeps the others.
  */
 export declare function reconcile(source: SourceRow[], mirror: MirrorRecord[], opts?: {
-  composite?: boolean;
+  memberships?: boolean;
 }): SyncAction[];
 /** DB I/O port. The concrete store lives in the SDK/drizzle package. */
 export interface SyncStore {
@@ -147,6 +182,12 @@ export interface SyncResult {
     archived: number;
   };
 }
+/**
+ * Resolve each action's host-side company refs — the primary one and, for
+ * contacts, every membership — to `crm_companies.id`s in one lookup. Shared by
+ * `runSync` and the cloud push receiver so both persist identical actions.
+ */
+export declare function resolveActions(store: SyncStore, actions: SyncAction[]): Promise<PersistAction[]>;
 /**
  * Run a full sync: compile the config's views, then reconcile + persist each,
  * companies first. Returns per-entity and total action counts.

package/dist/sync-engine.mjs

@@ -1,67 +1,103 @@
 import { r as compileEntityViews } from "./view-compiler-CLvZ0wJW.mjs";
 //#region src/sync-engine.ts
+/** Actions that remove something — only safe when the source set is complete. */
+function isRemovalAction(action) {
+	return action.kind === "archive" || action.kind === "endMembership";
+}
+/** Every distinct non-null company ref in a person's rows, in arrival order. */
+function collectCompanyRefs(rows) {
+	const refs = [];
+	for (const row of rows) {
+		const ref = row.companyRef ?? null;
+		if (ref !== null && !refs.includes(ref)) refs.push(ref);
+	}
+	return refs;
+}
+/**
+* The primary company for a person: the one they already have while it is
+* still one of theirs — so the displayed organisation never flips between
+* syncs — otherwise the lowest ref, which is deterministic for a new person.
+*/
+function pickPrimaryRef(refs, current) {
+	if (current !== null && refs.includes(current)) return current;
+	return [...refs].sort()[0] ?? null;
+}
+/**
+* The mirror row that represents a source identity. Normally there is exactly
+* one; before contact consolidation has run there can be several (one per
+* tenant), and the live, earliest-listed one stands for the person while the
+* rest are left alone for the consolidation script to fold in.
+*/
+function canonicalMirror(rows) {
+	return rows.find((row) => !row.archivedAt) ?? rows[0];
+}
 /**
 * Diff a view's rows against the current mirror population for one entity.
 *
-* - source row with no mirror row      → create
-* - source row with a live mirror row  → update (overwrite identity fields)
-* - source row with an archived mirror → restore (re-activate + update)
-* - live mirror row absent from source → archive (soft delete, keep history)
-* - archived mirror row absent from source → no-op
+* - source identity with no mirror row      → create
+* - source identity with a live mirror row  → update (overwrite identity fields)
+* - source identity with an archived mirror → restore (re-activate + update)
+* - live mirror row absent from source      → archive (soft delete, keep history)
+* - archived mirror row absent from source  → no-op
 *
-* Source rows are de-duplicated by the reconciliation key (first wins). In
-* simple mode (default) the key is `sourceRef`. In composite mode — used for
-* `through` (join-table) entities, where the compiled view fans a person out
-* into one row per membership — the key is `(sourceRef, companyRef)`, so a
-* person in several companies materializes one mirror row per company and a
-* single membership leaving archives only that one row.
+* Identity is always the source primary key. A `through` (join-table) view
+* fans one person out into a row per tenant; those rows are ONE person, so they
+* collapse into one action. With `memberships` on (contacts), that action also
+* carries every tenant ref the person was seen with, and each tenant the mirror
+* still has as active but the source no longer lists yields `endMembership` —
+* a person leaving one tenant ends that membership and keeps the others.
 */
 function reconcile(source, mirror, opts = {}) {
-	const keyOf = (sourceRef, companyRef) => opts.composite ? `${sourceRef}\0${companyRef ?? ""}` : sourceRef;
-	const seen = /* @__PURE__ */ new Set();
-	const rows = [];
-	for (const row of source) {
-		const key = keyOf(row.sourceRef, row.companyRef ?? null);
-		if (!seen.has(key)) {
-			seen.add(key);
-			rows.push(row);
-		}
-	}
-	const byKey = new Map(mirror.map((m) => [keyOf(m.sourceRef, m.companyRef), m]));
-	const liveKeys = /* @__PURE__ */ new Set();
+	const rowsByRef = groupBySourceRef(source);
+	const mirrorByRef = groupBySourceRef(mirror);
 	const actions = [];
-	for (const row of rows) {
-		const companyRef = row.companyRef ?? null;
-		const key = keyOf(row.sourceRef, companyRef);
-		liveKeys.add(key);
-		const existing = byKey.get(key);
-		if (!existing) actions.push({
-			kind: "create",
-			sourceRef: row.sourceRef,
-			fields: row.fields,
-			companyRef
-		});
-		else if (existing.archivedAt) actions.push({
-			kind: "restore",
-			id: existing.id,
-			sourceRef: row.sourceRef,
-			fields: row.fields,
-			companyRef
-		});
-		else actions.push({
-			kind: "update",
-			id: existing.id,
-			sourceRef: row.sourceRef,
-			fields: row.fields,
-			companyRef
-		});
+	for (const [sourceRef, rows] of rowsByRef) {
+		const existing = canonicalMirror(mirrorByRef.get(sourceRef) ?? []);
+		actions.push(...personActions(sourceRef, rows, existing, opts));
+	}
+	for (const m of mirror) if (!(rowsByRef.has(m.sourceRef) || m.archivedAt)) actions.push({
+		kind: "archive",
+		id: m.id,
+		sourceRef: m.sourceRef
+	});
+	return actions;
+}
+function groupBySourceRef(items) {
+	const out = /* @__PURE__ */ new Map();
+	for (const item of items) {
+		const list = out.get(item.sourceRef);
+		if (list) list.push(item);
+		else out.set(item.sourceRef, [item]);
 	}
-	for (const m of mirror) {
-		const key = keyOf(m.sourceRef, m.companyRef);
-		if (!(liveKeys.has(key) || m.archivedAt)) actions.push({
-			kind: "archive",
-			id: m.id,
-			sourceRef: m.sourceRef
+	return out;
+}
+/** The create/update/restore for one present person, plus any ended tenants. */
+function personActions(sourceRef, rows, existing, opts) {
+	const first = rows[0];
+	const refs = collectCompanyRefs(rows);
+	const companyRef = opts.memberships ? pickPrimaryRef(refs, existing?.companyRef ?? null) : first.companyRef ?? null;
+	const membershipSet = opts.memberships ? { companyRefs: refs } : {};
+	if (!existing) return [{
+		kind: "create",
+		sourceRef,
+		fields: first.fields,
+		companyRef,
+		...membershipSet
+	}];
+	const actions = [{
+		kind: existing.archivedAt ? "restore" : "update",
+		id: existing.id,
+		sourceRef,
+		fields: first.fields,
+		companyRef,
+		...membershipSet
+	}];
+	if (opts.memberships) {
+		for (const held of existing.companyRefs ?? []) if (!refs.includes(held)) actions.push({
+			kind: "endMembership",
+			id: existing.id,
+			sourceRef,
+			companyRef: held
 		});
 	}
 	return actions;
@@ -74,20 +110,40 @@ const CONCEPT_ORDER = {
 function syncOrder(a, b) {
 	return (CONCEPT_ORDER[a.concept] ?? 99) - (CONCEPT_ORDER[b.concept] ?? 99);
 }
+/**
+* Resolve each action's host-side company refs — the primary one and, for
+* contacts, every membership — to `crm_companies.id`s in one lookup. Shared by
+* `runSync` and the cloud push receiver so both persist identical actions.
+*/
 async function resolveActions(store, actions) {
 	const refs = /* @__PURE__ */ new Set();
-	for (const action of actions) if (action.kind !== "archive" && action.companyRef) refs.add(action.companyRef);
+	for (const action of actions) {
+		if (isRemovalAction(action) || !("fields" in action)) continue;
+		if (action.companyRef) refs.add(action.companyRef);
+		for (const ref of action.companyRefs ?? []) refs.add(ref);
+	}
 	const resolved = refs.size ? await store.resolveCompanyRefs([...refs]) : /* @__PURE__ */ new Map();
 	return actions.map((action) => {
-		if (action.kind === "archive") return action;
+		if (action.kind === "archive" || action.kind === "endMembership") return action;
 		const companyId = action.companyRef ? resolved.get(action.companyRef) ?? null : null;
-		return {
-			kind: action.kind,
-			id: "id" in action ? action.id : "",
+		const memberships = action.companyRefs?.map((companyRef) => ({
+			companyRef,
+			companyId: resolved.get(companyRef) ?? null
+		}));
+		const base = {
 			sourceRef: action.sourceRef,
 			fields: action.fields,
 			companyId,
-			companySourceRef: action.companyRef ?? null
+			companySourceRef: action.companyRef ?? null,
+			...memberships ? { memberships } : {}
+		};
+		return action.kind === "create" ? {
+			kind: "create",
+			...base
+		} : {
+			kind: action.kind,
+			id: action.id,
+			...base
 		};
 	});
 }
@@ -96,19 +152,11 @@ function emptyTally() {
 		create: 0,
 		update: 0,
 		restore: 0,
-		archive: 0
+		archive: 0,
+		endMembership: 0
 	};
 }
 /**
-* An entity whose company relationship is a `through` (join-table) join fans out
-* into one source row per membership, so its mirror must be keyed compositely.
-*/
-function isCompositeEntity(config, entityKey) {
-	const entity = config.entities[entityKey];
-	if (!entity?.relationships) return false;
-	return Object.values(entity.relationships).some((rel) => "through" in rel.via);
-}
-/**
 * Run a full sync: compile the config's views, then reconcile + persist each,
 * companies first. Returns per-entity and total action counts.
 */
@@ -129,7 +177,7 @@ async function runSync(config, store, options = {}) {
 			role: view.role,
 			objectTypeId
 		})]);
-		const actions = reconcile(source, mirror, { composite: isCompositeEntity(config, view.entityKey) }).filter((a) => !(options.sample && a.kind === "archive"));
+		const actions = reconcile(source, mirror, { memberships: view.concept === "contact" }).filter((a) => !(options.sample && isRemovalAction(a)));
 		const persistActions = await resolveActions(store, actions);
 		await store.persist({
 			concept: view.concept,
@@ -211,4 +259,4 @@ async function previewSync(store, view, opts) {
 	};
 }
 //#endregion
-export { computeSampleWarnings, previewSync, reconcile, runSync };
+export { computeSampleWarnings, isRemovalAction, previewSync, reconcile, resolveActions, runSync };

package/dist/types.d.cts

@@ -84,12 +84,21 @@ export interface Company {
 }
 export interface Deal {
   closeDate: Date | null;
+  /** The organisation this deal belongs to, when one is linked. */
+  companyId: string | null;
   contactId: string | null;
   createdAt: Date;
   id: string;
   name: string;
   orgId: string;
   owner: string | null;
+  /**
+   * The board this deal belongs to. NULL means the org's default pipeline: the
+   * sync mirror wrote deals before pipelines existed, and a deal created with
+   * no pipeline lands on the default. Stage keys are unique per pipeline, so
+   * a board must filter on this, never on stage key alone.
+   */
+  pipelineId: string | null;
   position: number | null;
   stage: DealStage;
   /**
@@ -116,6 +125,11 @@ export interface Task {
   createdAt: Date;
   createdBy: string | null;
   description: string | null;
+  /**
+   * Whether `dueAt` is a calendar date (stored as midnight UTC) rather than a
+   * moment. Absent or null: a midnight-UTC `dueAt` is read as a date.
+   */
+  dueAllDay?: boolean | null;
   dueAt: Date | null;
   entityId: string | null;
   entityType: TaskEntityType | null;
@@ -203,6 +217,11 @@ export interface CreateTaskInput {
   assignee?: string;
   createdBy?: string;
   description?: string;
+  /**
+   * Whether `dueAt` is a calendar date (stored as midnight UTC) rather than a
+   * moment. Absent or null: a midnight-UTC `dueAt` is read as a date.
+   */
+  dueAllDay?: boolean | null;
   dueAt?: Date;
   entityId?: string;
   entityType?: TaskEntityType;
@@ -212,6 +231,11 @@ export interface CreateTaskInput {
 export interface UpdateTaskInput {
   assignee?: string | null;
   description?: string | null;
+  /**
+   * Whether `dueAt` is a calendar date (stored as midnight UTC) rather than a
+   * moment. Absent or null: a midnight-UTC `dueAt` is read as a date.
+   */
+  dueAllDay?: boolean | null;
   dueAt?: Date | null;
   entityId?: string | null;
   entityType?: TaskEntityType | null;
@@ -244,6 +268,17 @@ export interface ContactFilters {
    * row is no longer sync-provenanced.
    */
   excludeArchived?: boolean;
+  /**
+   * Case-insensitive substring match on name or email.
+   *
+   * Applied in SQL, not over an already-fetched page: a filter applied after
+   * paging returns a partial page and a cursor that skips the rows it dropped,
+   * so "page 2" of a search is not the second page of the matches. An empty or
+   * whitespace-only value is ignored rather than matching nothing.
+   *
+   * LIKE metacharacters in the term are escaped and matched literally — a
+   * search for `%` finds contacts containing a percent sign, not every row.
+   */
   search?: string;
   source?: RecordSource;
   status?: ContactStatus;

package/dist/types.d.mts

@@ -84,12 +84,21 @@ export interface Company {
 }
 export interface Deal {
   closeDate: Date | null;
+  /** The organisation this deal belongs to, when one is linked. */
+  companyId: string | null;
   contactId: string | null;
   createdAt: Date;
   id: string;
   name: string;
   orgId: string;
   owner: string | null;
+  /**
+   * The board this deal belongs to. NULL means the org's default pipeline: the
+   * sync mirror wrote deals before pipelines existed, and a deal created with
+   * no pipeline lands on the default. Stage keys are unique per pipeline, so
+   * a board must filter on this, never on stage key alone.
+   */
+  pipelineId: string | null;
   position: number | null;
   stage: DealStage;
   /**
@@ -116,6 +125,11 @@ export interface Task {
   createdAt: Date;
   createdBy: string | null;
   description: string | null;
+  /**
+   * Whether `dueAt` is a calendar date (stored as midnight UTC) rather than a
+   * moment. Absent or null: a midnight-UTC `dueAt` is read as a date.
+   */
+  dueAllDay?: boolean | null;
   dueAt: Date | null;
   entityId: string | null;
   entityType: TaskEntityType | null;
@@ -203,6 +217,11 @@ export interface CreateTaskInput {
   assignee?: string;
   createdBy?: string;
   description?: string;
+  /**
+   * Whether `dueAt` is a calendar date (stored as midnight UTC) rather than a
+   * moment. Absent or null: a midnight-UTC `dueAt` is read as a date.
+   */
+  dueAllDay?: boolean | null;
   dueAt?: Date;
   entityId?: string;
   entityType?: TaskEntityType;
@@ -212,6 +231,11 @@ export interface CreateTaskInput {
 export interface UpdateTaskInput {
   assignee?: string | null;
   description?: string | null;
+  /**
+   * Whether `dueAt` is a calendar date (stored as midnight UTC) rather than a
+   * moment. Absent or null: a midnight-UTC `dueAt` is read as a date.
+   */
+  dueAllDay?: boolean | null;
   dueAt?: Date | null;
   entityId?: string | null;
   entityType?: TaskEntityType | null;
@@ -244,6 +268,17 @@ export interface ContactFilters {
    * row is no longer sync-provenanced.
    */
   excludeArchived?: boolean;
+  /**
+   * Case-insensitive substring match on name or email.
+   *
+   * Applied in SQL, not over an already-fetched page: a filter applied after
+   * paging returns a partial page and a cursor that skips the rows it dropped,
+   * so "page 2" of a search is not the second page of the matches. An empty or
+   * whitespace-only value is ignored rather than matching nothing.
+   *
+   * LIKE metacharacters in the term are escaped and matched literally — a
+   * search for `%` finds contacts containing a percent sign, not every row.
+   */
   search?: string;
   source?: RecordSource;
   status?: ContactStatus;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/core",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "private": false,
   "description": "ORM/auth-agnostic CRM adapter contracts and shared domain types for Clivly.",
   "license": "MIT",