@clivly/core 0.11.0-next.0 → 0.11.0

package/dist/index.d.mts

@@ -1,16 +1,83 @@
-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 { Activity, ActivityType, Company, CompanyFilters, 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, UpdateCompanyInput, 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 relationshipsSchema, B as identityRefs, D as missingRequiredFields, E as filterSchema, F as ProjectionFieldBinding, I as ProjectionIdentity, L as ProjectionJoin, M as validateEntitiesConfig, N as BASE_REF, O as projectionFields, P as PROJECTION_KEY_PATTERN, R as ProjectionMapping, S as RelationshipsMap, T as entitiesConfigSchema, V as projectionSchema, _ as MATERIALIZING_CONCEPTS, a as ClivlyEntitiesConfig, b as RelationshipSpec, d as CrmConcept, g as FilterValue, h as FilterExpr, i as ClivlyConfigError, j as requiredFieldsFor, k as relationshipSchema, 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 defineClivlyConfig, x as RelationshipVia, y as REQUIRED_FIELDS, z as ProjectionRef } from "./entity-config-Ddgukq_E.mjs";
+import { A as relationshipsSchema, B as identityRefs, D as missingRequiredFields, E as filterSchema, F as ProjectionFieldBinding, I as ProjectionIdentity, L as ProjectionJoin, M as validateEntitiesConfig, N as BASE_REF, O as projectionFields, P as PROJECTION_KEY_PATTERN, R as ProjectionMapping, S as RelationshipsMap, T as entitiesConfigSchema, V as projectionSchema, _ as MATERIALIZING_CONCEPTS, a as ClivlyEntitiesConfig, b as RelationshipSpec, d as CrmConcept, g as FilterValue, h as FilterExpr, i as ClivlyConfigError, j as requiredFieldsFor, k as relationshipSchema, 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 defineClivlyConfig, x as RelationshipVia, y as REQUIRED_FIELDS, z as ProjectionRef } from "./entity-config-OhC4Otkz.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";
 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";
+//#region src/host-owned-fields.d.ts
+/**
+ * Which fields a CRM record lets a user edit.
+ *
+ * A record synced from the host app carries a `sourceRef`. Its identity fields
+ * are rewritten from the host view on every sync run, so an edit to one would
+ * be silently reverted minutes later — the user sees their change accepted,
+ * then gone, with nothing explaining why. That is worse than refusing it.
+ *
+ * So host-owned fields are rejected at the API, not merely disabled in the UI:
+ * the UI is not the security boundary, and the SDK and any future public API
+ * reach the same routers.
+ *
+ * Records created inside the CRM have no `sourceRef` and are fully editable —
+ * nothing else owns them.
+ *
+ * This is the cheap half of a capability matrix. It answers "may a user write
+ * this?" but not "may the sync engine write this?", which stays implicit
+ * because sync bypasses these routers entirely. An override model (the
+ * `stageOverrideAt` pattern on `crm_deals`) can replace this later without
+ * changing callers.
+ */
+/** Contact fields the host view owns when the row is synced. */
+declare const HOST_OWNED_CONTACT_FIELDS: readonly ["email", "name"];
+/**
+ * Company fields the host view owns when the row is synced.
+ *
+ * `email` and `phone` joined this list in the same change that made them
+ * mappable (migration 0048). They are not identity fields, but ownership here
+ * follows what sync rewrites, not what feels identity-like: both flow from the
+ * host view on every run, exactly as `email` does for contacts above. Widening
+ * `CANONICAL_FIELDS.company` without widening this list is the specific bug
+ * this module's doc comment calls worse than refusing the edit.
+ *
+ * `primaryContactId` is deliberately absent: it is a CRM-side judgement about
+ * who to talk to, never sourced from the host, so it stays editable on synced
+ * rows.
+ */
+declare const HOST_OWNED_COMPANY_FIELDS: readonly ["domain", "name", "email", "phone"];
+type HostOwnedContactField = (typeof HOST_OWNED_CONTACT_FIELDS)[number];
+type HostOwnedCompanyField = (typeof HOST_OWNED_COMPANY_FIELDS)[number];
+/** The subset of a record this module needs to make its decision. */
+interface SourcedRecord {
+  sourceRef?: string | null;
+}
+/**
+ * True when the record is owned by a host view rather than by the CRM.
+ *
+ * Deliberately keyed on `sourceRef` and not `entityRole`: `entityRole` is a
+ * mapping label that can be absent on a synced row, while `sourceRef` is the
+ * identity the sync engine reconciles against and is set for exactly the rows
+ * sync will rewrite.
+ */
+export declare function isHostOwned(record: SourcedRecord): boolean;
+/**
+ * Host-owned contact fields this patch would change, or `[]` when the patch is
+ * allowed. Callers turn a non-empty result into a 400 naming the fields.
+ */
+export declare function rejectedContactFields(contact: SourcedRecord, patch: Readonly<Record<string, unknown>>): HostOwnedContactField[];
+/** Host-owned company fields this patch would change, or `[]`. */
+export declare function rejectedCompanyFields(company: SourcedRecord, patch: Readonly<Record<string, unknown>>): HostOwnedCompanyField[];
+/**
+ * The message shown when a write is refused. Names the fields and says where
+ * they come from, so the reason is actionable rather than a bare "forbidden".
+ */
+export declare function hostOwnedFieldMessage(fields: readonly string[]): string;
+//#endregion
 //#region src/projection-cardinality.d.ts
