clivly 0.9.4 → 0.9.6

package/{internal-o2M7FGlR.d.mts → internal-CvlFk3KC.d.mts}

@@ -27,10 +27,62 @@ declare function emptyProjectionDraft(baseTable: string): ProjectionDraft;
  * 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. */
+/**
+ * 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;
@@ -60,9 +112,37 @@ declare function quoteIdent(name: string): string;
  * 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): {
+  columns: string[];
+  selectItems: string[];
+};
 declare function compileProjectionJoins(projection: ProjectionMapping): string[];
 /** `FROM <baseTable> AS "base"` — the alias every ref resolves against. */
 declare function compileProjectionFrom(projection: ProjectionMapping): string;
+/**
+ * Hard ceiling on preview rows, regardless of what a caller asks for.
+ *
+ * A preview runs against a production database from a button a user can click
+ * 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;
+/**
+ * One SELECT reading a few rows through an UNSAVED projection, for the derived
+ * object builder's preview.
+ *
+ * Lives here, beside the view compiler, because both sides of the round trip
+ * need the identical statement: an embedded org runs it against its own
+ * database from `@clivly.com/api`, and a cloud org's host app runs it from
+ * `@clivly/sdk`. Two copies would be free to disagree about what the user is
+ * being shown, which is the whole value of a preview.
+ *
+ * Columns are aliased by FIELD NAME, not by ref token. That is the deliberate
+ * difference from the push source, which aliases by token because cloud ingest
+ * 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;
 //#endregion
 //#region ../core/src/projection-validate.d.ts
 /**
@@ -97,4 +177,4 @@ declare function coversUniqueKey(table: DiscoveredSchemaTable, columns: string[]
 /** Is this table's payload rich enough to validate a projection against? */
 declare function hasRichMeta(table: DiscoveredSchemaTable): boolean;
 //#endregion
-export { joinFansOut as _, validateProjection as a, compileProjectionJoins as c, describeCardinality as d, draftErrors as f, fanOutJoins as g, suggestJoinConditions as h, primaryKeyColumns as i, quoteIdent as l, emptyProjectionDraft as m, coversUniqueKey as n, compileProjectionFrom as o, draftToProjection as p, hasRichMeta as r, compileProjectionIdentity as s, columnMetaFor as t, ProjectionDraft as u };
+export { fanOutJoins as C, suggestJoinConditions as S, draftErrors as _, validateProjection as a, emptyProjectionDraft as b, compileProjectionIdentity as c, compileProjectionSelect as d, quoteIdent as f, describeCardinality as g, addDraftJoin as h, primaryKeyColumns as i, compileProjectionJoins as l, ProjectionDraft as m, coversUniqueKey as n, PREVIEW_MAX_ROWS as o, DraftRefOption as p, hasRichMeta as r, compileProjectionFrom as s, columnMetaFor as t, compileProjectionPreview as u, draftRefOptions as v, joinFansOut as w, removeDraftJoin as x, draftToProjection as y };

package/{internal-wCXSELDN.d.cts → internal-DGUOLQAq.d.cts}

@@ -27,10 +27,62 @@ declare function emptyProjectionDraft(baseTable: string): ProjectionDraft;
  * 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. */
+/**
+ * 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;
@@ -60,9 +112,37 @@ declare function quoteIdent(name: string): string;
  * 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): {
+  columns: string[];
+  selectItems: string[];
+};
 declare function compileProjectionJoins(projection: ProjectionMapping): string[];
 /** `FROM <baseTable> AS "base"` — the alias every ref resolves against. */
 declare function compileProjectionFrom(projection: ProjectionMapping): string;
+/**
+ * Hard ceiling on preview rows, regardless of what a caller asks for.
+ *
+ * A preview runs against a production database from a button a user can click
+ * 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;
+/**
+ * One SELECT reading a few rows through an UNSAVED projection, for the derived
+ * object builder's preview.
+ *
+ * Lives here, beside the view compiler, because both sides of the round trip
+ * need the identical statement: an embedded org runs it against its own
+ * database from `@clivly.com/api`, and a cloud org's host app runs it from
+ * `@clivly/sdk`. Two copies would be free to disagree about what the user is
+ * being shown, which is the whole value of a preview.
+ *
+ * Columns are aliased by FIELD NAME, not by ref token. That is the deliberate
+ * difference from the push source, which aliases by token because cloud ingest
+ * 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;
 //#endregion
 //#region ../core/src/projection-validate.d.ts
 /**
@@ -97,4 +177,4 @@ declare function coversUniqueKey(table: DiscoveredSchemaTable, columns: string[]
 /** Is this table's payload rich enough to validate a projection against? */
 declare function hasRichMeta(table: DiscoveredSchemaTable): boolean;
 //#endregion
