clivly 0.9.3 → 0.9.5

package/README.md

@@ -87,7 +87,10 @@ Detects your framework, ORM, auth adapter and app layout, then scaffolds:
 | The auth-verify route for your framework | Yes — `--force` to overwrite |
 
 Plus `CLIVLY_SECRET_KEY`, `CLIVLY_SYNC_TRIGGER_URL` and
-`CLIVLY_SYNC_TRIGGER_SECRET` placeholders in your env file.
+`CLIVLY_SYNC_TRIGGER_SECRET` in your env file. The two secrets are written
+empty, for you or `clivly login` to fill; the trigger URL gets a visible
+`https://<yourDomain.com>/api/clivly/tick` template, because there the shape is
+the documentation.
 
 | Flag | Purpose |
 | --- | --- |
@@ -233,7 +236,7 @@ the CLI requires pairing.
 | --- | --- | --- |
 | `CLIVLY_SECRET_KEY` | Dashboard → **Connect app**, or **Settings → API keys** | **Shown once.** Copy it immediately; you cannot retrieve it later, only regenerate. Regenerating **revokes the previous key**, so redeploy after rotating. The legacy name `CLIVLY_API_KEY` is still accepted as a fallback |
 | `CLIVLY_SYNC_TRIGGER_SECRET` | Dashboard → **Integrations → Remote sync** | Must match the value in your app's env exactly. A mismatch surfaces as a `401` on the signed trigger |
-| `CLIVLY_SYNC_TRIGGER_URL` | Your own deployment | The public URL of your mounted tick route, e.g. `https://app.example.com/api/clivly/tick`. Optional until you deploy — push-only setups can leave it unset |
+| `CLIVLY_SYNC_TRIGGER_URL` | Your own deployment | The public URL of your mounted tick route. `init` and `login` both scaffold it as `https://<yourDomain.com>/api/clivly/tick` — the angle brackets mark it unedited, and the SDK ignores it until you replace them, so leaving it alone costs nothing. Optional until you deploy — push-only setups can leave it as the template |
 | `CLIVLY_PUBLISHABLE_KEY` | Same place as the secret key | Only needed for the chat widget. Safe to expose in client code |
 
 Write them into the env file of the package that imports `clivly`, then re-run
@@ -265,7 +268,7 @@ It answers two questions under two headings:
   scope; `clivly doctor` is local by definition and omits it.
 - **This project** — the local ladder, run here on your machine: credential →
   Clivly reachable → `clivly.config` loads → `clivly.config` is edge-safe →
-  setup checks → sync trigger URL.
+  boot hook wired → setup checks → sync trigger URL.
 
 ```text
 Clivly status
@@ -278,11 +281,23 @@ Workspace
   🔒 Let Clivly start a sync
 
 This project
-  ✅ Step 1 of 6 · API key present
-  ✅ Step 2 of 6 · Clivly reachable — Acme
+  ✅ Step 1 of 7 · API key present
+  ✅ Step 2 of 7 · Clivly reachable — Acme
   ...
 ```
 
+**Boot hook wired** is the rung to know about. It finds the boot site for your
+framework and confirms something there actually starts Clivly — and on Next.js
+below 15, that `experimental.instrumentationHook` is set in `next.config`,
+without which `instrumentation.ts` is ignored outright and your app never checks
+in. That failure is otherwise completely silent: the file is present, the config
+loads, the credentials work, and the dashboard stays empty.
+
+It is the one rung with no prerequisites, so it still reports when the config
+above it fails to load. A framework the CLI does not recognise shows it as
+skipped rather than passed — there is nowhere known to look, and a green step
+for an unasked question is what made this worth adding.
+
 If the Workspace section reads
 `⚠️ This Clivly server does not report setup progress`, or names a rejected key
 or an unreachable host, that means the question could not be asked — not that