-declare function joinFansOut(join: ProjectionJoin, joinTable: DiscoveredSchemaTable): boolean;
+export declare function joinFansOut(join: ProjectionJoin, joinTable: DiscoveredSchemaTable): boolean;
 /** Every join in the projection that can multiply rows. */
-declare function fanOutJoins(projection: ProjectionMapping, tablesByName: Map<string, DiscoveredSchemaTable>): ProjectionJoin[];
+export declare function fanOutJoins(projection: ProjectionMapping, tablesByName: Map<string, DiscoveredSchemaTable>): ProjectionJoin[];
 //#endregion
 //#region src/projection-sql.d.ts
 /**
@@ -24,7 +91,7 @@ declare function fanOutJoins(projection: ProjectionMapping, tablesByName: Map<st
  * deterministic and injection-safe.
  */
 /** Quote a single identifier part, escaping embedded double-quotes. */
-declare function quoteIdent(name: string): string;
+export declare function quoteIdent(name: string): string;
 /**
  * The identity expression. Composite identities concatenate their parts with
  * `::`; validation guarantees every part is NOT NULL and non-text, which is
@@ -35,14 +102,14 @@ declare function quoteIdent(name: string): string;
  * also orders and keyset-paginates by it. Sharing one definition is what keeps
  * a pushed row's `id` identical to the one the view would have produced.
  */