-export { joinFansOut as _, validateProjection as a, compileProjectionJoins as c, describeCardinality as d, draftErrors as f, fanOutJoins as g, suggestJoinConditions as h, primaryKeyColumns as i, quoteIdent as l, emptyProjectionDraft as m, coversUniqueKey as n, compileProjectionFrom as o, draftToProjection as p, hasRichMeta as r, compileProjectionIdentity as s, columnMetaFor as t, ProjectionDraft as u };
+export { fanOutJoins as C, suggestJoinConditions as S, draftErrors as _, validateProjection as a, emptyProjectionDraft as b, compileProjectionIdentity as c, compileProjectionSelect as d, quoteIdent as f, describeCardinality as g, addDraftJoin as h, primaryKeyColumns as i, compileProjectionJoins as l, ProjectionDraft as m, coversUniqueKey as n, PREVIEW_MAX_ROWS as o, DraftRefOption as p, hasRichMeta as r, compileProjectionFrom as s, columnMetaFor as t, compileProjectionPreview as u, draftRefOptions as v, joinFansOut as w, removeDraftJoin as x, draftToProjection as y };

package/internal-entity-config.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config-7sGCk_nw.cjs");
+const require_entity_config = require("./entity-config-DE30_RpU.cjs");
 exports.CANONICAL_FIELDS = require_entity_config.CANONICAL_FIELDS;
 exports.CRM_CONCEPTS = require_entity_config.CRM_CONCEPTS;
 exports.CUSTOM_CONCEPT = require_entity_config.CUSTOM_CONCEPT;

package/internal-entity-config.mjs

@@ -1,2 +1,2 @@
-import { a as MATERIALIZING_CONCEPTS, c as entitiesConfigSchema, d as relationshipSchema, f as relationshipsSchema, i as ClivlyConfigError, l as filterSchema, n as CRM_CONCEPTS, o as customObjectDeclarations, p as validateEntitiesConfig, r as CUSTOM_CONCEPT, s as defineClivlyConfig, t as CANONICAL_FIELDS, u as projectionFields } from "./entity-config-B74SPOUZ.mjs";
+import { a as MATERIALIZING_CONCEPTS, c as entitiesConfigSchema, d as relationshipSchema, f as relationshipsSchema, i as ClivlyConfigError, l as filterSchema, n as CRM_CONCEPTS, o as customObjectDeclarations, p as validateEntitiesConfig, r as CUSTOM_CONCEPT, s as defineClivlyConfig, t as CANONICAL_FIELDS, u as projectionFields } from "./entity-config-CusbTOJ1.mjs";
 export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, MATERIALIZING_CONCEPTS, customObjectDeclarations, defineClivlyConfig, entitiesConfigSchema, filterSchema, projectionFields, relationshipSchema, relationshipsSchema, validateEntitiesConfig };