@@ -406,7 +421,7 @@ work, and are kept because output and docs have recommended them — but prefer
 | --- | --- |
 | `clivly ping` | Credential + reachability |
 | `clivly connect` | The above, plus config and trigger URL |
-| `clivly doctor` | Config, setup checks and edge safety |
+| `clivly doctor` | Config, edge safety, boot hook and setup checks |
 
 Each prints a deprecation notice, then the steps it covers, renumbered to its own
 scope:
@@ -478,6 +493,8 @@ socket reconnect. The CLI does not enable this setting on your behalf.
 | `init` cannot find your schema | Pass `--schema <path\|package>` |
 | `init` scaffolded a `db` import that doesn't resolve | The probe cannot evaluate a db module that throws without `DATABASE_URL`. Fix the `TODO(clivly)` import path it left, or pass `--db-import` |
 | `clivly login` exits non-zero, pairing unavailable | The backend has `CLIVLY_CLI_PAIRING_ENABLED` off. Use the manual credential path above |
+| App runs, no errors, dashboard stays silent | Run `clivly status` — the **Boot hook wired** step names the cause. On Next.js below 15 it is almost always the missing `experimental: { instrumentationHook: true }` in `next.config` |
+| `Clivly reachable` fails with `invalid_api_key` (401) | The key is not one this org accepts. Re-run `npx clivly login` to re-pair, and check the key belongs to the org whose dashboard you are watching |
 | `clivly dev` cannot start | Install `cloudflared`, or set `CLIVLY_SYNC_TRIGGER_URL` to a tunnel you run yourself |
 | Credentials written but the app never loads them | Wrong env file for your framework — see the table under `clivly login` |
 

package/core-entity-config.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config-DtBsl2MQ.cjs");
+const require_entity_config = require("./entity-config-7sGCk_nw.cjs");
 //#region src/core-entity-config.ts
 require("./deprecate-subpath-B9ngvizt.cjs").warnDeprecatedSubpath("clivly/core/entity-config", "clivly/internal/entity-config");
 //#endregion

package/core-entity-config.mjs

@@ -1,4 +1,4 @@
-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-kUHri9yA.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-B74SPOUZ.mjs";
 import { t as warnDeprecatedSubpath } from "./deprecate-subpath-CmvZtCpE.mjs";
 //#region src/core-entity-config.ts
 warnDeprecatedSubpath("clivly/core/entity-config", "clivly/internal/entity-config");

package/core-mappings-config.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_mappings_config = require("./mappings-config-B0RqFLxu.cjs");
+const require_mappings_config = require("./mappings-config-CLyEg0sf.cjs");
 const require_deprecate_subpath = require("./deprecate-subpath-B9ngvizt.cjs");
 require("./internal-mappings-config.cjs");
 //#region src/core-mappings-config.ts

package/core-mappings-config.mjs

@@ -1,4 +1,4 @@
-import { n as mappingsToEntitiesConfig, t as entitiesToMappings } from "./mappings-config-B1b1HVBg.mjs";
+import { n as mappingsToEntitiesConfig, t as entitiesToMappings } from "./mappings-config-DQS_s4dg.mjs";
 import { t as warnDeprecatedSubpath } from "./deprecate-subpath-CmvZtCpE.mjs";
 import "./internal-mappings-config.mjs";
 //#region src/core-mappings-config.ts

package/core-sync-engine.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_deprecate_subpath = require("./deprecate-subpath-B9ngvizt.cjs");
-const require_sync_engine = require("./sync-engine-abE94g6X.cjs");
+const require_sync_engine = require("./sync-engine-C4A5jgA4.cjs");
 require("./internal-sync-engine.cjs");
 //#region src/core-sync-engine.ts
 require_deprecate_subpath.warnDeprecatedSubpath("clivly/core/sync-engine", "clivly/internal/sync-engine");

package/core-sync-engine.mjs

