@clivly/core 0.9.6 → 0.10.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { Activity, ActivityType, Company, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, RecordSource, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateDealInput, UpdateTaskInput } from "./types.cjs";
+import { 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 } from "./types.cjs";
 import { CRMAdapter } from "./adapter.cjs";
 import { ClivlyAuthAdapter, ClivlyUser, CrmMembership, MembershipResolver, authCustom } from "./auth-adapter.cjs";
-import { A as BASE_REF, C as defineClivlyConfig, D as relationshipSchema, F as ProjectionRef, I as identityRefs, L as projectionSchema, M as ProjectionIdentity, N as ProjectionJoin, O as relationshipsSchema, P as ProjectionMapping, T as filterSchema, _ as MATERIALIZING_CONCEPTS, a as ClivlyEntitiesConfig, b as RelationshipVia, d as CrmConcept, g as FilterValue, h as FilterExpr, i as ClivlyConfigError, j as ProjectionFieldBinding, k as validateEntitiesConfig, l as ConfigValidationError, m as DiscoveredSchemaTable, n as CRM_CONCEPTS, p as DiscoveredColumnMeta, s as ClivlyEntityConfig, t as CANONICAL_FIELDS, u as ConfigValidationResult, v as MaterializingConcept, w as entitiesConfigSchema, x as RelationshipsMap, y as RelationshipSpec } from "./entity-config-buOIVtMM.cjs";
+import { A as BASE_REF, C as defineClivlyConfig, D as relationshipSchema, E as projectionFields, F as ProjectionMapping, I as ProjectionRef, L as identityRefs, M as ProjectionFieldBinding, N as ProjectionIdentity, O as relationshipsSchema, P as ProjectionJoin, R as projectionSchema, T as filterSchema, _ as MATERIALIZING_CONCEPTS, a as ClivlyEntitiesConfig, b as RelationshipVia, d as CrmConcept, g as FilterValue, h as FilterExpr, i as ClivlyConfigError, j as PROJECTION_KEY_PATTERN, k as validateEntitiesConfig, l as ConfigValidationError, m as DiscoveredSchemaTable, n as CRM_CONCEPTS, p as DiscoveredColumnMeta, s as ClivlyEntityConfig, t as CANONICAL_FIELDS, u as ConfigValidationResult, v as MaterializingConcept, w as entitiesConfigSchema, x as RelationshipsMap, y as RelationshipSpec } from "./entity-config-DCa785OE.cjs";
 import { ConnectionLiveness, IntegrationFacts, IntegrationState, IntegrationStatus, IntegrationStep, NextAction, StepId, StepProblem, StepState } from "./integration-state.cjs";
 import { RelationshipCandidate, buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.cjs";
 import { EntityMappingRow, mappingsToEntitiesConfig } from "./mappings-config.cjs";
@@ -12,90 +12,6 @@ declare function joinFansOut(join: ProjectionJoin, joinTable: DiscoveredSchemaTa
 /** Every join in the projection that can multiply rows. */
 declare function fanOutJoins(projection: ProjectionMapping, tablesByName: Map<string, DiscoveredSchemaTable>): ProjectionJoin[];
 //#endregion
-//#region src/projection-draft.d.ts
-/**
- * The builder's in-progress shape.
- *
- * A draft is deliberately looser than a `ProjectionMapping`: it exists while
- * the user is still choosing things, so every field can be empty. All of the
- * builder's rules live here as pure functions, which keeps the React components
- * presentational and lets the rules be tested without a DOM.
- */
-interface ProjectionDraft {
-  baseTable: string;
-  entityKey: string;
-  fieldBindings: Record<string, ProjectionFieldBinding>;
-  identity: ProjectionIdentity;
-  joins: ProjectionJoin[];
-}
-declare function emptyProjectionDraft(baseTable: string): ProjectionDraft;
-/**
- * The ON conditions implied by a foreign key between the two tables, so the
- * builder can pre-fill a join instead of making the user hand-pick columns.
- * Returns [] when no FK relates them — the user then picks manually.
- */
-declare function suggestJoinConditions(baseTable: string, joinTable: string, schema: DiscoveredSchemaTable[], joinKey: string): ProjectionJoin["on"];
-/**
- * Add a join on `joinTable`, keyed and pre-filled.
- *
- * The key is the table's own name where that is free, because it is what the
- * user already calls the table; a collision falls back to `_2`, `_3` and so on.
- * Uniqueness is not cosmetic — the key is the SQL alias and the name every ref
- * addresses the table by, so two joins sharing one would make every ref
- * ambiguous. `base` is reserved for the base table and can never be taken.
- */
-declare function addDraftJoin(draft: ProjectionDraft, joinTable: string, schema: DiscoveredSchemaTable[]): ProjectionDraft;
-/**
- * Remove a join, and everything that addressed it.
- *
- * Refs to a removed join are refs to a table the projection no longer declares.
- * Left in place they fail validation as "unknown ref table", which blames the
- * field — or, worse, the identity — for the join's removal. Identity falls back
- * to the base primary key, the same default a new draft starts from.
- */
-declare function removeDraftJoin(draft: ProjectionDraft, joinKey: string): ProjectionDraft;
-/** One selectable table in the builder's column pickers. */
-interface DraftRefOption {
-  columns: string[];
-  label: string;
-  ref: string;
-}
-/**
- * Every table a field or identity may currently read from, in ref order: the
- * base table first, then each join.
- *
- * Returns [] when the base table is not in the discovered schema — there is
- * nothing truthful to offer, and inventing columns would let someone build a
- * projection that cannot compile.
- */
-declare function draftRefOptions(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): DraftRefOption[];
-/** A draft becomes a projection once it has a valid key and ≥1 binding. */
-declare function draftToProjection(draft: ProjectionDraft): ProjectionMapping | null;
-/**
- * Every reason this draft cannot be saved, one per cause and each anchored to
- * the section that owns it.
- *
- * One lumped "Name the object and map a field." was all this used to return for
- * an incomplete draft, at the bare path "projection". Two consequences, both
- * bad: a builder had nowhere to attach the message, and — because it returned
- * before validating — a fanning join under a `base_pk` identity stayed silent
- * until the draft was otherwise complete, which is well after the point where
- * the user chose the join.
- */
-declare function draftErrors(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): ConfigValidationError[];
-/**
- * Per-join fan-out, for the builder's inline cardinality hints.
- *
- * Answered from the joins alone. Joins are chosen before the key and the fields
- * are filled in, and a fan-out warning is precisely what should steer the
- * identity choice while it is being made — requiring a complete draft put the
- * hint after the decision it exists to inform.
- */
-declare function describeCardinality(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): Array<{
-  fansOut: boolean;
-  joinKey: string;
-}>;
-//#endregion
 //#region src/projection-sql.d.ts
 /**
  * SQL generation for projection-backed entities.
@@ -153,6 +69,27 @@ declare const PREVIEW_MAX_ROWS = 50;
 declare function compileProjectionPreview(projection: ProjectionMapping, limit: number): string;
 //#endregion
 //#region src/projection-validate.d.ts
+/**
+ * A derived object's filter is evaluated in the cloud against pushed rows, so
+ * it can only name columns of the base table.
+ *
+ * Every rejected shape here fails *silently* today, which is the whole reason
+ * the check exists — a filter that cannot be honoured must error, never quietly
+ * return the wrong rows. The three shapes fail in different directions:
+ *
+ * - `$raw` is opaque SQL meant for the embedded model. The cloud path cannot
+ *   evaluate it and passes every row, so the filter is ignored and the object
+ *   syncs UNFILTERED.
+ * - A joined-table column resolves to nothing on a pushed row, so under a
+ *   positive operator (`eq`, `in`) no row matches and the object syncs EMPTY.
+ * - The same unresolvable column under a NEGATIVE operator (`ne`, `isNull`,
+ *   `notIn`) is the dangerous one: the missing cell reads as null, so the
+ *   predicate is true for every row and a filter meant to narrow the sync
+ *   ADMITS EVERYTHING. Nobody notices extra rows arriving.
+ *
+ * Rejecting an unresolvable column closes the last two together.
+ */
+declare function validateProjectionFilter(filter: FilterExpr | undefined, projection: ProjectionMapping, schema: DiscoveredSchemaTable[], base: string): ConfigValidationError[];
 /**
  * Validate a projection against the discovered schema. Returns every error
  * found (not just the first) so a builder UI can show them all at once.
@@ -182,7 +119,116 @@ declare function primaryKeyColumns(table: DiscoveredSchemaTable): string[];
  * match many.
  */
 declare function coversUniqueKey(table: DiscoveredSchemaTable, columns: string[]): boolean;
-/** Is this table's payload rich enough to validate a projection against? */
-declare function hasRichMeta(table: DiscoveredSchemaTable): boolean;
+/**
+ * A discovered table whose enrichment metadata is known to be present.
+ *
+ * This narrows only the *presence* of the two optional fields. It says nothing
+ * about their contents — an empty `uniqueConstraints` is a known-empty fact
+ * (the table genuinely has no unique keys), which is exactly the distinction
+ * `hasRichMeta` has always drawn and must keep drawing.
+ */
+type RichMetaTable = DiscoveredSchemaTable & {
+  columnsMeta: DiscoveredColumnMeta[];
+  uniqueConstraints: string[][];
+};
+/**
+ * Is this table's payload rich enough to validate a projection against?
+ *
+ * A type predicate rather than a plain boolean so the narrowing is visible to
+ * the compiler: callers that guard on this can iterate `columnsMeta` directly
+ * instead of casting, and a cast that outlives its guard becomes a type error
+ * rather than a silent walk over `undefined`.
+ *
+ * The invariant is unchanged: this reports whether the metadata is *known*,
+ * never whether the table has keys. Absent metadata stays UNKNOWN.
+ */
+declare function hasRichMeta(table: DiscoveredSchemaTable): table is RichMetaTable;
+//#endregion
+//#region src/slug.d.ts
+/**
+ * The one `slugify`.
+ *
+ * Three byte-identical copies existed before this module — in `@clivly/api`
+ * (the custom object-type slug), in `apps/web`'s onboarding route (the
+ * organisation slug), and in `@clivly/sdk`. The first two now import this; the
+ * SDK's copy stays where it is on purpose, because `@clivly/sdk` cannot depend
+ * on this package and its own comment records that its pattern is deliberately
+ * kept in step with the server's by hand.
+ *
+ * Note that the two callers this replaces slug *different things* — an
+ * object type and an organisation. They share a transform, not a namespace.
+ * Sharing the function stops the transform drifting; it does not make those two
+ * identifiers the same identifier.
+ */
+/**
+ * Lowercase, trim, collapse every run of non-alphanumerics to one hyphen, and
+ * drop leading/trailing hyphens. `"Participant Info"` becomes
+ * `"participant-info"`.
+ *
+ * The result is NOT guaranteed to be an acceptable slug. Both
+ * `OBJECT_TYPE_SLUG_PATTERN` (server) and `PROJECTION_KEY_PATTERN` (this
+ * package) require a leading letter, and this function happily returns
+ * `"2024-invoices"` for `"2024 Invoices"`. Callers that need an
+ * acceptance-guaranteed identifier want `toObjectTypeSlug`.
+ */
+declare function slugify(value: string): string;
+/**
+ * A slug the server will accept, derived from a display name.
+ *
+ * `slugify` alone is not enough: the server's `OBJECT_TYPE_SLUG_PATTERN`
+ * (`apps/server/src/index.ts`) demands a leading letter, so a name beginning
+ * with a digit slugs to something the platform rejects at push time — long
+ * after the object was authored. `@clivly/sdk`'s `custom-slug.ts` already knows
+ * this case and deliberately withholds `"2024-invoices"` as a suggestion
+ * because it would be rejected too.
+ *
+ * The prefix is applied ONLY when the derived slug does not already start with
+ * a letter, so the overwhelmingly common name is untouched.
+ *
+ * This value must be shown to whoever authored the name. It is the identifier
+ * the host app declares as its `objectType`, so a slug derived silently is a
+ * slug the developer cannot copy into their config.
+ *
+ * Returns an empty string for a name with no alphanumerics at all — the caller
+ * decides whether that is "keep typing" or an error, since only it knows
+ * whether the field is still being edited.
+ */
+declare function toObjectTypeSlug(displayName: string): string;
+//#endregion
+//#region src/stage-rules.d.ts
+type ConditionOp = "is_empty" | "is_not_empty" | "equals" | "not_equals" | "greater_than" | "less_than" | "before" | "after";
+interface Condition {
+  field: string;
+  op: ConditionOp;
+  value?: string;
+}
+interface EvaluableRule {
+  conditions: Condition[];
+  id: string;
+}
+/**
+ * Whether one condition holds for a host row.
+ *
+ * `mappedFields` is the set of columns the organization actually exposed. A
+ * condition naming anything outside it never matches, whatever the operator: a
+ * rule referencing a dropped column must fail safe, because treating the field
+ * as null would make `is_empty` match every deal.
+ */
+declare function matchesCondition(condition: Condition, fields: Record<string, string | null>, mappedFields: Set<string>): boolean;
+/**
+ * The id of the first rule whose conditions all hold, or null when none do.
+ *
+ * Returns a rule id rather than a stage key because the caller needs the
+ * matched rule's `allowClose` before it may move a deal into a closed stage.
+ *
+ * `rules` must arrive already ordered — stage position first, then rule
+ * position within a stage. Sorting needs stage rows this module deliberately
+ * does not see.
+ *
+ * A rule with no conditions never matches: an empty list would otherwise
+ * vacuously AND to true and capture every deal, which is the opposite of what
+ * a half-written rule should do.
+ */
+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 CompileOptions, type CompiledView, 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 DraftRefOption, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, type IntegrationFacts, type IntegrationState, type IntegrationStatus, type IntegrationStep, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type NextAction, type Note, PREVIEW_MAX_ROWS, type PersistAction, type ProjectionDraft, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type StepId, type StepProblem, type StepState, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, addDraftJoin, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, compileProjectionPreview, compileProjectionSelect, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftRefOptions, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, quoteIdent, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, removeDraftJoin, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };
+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 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 IntegrationFacts, type IntegrationState, type IntegrationStatus, type IntegrationStep, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type NextAction, type Note, OPEN_STAGE_TYPE, PREVIEW_MAX_ROWS, PROJECTION_KEY_PATTERN, type PersistAction, type PipelineConfig, type PipelineKind, type PipelineStageConfig, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, 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 UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, type ValueInterval, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, compileProjectionPreview, compileProjectionSelect, coversUniqueKey, defineClivlyConfig, entitiesConfigSchema, evaluateStage, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, isClosedStageType, joinFansOut, mappingsToEntitiesConfig, matchesCondition, primaryKeyColumns, projectionFields, projectionSchema, quoteIdent, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, slugify, toObjectTypeSlug, validateEntitiesConfig, validateProjection, validateProjectionFilter };

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { Activity, ActivityType, Company, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, RecordSource, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateDealInput, UpdateTaskInput } from "./types.mjs";
+import { 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 } from "./types.mjs";
 import { CRMAdapter } from "./adapter.mjs";
 import { ClivlyAuthAdapter, ClivlyUser, CrmMembership, MembershipResolver, authCustom } from "./auth-adapter.mjs";