package/internal-entity-heuristics.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config-7sGCk_nw.cjs");
+const require_entity_config = require("./entity-config-DE30_RpU.cjs");
 const require_mapping_score = require("./mapping-score-CaB3F4Uu.cjs");
 //#region ../core/src/entity-heuristics.ts
 const TARGET_CONCEPTS = [

package/internal-entity-heuristics.mjs

@@ -1,4 +1,4 @@
-import { a as MATERIALIZING_CONCEPTS } from "./entity-config-B74SPOUZ.mjs";
+import { a as MATERIALIZING_CONCEPTS } from "./entity-config-CusbTOJ1.mjs";
 import { a as W, c as isTextLike, i as RELATIONSHIP_TIERS, l as isTimestampLike, n as CONCEPT_TIERS, o as isAmbiguous, r as FIELD_TIERS, s as isNumericLike, u as tierFor } from "./mapping-score-C68uAqGB.mjs";
 //#region ../core/src/entity-heuristics.ts
 const TARGET_CONCEPTS = [

package/internal-mappings-config.cjs

@@ -1,4 +1,4 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_mappings_config = require("./mappings-config-CLyEg0sf.cjs");
+const require_mappings_config = require("./mappings-config-CjCmT-aU.cjs");
 exports.entitiesToMappings = require_mappings_config.entitiesToMappings;
 exports.mappingsToEntitiesConfig = require_mappings_config.mappingsToEntitiesConfig;

package/internal-mappings-config.mjs

@@ -1,2 +1,2 @@
-import { n as mappingsToEntitiesConfig, t as entitiesToMappings } from "./mappings-config-DQS_s4dg.mjs";
+import { n as mappingsToEntitiesConfig, t as entitiesToMappings } from "./mappings-config-7qQ47p9K.mjs";
 export { entitiesToMappings, mappingsToEntitiesConfig };

package/internal-sync-engine.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sync_engine = require("./sync-engine-C4A5jgA4.cjs");
+const require_sync_engine = require("./sync-engine-BLgwLpR6.cjs");
 exports.computeSampleWarnings = require_sync_engine.computeSampleWarnings;
 exports.previewSync = require_sync_engine.previewSync;
 exports.reconcile = require_sync_engine.reconcile;

package/internal-sync-engine.mjs

@@ -1,2 +1,2 @@
-import { i as runSync, n as previewSync, r as reconcile, t as computeSampleWarnings } from "./sync-engine-Dt5QQSKO.mjs";
+import { i as runSync, n as previewSync, r as reconcile, t as computeSampleWarnings } from "./sync-engine-B_IzoUSx.mjs";
 export { computeSampleWarnings, previewSync, reconcile, runSync };

package/internal-view-compiler.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_view_compiler = require("./view-compiler-B5nDal14.cjs");
+const require_view_compiler = require("./view-compiler-BHI5E4QI.cjs");
 exports.DEFAULT_VIEW_PREFIX = require_view_compiler.DEFAULT_VIEW_PREFIX;
 exports.compileEntityView = require_view_compiler.compileEntityView;
 exports.compileEntityViews = require_view_compiler.compileEntityViews;

package/internal-view-compiler.mjs

@@ -1,2 +1,2 @@
-import { a as explainViewExecutionError, i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-CSYwEWf5.mjs";
+import { a as explainViewExecutionError, i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-D_6gfXFr.mjs";
 export { DEFAULT_VIEW_PREFIX, compileEntityView, compileEntityViews, explainEntitiesConfig, explainViewExecutionError };

package/internal.cjs

@@ -1,19 +1,21 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_projection = require("./projection-Dz6_i1-w.cjs");
-const require_entity_config = require("./entity-config-7sGCk_nw.cjs");
-const require_mappings_config = require("./mappings-config-CLyEg0sf.cjs");
+const require_projection = require("./projection-DEwL-D8R.cjs");
+const require_entity_config = require("./entity-config-DE30_RpU.cjs");
+const require_mappings_config = require("./mappings-config-CjCmT-aU.cjs");
 const require_auth_adapter = require("./auth-adapter-CiEXcweZ.cjs");
 const require_mapping_form = require("./mapping-form-BpfON_ME.cjs");
-const require_internal = require("./internal-DqduZU3l.cjs");
-const require_projection_sql = require("./projection-sql-Cl1qIn8m.cjs");
-const require_view_compiler = require("./view-compiler-B5nDal14.cjs");
-const require_sync_engine = require("./sync-engine-C4A5jgA4.cjs");
+const require_internal = require("./internal-BQ47iN6f.cjs");
+const require_projection_sql = require("./projection-sql-iHy-Cx6V.cjs");
+const require_view_compiler = require("./view-compiler-BHI5E4QI.cjs");
+const require_sync_engine = require("./sync-engine-BLgwLpR6.cjs");
 exports.BASE_REF = require_projection.BASE_REF;
 exports.CANONICAL_FIELDS = require_entity_config.CANONICAL_FIELDS;
 exports.CRM_CONCEPTS = require_entity_config.CRM_CONCEPTS;
 exports.ClivlyConfigError = require_entity_config.ClivlyConfigError;
 exports.DEFAULT_VIEW_PREFIX = require_view_compiler.DEFAULT_VIEW_PREFIX;
 exports.MATERIALIZING_CONCEPTS = require_entity_config.MATERIALIZING_CONCEPTS;
+exports.PREVIEW_MAX_ROWS = require_projection_sql.PREVIEW_MAX_ROWS;
+exports.addDraftJoin = require_internal.addDraftJoin;
 exports.authCustom = require_auth_adapter.authCustom;
 exports.buildFilterFromDiscriminator = require_mapping_form.buildFilterFromDiscriminator;
 exports.buildRelationships = require_mapping_form.buildRelationships;
@@ -23,10 +25,13 @@ exports.compileEntityViews = require_view_compiler.compileEntityViews;
 exports.compileProjectionFrom = require_projection_sql.compileProjectionFrom;
 exports.compileProjectionIdentity = require_projection_sql.compileProjectionIdentity;
 exports.compileProjectionJoins = require_projection_sql.compileProjectionJoins;
+exports.compileProjectionPreview = require_projection_sql.compileProjectionPreview;
+exports.compileProjectionSelect = require_projection_sql.compileProjectionSelect;
 exports.coversUniqueKey = require_entity_config.coversUniqueKey;
 exports.defineClivlyConfig = require_entity_config.defineClivlyConfig;
 exports.describeCardinality = require_internal.describeCardinality;
 exports.draftErrors = require_internal.draftErrors;
+exports.draftRefOptions = require_internal.draftRefOptions;
 exports.draftToProjection = require_internal.draftToProjection;
 exports.emptyProjectionDraft = require_internal.emptyProjectionDraft;
 exports.entitiesConfigSchema = require_entity_config.entitiesConfigSchema;
@@ -44,6 +49,7 @@ exports.reconcile = require_sync_engine.reconcile;
 exports.relationshipSchema = require_entity_config.relationshipSchema;
 exports.relationshipViaSignature = require_mapping_form.relationshipViaSignature;
 exports.relationshipsSchema = require_entity_config.relationshipsSchema;
+exports.removeDraftJoin = require_internal.removeDraftJoin;
 exports.runSync = require_sync_engine.runSync;
 exports.suggestJoinConditions = require_internal.suggestJoinConditions;
 exports.validateEntitiesConfig = require_entity_config.validateEntitiesConfig;

package/internal.d.cts

@@ -7,5 +7,5 @@ import { i as mappingsToEntitiesConfig, t as EntityMappingRow } from "./mappings
 import { a as compileEntityView, i as ExplainResult, n as CompiledView, o as compileEntityViews, r as DEFAULT_VIEW_PREFIX, s as explainEntitiesConfig, t as CompileOptions } from "./view-compiler-CmEdAMwj.cjs";
 import { c as SyncResult, f as reconcile, l as SyncStore, n as MirrorRecord, o as SourceRow, p as runSync, r as PersistAction, s as SyncAction, t as EntitySyncResult } from "./sync-engine-BG2O1an2.cjs";
 import { a as IntegrationStep, c as StepProblem, i as IntegrationStatus, l as StepState, n as IntegrationFacts, o as NextAction, r as IntegrationState, s as StepId, t as ConnectionLiveness } from "./integration-state-BK-riZnm.cjs";
-import { _ as joinFansOut, a as validateProjection, c as compileProjectionJoins, d as describeCardinality, f as draftErrors, g as fanOutJoins, h as suggestJoinConditions, i as primaryKeyColumns, l as quoteIdent, m as emptyProjectionDraft, n as coversUniqueKey, o as compileProjectionFrom, p as draftToProjection, r as hasRichMeta, s as compileProjectionIdentity, t as columnMetaFor, u as ProjectionDraft } from "./internal-wCXSELDN.cjs";
-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 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, 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, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, quoteIdent, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };
+import { C as fanOutJoins, S as suggestJoinConditions, _ as draftErrors, a as validateProjection, b as emptyProjectionDraft, c as compileProjectionIdentity, d as compileProjectionSelect, f as quoteIdent, g as describeCardinality, h as addDraftJoin, i as primaryKeyColumns, l as compileProjectionJoins, m as ProjectionDraft, n as coversUniqueKey, o as PREVIEW_MAX_ROWS, p as DraftRefOption, r as hasRichMeta, s as compileProjectionFrom, t as columnMetaFor, u as compileProjectionPreview, v as draftRefOptions, w as joinFansOut, x as removeDraftJoin, y as draftToProjection } from "./internal-DGUOLQAq.cjs";
+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 };

package/internal.d.mts

@@ -7,5 +7,5 @@ import { i as mappingsToEntitiesConfig, t as EntityMappingRow } from "./mappings
 import { a as compileEntityView, i as ExplainResult, n as CompiledView, o as compileEntityViews, r as DEFAULT_VIEW_PREFIX, s as explainEntitiesConfig, t as CompileOptions } from "./view-compiler-Bo7pqXW3.mjs";
 import { c as SyncResult, f as reconcile, l as SyncStore, n as MirrorRecord, o as SourceRow, p as runSync, r as PersistAction, s as SyncAction, t as EntitySyncResult } from "./sync-engine-DgQbrJON.mjs";
 import { a as IntegrationStep, c as StepProblem, i as IntegrationStatus, l as StepState, n as IntegrationFacts, o as NextAction, r as IntegrationState, s as StepId, t as ConnectionLiveness } from "./integration-state-BK-riZnm.mjs";
-import { _ as joinFansOut, a as validateProjection, c as compileProjectionJoins, d as describeCardinality, f as draftErrors, g as fanOutJoins, h as suggestJoinConditions, i as primaryKeyColumns, l as quoteIdent, m as emptyProjectionDraft, n as coversUniqueKey, o as compileProjectionFrom, p as draftToProjection, r as hasRichMeta, s as compileProjectionIdentity, t as columnMetaFor, u as ProjectionDraft } from "./internal-o2M7FGlR.mjs";
-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 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, 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, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, quoteIdent, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };
+import { C as fanOutJoins, S as suggestJoinConditions, _ as draftErrors, a as validateProjection, b as emptyProjectionDraft, c as compileProjectionIdentity, d as compileProjectionSelect, f as quoteIdent, g as describeCardinality, h as addDraftJoin, i as primaryKeyColumns, l as compileProjectionJoins, m as ProjectionDraft, n as coversUniqueKey, o as PREVIEW_MAX_ROWS, p as DraftRefOption, r as hasRichMeta, s as compileProjectionFrom, t as columnMetaFor, u as compileProjectionPreview, v as draftRefOptions, w as joinFansOut, x as removeDraftJoin, y as draftToProjection } from "./internal-CvlFk3KC.mjs";
+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 };