@@ -1,5 +1,5 @@
 import { t as warnDeprecatedSubpath } from "./deprecate-subpath-CmvZtCpE.mjs";
-import { i as runSync, n as previewSync, r as reconcile, t as computeSampleWarnings } from "./sync-engine-SuxSzbZ4.mjs";
+import { i as runSync, n as previewSync, r as reconcile, t as computeSampleWarnings } from "./sync-engine-Dt5QQSKO.mjs";
 import "./internal-sync-engine.mjs";
 //#region src/core-sync-engine.ts
 warnDeprecatedSubpath("clivly/core/sync-engine", "clivly/internal/sync-engine");

package/core-view-compiler.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_deprecate_subpath = require("./deprecate-subpath-B9ngvizt.cjs");
-const require_view_compiler = require("./view-compiler-Blu4OXJ7.cjs");
+const require_view_compiler = require("./view-compiler-B5nDal14.cjs");
 require("./internal-view-compiler.cjs");
 //#region src/core-view-compiler.ts
 require_deprecate_subpath.warnDeprecatedSubpath("clivly/core/view-compiler", "clivly/internal/view-compiler");

package/core-view-compiler.mjs

@@ -1,5 +1,5 @@
 import { t as warnDeprecatedSubpath } from "./deprecate-subpath-CmvZtCpE.mjs";
-import { a as explainViewExecutionError, i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-CQx8TRrW.mjs";
+import { a as explainViewExecutionError, i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-CSYwEWf5.mjs";
 import "./internal-view-compiler.mjs";
 //#region src/core-view-compiler.ts
 warnDeprecatedSubpath("clivly/core/view-compiler", "clivly/internal/view-compiler");

package/core.cjs

@@ -1,13 +1,14 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_projection = require("./projection-C5244vGa.cjs");
-const require_entity_config = require("./entity-config-DtBsl2MQ.cjs");
-const require_mappings_config = require("./mappings-config-B0RqFLxu.cjs");
+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_deprecate_subpath = require("./deprecate-subpath-B9ngvizt.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-CwnEG6Wl.cjs");
-const require_view_compiler = require("./view-compiler-Blu4OXJ7.cjs");
-const require_sync_engine = require("./sync-engine-abE94g6X.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");
 //#region src/core.ts
 require_deprecate_subpath.warnDeprecatedSubpath("clivly/core", "clivly/sdk", "Import \"defineClivlyConfig\" and its config types from \"clivly/sdk\"; import everything else from \"clivly/internal\" (no stability guarantee — see STABILITY.md).");
 //#endregion
@@ -23,6 +24,9 @@ exports.buildRelationships = require_mapping_form.buildRelationships;
 exports.columnMetaFor = require_entity_config.columnMetaFor;
 exports.compileEntityView = require_view_compiler.compileEntityView;
 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.coversUniqueKey = require_entity_config.coversUniqueKey;
 exports.defineClivlyConfig = require_entity_config.defineClivlyConfig;
 exports.describeCardinality = require_internal.describeCardinality;
@@ -39,6 +43,7 @@ exports.joinFansOut = require_entity_config.joinFansOut;
 exports.mappingsToEntitiesConfig = require_mappings_config.mappingsToEntitiesConfig;
 exports.primaryKeyColumns = require_entity_config.primaryKeyColumns;
 exports.projectionSchema = require_projection.projectionSchema;
+exports.quoteIdent = require_projection_sql.quoteIdent;
 exports.reconcile = require_sync_engine.reconcile;
 exports.relationshipSchema = require_entity_config.relationshipSchema;
 exports.relationshipViaSignature = require_mapping_form.relationshipViaSignature;

package/core.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 { a as validateProjection, c as draftErrors, d as suggestJoinConditions, f as fanOutJoins, i as primaryKeyColumns, l as draftToProjection, n as coversUniqueKey, o as ProjectionDraft, p as joinFansOut, r as hasRichMeta, s as describeCardinality, t as columnMetaFor, u as emptyProjectionDraft } from "./internal-Da_dlcQ_.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, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };
+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 };

package/core.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 { a as validateProjection, c as draftErrors, d as suggestJoinConditions, f as fanOutJoins, i as primaryKeyColumns, l as draftToProjection, n as coversUniqueKey, o as ProjectionDraft, p as joinFansOut, r as hasRichMeta, s as describeCardinality, t as columnMetaFor, u as emptyProjectionDraft } from "./internal-CDY8g9Ic.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, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };
+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 };