-declare function compileProjectionIdentity(projection: ProjectionMapping, basePkColumn: string): string;
-declare function compileProjectionSelect(projection: ProjectionMapping, basePkColumn: string): {
+export declare function compileProjectionIdentity(projection: ProjectionMapping, basePkColumn: string): string;
+export declare function compileProjectionSelect(projection: ProjectionMapping, basePkColumn: string): {
   columns: string[];
   selectItems: string[];
 };
-declare function compileProjectionJoins(projection: ProjectionMapping): string[];
+export declare function compileProjectionJoins(projection: ProjectionMapping): string[];
 /** `FROM <baseTable> AS "base"` — the alias every ref resolves against. */
-declare function compileProjectionFrom(projection: ProjectionMapping): string;
+export declare function compileProjectionFrom(projection: ProjectionMapping): string;
 /**
  * Hard ceiling on preview rows, regardless of what a caller asks for.
  *
@@ -50,7 +117,7 @@ declare function compileProjectionFrom(projection: ProjectionMapping): string;
  * as often as they like, so the cap belongs beside the query rather than in
  * whichever caller happens to be passing a limit today.
  */
-declare const PREVIEW_MAX_ROWS = 50;
+export declare const PREVIEW_MAX_ROWS = 50;
 /**
  * One SELECT reading a few rows through an UNSAVED projection, for the derived
  * object builder's preview.
@@ -66,7 +133,7 @@ declare const PREVIEW_MAX_ROWS = 50;
  * reads `row[token]`; a preview is read by a person, in a table whose headers
  * are the field names they just typed.
  */
-declare function compileProjectionPreview(projection: ProjectionMapping, limit: number): string;
+export declare function compileProjectionPreview(projection: ProjectionMapping, limit: number): string;
 //#endregion
 //#region src/projection-validate.d.ts
 /**
@@ -89,12 +156,12 @@ declare function compileProjectionPreview(projection: ProjectionMapping, limit:
  *
  * Rejecting an unresolvable column closes the last two together.
  */
-declare function validateProjectionFilter(filter: FilterExpr | undefined, projection: ProjectionMapping, schema: DiscoveredSchemaTable[], base: string): ConfigValidationError[];
+export 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.
  */
-declare function validateProjection(projection: ProjectionMapping, schema: DiscoveredSchemaTable[], base: string): ConfigValidationError[];
+export declare function validateProjection(projection: ProjectionMapping, schema: DiscoveredSchemaTable[], base: string): ConfigValidationError[];
 //#endregion
 //#region src/schema-meta.d.ts
 /**
@@ -105,12 +172,12 @@ declare function validateProjection(projection: ProjectionMapping, schema: Disco
  * projection validation fail closed: we cannot prove a join is many-to-one, so
  * we refuse to compile it rather than guess.
  */
-declare function columnMetaFor(table: DiscoveredSchemaTable, column: string): DiscoveredColumnMeta | undefined;
+export declare function columnMetaFor(table: DiscoveredSchemaTable, column: string): DiscoveredColumnMeta | undefined;
 /**
  * Every primary-key column. More than one entry means a composite PK, which is
  * why `base_pk` identity is rejected for such tables.
  */
-declare function primaryKeyColumns(table: DiscoveredSchemaTable): string[];
+export declare function primaryKeyColumns(table: DiscoveredSchemaTable): string[];
 /**
  * Do `columns` contain every column of at least one unique key on `table`?
  *
@@ -118,7 +185,7 @@ declare function primaryKeyColumns(table: DiscoveredSchemaTable): string[];
  * joined table matches at most one row per base row; one that does not can
  * match many.
  */
-declare function coversUniqueKey(table: DiscoveredSchemaTable, columns: string[]): boolean;
+export declare function coversUniqueKey(table: DiscoveredSchemaTable, columns: string[]): boolean;
 /**
  * A discovered table whose enrichment metadata is known to be present.
  *
@@ -142,7 +209,7 @@ type RichMetaTable = DiscoveredSchemaTable & {
  * 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;
+export declare function hasRichMeta(table: DiscoveredSchemaTable): table is RichMetaTable;
 //#endregion
 //#region src/slug.d.ts
 /**
@@ -171,7 +238,7 @@ declare function hasRichMeta(table: DiscoveredSchemaTable): table is RichMetaTab
  * `"2024-invoices"` for `"2024 Invoices"`. Callers that need an
  * acceptance-guaranteed identifier want `toObjectTypeSlug`.
  */
-declare function slugify(value: string): string;
+export declare function slugify(value: string): string;
 /**
  * A slug the server will accept, derived from a display name.
  *
@@ -193,7 +260,7 @@ declare function slugify(value: string): string;
  * 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;
+export 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";
@@ -214,7 +281,7 @@ interface EvaluableRule {
  * 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;
+export 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.
  *
@@ -229,6 +296,6 @@ declare function matchesCondition(condition: Condition, fields: Record<string, s
  * 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;
+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 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, REQUIRED_FIELDS, 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, missingRequiredFields, primaryKeyColumns, projectionFields, projectionSchema, quoteIdent, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, requiredFieldsFor, runSync, slugify, toObjectTypeSlug, validateEntitiesConfig, validateProjection, validateProjectionFilter };
+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 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 };

package/dist/index.mjs

@@ -1,12 +1,90 @@
 import { authCustom } from "./auth-adapter.mjs";
 import { i as projectionSchema, n as PROJECTION_KEY_PATTERN, r as identityRefs, t as BASE_REF } from "./projection-SCNrLJMV.mjs";
 import { i as primaryKeyColumns, n as coversUniqueKey, r as hasRichMeta, t as columnMetaFor } from "./schema-meta-Ac7938mT.mjs";
-import { _ as validateProjection, a as MATERIALIZING_CONCEPTS, b as joinFansOut, c as defineClivlyConfig, d as missingRequiredFields, f as projectionFields, g as validateEntitiesConfig, h as requiredFieldsFor, i as ClivlyConfigError, l as entitiesConfigSchema, m as relationshipsSchema, n as CRM_CONCEPTS, o as REQUIRED_FIELDS, p as relationshipSchema, t as CANONICAL_FIELDS, u as filterSchema, v as validateProjectionFilter, y as fanOutJoins } from "./entity-config-BTAJe1Zj.mjs";
+import { _ as validateProjection, a as MATERIALIZING_CONCEPTS, b as joinFansOut, c as defineClivlyConfig, d as missingRequiredFields, f as projectionFields, g as validateEntitiesConfig, h as requiredFieldsFor, i as ClivlyConfigError, l as entitiesConfigSchema, m as relationshipsSchema, n as CRM_CONCEPTS, o as REQUIRED_FIELDS, p as relationshipSchema, t as CANONICAL_FIELDS, u as filterSchema, v as validateProjectionFilter, y as fanOutJoins } from "./entity-config-C0rtu-K_.mjs";
 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 { OPEN_STAGE_TYPE, isClosedStageType } from "./types.mjs";
+//#region src/host-owned-fields.ts
+/**
+* Which fields a CRM record lets a user edit.
+*
+* A record synced from the host app carries a `sourceRef`. Its identity fields
+* are rewritten from the host view on every sync run, so an edit to one would
+* be silently reverted minutes later — the user sees their change accepted,
+* then gone, with nothing explaining why. That is worse than refusing it.
+*
+* So host-owned fields are rejected at the API, not merely disabled in the UI:
+* the UI is not the security boundary, and the SDK and any future public API
+* reach the same routers.
+*
+* Records created inside the CRM have no `sourceRef` and are fully editable —
+* nothing else owns them.
+*
+* This is the cheap half of a capability matrix. It answers "may a user write
+* this?" but not "may the sync engine write this?", which stays implicit
+* because sync bypasses these routers entirely. An override model (the
+* `stageOverrideAt` pattern on `crm_deals`) can replace this later without
+* changing callers.
+*/
+/** Contact fields the host view owns when the row is synced. */
+const HOST_OWNED_CONTACT_FIELDS = ["email", "name"];
+/**
+* Company fields the host view owns when the row is synced.
+*
+* `email` and `phone` joined this list in the same change that made them
+* mappable (migration 0048). They are not identity fields, but ownership here
+* follows what sync rewrites, not what feels identity-like: both flow from the
+* host view on every run, exactly as `email` does for contacts above. Widening
+* `CANONICAL_FIELDS.company` without widening this list is the specific bug
+* this module's doc comment calls worse than refusing the edit.
+*
+* `primaryContactId` is deliberately absent: it is a CRM-side judgement about
+* who to talk to, never sourced from the host, so it stays editable on synced
+* rows.
+*/
+const HOST_OWNED_COMPANY_FIELDS = [
+	"domain",
+	"name",
+	"email",
+	"phone"
+];
+/**
+* True when the record is owned by a host view rather than by the CRM.
+*
+* Deliberately keyed on `sourceRef` and not `entityRole`: `entityRole` is a
+* mapping label that can be absent on a synced row, while `sourceRef` is the
+* identity the sync engine reconciles against and is set for exactly the rows
+* sync will rewrite.
+*/
+function isHostOwned(record) {
+	return Boolean(record.sourceRef);
+}
+function rejectedFields(record, patch, owned) {
+	if (!isHostOwned(record)) return [];
+	return owned.filter((field) => patch[field] !== void 0);
+}
+/**
+* Host-owned contact fields this patch would change, or `[]` when the patch is
+* allowed. Callers turn a non-empty result into a 400 naming the fields.
+*/
+function rejectedContactFields(contact, patch) {
+	return rejectedFields(contact, patch, HOST_OWNED_CONTACT_FIELDS);
+}
+/** Host-owned company fields this patch would change, or `[]`. */
+function rejectedCompanyFields(company, patch) {
+	return rejectedFields(company, patch, HOST_OWNED_COMPANY_FIELDS);
+}
+/**
+* The message shown when a write is refused. Names the fields and says where
+* they come from, so the reason is actionable rather than a bare "forbidden".
+*/
+function hostOwnedFieldMessage(fields) {
+	return `The ${fields.join(", ")} ${fields.length > 1 ? "fields are" : "field is"} synced from your app and cannot be edited here. Change it in your app and it will update on the next sync.`;
+}
+//#endregion
 //#region src/slug.ts
 /**
 * The one `slugify`.
@@ -150,4 +228,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, coversUniqueKey, defineClivlyConfig, entitiesConfigSchema, evaluateStage, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, isClosedStageType, joinFansOut, mappingsToEntitiesConfig, matchesCondition, missingRequiredFields, primaryKeyColumns, projectionFields, projectionSchema, quoteIdent, reconcile, 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, 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 };

package/dist/integration-state.d.cts

@@ -1,20 +1,20 @@
 //#region src/integration-state.d.ts
-declare const INTEGRATION_STEPS: readonly ["credential", "application", "schema", "mapping", "trigger", "sync", "widget"];
-type StepId = (typeof INTEGRATION_STEPS)[number];
+export declare const INTEGRATION_STEPS: readonly ["credential", "application", "schema", "mapping", "trigger", "sync", "widget"];
+export type StepId = (typeof INTEGRATION_STEPS)[number];
 /** `blocked` means "prerequisite unmet", never "broken" — see C-19. */
-type StepState = "done" | "active" | "blocked" | "failed" | "skipped";
-type IntegrationStatus = "not_configured" | "sdk_installed" | "awaiting_connection" | "connected" | "schema_discovered" | "mapping_required" | "trigger_required" | "ready_to_sync" | "syncing" | "healthy" | "warning" | "error" |
+export type StepState = "done" | "active" | "blocked" | "failed" | "skipped";
+export type IntegrationStatus = "not_configured" | "sdk_installed" | "awaiting_connection" | "connected" | "schema_discovered" | "mapping_required" | "trigger_required" | "ready_to_sync" | "syncing" | "healthy" | "warning" | "error" |
 /**
  * @deprecated No longer derived. Liveness is its own dimension — read
  * `ConnectionHealth` from `deriveLiveness`. Setup progress does not move
  * backwards just because an app stopped running.
  */
 "disconnected";
-declare const INTEGRATION_STEP_LABELS: Record<StepId, string>;
+export declare const INTEGRATION_STEP_LABELS: Record<StepId, string>;
 /** Each step's prerequisites. Ordering is enforced by a test, not convention. */
-declare const STEP_PREREQUISITES: Record<StepId, readonly StepId[]>;
-declare function stepIndex(id: StepId): number;
-interface RunFact {
+export declare const STEP_PREREQUISITES: Record<StepId, readonly StepId[]>;
+export declare function stepIndex(id: StepId): number;
+export interface RunFact {
   at: number;
   message?: string;
   ok: boolean;
@@ -36,8 +36,8 @@ interface RunFact {
  * such a host to `local_dev` would file a production box's faults under local
  * development, where nobody would look for them.
  */
-type HostEnvironment = "local_dev" | "preview" | "production" | "unknown";
-interface IntegrationFacts {
+export type HostEnvironment = "local_dev" | "preview" | "production" | "unknown";
+export interface IntegrationFacts {
   discoveredTableCount: number;
   /** The environment the app reported on its last heartbeat. */
   environment?: HostEnvironment | null;
@@ -95,12 +95,12 @@ interface IntegrationFacts {
   warnings: string[];
   widgetInstalled: boolean;
 }
-interface StepProblem {
+export interface StepProblem {
   code: string;
   fix: string;
   message: string;
 }
-interface IntegrationStep {
+export interface IntegrationStep {
   blockedBy: StepId | null;
   evidence: string | null;
   id: StepId;
@@ -108,10 +108,10 @@ interface IntegrationStep {
   problem: StepProblem | null;
   state: StepState;
 }
-declare function formatAge(ms: number): string;
+export declare function formatAge(ms: number): string;
 /** The cadence `createClivlySDK` uses when the host app configures none. */
-declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 60000;
-type ConnectionHealth = "live" | "live_with_issues" | "stale" | "offline";
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 60000;
+export type ConnectionHealth = "live" | "live_with_issues" | "stale" | "offline";
 /**
  * Clivly's own answer to "is this app up", obtained by asking it rather than
  * waiting to be told.
@@ -121,15 +121,15 @@ type ConnectionHealth = "live" | "live_with_issues" | "stale" | "offline";
  * that answers `200`. Only silence — a timeout, a refused connection, DNS that
  * does not resolve — means offline.
  */
-interface ReachabilityProbe {
+export interface ReachabilityProbe {
   /** When Clivly performed the check. Probe results are cached, so this ages. */
   checkedAt: number;
   /** Did anything answer at the other end? */
   reachable: boolean;
 }
 /** Which algorithm decides whether this deployment is up. */
-type PresenceTransport = "websocket" | "http";
-type PresenceConnectionState = "connected" | "reconnecting" | "disconnected";
+export type PresenceTransport = "websocket" | "http";
+export type PresenceConnectionState = "connected" | "reconnecting" | "disconnected";
 /**
  * A deployment's connection state as its `PresenceRoom` last persisted it.
  *
@@ -138,13 +138,13 @@ type PresenceConnectionState = "connected" | "reconnecting" | "disconnected";
  * shown as live for 150 seconds and offline only after ten minutes, which is
  * the whole reason this transport exists.
  */
-interface DeploymentPresence {
+export interface DeploymentPresence {
   /** Sockets currently accepted in the room. */
   activeInstanceCount: number;
   connectionState: PresenceConnectionState;
   transport: PresenceTransport;
 }
-interface ConnectionLiveness {
+export interface ConnectionLiveness {
   /** `"8s ago"`, or `"No heartbeat yet"` when the app has never reported. */
   ageLabel: string;
   ageMs: number | null;
@@ -165,30 +165,30 @@ interface ConnectionLiveness {
  * negative — falls back to the SDK default rather than producing a window of
  * zero that would call every app offline.
  */
-declare function livenessWindows(intervalMs: number | null | undefined): {
+export declare function livenessWindows(intervalMs: number | null | undefined): {
   liveMs: number;
   staleMs: number;
 };
-declare function deriveLiveness(facts: IntegrationFacts): ConnectionLiveness;
+export declare function deriveLiveness(facts: IntegrationFacts): ConnectionLiveness;
 /**
  * Walk the ladder once. A step is `blocked` when an earlier step it needs has
  * not been satisfied — a prerequisite statement, not a verdict about this step
  * — and only the first unsatisfied step is `active`, so exactly one root cause
  * ever surfaces.
  */
-declare function resolveSteps(facts: IntegrationFacts): IntegrationStep[];
+export declare function resolveSteps(facts: IntegrationFacts): IntegrationStep[];
 /**
  * Collapse the ladder to the single status the surfaces switch on. This is the
  * setup dimension only: it answers how far configuration got, never whether the
  * app is up. Pair it with `deriveLiveness` for the second half of the picture.
  */
-declare function deriveStatus(steps: IntegrationStep[], facts: IntegrationFacts): IntegrationStatus;
-interface NextAction {
+export declare function deriveStatus(steps: IntegrationStep[], facts: IntegrationFacts): IntegrationStatus;
+export interface NextAction {
   command: string | null;
   envFile: string | null;
   label: string;
 }
-interface IntegrationState {
+export interface IntegrationState {
   /**
    * Is the app running right now. Deliberately alongside `status` rather than
    * folded into it: a surface must be able to say "setup reached mapping" and
@@ -205,14 +205,13 @@ interface IntegrationState {
  * dialog prints it too, and it must be the same string as the one the ladder
  * recommends — that pairing is what C-05 broke.
  */
-declare const INSTALL_COMMAND = "npx clivly init";
+export declare const INSTALL_COMMAND = "npx clivly init";
 /**
  * THE one producer of `next.command`. Six surfaces previously each invented
  * their own "run this next" string, and one of them named a read-only command
  * as the fix for a write problem (C-05). If you need a command for the
  * next-action slot, call this — do not write another one.
  */
-declare function nextAction(steps: IntegrationStep[], status: IntegrationStatus, liveness: ConnectionLiveness): NextAction | null;
-declare function computeIntegrationState(facts: IntegrationFacts): IntegrationState;
-//#endregion
-export { ConnectionHealth, ConnectionLiveness, DEFAULT_HEARTBEAT_INTERVAL_MS, DeploymentPresence, HostEnvironment, INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, IntegrationFacts, IntegrationState, IntegrationStatus, IntegrationStep, NextAction, PresenceConnectionState, PresenceTransport, ReachabilityProbe, RunFact, STEP_PREREQUISITES, StepId, StepProblem, StepState, computeIntegrationState, deriveLiveness, deriveStatus, formatAge, livenessWindows, nextAction, resolveSteps, stepIndex };
+export declare function nextAction(steps: IntegrationStep[], status: IntegrationStatus, liveness: ConnectionLiveness): NextAction | null;
+export declare function computeIntegrationState(facts: IntegrationFacts): IntegrationState;
+//#endregion

package/dist/integration-state.d.mts

@@ -1,20 +1,20 @@
 //#region src/integration-state.d.ts
-declare const INTEGRATION_STEPS: readonly ["credential", "application", "schema", "mapping", "trigger", "sync", "widget"];
-type StepId = (typeof INTEGRATION_STEPS)[number];
+export declare const INTEGRATION_STEPS: readonly ["credential", "application", "schema", "mapping", "trigger", "sync", "widget"];
+export type StepId = (typeof INTEGRATION_STEPS)[number];
 /** `blocked` means "prerequisite unmet", never "broken" — see C-19. */
-type StepState = "done" | "active" | "blocked" | "failed" | "skipped";
-type IntegrationStatus = "not_configured" | "sdk_installed" | "awaiting_connection" | "connected" | "schema_discovered" | "mapping_required" | "trigger_required" | "ready_to_sync" | "syncing" | "healthy" | "warning" | "error" |
+export type StepState = "done" | "active" | "blocked" | "failed" | "skipped";
+export type IntegrationStatus = "not_configured" | "sdk_installed" | "awaiting_connection" | "connected" | "schema_discovered" | "mapping_required" | "trigger_required" | "ready_to_sync" | "syncing" | "healthy" | "warning" | "error" |
 /**
  * @deprecated No longer derived. Liveness is its own dimension — read
  * `ConnectionHealth` from `deriveLiveness`. Setup progress does not move
  * backwards just because an app stopped running.
  */
 "disconnected";
-declare const INTEGRATION_STEP_LABELS: Record<StepId, string>;
+export declare const INTEGRATION_STEP_LABELS: Record<StepId, string>;
 /** Each step's prerequisites. Ordering is enforced by a test, not convention. */
-declare const STEP_PREREQUISITES: Record<StepId, readonly StepId[]>;
-declare function stepIndex(id: StepId): number;
-interface RunFact {
+export declare const STEP_PREREQUISITES: Record<StepId, readonly StepId[]>;
+export declare function stepIndex(id: StepId): number;
+export interface RunFact {
   at: number;
   message?: string;
   ok: boolean;
@@ -36,8 +36,8 @@ interface RunFact {
  * such a host to `local_dev` would file a production box's faults under local
  * development, where nobody would look for them.
  */
-type HostEnvironment = "local_dev" | "preview" | "production" | "unknown";
-interface IntegrationFacts {
+export type HostEnvironment = "local_dev" | "preview" | "production" | "unknown";
+export interface IntegrationFacts {
   discoveredTableCount: number;
   /** The environment the app reported on its last heartbeat. */
   environment?: HostEnvironment | null;
@@ -95,12 +95,12 @@ interface IntegrationFacts {
   warnings: string[];
   widgetInstalled: boolean;
 }
-interface StepProblem {
+export interface StepProblem {
   code: string;
   fix: string;
   message: string;
 }
-interface IntegrationStep {
+export interface IntegrationStep {
   blockedBy: StepId | null;
   evidence: string | null;
   id: StepId;
@@ -108,10 +108,10 @@ interface IntegrationStep {
   problem: StepProblem | null;
   state: StepState;
 }
-declare function formatAge(ms: number): string;
+export declare function formatAge(ms: number): string;
 /** The cadence `createClivlySDK` uses when the host app configures none. */
-declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 60000;
-type ConnectionHealth = "live" | "live_with_issues" | "stale" | "offline";
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 60000;
+export type ConnectionHealth = "live" | "live_with_issues" | "stale" | "offline";
 /**
  * Clivly's own answer to "is this app up", obtained by asking it rather than
  * waiting to be told.
@@ -121,15 +121,15 @@ type ConnectionHealth = "live" | "live_with_issues" | "stale" | "offline";
  * that answers `200`. Only silence — a timeout, a refused connection, DNS that
  * does not resolve — means offline.
  */
-interface ReachabilityProbe {
+export interface ReachabilityProbe {
   /** When Clivly performed the check. Probe results are cached, so this ages. */
   checkedAt: number;
   /** Did anything answer at the other end? */
   reachable: boolean;
 }
 /** Which algorithm decides whether this deployment is up. */
-type PresenceTransport = "websocket" | "http";
-type PresenceConnectionState = "connected" | "reconnecting" | "disconnected";
+export type PresenceTransport = "websocket" | "http";
+export type PresenceConnectionState = "connected" | "reconnecting" | "disconnected";
 /**
  * A deployment's connection state as its `PresenceRoom` last persisted it.
  *
@@ -138,13 +138,13 @@ type PresenceConnectionState = "connected" | "reconnecting" | "disconnected";
  * shown as live for 150 seconds and offline only after ten minutes, which is
  * the whole reason this transport exists.
  */
-interface DeploymentPresence {
+export interface DeploymentPresence {
   /** Sockets currently accepted in the room. */
   activeInstanceCount: number;
   connectionState: PresenceConnectionState;
   transport: PresenceTransport;
 }
-interface ConnectionLiveness {
+export interface ConnectionLiveness {
   /** `"8s ago"`, or `"No heartbeat yet"` when the app has never reported. */
   ageLabel: string;
   ageMs: number | null;
@@ -165,30 +165,30 @@ interface ConnectionLiveness {
  * negative — falls back to the SDK default rather than producing a window of
  * zero that would call every app offline.
  */
-declare function livenessWindows(intervalMs: number | null | undefined): {
+export declare function livenessWindows(intervalMs: number | null | undefined): {
   liveMs: number;
   staleMs: number;
 };
-declare function deriveLiveness(facts: IntegrationFacts): ConnectionLiveness;
+export declare function deriveLiveness(facts: IntegrationFacts): ConnectionLiveness;
 /**
  * Walk the ladder once. A step is `blocked` when an earlier step it needs has
  * not been satisfied — a prerequisite statement, not a verdict about this step
  * — and only the first unsatisfied step is `active`, so exactly one root cause
  * ever surfaces.
  */
-declare function resolveSteps(facts: IntegrationFacts): IntegrationStep[];
+export declare function resolveSteps(facts: IntegrationFacts): IntegrationStep[];
 /**
  * Collapse the ladder to the single status the surfaces switch on. This is the
  * setup dimension only: it answers how far configuration got, never whether the
  * app is up. Pair it with `deriveLiveness` for the second half of the picture.
  */
-declare function deriveStatus(steps: IntegrationStep[], facts: IntegrationFacts): IntegrationStatus;
-interface NextAction {
+export declare function deriveStatus(steps: IntegrationStep[], facts: IntegrationFacts): IntegrationStatus;
+export interface NextAction {
   command: string | null;
   envFile: string | null;
   label: string;
 }
-interface IntegrationState {
+export interface IntegrationState {
   /**
    * Is the app running right now. Deliberately alongside `status` rather than
    * folded into it: a surface must be able to say "setup reached mapping" and
@@ -205,14 +205,13 @@ interface IntegrationState {
  * dialog prints it too, and it must be the same string as the one the ladder
  * recommends — that pairing is what C-05 broke.
  */
-declare const INSTALL_COMMAND = "npx clivly init";
+export declare const INSTALL_COMMAND = "npx clivly init";
 /**
  * THE one producer of `next.command`. Six surfaces previously each invented
  * their own "run this next" string, and one of them named a read-only command
  * as the fix for a write problem (C-05). If you need a command for the
  * next-action slot, call this — do not write another one.
  */
-declare function nextAction(steps: IntegrationStep[], status: IntegrationStatus, liveness: ConnectionLiveness): NextAction | null;
-declare function computeIntegrationState(facts: IntegrationFacts): IntegrationState;
-//#endregion
-export { ConnectionHealth, ConnectionLiveness, DEFAULT_HEARTBEAT_INTERVAL_MS, DeploymentPresence, HostEnvironment, INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, IntegrationFacts, IntegrationState, IntegrationStatus, IntegrationStep, NextAction, PresenceConnectionState, PresenceTransport, ReachabilityProbe, RunFact, STEP_PREREQUISITES, StepId, StepProblem, StepState, computeIntegrationState, deriveLiveness, deriveStatus, formatAge, livenessWindows, nextAction, resolveSteps, stepIndex };
+export declare function nextAction(steps: IntegrationStep[], status: IntegrationStatus, liveness: ConnectionLiveness): NextAction | null;
+export declare function computeIntegrationState(facts: IntegrationFacts): IntegrationState;
+//#endregion