package/internal.mjs

@@ -1,10 +1,10 @@
-import { i as projectionSchema, r as identityRefs, t as BASE_REF } from "./projection-CSGJbZlZ.mjs";
-import { _ as columnMetaFor, a as MATERIALIZING_CONCEPTS, b as primaryKeyColumns, c as entitiesConfigSchema, d as relationshipSchema, f as relationshipsSchema, g as joinFansOut, h as fanOutJoins, i as ClivlyConfigError, l as filterSchema, m as validateProjection, n as CRM_CONCEPTS, p as validateEntitiesConfig, s as defineClivlyConfig, t as CANONICAL_FIELDS, v as coversUniqueKey, y as hasRichMeta } from "./entity-config-B74SPOUZ.mjs";
-import { n as mappingsToEntitiesConfig } from "./mappings-config-DQS_s4dg.mjs";
+import { a as projectionSchema, i as identityRefs, t as BASE_REF } from "./projection-hnPSgH6G.mjs";
+import { _ as columnMetaFor, a as MATERIALIZING_CONCEPTS, b as primaryKeyColumns, c as entitiesConfigSchema, d as relationshipSchema, f as relationshipsSchema, g as joinFansOut, h as fanOutJoins, i as ClivlyConfigError, l as filterSchema, m as validateProjection, n as CRM_CONCEPTS, p as validateEntitiesConfig, s as defineClivlyConfig, t as CANONICAL_FIELDS, v as coversUniqueKey, y as hasRichMeta } from "./entity-config-CusbTOJ1.mjs";
+import { n as mappingsToEntitiesConfig } from "./mappings-config-7qQ47p9K.mjs";
 import { t as authCustom } from "./auth-adapter-gfVDxf3d.mjs";
 import { n as buildRelationships, r as relationshipViaSignature, t as buildFilterFromDiscriminator } from "./mapping-form-DigkuvFc.mjs";