package/core.mjs

@@ -1,13 +1,14 @@
-import { i as projectionSchema, r as identityRefs, t as BASE_REF } from "./projection-D7xmQP4S.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-kUHri9yA.mjs";
-import { n as mappingsToEntitiesConfig } from "./mappings-config-B1b1HVBg.mjs";
+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 { t as warnDeprecatedSubpath } from "./deprecate-subpath-CmvZtCpE.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-Df-PtOH_.mjs";
-import { i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-CQx8TRrW.mjs";
-import { i as runSync, r as reconcile } from "./sync-engine-SuxSzbZ4.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";
 //#region src/core.ts
 warnDeprecatedSubpath("clivly/core", "clivly/sdk", "Import \"defineClivlyConfig\" and its config types from \"clivly/sdk\"; import everything else from \"clivly/internal\" (no stability guarantee — see STABILITY.md).");
 //#endregion
-export { BASE_REF, CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, DEFAULT_VIEW_PREFIX, MATERIALIZING_CONCEPTS, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };
+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 };

package/drizzle.cjs

@@ -1,7 +1,78 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_projection = require("./projection-Dz6_i1-w.cjs");
 const require_drizzle_meta = require("./drizzle-meta-Bb1JWYqf.cjs");
+const require_projection_sql = require("./projection-sql-Cl1qIn8m.cjs");
 const require_drizzle = require("./drizzle-bfjVzYR6.cjs");
 let drizzle_orm = require("drizzle-orm");
