@clivly/core 0.9.1 → 0.9.2

package/dist/integration-state.d.cts

@@ -3,7 +3,13 @@ declare const INTEGRATION_STEPS: readonly ["credential", "application", "schema"
 type StepId = (typeof INTEGRATION_STEPS)[number];
 /** `blocked` means "prerequisite unmet", never "broken" — see C-19. */
 type StepState = "done" | "active" | "blocked" | "failed" | "skipped";
-type IntegrationStatus = "not_configured" | "sdk_installed" | "awaiting_connection" | "connected" | "schema_discovered" | "mapping_required" | "trigger_required" | "ready_to_sync" | "syncing" | "healthy" | "warning" | "error" | "disconnected";
+type IntegrationStatus = "not_configured" | "sdk_installed" | "awaiting_connection" | "connected" | "schema_discovered" | "mapping_required" | "trigger_required" | "ready_to_sync" | "syncing" | "healthy" | "warning" | "error" |
+/**
+ * @deprecated No longer derived. Liveness is its own dimension — read
+ * `ConnectionHealth` from `deriveLiveness`. Setup progress does not move
+ * backwards just because an app stopped running.
+ */
+"disconnected";
 declare const INTEGRATION_STEP_LABELS: Record<StepId, string>;
 /** Each step's prerequisites. Ordering is enforced by a test, not convention. */
 declare const STEP_PREREQUISITES: Record<StepId, readonly StepId[]>;
@@ -13,8 +19,20 @@ interface RunFact {
   message?: string;
   ok: boolean;
 }
+/**
+ * Where the reporting app is running, as the app itself understands it.
+ *
+ * `unknown` is a real value, not an absence: `detectHostEnvironment` refuses to
+ * guess when nothing places the app, and a bare `node server.js` with no
+ * NODE_ENV must still be able to connect and be shown as itself. Defaulting
+ * such a host to `local_dev` would file a production box's faults under local
+ * development, where nobody would look for them.
+ */
+type HostEnvironment = "local_dev" | "preview" | "production" | "unknown";
 interface IntegrationFacts {
   discoveredTableCount: number;
+  /** The environment the app reported on its last heartbeat. */
+  environment?: HostEnvironment | null;
   /**
    * Has this app ever checked in? Distinguishes "never installed" from "was
    * working, now silent" — the same absent heartbeat means different things,
@@ -22,10 +40,27 @@ interface IntegrationFacts {
    */
   everConnected: boolean;
   hasCredential: boolean;
+  /**
+   * The cadence the app said it heartbeats at. Liveness windows are multiples
+   * of this rather than a fixed constant, so an app that deliberately reports
+   * slowly is not called dead for obeying its own configuration.
+   */
+  heartbeatIntervalMs?: number | null;
   lastHeartbeatAt: number | null;
   lastRun: RunFact | null;
   mappedEntityCount: number;
   now: number;
+  /**
+   * Deployment presence, when this deployment has one. Absent or `http`
+   * transport keeps the cadence-derived behaviour every SDK in the field uses.
+   */
+  presence?: DeploymentPresence | null;
+  /**
+   * Faults the running app diagnosed about itself on its last heartbeat — an
+   * unreadable database, a secret missing from the process environment. These
+   * are what make a reachable app `live_with_issues`; unfinished setup is not.
+   */
+  reportedIssues?: StepProblem[];
   syncInFlight: boolean;
   /** A trigger URL and secret both exist, so Clivly can ask the app to sync. */
   triggerConfigured: boolean;
@@ -46,6 +81,52 @@ interface IntegrationStep {
   state: StepState;
 }
 declare function formatAge(ms: number): string;
+/** The cadence `createClivlySDK` uses when the host app configures none. */
+declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 60000;
+type ConnectionHealth = "live" | "live_with_issues" | "stale" | "offline";
+/** Which algorithm decides whether this deployment is up. */
+type PresenceTransport = "websocket" | "http";
+type PresenceConnectionState = "connected" | "reconnecting" | "disconnected";
+/**
+ * A deployment's connection state as its `PresenceRoom` last persisted it.
+ *
+ * This exists because a socket has an explicit state and a timestamp does not.
+ * Deriving WebSocket liveness from heartbeat age would leave a disconnected app
+ * shown as live for 150 seconds and offline only after ten minutes, which is
+ * the whole reason this transport exists.
+ */
+interface DeploymentPresence {
+  /** Sockets currently accepted in the room. */
+  activeInstanceCount: number;
+  connectionState: PresenceConnectionState;
+  transport: PresenceTransport;
+}
+interface ConnectionLiveness {
+  /** `"8s ago"`, or `"No heartbeat yet"` when the app has never reported. */
+  ageLabel: string;
+  ageMs: number | null;
+  environment: HostEnvironment | null;
+  health: ConnectionHealth;
+  /**
+   * Faults on a reachable app. Empty unless `health` is `live_with_issues`.
+   */
+  issues: StepProblem[];
+  /** Present when a deployment-presence record supplied this liveness result. */
+  presence?: Pick<DeploymentPresence, "connectionState" | "transport">;
+  /** Is a heartbeat recent enough to speak for the app as it is right now? */
+  reachable: boolean;
+}
+/**
+ * The two boundaries that separate live from stale from offline, in terms of
+ * the app's own reported cadence. A cadence we cannot believe — absent, zero,
+ * negative — falls back to the SDK default rather than producing a window of
+ * zero that would call every app offline.
+ */
+declare function livenessWindows(intervalMs: number | null | undefined): {
+  liveMs: number;
+  staleMs: number;
+};
+declare function deriveLiveness(facts: IntegrationFacts): ConnectionLiveness;
 /**
  * Walk the ladder once. A step is `blocked` when an earlier step it needs has
  * not been satisfied — a prerequisite statement, not a verdict about this step
@@ -54,10 +135,9 @@ declare function formatAge(ms: number): string;
  */
 declare function resolveSteps(facts: IntegrationFacts): IntegrationStep[];
 /**
- * Collapse the ladder to the single status the surfaces switch on. Live
- * conditions — a run in flight, a failure, a heartbeat gone quiet — win over
- * ladder position, because they describe the integration as it is now rather
- * than how far setup once got.
+ * Collapse the ladder to the single status the surfaces switch on. This is the
+ * setup dimension only: it answers how far configuration got, never whether the
+ * app is up. Pair it with `deriveLiveness` for the second half of the picture.
  */
 declare function deriveStatus(steps: IntegrationStep[], facts: IntegrationFacts): IntegrationStatus;
 interface NextAction {
@@ -66,6 +146,13 @@ interface NextAction {
   label: string;
 }
 interface IntegrationState {
+  /**
+   * Is the app running right now. Deliberately alongside `status` rather than
+   * folded into it: a surface must be able to say "setup reached mapping" and
+   * "the app is offline" in the same breath without either overwriting the
+   * other.
+   */
+  liveness: ConnectionLiveness;
   next: NextAction | null;
   status: IntegrationStatus;
   steps: IntegrationStep[];
@@ -82,7 +169,7 @@ declare const INSTALL_COMMAND = "npx clivly init";
  * as the fix for a write problem (C-05). If you need a command for the
  * next-action slot, call this — do not write another one.
  */
-declare function nextAction(steps: IntegrationStep[], status: IntegrationStatus): NextAction | null;
+declare function nextAction(steps: IntegrationStep[], status: IntegrationStatus, liveness: ConnectionLiveness): NextAction | null;
 declare function computeIntegrationState(facts: IntegrationFacts): IntegrationState;
 //#endregion
-export { INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, IntegrationFacts, IntegrationState, IntegrationStatus, IntegrationStep, NextAction, RunFact, STEP_PREREQUISITES, StepId, StepProblem, StepState, computeIntegrationState, deriveStatus, formatAge, nextAction, resolveSteps, stepIndex };
+export { ConnectionHealth, ConnectionLiveness, DEFAULT_HEARTBEAT_INTERVAL_MS, DeploymentPresence, HostEnvironment, INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, IntegrationFacts, IntegrationState, IntegrationStatus, IntegrationStep, NextAction, PresenceConnectionState, PresenceTransport, RunFact, STEP_PREREQUISITES, StepId, StepProblem, StepState, computeIntegrationState, deriveLiveness, deriveStatus, formatAge, livenessWindows, nextAction, resolveSteps, stepIndex };

package/dist/integration-state.d.mts

@@ -3,7 +3,13 @@ declare const INTEGRATION_STEPS: readonly ["credential", "application", "schema"
 type StepId = (typeof INTEGRATION_STEPS)[number];
 /** `blocked` means "prerequisite unmet", never "broken" — see C-19. */
 type StepState = "done" | "active" | "blocked" | "failed" | "skipped";
-type IntegrationStatus = "not_configured" | "sdk_installed" | "awaiting_connection" | "connected" | "schema_discovered" | "mapping_required" | "trigger_required" | "ready_to_sync" | "syncing" | "healthy" | "warning" | "error" | "disconnected";
+type IntegrationStatus = "not_configured" | "sdk_installed" | "awaiting_connection" | "connected" | "schema_discovered" | "mapping_required" | "trigger_required" | "ready_to_sync" | "syncing" | "healthy" | "warning" | "error" |
+/**
+ * @deprecated No longer derived. Liveness is its own dimension — read
+ * `ConnectionHealth` from `deriveLiveness`. Setup progress does not move
+ * backwards just because an app stopped running.
+ */
+"disconnected";
 declare const INTEGRATION_STEP_LABELS: Record<StepId, string>;
 /** Each step's prerequisites. Ordering is enforced by a test, not convention. */
 declare const STEP_PREREQUISITES: Record<StepId, readonly StepId[]>;
@@ -13,8 +19,20 @@ interface RunFact {
   message?: string;
   ok: boolean;
 }
+/**
+ * Where the reporting app is running, as the app itself understands it.
+ *
+ * `unknown` is a real value, not an absence: `detectHostEnvironment` refuses to
+ * guess when nothing places the app, and a bare `node server.js` with no
+ * NODE_ENV must still be able to connect and be shown as itself. Defaulting
+ * such a host to `local_dev` would file a production box's faults under local
+ * development, where nobody would look for them.
+ */
+type HostEnvironment = "local_dev" | "preview" | "production" | "unknown";
 interface IntegrationFacts {
   discoveredTableCount: number;
+  /** The environment the app reported on its last heartbeat. */
+  environment?: HostEnvironment | null;
   /**
    * Has this app ever checked in? Distinguishes "never installed" from "was
    * working, now silent" — the same absent heartbeat means different things,
@@ -22,10 +40,27 @@ interface IntegrationFacts {
    */
   everConnected: boolean;
   hasCredential: boolean;
+  /**
+   * The cadence the app said it heartbeats at. Liveness windows are multiples
+   * of this rather than a fixed constant, so an app that deliberately reports
+   * slowly is not called dead for obeying its own configuration.
+   */
+  heartbeatIntervalMs?: number | null;
   lastHeartbeatAt: number | null;
   lastRun: RunFact | null;
   mappedEntityCount: number;
   now: number;
+  /**
+   * Deployment presence, when this deployment has one. Absent or `http`
+   * transport keeps the cadence-derived behaviour every SDK in the field uses.
+   */
+  presence?: DeploymentPresence | null;
+  /**
+   * Faults the running app diagnosed about itself on its last heartbeat — an
+   * unreadable database, a secret missing from the process environment. These
+   * are what make a reachable app `live_with_issues`; unfinished setup is not.
+   */
+  reportedIssues?: StepProblem[];
   syncInFlight: boolean;
   /** A trigger URL and secret both exist, so Clivly can ask the app to sync. */
   triggerConfigured: boolean;
@@ -46,6 +81,52 @@ interface IntegrationStep {
   state: StepState;
 }
 declare function formatAge(ms: number): string;
+/** The cadence `createClivlySDK` uses when the host app configures none. */
+declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 60000;
+type ConnectionHealth = "live" | "live_with_issues" | "stale" | "offline";
+/** Which algorithm decides whether this deployment is up. */
+type PresenceTransport = "websocket" | "http";
+type PresenceConnectionState = "connected" | "reconnecting" | "disconnected";
+/**
+ * A deployment's connection state as its `PresenceRoom` last persisted it.
+ *
+ * This exists because a socket has an explicit state and a timestamp does not.
+ * Deriving WebSocket liveness from heartbeat age would leave a disconnected app
+ * shown as live for 150 seconds and offline only after ten minutes, which is
+ * the whole reason this transport exists.
+ */
+interface DeploymentPresence {
+  /** Sockets currently accepted in the room. */
+  activeInstanceCount: number;
+  connectionState: PresenceConnectionState;
+  transport: PresenceTransport;
+}
+interface ConnectionLiveness {
+  /** `"8s ago"`, or `"No heartbeat yet"` when the app has never reported. */
+  ageLabel: string;
+  ageMs: number | null;
+  environment: HostEnvironment | null;
+  health: ConnectionHealth;
+  /**
+   * Faults on a reachable app. Empty unless `health` is `live_with_issues`.
+   */
+  issues: StepProblem[];
+  /** Present when a deployment-presence record supplied this liveness result. */
+  presence?: Pick<DeploymentPresence, "connectionState" | "transport">;
+  /** Is a heartbeat recent enough to speak for the app as it is right now? */
+  reachable: boolean;
+}
+/**
+ * The two boundaries that separate live from stale from offline, in terms of
+ * the app's own reported cadence. A cadence we cannot believe — absent, zero,
+ * negative — falls back to the SDK default rather than producing a window of
+ * zero that would call every app offline.
+ */
+declare function livenessWindows(intervalMs: number | null | undefined): {
+  liveMs: number;
+  staleMs: number;
+};
+declare function deriveLiveness(facts: IntegrationFacts): ConnectionLiveness;
 /**
  * Walk the ladder once. A step is `blocked` when an earlier step it needs has
  * not been satisfied — a prerequisite statement, not a verdict about this step
@@ -54,10 +135,9 @@ declare function formatAge(ms: number): string;
  */
 declare function resolveSteps(facts: IntegrationFacts): IntegrationStep[];
 /**
- * Collapse the ladder to the single status the surfaces switch on. Live
- * conditions — a run in flight, a failure, a heartbeat gone quiet — win over
- * ladder position, because they describe the integration as it is now rather
- * than how far setup once got.
+ * Collapse the ladder to the single status the surfaces switch on. This is the
+ * setup dimension only: it answers how far configuration got, never whether the
+ * app is up. Pair it with `deriveLiveness` for the second half of the picture.
  */
 declare function deriveStatus(steps: IntegrationStep[], facts: IntegrationFacts): IntegrationStatus;
 interface NextAction {
@@ -66,6 +146,13 @@ interface NextAction {
   label: string;
 }
 interface IntegrationState {
+  /**
+   * Is the app running right now. Deliberately alongside `status` rather than
+   * folded into it: a surface must be able to say "setup reached mapping" and
+   * "the app is offline" in the same breath without either overwriting the
+   * other.
+   */
+  liveness: ConnectionLiveness;
   next: NextAction | null;
   status: IntegrationStatus;
   steps: IntegrationStep[];
@@ -82,7 +169,7 @@ declare const INSTALL_COMMAND = "npx clivly init";
  * as the fix for a write problem (C-05). If you need a command for the
  * next-action slot, call this — do not write another one.
  */
-declare function nextAction(steps: IntegrationStep[], status: IntegrationStatus): NextAction | null;
+declare function nextAction(steps: IntegrationStep[], status: IntegrationStatus, liveness: ConnectionLiveness): NextAction | null;
 declare function computeIntegrationState(facts: IntegrationFacts): IntegrationState;
 //#endregion
-export { INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, IntegrationFacts, IntegrationState, IntegrationStatus, IntegrationStep, NextAction, RunFact, STEP_PREREQUISITES, StepId, StepProblem, StepState, computeIntegrationState, deriveStatus, formatAge, nextAction, resolveSteps, stepIndex };
+export { ConnectionHealth, ConnectionLiveness, DEFAULT_HEARTBEAT_INTERVAL_MS, DeploymentPresence, HostEnvironment, INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, IntegrationFacts, IntegrationState, IntegrationStatus, IntegrationStep, NextAction, PresenceConnectionState, PresenceTransport, RunFact, STEP_PREREQUISITES, StepId, StepProblem, StepState, computeIntegrationState, deriveLiveness, deriveStatus, formatAge, livenessWindows, nextAction, resolveSteps, stepIndex };

package/dist/integration-state.mjs

@@ -30,8 +30,6 @@ const STEP_PREREQUISITES = {
 function stepIndex(id) {
 	return INTEGRATION_STEPS.indexOf(id);
 }
-/** A heartbeat older than this means the app stopped checking in. */
-const HEARTBEAT_STALE_MS = 600 * 1e3;
 function formatAge(ms) {
 	if (ms < 6e4) return `${Math.max(1, Math.round(ms / 1e3))}s ago`;
 	if (ms < 36e5) return `${Math.round(ms / 6e4)}m ago`;
@@ -40,12 +38,96 @@ function formatAge(ms) {
 function heartbeatAge(facts) {
 	return facts.lastHeartbeatAt === null ? null : facts.now - facts.lastHeartbeatAt;
 }
+/** The cadence `createClivlySDK` uses when the host app configures none. */
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 6e4;
+const LIVE_INTERVALS = 2.5;
+const STALE_INTERVALS = 10;
+/**
+* The two boundaries that separate live from stale from offline, in terms of
+* the app's own reported cadence. A cadence we cannot believe — absent, zero,
+* negative — falls back to the SDK default rather than producing a window of
+* zero that would call every app offline.
+*/
+function livenessWindows(intervalMs) {
+	const interval = typeof intervalMs === "number" && intervalMs > 0 ? intervalMs : DEFAULT_HEARTBEAT_INTERVAL_MS;
+	return {
+		liveMs: interval * LIVE_INTERVALS,
+		staleMs: interval * STALE_INTERVALS
+	};
+}
+/**
+* Faults worth showing on an app that is up. Deliberately excludes anything the
+* developer simply has not done yet — no schema, no mapping, no trigger are all
+* setup stages, and painting a fresh install amber would make the signal
+* meaningless.
+*/
+function livenessIssues(facts) {
+	const issues = [...facts.reportedIssues ?? []];
+	if (facts.lastRun && !facts.lastRun.ok) issues.push({
+		code: "sync_failed",
+		message: facts.lastRun.message ?? "The last sync run failed.",
+		fix: "Open the run log to see how your app responded."
+	});
+	return issues;
+}
+function websocketLiveness(facts, presence, base) {
+	if (!(presence.connectionState === "connected" && presence.activeInstanceCount > 0)) {
+		const health = presence.connectionState === "reconnecting" ? "stale" : "offline";
+		return {
+			...base,
+			health,
+			issues: [],
+			reachable: false
+		};
+	}
+	const issues = livenessIssues(facts);
+	return {
+		...base,
+		health: issues.length > 0 ? "live_with_issues" : "live",
+		issues,
+		reachable: true
+	};
+}
+function deriveLiveness(facts) {
+	const ageMs = heartbeatAge(facts);
+	const environment = facts.environment ?? null;
+	const { liveMs, staleMs } = livenessWindows(facts.heartbeatIntervalMs);
+	const base = {
+		ageMs,
+		ageLabel: ageMs === null ? "No heartbeat yet" : formatAge(ageMs),
+		environment,
+		...facts.presence ? { presence: {
+			connectionState: facts.presence.connectionState,
+			transport: facts.presence.transport
+		} } : {}
+	};
+	if (facts.presence && facts.presence.transport === "websocket") return websocketLiveness(facts, facts.presence, base);
+	if (ageMs === null || ageMs >= staleMs) return {
+		...base,
+		health: "offline",
+		issues: [],
+		reachable: false
+	};
+	if (ageMs >= liveMs) return {
+		...base,
+		health: "stale",
+		issues: [],
+		reachable: false
+	};
+	const issues = livenessIssues(facts);
+	return {
+		...base,
+		health: issues.length > 0 ? "live_with_issues" : "live",
+		issues,
+		reachable: true
+	};
+}
 /** Is the raw condition behind each step met, ignoring prerequisites? */
 function isSatisfied(id, facts) {
 	const age = heartbeatAge(facts);
 	switch (id) {
 		case "credential": return facts.hasCredential;
-		case "application": return age !== null && age < HEARTBEAT_STALE_MS;
+		case "application": return facts.everConnected || age !== null;
 		case "schema": return facts.discoveredTableCount > 0;
 		case "mapping": return facts.mappedEntityCount > 0;
 		case "trigger": return facts.triggerConfigured;
@@ -68,19 +150,6 @@ function problemFor(id, facts) {
 		message: facts.lastRun.message ?? "The last sync run failed.",
 		fix: "Open the run log to see the host response."
 	};
-	if (id === "application") {
-		const age = heartbeatAge(facts);
-		if (age !== null && age >= HEARTBEAT_STALE_MS) return {
-			code: "heartbeat_stale",
-			message: `Your app stopped checking in ${formatAge(age)}.`,
-			fix: "Start your app, then run `npx clivly status`."
-		};
-		if (age === null && facts.everConnected) return {
-			code: "heartbeat_stale",
-			message: "Your application stopped checking in.",
-			fix: "Start your app, then run `npx clivly status`."
-		};
-	}
 	return null;
 }
 /**
@@ -146,14 +215,12 @@ const STEP_STATUS_WHEN_ACTIVE = {
 	widget: "healthy"
 };
 /**
-* Collapse the ladder to the single status the surfaces switch on. Live
-* conditions — a run in flight, a failure, a heartbeat gone quiet — win over
-* ladder position, because they describe the integration as it is now rather
-* than how far setup once got.
+* Collapse the ladder to the single status the surfaces switch on. This is the
+* setup dimension only: it answers how far configuration got, never whether the
+* app is up. Pair it with `deriveLiveness` for the second half of the picture.
 */
 function deriveStatus(steps, facts) {
 	if (facts.syncInFlight) return "syncing";
-	if (steps.find((step) => step.id === "application")?.problem?.code === "heartbeat_stale") return "disconnected";
 	if (steps.some((step) => step.state === "failed")) return "error";
 	const blocking = steps.find((step) => step.state === "active" || step.state === "blocked");
 	if (blocking) return STEP_STATUS_WHEN_ACTIVE[blocking.id];
@@ -208,13 +275,13 @@ const NEXT_BY_STEP = {
 * as the fix for a write problem (C-05). If you need a command for the
 * next-action slot, call this — do not write another one.
 */
-function nextAction(steps, status) {
+function nextAction(steps, status, liveness) {
 	if (status === "healthy" || status === "syncing") return null;
 	const blocking = steps.find((step) => step.state === "failed") ?? steps.find((step) => step.state === "active");
 	if (!blocking) return null;
-	if (blocking.problem?.code === "heartbeat_stale") return {
-		label: "Reconnect your app",
-		command: "npx clivly status",
+	if (steps.find((step) => step.id === "application")?.state === "done" && !liveness.reachable) return {
+		label: "Start your app",
+		command: null,
 		envFile: null
 	};
 	return NEXT_BY_STEP[blocking.id];
@@ -222,11 +289,13 @@ function nextAction(steps, status) {
 function computeIntegrationState(facts) {
 	const steps = resolveSteps(facts);
 	const status = deriveStatus(steps, facts);
+	const liveness = deriveLiveness(facts);
 	return {
 		status,
 		steps,
-		next: nextAction(steps, status)
+		liveness,
+		next: nextAction(steps, status, liveness)
 	};
 }
 //#endregion
-export { INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, STEP_PREREQUISITES, computeIntegrationState, deriveStatus, formatAge, nextAction, resolveSteps, stepIndex };
+export { DEFAULT_HEARTBEAT_INTERVAL_MS, INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, STEP_PREREQUISITES, computeIntegrationState, deriveLiveness, deriveStatus, formatAge, livenessWindows, nextAction, resolveSteps, stepIndex };

package/dist/mapping-form.d.cts

@@ -1,4 +1,4 @@
-import { b as RelationshipsMap, m as FilterExpr, y as RelationshipVia } from "./entity-config-CLxI8dVb.cjs";
+import { b as RelationshipVia, h as FilterExpr, x as RelationshipsMap } from "./entity-config-buOIVtMM.cjs";
 //#region src/mapping-form.d.ts
 /**
  * A relationship the mapping UI can offer or has configured, in the shape the

package/dist/mapping-form.d.mts

@@ -1,4 +1,4 @@
-import { b as RelationshipsMap, m as FilterExpr, y as RelationshipVia } from "./entity-config-CLxI8dVb.mjs";
+import { b as RelationshipVia, h as FilterExpr, x as RelationshipsMap } from "./entity-config-buOIVtMM.mjs";
 //#region src/mapping-form.d.ts
 /**
  * A relationship the mapping UI can offer or has configured, in the shape the

package/dist/mappings-config.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config-Dh8aEcgj.cjs");
+const require_entity_config = require("./entity-config-Bfq3OkCU.cjs");
 //#region src/mappings-config.ts
 const RESERVED_FIELD = "id";
 /**
@@ -122,5 +122,29 @@ function mappingsToEntitiesConfig(rows) {
 	for (const { row, key } of assigned) entities[key] = buildEntity(row, refIndex);
 	return { entities };
 }
+const CUSTOM_CONCEPT = "custom";
+function entitiesToMappings(config) {
+	const rows = [];
+	for (const [entityKey, entity] of Object.entries(config.entities)) {
+		const row = {
+			entityKey,
+			sourceTable: entity.projection?.baseTable ?? entity.source,
+			targetConcept: entity.concept,
+			role: entity.role ?? DEFAULT_ROLE,
+			fieldMap: entity.projection ? {} : entity.fields
+		};
+		if (entity.filter) row.filter = entity.filter;
+		if (entity.relationships) row.relationships = entity.relationships;
+		if (entity.projection) row.projection = entity.projection;
+		if (entity.concept === CUSTOM_CONCEPT) {
+			row.objectTypeSlug = entityKey;
+			if (entity.objectType) row.objectType = entity.objectType;
+		}
+		if (entity.targetObjectTypeId) row.targetObjectTypeId = entity.targetObjectTypeId;
+		rows.push(row);
+	}
+	return rows;
+}
 //#endregion
+exports.entitiesToMappings = entitiesToMappings;
 exports.mappingsToEntitiesConfig = mappingsToEntitiesConfig;

package/dist/mappings-config.d.cts

@@ -1,4 +1,4 @@
-import { M as ProjectionMapping, a as ClivlyEntitiesConfig } from "./entity-config-CLxI8dVb.cjs";
+import { P as ProjectionMapping, a as ClivlyEntitiesConfig, h as FilterExpr, x as RelationshipsMap } from "./entity-config-buOIVtMM.cjs";
 //#region src/mappings-config.d.ts
 /**
  * Mappings → Entity Config bridge.
@@ -43,5 +43,43 @@ interface EntityMappingRow {
  * eligible — a no-op the view compiler and sync engine both tolerate.
  */
 declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
+/**
+ * Entity Config → Mappings, the inverse of `mappingsToEntitiesConfig`.
+ *
+ * `objectType` in config creates the custom object but nothing creates the
+ * MAPPING, so config-as-code ended at a created object and a sync that stored
+ * nothing. This produces the rows that close that gap.
+ *
+ * The two shapes align column for column, with one asymmetry that cannot be
+ * resolved by naming: the row model has no entity-key column — a row is keyed by
+ * `(sourceTable, targetConcept, role)` — while a CUSTOM entity's key *is* its
+ * object type slug, and is routinely different from its source table
+ * ("client-accounts" derived from "accounts"). So the key travels explicitly on
+ * every row rather than being left for the reverse derivation to guess.
+ */
+interface MappingFromConfig {
+  /**
+   * The config entity key this row came from. Not a row column — the caller
+   * needs it to resolve a custom object type and to report what it wrote.
+   */
+  entityKey: string;
+  fieldMap: Record<string, string>;
+  filter?: FilterExpr;
+  /** Declared custom object, when the config declares one rather than pinning an id. */
+  objectType?: {
+    iconKey?: string;
+    name: string;
+    pluralName?: string;
+  };
+  /** The custom object type's slug — the entity key. Custom entities only. */
+  objectTypeSlug?: string;
+  projection?: ProjectionMapping;
+  relationships?: RelationshipsMap;
+  role: string;
+  sourceTable: string;
+  targetConcept: string;
+  targetObjectTypeId?: string;
+}
+declare function entitiesToMappings(config: ClivlyEntitiesConfig): MappingFromConfig[];
 //#endregion
-export { EntityMappingRow, mappingsToEntitiesConfig };
+export { EntityMappingRow, MappingFromConfig, entitiesToMappings, mappingsToEntitiesConfig };

package/dist/mappings-config.d.mts

@@ -1,4 +1,4 @@
-import { M as ProjectionMapping, a as ClivlyEntitiesConfig } from "./entity-config-CLxI8dVb.mjs";
+import { P as ProjectionMapping, a as ClivlyEntitiesConfig, h as FilterExpr, x as RelationshipsMap } from "./entity-config-buOIVtMM.mjs";
 //#region src/mappings-config.d.ts
 /**
  * Mappings → Entity Config bridge.
@@ -43,5 +43,43 @@ interface EntityMappingRow {
  * eligible — a no-op the view compiler and sync engine both tolerate.
  */
 declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
+/**
+ * Entity Config → Mappings, the inverse of `mappingsToEntitiesConfig`.
+ *
+ * `objectType` in config creates the custom object but nothing creates the
+ * MAPPING, so config-as-code ended at a created object and a sync that stored
+ * nothing. This produces the rows that close that gap.
+ *
+ * The two shapes align column for column, with one asymmetry that cannot be
+ * resolved by naming: the row model has no entity-key column — a row is keyed by
+ * `(sourceTable, targetConcept, role)` — while a CUSTOM entity's key *is* its
+ * object type slug, and is routinely different from its source table
+ * ("client-accounts" derived from "accounts"). So the key travels explicitly on
+ * every row rather than being left for the reverse derivation to guess.
+ */
+interface MappingFromConfig {
+  /**
+   * The config entity key this row came from. Not a row column — the caller
+   * needs it to resolve a custom object type and to report what it wrote.
+   */
+  entityKey: string;
+  fieldMap: Record<string, string>;
+  filter?: FilterExpr;
+  /** Declared custom object, when the config declares one rather than pinning an id. */
+  objectType?: {
+    iconKey?: string;
+    name: string;
+    pluralName?: string;
+  };
+  /** The custom object type's slug — the entity key. Custom entities only. */
+  objectTypeSlug?: string;
+  projection?: ProjectionMapping;
+  relationships?: RelationshipsMap;
+  role: string;
+  sourceTable: string;
+  targetConcept: string;
+  targetObjectTypeId?: string;
+}
+declare function entitiesToMappings(config: ClivlyEntitiesConfig): MappingFromConfig[];
 //#endregion
-export { EntityMappingRow, mappingsToEntitiesConfig };
+export { EntityMappingRow, MappingFromConfig, entitiesToMappings, mappingsToEntitiesConfig };