-import { a as suggestJoinConditions, i as emptyProjectionDraft, n as draftErrors, r as draftToProjection, t as describeCardinality } from "./internal-CykXpEGk.mjs";
-import { a as quoteIdent, n as compileProjectionIdentity, r as compileProjectionJoins, t as compileProjectionFrom } from "./projection-sql-BgnfiGqF.mjs";
-import { i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-CSYwEWf5.mjs";
-import { i as runSync, r as reconcile } from "./sync-engine-Dt5QQSKO.mjs";
-export { BASE_REF, CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, DEFAULT_VIEW_PREFIX, MATERIALIZING_CONCEPTS, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, quoteIdent, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };
+import { a as draftToProjection, c as suggestJoinConditions, i as draftRefOptions, n as describeCardinality, o as emptyProjectionDraft, r as draftErrors, s as removeDraftJoin, t as addDraftJoin } from "./internal-ChufvXE6.mjs";
+import { a as compileProjectionPreview, i as compileProjectionJoins, n as compileProjectionFrom, o as compileProjectionSelect, r as compileProjectionIdentity, s as quoteIdent, t as PREVIEW_MAX_ROWS } from "./projection-sql-9zzTVGvf.mjs";
+import { i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-D_6gfXFr.mjs";
+import { i as runSync, r as reconcile } from "./sync-engine-B_IzoUSx.mjs";
+export { BASE_REF, CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, DEFAULT_VIEW_PREFIX, MATERIALIZING_CONCEPTS, PREVIEW_MAX_ROWS, 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 };

package/{mappings-config-DQS_s4dg.mjs → mappings-config-7qQ47p9K.mjs}

@@ -1,4 +1,4 @@
-import { t as CANONICAL_FIELDS } from "./entity-config-B74SPOUZ.mjs";
+import { t as CANONICAL_FIELDS } from "./entity-config-CusbTOJ1.mjs";
 //#region ../core/src/mappings-config.ts
 const RESERVED_FIELD = "id";
 /**

package/{mappings-config-CLyEg0sf.cjs → mappings-config-CjCmT-aU.cjs}

@@ -1,4 +1,4 @@
-const require_entity_config = require("./entity-config-7sGCk_nw.cjs");
+const require_entity_config = require("./entity-config-DE30_RpU.cjs");
 //#region ../core/src/mappings-config.ts
 const RESERVED_FIELD = "id";
 /**

package/{namespace-probe-Cn7voAd0.d.mts → namespace-probe-Ckn9yJ6F.d.mts}

@@ -1,4 +1,4 @@
-import { a as ClivlyEntitiesConfig } from "./entity-config-B2RA53nw.mjs";
+import { P as ProjectionMapping, a as ClivlyEntitiesConfig } from "./entity-config-B2RA53nw.mjs";
 import { r as IntegrationState } from "./integration-state-BK-riZnm.mjs";
 //#region ../sdk/src/drizzle-meta.d.ts
 declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
@@ -340,6 +340,20 @@ interface CursorStore {
   get(entity: string): Promise<SyncCursor | null> | SyncCursor | null;
   set(entity: string, cursor: SyncCursor | null): Promise<void> | void;
 }
+/** @see ClivlySDK.describeSyncTrigger */
+interface SyncTriggerDescription {
+  /**
+   * `syncTrigger.url` exactly as configured, placeholder and all. The raw
+   * value, so a caller can say what is in the file rather than what survived
+   * resolution.
+   */
+  configured?: string;
+  /**
+   * The URL that would be reported to Clivly on the next heartbeat, or
+   * `undefined` when nothing resolves. An unedited placeholder never resolves.
+   */
+  resolved?: string;
+}
 interface ClivlySDK {
   /**
    * Send a single heartbeat and report the outcome richly: `ok`, the HTTP
@@ -375,6 +389,18 @@ interface ClivlySDK {
    * anyone who can reach it — set a secret if it's publicly routable.
    */
   createClivlyHandler(): (req: Request) => Promise<Response>;
+  /**
+   * What this app would tell Clivly about its sync trigger route, right now.
+   *
+   * Computed per call rather than frozen at creation: `resolved` can start as
+   * `undefined` and become a real URL once the mounted route has served its
+   * first request and observed its own origin.
+   *
+   * Exists for `clivly status`, which has to tell "no trigger configured"
+   * apart from "configured, but still the scaffolded placeholder" — a
+   * distinction `resolved` alone erases, since it skips placeholders by design.
+   */
+  describeSyncTrigger(): SyncTriggerDescription;
   /** Validate this setup end-to-end (read-only) before the first sync. */
   doctor(): Promise<DoctorReport>;
   /**
@@ -451,8 +477,25 @@ interface ClivlySDK {
 interface NamespaceIntrospector {
   /** All base table names in the reachable schema. */
   listTables(): Promise<string[]>;
+  /**
+   * Read a few rows through an unsaved projection, for the dashboard's derived
+   * object preview. Rows are keyed by field name.
+   *
+   * Optional because it is the only capability here that needs more than a
+   * table name, and because an introspector may be hand-written. Absent, the
+   * dashboard says preview is unavailable rather than failing — see
+   * `previewProjection`.
+   *
+   * This is what makes preview cost the host an SDK upgrade and nothing else:
+   * `drizzleIntrospector(db)` already closes over the connection, so a config
+   * that set `introspector` for the "Namespace reachable" check gains preview
+   * without touching a line.
+   */
+  runProjection?(projection: ProjectionMapping, opts: {
+    limit: number;
+  }): Promise<Record<string, unknown>[]>;
   /** Prove a table is genuinely selectable (SELECT ... LIMIT 1). Throws if unreachable/denied. */
   sampleSelect(table: string): Promise<void>;
 }
 //#endregion
-export { SyncSource as _, ClivlyConnectResult as a, ClivlyUser as c, DiscoveredTable as d, DoctorCheck as f, EnsuredObjectTypeResult as g, EnsuredMappingResult as h, ClivlyConnectReason as i, CreateChatSessionHandlerOptions as l, EnsureSchemaResult as m, ChatSessionRequestBody as n, ClivlySDK as o, DoctorReport as p, ChatWidgetVisitor as r, ClivlySDKConfig as s, NamespaceIntrospector as t, CursorStore as u };
+export { SyncSource as _, ClivlyConnectResult as a, ClivlyUser as c, DiscoveredTable as d, DoctorCheck as f, EnsuredObjectTypeResult as g, EnsuredMappingResult as h, ClivlyConnectReason as i, CreateChatSessionHandlerOptions as l, EnsureSchemaResult as m, ChatSessionRequestBody as n, ClivlySDK as o, DoctorReport as p, ChatWidgetVisitor as r, ClivlySDKConfig as s, NamespaceIntrospector as t, CursorStore as u, SyncTriggerDescription as v };

package/{namespace-probe-BoGI18dQ.d.cts → namespace-probe-DaTJINS-.d.cts}

@@ -1,4 +1,4 @@
-import { a as ClivlyEntitiesConfig } from "./entity-config-B2RA53nw.cjs";
+import { P as ProjectionMapping, a as ClivlyEntitiesConfig } from "./entity-config-B2RA53nw.cjs";
 import { r as IntegrationState } from "./integration-state-BK-riZnm.cjs";
 //#region ../sdk/src/drizzle-meta.d.ts
 declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
@@ -340,6 +340,20 @@ interface CursorStore {
   get(entity: string): Promise<SyncCursor | null> | SyncCursor | null;
   set(entity: string, cursor: SyncCursor | null): Promise<void> | void;
 }
+/** @see ClivlySDK.describeSyncTrigger */
+interface SyncTriggerDescription {
+  /**
+   * `syncTrigger.url` exactly as configured, placeholder and all. The raw
+   * value, so a caller can say what is in the file rather than what survived
+   * resolution.
+   */
+  configured?: string;
+  /**
+   * The URL that would be reported to Clivly on the next heartbeat, or
+   * `undefined` when nothing resolves. An unedited placeholder never resolves.
+   */
+  resolved?: string;
+}
 interface ClivlySDK {
   /**
    * Send a single heartbeat and report the outcome richly: `ok`, the HTTP
@@ -375,6 +389,18 @@ interface ClivlySDK {
    * anyone who can reach it — set a secret if it's publicly routable.
    */
   createClivlyHandler(): (req: Request) => Promise<Response>;
+  /**
+   * What this app would tell Clivly about its sync trigger route, right now.
+   *
+   * Computed per call rather than frozen at creation: `resolved` can start as
+   * `undefined` and become a real URL once the mounted route has served its
+   * first request and observed its own origin.
+   *
+   * Exists for `clivly status`, which has to tell "no trigger configured"
+   * apart from "configured, but still the scaffolded placeholder" — a
+   * distinction `resolved` alone erases, since it skips placeholders by design.
+   */
+  describeSyncTrigger(): SyncTriggerDescription;
   /** Validate this setup end-to-end (read-only) before the first sync. */
   doctor(): Promise<DoctorReport>;
   /**
@@ -451,8 +477,25 @@ interface ClivlySDK {
 interface NamespaceIntrospector {
   /** All base table names in the reachable schema. */
   listTables(): Promise<string[]>;
+  /**
+   * Read a few rows through an unsaved projection, for the dashboard's derived
+   * object preview. Rows are keyed by field name.
+   *
+   * Optional because it is the only capability here that needs more than a
+   * table name, and because an introspector may be hand-written. Absent, the
+   * dashboard says preview is unavailable rather than failing — see
+   * `previewProjection`.
+   *
+   * This is what makes preview cost the host an SDK upgrade and nothing else:
+   * `drizzleIntrospector(db)` already closes over the connection, so a config
+   * that set `introspector` for the "Namespace reachable" check gains preview
+   * without touching a line.
+   */
+  runProjection?(projection: ProjectionMapping, opts: {
+    limit: number;
+  }): Promise<Record<string, unknown>[]>;
   /** Prove a table is genuinely selectable (SELECT ... LIMIT 1). Throws if unreachable/denied. */
   sampleSelect(table: string): Promise<void>;
 }
 //#endregion
-export { SyncSource as _, ClivlyConnectResult as a, ClivlyUser as c, DiscoveredTable as d, DoctorCheck as f, EnsuredObjectTypeResult as g, EnsuredMappingResult as h, ClivlyConnectReason as i, CreateChatSessionHandlerOptions as l, EnsureSchemaResult as m, ChatSessionRequestBody as n, ClivlySDK as o, DoctorReport as p, ChatWidgetVisitor as r, ClivlySDKConfig as s, NamespaceIntrospector as t, CursorStore as u };
+export { SyncSource as _, ClivlyConnectResult as a, ClivlyUser as c, DiscoveredTable as d, DoctorCheck as f, EnsuredObjectTypeResult as g, EnsuredMappingResult as h, ClivlyConnectReason as i, CreateChatSessionHandlerOptions as l, EnsureSchemaResult as m, ChatSessionRequestBody as n, ClivlySDK as o, DoctorReport as p, ChatWidgetVisitor as r, ClivlySDKConfig as s, NamespaceIntrospector as t, CursorStore as u, SyncTriggerDescription as v };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clivly",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "private": false,
   "type": "module",
   "description": "Clivly CLI — scaffold a CRM into your app (clivly init).",

package/{projection-Dz6_i1-w.cjs → projection-DEwL-D8R.cjs}

@@ -4303,6 +4303,12 @@ Object.defineProperty(exports, "BASE_REF", {
 		return BASE_REF;
 	}
 });
+Object.defineProperty(exports, "PROJECTION_KEY_MESSAGE", {
+	enumerable: true,
+	get: function() {
+		return PROJECTION_KEY_MESSAGE;
+	}
+});
 Object.defineProperty(exports, "PROJECTION_KEY_PATTERN", {
 	enumerable: true,
 	get: function() {

package/{projection-CSGJbZlZ.mjs → projection-hnPSgH6G.mjs}

@@ -4297,4 +4297,4 @@ function identityRefs(identity, basePkColumn) {
 	return identity.parts;
 }
 //#endregion
-export { _enum as a, literal as c, strictObject as d, string as f, projectionSchema as i, number as l, PROJECTION_KEY_PATTERN as n, array as o, union as p, identityRefs as r, boolean as s, BASE_REF as t, record as u };
+export { projectionSchema as a, boolean as c, record as d, strictObject as f, identityRefs as i, literal as l, union as m, PROJECTION_KEY_MESSAGE as n, _enum as o, string as p, PROJECTION_KEY_PATTERN as r, array as s, BASE_REF as t, number as u };