+//#region ../sdk/src/drizzle-projection.ts
+/** `<ref>.<column>` — the token `fields` carries and cloud-ingest reads. */
+function refToken(ref) {
+	return `${ref.table}.${ref.column}`;
+}
+function refSql(ref) {
+	return `${require_projection_sql.quoteIdent(ref.table)}.${require_projection_sql.quoteIdent(ref.column)}`;
+}
+function parseRef(value) {
+	if (typeof value !== "string") return value;
+	const dot = value.indexOf(".");
+	if (dot <= 0 || dot === value.length - 1) throw new Error(`fromDrizzleProjection: cursorField "${value}" must be a ref token like "base.updated_at".`);
+	return {
+		table: value.slice(0, dot),
+		column: value.slice(dot + 1)
+	};
+}
+/**
+* Refs address tables symbolically — `base` or a join key — never by table name,
+* which is what stops a projection reaching a table it did not declare. An
+* unresolvable ref would otherwise compile to SQL referencing a missing alias
+* and fail at the database with a message that never mentions the config.
+*/
+function assertKnownRef(ref, known, context) {
+	if (!known.has(ref.table)) throw new Error(`fromDrizzleProjection: ${context} names unknown ref "${ref.table}" — expected "${[...known].join("\", \"")}".`);
+}
+function normalizeRows(result) {
+	if (Array.isArray(result)) return result;
+	const rows = result.rows;
+	if (Array.isArray(rows)) return rows;
+	throw new Error("fromDrizzleProjection: db.execute() returned neither an array of rows nor { rows }.");
+}
+function fromDrizzleProjection(db, projection, opts) {
+	const client = db;
+	const known = /* @__PURE__ */ new Set([require_projection.BASE_REF, ...projection.joins.map((j) => j.key)]);
+	if (projection.identity.kind === "base_pk" && projection.identity.column === void 0 && opts.basePkColumn === void 0) throw new Error(`fromDrizzleProjection: projection "${projection.entityKey}" has a base_pk identity with no column — pass { basePkColumn }.`);
+	const cursorRef = parseRef(opts.cursorField);
+	assertKnownRef(cursorRef, known, "cursorField");
+	for (const [field, binding] of Object.entries(projection.fieldBindings)) assertKnownRef(binding.from, known, `field "${field}"`);
+	const identityExpr = require_projection_sql.compileProjectionIdentity(projection, opts.basePkColumn ?? "");
+	const cursorToken = refToken(cursorRef);
+	const cursorExpr = `CAST(${refSql(cursorRef)} AS timestamptz)`;
+	const cursorRead = `to_char(${cursorExpr} AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')`;
+	const selectItems = [`${identityExpr} AS ${require_projection_sql.quoteIdent("id")}`, `${cursorRead} AS ${require_projection_sql.quoteIdent(cursorToken)}`];
+	const emitted = /* @__PURE__ */ new Set([cursorToken]);
+	for (const binding of Object.values(projection.fieldBindings)) {
+		const token = refToken(binding.from);
+		if (emitted.has(token)) continue;
+		emitted.add(token);
+		selectItems.push(`${refSql(binding.from)} AS ${require_projection_sql.quoteIdent(token)}`);
+	}
+	const head = [
+		`select ${selectItems.join(", ")}`,
+		require_projection_sql.compileProjectionFrom(projection),
+		...require_projection_sql.compileProjectionJoins(projection)
+	].join(" ");
+	return {
+		entity: opts.entity,
+		cursorField: cursorToken,
+		idField: "id",
+		...opts.objectType === void 0 ? {} : { objectType: opts.objectType },
+		fetchPage: async ({ since, limit }) => {
+			const where = since ? drizzle_orm.sql` where (${drizzle_orm.sql.raw(cursorExpr)}, ${drizzle_orm.sql.raw(identityExpr)}) > (${since.time.toISOString()}::timestamptz, ${since.id})` : drizzle_orm.sql``;
+			const query = drizzle_orm.sql`${drizzle_orm.sql.raw(head)}${where} order by ${drizzle_orm.sql.raw(cursorExpr)} asc, ${drizzle_orm.sql.raw(identityExpr)} asc limit ${limit}`;
+			return normalizeRows(await client.execute(query));
+		}
+	};
+}
+//#endregion
 //#region ../sdk/src/drizzle.ts
 function inferIdField(table) {
 	const columns = (0, drizzle_orm.getTableColumns)(table);
@@ -14,14 +85,6 @@ function inferIdField(table) {
 	const kind = primaryKeys.length === 0 ? "no" : "a composite";
 	throw new Error(`fromDrizzle: table "${(0, drizzle_orm.getTableName)(table)}" has ${kind} single-column primary key — pass { idField } explicitly.`);
 }
-/**
-* Build a `SyncSource` from a Drizzle table, generating the keyset-paginated
-* `fetchPage` the SDK needs. `cursorField`/`idField` are drizzle property keys;
-* `idField` defaults to the table's single-column primary key.
-*
-* `drizzle-orm` is an optional peer dependency — installed only when you import
-* `@clivly/sdk/drizzle`.
-*/
 function fromDrizzle(db, table, opts) {
 	const drizzleDb = db;
 	const idField = opts.idField ?? inferIdField(table);
@@ -38,7 +101,8 @@ function fromDrizzle(db, table, opts) {
 		entity: opts.entity,
 		cursorField: cursorColumnName,
 		idField: idColumnName,
-		fetchPage: ({ since, limit }) => drizzleDb.select(projection).from(table).where(since ? drizzle_orm.sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy((0, drizzle_orm.asc)(cursorColumn), (0, drizzle_orm.asc)(idColumn)).limit(limit)
+		fetchPage: ({ since, limit }) => drizzleDb.select(projection).from(table).where(since ? drizzle_orm.sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy((0, drizzle_orm.asc)(cursorColumn), (0, drizzle_orm.asc)(idColumn)).limit(limit),
+		...opts.objectType === void 0 ? {} : { objectType: opts.objectType }
 	};
 	const uniqueConstraints = require_drizzle.buildUniqueConstraints(table);
 	const meta = {
@@ -79,3 +143,4 @@ exports.buildUniqueConstraints = require_drizzle.buildUniqueConstraints;
 exports.discoverFromDrizzle = require_drizzle.discoverFromDrizzle;
 exports.drizzleIntrospector = drizzleIntrospector;
 exports.fromDrizzle = fromDrizzle;
+exports.fromDrizzleProjection = fromDrizzleProjection;

package/drizzle.d.cts

@@ -1,23 +1,99 @@
+import { F as ProjectionRef, P as ProjectionMapping } from "./entity-config-B2RA53nw.cjs";
 import { n as buildUniqueConstraints, r as discoverFromDrizzle } from "./drizzle-DEtRrqtc.cjs";
-import { _ as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-EYyxWZnf.cjs";
+import { _ as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-BoGI18dQ.cjs";
 import { Table } from "drizzle-orm";
+//#region ../sdk/src/drizzle-projection.d.ts
+/**
+ * Build a `SyncSource` that actually executes a projection's joins.
+ *
+ * `fromDrizzle` emits a single-table select, so a projection entity paired with
+ * it pushed raw base-table rows and every joined field mirrored empty — the
+ * declared joins were inert, and the only symptom was a dry run reporting a
+ * missing column whose name was correct.
+ *
+ * The row shape is the contract the cloud already relies on. A projection's
+ * `fields` are ref *tokens* (`client_name -> "cl.full_name"`, from
+ * `projectionFields`), and `cloud-ingest` reads `row[token]` verbatim plus
+ * `row.id` for `sourceRef`. So this aliases every binding by its token rather
+ * than by its field name.
+ *
+ * That is the one deliberate difference from the view compiler, which aliases
+ * by field name because the sync engine reads the compiled view directly. FROM,
+ * JOIN and the identity expression all come from `@clivly/core`, so both paths
+ * join identically and produce the same `id` for the same row.
+ *
+ * `drizzle-orm` is an optional peer dependency — installed only when you import
+ * `@clivly/sdk/drizzle`. The `db` only needs `.execute()`, the same surface
+ * `drizzleIntrospector` requires.
+ */
+interface FromDrizzleProjectionOptions {
+  /**
+   * The base table's primary key, required only when `identity` is `base_pk`
+   * without an explicit column. Unlike `fromDrizzle` there is no `Table` object
+   * to infer it from — a projection names tables as strings.
+   */
+  basePkColumn?: string;
+  /**
+   * The column to keyset-paginate on, as a ref token (`"base.updated_at"`) or
+   * a `ProjectionRef`. A projection spans several tables, so there is no
+   * single table to infer a cursor from.
+   */
+  cursorField: string | ProjectionRef;
+  /** The source name rows are pushed under. */
+  entity: string;
+  /**
+   * The custom object slug. Accepted here so the result is directly assignable
+   * to `source.custom` — bolting it on with a spread afterwards drops the
+   * non-enumerable drizzle metadata.
+   */
+  objectType?: string;
+}
+declare function fromDrizzleProjection(db: unknown, projection: ProjectionMapping, opts: FromDrizzleProjectionOptions & {
+  objectType: string;
+}): SyncSource & {
+  objectType: string;
+};
+declare function fromDrizzleProjection(db: unknown, projection: ProjectionMapping, opts: FromDrizzleProjectionOptions): SyncSource;
+//#endregion
 //#region ../sdk/src/drizzle.d.ts
 interface DrizzleDb {
   select: (...args: any[]) => any;
 }
+interface FromDrizzleOptions {
+  cursorField: string;
+  entity: string;
+  idField?: string;
+  /**
+   * Custom-object slug, for sources destined for `source.custom`.
+   *
+   * Pass it here rather than attaching it afterwards. `source.custom` is typed
+   * `Array<SyncSource & { objectType: string }>`, so before this option existed
+   * the only way to satisfy that type was to bolt the property on post-hoc —
+   * and the idiomatic spread (`{ ...fromDrizzle(...), objectType }`) copies only
+   * ENUMERABLE own properties, silently dropping the non-enumerable
+   * `DRIZZLE_META` below. `doctor` would then report a `fromDrizzle` source as
+   * "hand-written" and skip its cursor/id column checks, which is both a lost
+   * check and a false explanation.
+   */
+  objectType?: string;
+}
 /**
  * Build a `SyncSource` from a Drizzle table, generating the keyset-paginated
  * `fetchPage` the SDK needs. `cursorField`/`idField` are drizzle property keys;
  * `idField` defaults to the table's single-column primary key.
  *
+ * Pass `objectType` for custom objects — the result is then directly assignable
+ * to `source.custom` with no spread or mutation.
+ *
  * `drizzle-orm` is an optional peer dependency — installed only when you import
  * `@clivly/sdk/drizzle`.
  */
-declare function fromDrizzle(db: DrizzleDb, table: Table, opts: {
-  entity: string;
-  cursorField: string;
-  idField?: string;
-}): SyncSource;
+declare function fromDrizzle(db: DrizzleDb, table: Table, opts: FromDrizzleOptions & {
+  objectType: string;
+}): SyncSource & {
+  objectType: string;
+};
+declare function fromDrizzle(db: DrizzleDb, table: Table, opts: FromDrizzleOptions): SyncSource;
 /**
  * Build a `NamespaceIntrospector` from any Drizzle client that exposes
  * `.execute()`. Reads `information_schema` in the connection's default schema
@@ -25,4 +101,4 @@ declare function fromDrizzle(db: DrizzleDb, table: Table, opts: {
  */
 declare function drizzleIntrospector(db: unknown): NamespaceIntrospector;
 //#endregion
-export { buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle };
+export { type FromDrizzleProjectionOptions, buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle, fromDrizzleProjection };

package/drizzle.d.mts

@@ -1,23 +1,99 @@
+import { F as ProjectionRef, P as ProjectionMapping } from "./entity-config-B2RA53nw.mjs";
 import { n as buildUniqueConstraints, r as discoverFromDrizzle } from "./drizzle-CiK8MMEZ.mjs";
-import { _ as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-BmdGnYMn.mjs";
+import { _ as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-Cn7voAd0.mjs";
 import { Table } from "drizzle-orm";
+//#region ../sdk/src/drizzle-projection.d.ts
+/**
+ * Build a `SyncSource` that actually executes a projection's joins.
+ *
+ * `fromDrizzle` emits a single-table select, so a projection entity paired with
+ * it pushed raw base-table rows and every joined field mirrored empty — the
+ * declared joins were inert, and the only symptom was a dry run reporting a
+ * missing column whose name was correct.
+ *
+ * The row shape is the contract the cloud already relies on. A projection's
+ * `fields` are ref *tokens* (`client_name -> "cl.full_name"`, from
+ * `projectionFields`), and `cloud-ingest` reads `row[token]` verbatim plus
+ * `row.id` for `sourceRef`. So this aliases every binding by its token rather
+ * than by its field name.
+ *
+ * That is the one deliberate difference from the view compiler, which aliases
+ * by field name because the sync engine reads the compiled view directly. FROM,
+ * JOIN and the identity expression all come from `@clivly/core`, so both paths
+ * join identically and produce the same `id` for the same row.
+ *
+ * `drizzle-orm` is an optional peer dependency — installed only when you import
+ * `@clivly/sdk/drizzle`. The `db` only needs `.execute()`, the same surface
+ * `drizzleIntrospector` requires.
+ */
+interface FromDrizzleProjectionOptions {
+  /**
+   * The base table's primary key, required only when `identity` is `base_pk`
+   * without an explicit column. Unlike `fromDrizzle` there is no `Table` object
+   * to infer it from — a projection names tables as strings.
+   */
+  basePkColumn?: string;
+  /**
+   * The column to keyset-paginate on, as a ref token (`"base.updated_at"`) or
+   * a `ProjectionRef`. A projection spans several tables, so there is no
+   * single table to infer a cursor from.
+   */
+  cursorField: string | ProjectionRef;
+  /** The source name rows are pushed under. */
+  entity: string;
+  /**
+   * The custom object slug. Accepted here so the result is directly assignable
+   * to `source.custom` — bolting it on with a spread afterwards drops the
+   * non-enumerable drizzle metadata.
+   */
+  objectType?: string;
+}
+declare function fromDrizzleProjection(db: unknown, projection: ProjectionMapping, opts: FromDrizzleProjectionOptions & {
+  objectType: string;
+}): SyncSource & {
+  objectType: string;
+};
+declare function fromDrizzleProjection(db: unknown, projection: ProjectionMapping, opts: FromDrizzleProjectionOptions): SyncSource;
+//#endregion
 //#region ../sdk/src/drizzle.d.ts
 interface DrizzleDb {
   select: (...args: any[]) => any;
 }
+interface FromDrizzleOptions {
+  cursorField: string;
+  entity: string;
+  idField?: string;
+  /**
+   * Custom-object slug, for sources destined for `source.custom`.
+   *
+   * Pass it here rather than attaching it afterwards. `source.custom` is typed
+   * `Array<SyncSource & { objectType: string }>`, so before this option existed
+   * the only way to satisfy that type was to bolt the property on post-hoc —
+   * and the idiomatic spread (`{ ...fromDrizzle(...), objectType }`) copies only
+   * ENUMERABLE own properties, silently dropping the non-enumerable
+   * `DRIZZLE_META` below. `doctor` would then report a `fromDrizzle` source as
+   * "hand-written" and skip its cursor/id column checks, which is both a lost
+   * check and a false explanation.
+   */
+  objectType?: string;
+}
 /**
  * Build a `SyncSource` from a Drizzle table, generating the keyset-paginated
  * `fetchPage` the SDK needs. `cursorField`/`idField` are drizzle property keys;
  * `idField` defaults to the table's single-column primary key.
  *
+ * Pass `objectType` for custom objects — the result is then directly assignable
+ * to `source.custom` with no spread or mutation.
+ *
  * `drizzle-orm` is an optional peer dependency — installed only when you import
  * `@clivly/sdk/drizzle`.
  */
-declare function fromDrizzle(db: DrizzleDb, table: Table, opts: {
-  entity: string;
-  cursorField: string;
-  idField?: string;
-}): SyncSource;
+declare function fromDrizzle(db: DrizzleDb, table: Table, opts: FromDrizzleOptions & {
+  objectType: string;
+}): SyncSource & {
+  objectType: string;
+};
+declare function fromDrizzle(db: DrizzleDb, table: Table, opts: FromDrizzleOptions): SyncSource;
 /**
  * Build a `NamespaceIntrospector` from any Drizzle client that exposes
  * `.execute()`. Reads `information_schema` in the connection's default schema
@@ -25,4 +101,4 @@ declare function fromDrizzle(db: DrizzleDb, table: Table, opts: {
  */
 declare function drizzleIntrospector(db: unknown): NamespaceIntrospector;
 //#endregion
-export { buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle };
+export { type FromDrizzleProjectionOptions, buildUniqueConstraints, discoverFromDrizzle, drizzleIntrospector, fromDrizzle, fromDrizzleProjection };