-import { A as BASE_REF, C as defineClivlyConfig, D as relationshipSchema, F as ProjectionRef, I as identityRefs, L as projectionSchema, M as ProjectionIdentity, N as ProjectionJoin, O as relationshipsSchema, P as ProjectionMapping, T as filterSchema, _ as MATERIALIZING_CONCEPTS, a as ClivlyEntitiesConfig, b as RelationshipVia, d as CrmConcept, g as FilterValue, h as FilterExpr, i as ClivlyConfigError, j as ProjectionFieldBinding, k as validateEntitiesConfig, l as ConfigValidationError, m as DiscoveredSchemaTable, n as CRM_CONCEPTS, p as DiscoveredColumnMeta, s as ClivlyEntityConfig, t as CANONICAL_FIELDS, u as ConfigValidationResult, v as MaterializingConcept, w as entitiesConfigSchema, x as RelationshipsMap, y as RelationshipSpec } from "./entity-config-buOIVtMM.mjs";
+import { A as BASE_REF, C as defineClivlyConfig, D as relationshipSchema, E as projectionFields, F as ProjectionMapping, I as ProjectionRef, L as identityRefs, M as ProjectionFieldBinding, N as ProjectionIdentity, O as relationshipsSchema, P as ProjectionJoin, R as projectionSchema, T as filterSchema, _ as MATERIALIZING_CONCEPTS, a as ClivlyEntitiesConfig, b as RelationshipVia, d as CrmConcept, g as FilterValue, h as FilterExpr, i as ClivlyConfigError, j as PROJECTION_KEY_PATTERN, k as validateEntitiesConfig, l as ConfigValidationError, m as DiscoveredSchemaTable, n as CRM_CONCEPTS, p as DiscoveredColumnMeta, s as ClivlyEntityConfig, t as CANONICAL_FIELDS, u as ConfigValidationResult, v as MaterializingConcept, w as entitiesConfigSchema, x as RelationshipsMap, y as RelationshipSpec } from "./entity-config-DCa785OE.mjs";
 import { ConnectionLiveness, IntegrationFacts, IntegrationState, IntegrationStatus, IntegrationStep, NextAction, StepId, StepProblem, StepState } from "./integration-state.mjs";
 import { RelationshipCandidate, buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.mjs";
 import { EntityMappingRow, mappingsToEntitiesConfig } from "./mappings-config.mjs";
@@ -12,90 +12,6 @@ declare function joinFansOut(join: ProjectionJoin, joinTable: DiscoveredSchemaTa
 /** Every join in the projection that can multiply rows. */
 declare function fanOutJoins(projection: ProjectionMapping, tablesByName: Map<string, DiscoveredSchemaTable>): ProjectionJoin[];
 //#endregion
-//#region src/projection-draft.d.ts
-/**
- * The builder's in-progress shape.
- *
- * A draft is deliberately looser than a `ProjectionMapping`: it exists while
- * the user is still choosing things, so every field can be empty. All of the
- * builder's rules live here as pure functions, which keeps the React components
- * presentational and lets the rules be tested without a DOM.
- */
-interface ProjectionDraft {
-  baseTable: string;
-  entityKey: string;
-  fieldBindings: Record<string, ProjectionFieldBinding>;
-  identity: ProjectionIdentity;
-  joins: ProjectionJoin[];
-}
-declare function emptyProjectionDraft(baseTable: string): ProjectionDraft;
-/**
- * The ON conditions implied by a foreign key between the two tables, so the
- * builder can pre-fill a join instead of making the user hand-pick columns.
- * Returns [] when no FK relates them — the user then picks manually.
- */
-declare function suggestJoinConditions(baseTable: string, joinTable: string, schema: DiscoveredSchemaTable[], joinKey: string): ProjectionJoin["on"];
-/**
- * Add a join on `joinTable`, keyed and pre-filled.
- *
- * The key is the table's own name where that is free, because it is what the
- * user already calls the table; a collision falls back to `_2`, `_3` and so on.
- * Uniqueness is not cosmetic — the key is the SQL alias and the name every ref
- * addresses the table by, so two joins sharing one would make every ref
- * ambiguous. `base` is reserved for the base table and can never be taken.
- */
-declare function addDraftJoin(draft: ProjectionDraft, joinTable: string, schema: DiscoveredSchemaTable[]): ProjectionDraft;
-/**
- * Remove a join, and everything that addressed it.
- *
- * Refs to a removed join are refs to a table the projection no longer declares.
- * Left in place they fail validation as "unknown ref table", which blames the
- * field — or, worse, the identity — for the join's removal. Identity falls back
- * to the base primary key, the same default a new draft starts from.
- */
-declare function removeDraftJoin(draft: ProjectionDraft, joinKey: string): ProjectionDraft;
-/** One selectable table in the builder's column pickers. */
-interface DraftRefOption {
-  columns: string[];
-  label: string;
-  ref: string;
-}
-/**
- * Every table a field or identity may currently read from, in ref order: the
- * base table first, then each join.
- *
- * Returns [] when the base table is not in the discovered schema — there is
- * nothing truthful to offer, and inventing columns would let someone build a
- * projection that cannot compile.
- */
-declare function draftRefOptions(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): DraftRefOption[];
-/** A draft becomes a projection once it has a valid key and ≥1 binding. */
-declare function draftToProjection(draft: ProjectionDraft): ProjectionMapping | null;
-/**
- * Every reason this draft cannot be saved, one per cause and each anchored to
- * the section that owns it.
- *
- * One lumped "Name the object and map a field." was all this used to return for
- * an incomplete draft, at the bare path "projection". Two consequences, both
- * bad: a builder had nowhere to attach the message, and — because it returned
- * before validating — a fanning join under a `base_pk` identity stayed silent
- * until the draft was otherwise complete, which is well after the point where
- * the user chose the join.
- */
-declare function draftErrors(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): ConfigValidationError[];
-/**
- * Per-join fan-out, for the builder's inline cardinality hints.
- *
- * Answered from the joins alone. Joins are chosen before the key and the fields
- * are filled in, and a fan-out warning is precisely what should steer the
- * identity choice while it is being made — requiring a complete draft put the
- * hint after the decision it exists to inform.
- */
-declare function describeCardinality(draft: ProjectionDraft, schema: DiscoveredSchemaTable[]): Array<{
-  fansOut: boolean;
-  joinKey: string;
-}>;
-//#endregion
 //#region src/projection-sql.d.ts
 /**
  * SQL generation for projection-backed entities.
@@ -153,6 +69,27 @@ declare const PREVIEW_MAX_ROWS = 50;
 declare function compileProjectionPreview(projection: ProjectionMapping, limit: number): string;
 //#endregion
 //#region src/projection-validate.d.ts
+/**
+ * A derived object's filter is evaluated in the cloud against pushed rows, so
+ * it can only name columns of the base table.
+ *
+ * Every rejected shape here fails *silently* today, which is the whole reason
+ * the check exists — a filter that cannot be honoured must error, never quietly
+ * return the wrong rows. The three shapes fail in different directions:
+ *
+ * - `$raw` is opaque SQL meant for the embedded model. The cloud path cannot
+ *   evaluate it and passes every row, so the filter is ignored and the object
+ *   syncs UNFILTERED.
+ * - A joined-table column resolves to nothing on a pushed row, so under a
+ *   positive operator (`eq`, `in`) no row matches and the object syncs EMPTY.
+ * - The same unresolvable column under a NEGATIVE operator (`ne`, `isNull`,
+ *   `notIn`) is the dangerous one: the missing cell reads as null, so the
+ *   predicate is true for every row and a filter meant to narrow the sync
+ *   ADMITS EVERYTHING. Nobody notices extra rows arriving.
+ *
+ * Rejecting an unresolvable column closes the last two together.
+ */
+declare function validateProjectionFilter(filter: FilterExpr | undefined, projection: ProjectionMapping, schema: DiscoveredSchemaTable[], base: string): ConfigValidationError[];
 /**
  * Validate a projection against the discovered schema. Returns every error
  * found (not just the first) so a builder UI can show them all at once.
@@ -182,7 +119,116 @@ declare function primaryKeyColumns(table: DiscoveredSchemaTable): string[];
  * match many.
  */
 declare function coversUniqueKey(table: DiscoveredSchemaTable, columns: string[]): boolean;
-/** Is this table's payload rich enough to validate a projection against? */
-declare function hasRichMeta(table: DiscoveredSchemaTable): boolean;
+/**
+ * A discovered table whose enrichment metadata is known to be present.
+ *
+ * This narrows only the *presence* of the two optional fields. It says nothing
+ * about their contents — an empty `uniqueConstraints` is a known-empty fact
+ * (the table genuinely has no unique keys), which is exactly the distinction
+ * `hasRichMeta` has always drawn and must keep drawing.
+ */
+type RichMetaTable = DiscoveredSchemaTable & {
+  columnsMeta: DiscoveredColumnMeta[];
+  uniqueConstraints: string[][];
+};
+/**
+ * Is this table's payload rich enough to validate a projection against?
+ *
+ * A type predicate rather than a plain boolean so the narrowing is visible to
+ * the compiler: callers that guard on this can iterate `columnsMeta` directly
+ * instead of casting, and a cast that outlives its guard becomes a type error
+ * rather than a silent walk over `undefined`.
+ *
+ * The invariant is unchanged: this reports whether the metadata is *known*,
+ * never whether the table has keys. Absent metadata stays UNKNOWN.
+ */
+declare function hasRichMeta(table: DiscoveredSchemaTable): table is RichMetaTable;
+//#endregion
+//#region src/slug.d.ts
+/**
+ * The one `slugify`.
+ *
+ * Three byte-identical copies existed before this module — in `@clivly/api`
+ * (the custom object-type slug), in `apps/web`'s onboarding route (the
+ * organisation slug), and in `@clivly/sdk`. The first two now import this; the
+ * SDK's copy stays where it is on purpose, because `@clivly/sdk` cannot depend
+ * on this package and its own comment records that its pattern is deliberately
+ * kept in step with the server's by hand.
+ *
+ * Note that the two callers this replaces slug *different things* — an
+ * object type and an organisation. They share a transform, not a namespace.
+ * Sharing the function stops the transform drifting; it does not make those two
+ * identifiers the same identifier.
+ */
+/**
+ * Lowercase, trim, collapse every run of non-alphanumerics to one hyphen, and
+ * drop leading/trailing hyphens. `"Participant Info"` becomes
+ * `"participant-info"`.
+ *
+ * The result is NOT guaranteed to be an acceptable slug. Both
+ * `OBJECT_TYPE_SLUG_PATTERN` (server) and `PROJECTION_KEY_PATTERN` (this
+ * package) require a leading letter, and this function happily returns
+ * `"2024-invoices"` for `"2024 Invoices"`. Callers that need an
+ * acceptance-guaranteed identifier want `toObjectTypeSlug`.
+ */
+declare function slugify(value: string): string;
+/**
+ * A slug the server will accept, derived from a display name.
+ *
+ * `slugify` alone is not enough: the server's `OBJECT_TYPE_SLUG_PATTERN`
+ * (`apps/server/src/index.ts`) demands a leading letter, so a name beginning
+ * with a digit slugs to something the platform rejects at push time — long
+ * after the object was authored. `@clivly/sdk`'s `custom-slug.ts` already knows
+ * this case and deliberately withholds `"2024-invoices"` as a suggestion
+ * because it would be rejected too.
+ *
+ * The prefix is applied ONLY when the derived slug does not already start with
+ * a letter, so the overwhelmingly common name is untouched.
+ *
+ * This value must be shown to whoever authored the name. It is the identifier
+ * the host app declares as its `objectType`, so a slug derived silently is a
+ * slug the developer cannot copy into their config.
+ *
+ * Returns an empty string for a name with no alphanumerics at all — the caller
+ * decides whether that is "keep typing" or an error, since only it knows
+ * whether the field is still being edited.
+ */
+declare function toObjectTypeSlug(displayName: string): string;
+//#endregion
+//#region src/stage-rules.d.ts
+type ConditionOp = "is_empty" | "is_not_empty" | "equals" | "not_equals" | "greater_than" | "less_than" | "before" | "after";
+interface Condition {
+  field: string;
+  op: ConditionOp;
+  value?: string;
+}
+interface EvaluableRule {
+  conditions: Condition[];
+  id: string;
+}
+/**
+ * Whether one condition holds for a host row.
+ *
+ * `mappedFields` is the set of columns the organization actually exposed. A
+ * condition naming anything outside it never matches, whatever the operator: a
+ * rule referencing a dropped column must fail safe, because treating the field
+ * as null would make `is_empty` match every deal.
+ */
+declare function matchesCondition(condition: Condition, fields: Record<string, string | null>, mappedFields: Set<string>): boolean;
+/**
+ * The id of the first rule whose conditions all hold, or null when none do.
+ *
+ * Returns a rule id rather than a stage key because the caller needs the
+ * matched rule's `allowClose` before it may move a deal into a closed stage.
+ *
+ * `rules` must arrive already ordered — stage position first, then rule
+ * position within a stage. Sorting needs stage rows this module deliberately
+ * does not see.
+ *
+ * A rule with no conditions never matches: an empty list would otherwise
+ * vacuously AND to true and capture every deal, which is the opposite of what
+ * a half-written rule should do.
+ */
+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 CompileOptions, type CompiledView, 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 DraftRefOption, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, type IntegrationFacts, type IntegrationState, type IntegrationStatus, type IntegrationStep, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type NextAction, type Note, PREVIEW_MAX_ROWS, type PersistAction, type ProjectionDraft, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type StepId, type StepProblem, type StepState, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, addDraftJoin, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, compileProjectionPreview, compileProjectionSelect, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftRefOptions, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, quoteIdent, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, removeDraftJoin, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };
+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 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 IntegrationFacts, type IntegrationState, type IntegrationStatus, type IntegrationStep, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type NextAction, type Note, OPEN_STAGE_TYPE, PREVIEW_MAX_ROWS, PROJECTION_KEY_PATTERN, type PersistAction, type PipelineConfig, type PipelineKind, type PipelineStageConfig, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, 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 UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, type ValueInterval, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, compileProjectionPreview, compileProjectionSelect, coversUniqueKey, defineClivlyConfig, entitiesConfigSchema, evaluateStage, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, isClosedStageType, joinFansOut, mappingsToEntitiesConfig, matchesCondition, primaryKeyColumns, projectionFields, projectionSchema, quoteIdent, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, slugify, toObjectTypeSlug, validateEntitiesConfig, validateProjection, validateProjectionFilter };