Governing a Salesforce Org You Never Let Us Touch

A governance tool pointed at your CRM is asking for a lot of trust. Your Salesforce org holds the pipeline, the customer list, and the revenue numbers; any tool that wants to "govern" it should have to say, precisely, what it will and will not do. So before we describe what the CoreModels Salesforce integration does, here is what it refuses to do — because the trust story is the product.

No credentials, ever

CoreModels never connects to your org. There is no OAuth grant to your Salesforce instance, no stored connected-app secret, no background sync job with org access. You run the describe export yourself — with the Salesforce CLI or any REST client — and upload the resulting JSON. A live describe pull is a capability we have deliberately deferred rather than quietly shipped: the current design decision is that the extraction step stays in your hands, on your side of the boundary.

This is not a limitation we apologize for. It means the blast radius of the integration is exactly one JSON file that you produced and inspected, and it means every question of org access is answered by your own tooling and your own audit logs, not ours.

Import is additive — meaning changes are a human act

When you import a describe export, CoreModels adds what is new: objects that are not yet governed become Types, ungoverned fields become Elements, active picklists become Taxonomies. What it never does is mutate or delete an existing governed node. If the org has changed a field's type, or dropped a value from a picklist, the import does not "helpfully" update the governed model to match. Re-importing is safe by construction, because already-governed datasets are skipped, not overwritten.

Surfacing the difference is the audit's job — and the audit is evidence, not enforcement. It reports drift as coded findings: a field removed, a type drifted, a value set narrowed or widened, an enum constraint gone. What happens next is a decision, and it belongs to a person. Maybe the org is right and the model should be updated; maybe the model is right and the org change should be reverted. CoreModels will not make that call, because a meaning change that nobody chose is precisely the failure mode this whole system exists to prevent.

The audit itself is strictly read-only, and even its bookkeeping is opt-in: an audit run is only recorded into the rolling history when the caller asks for it. The one exception is deliberate and symmetrical — the re-audit verb, which checks the stored org snapshot against the current governed model, always records its run, because a drift check with no record is a drift check that never happened.

Lossiness is reported, not hidden

Every translation between systems loses something, and the honest options are two: pretend otherwise, or say exactly what was lost. CoreModels imports and generations return a lossiness list alongside their results — a success can still carry an itemized account of what was approximated or dropped.

The Salesforce connector has real examples. A polymorphic lookup — a field that can point at more than one kind of object — is governed as a reference to its first target, and the full target list is preserved as metadata; the audit then reports the fact as a polymorphic-reference finding, so the approximation is never silent. Going the other way, Salesforce checkboxes cannot be marked required in metadata, so a governed NotNull on a boolean field is dropped at generation time — with a lossiness record saying so. And for very large orgs, when the encoded snapshot exceeds the storage cap, the import says snapshotStored: false with a lossiness record, rather than pretending re-audit will work later. You may not love every entry in a lossiness list, but you will never be surprised by an absence it didn't declare.

Drift as a trail, not a moment

A single audit is a point-in-time check. Governance needs a timeline. Every recorded run — CI audits, manual audits, re-audits — lands in a rolling history with its counts, finding codes, and artifact fingerprint, so "when did this drift start?" has a factual answer. The status badge renders the latest recorded run as a self-contained SVG: green for clean, yellow for warnings, red for errors, gray when nothing has been recorded yet. Grey is a governance statement too — it tells you, honestly, that nobody is watching.

The loop runs in both directions. A fresh describe export can be audited against the governed model (did the org drift?), and the governed model can be re-audited against the snapshot stored at import (did the model move away from the last-known org?). Both directions produce evidence; neither produces automatic action.

Generated artifacts are proposals, not deployments

CoreModels closes the loop by generating Metadata-API CustomObject XML from the governed model — restricted picklist value sets from taxonomies, Lookups from governed references, required flags from NotNull, governed-first fields minted with the __c suffix. And then it stops. The scaffolds are handed to you as files, for review and deployment through your org's normal change process: your pull requests, your approvals, your deployment tooling. CoreModels never deploys to your org — it has no credentials with which it could, which is the same promise as the first one, arriving from the other direction.

Why the posture is the point

Each of these rules costs us a feature that would demo well: live sync, auto-apply, one-click deploy. We hold the line anyway, because the alternative is a tool that changes meaning faster than people can review it — which is just the original Salesforce problem wearing a governance badge. Additive import, human-gated change, declared lossiness, drift as recorded evidence, review-and-deploy: that is the contract, and every route in the integration is shaped by it.

The Salesforce quickstart in the CoreModels docs states these same guarantees next to every call — including an explicit list of what is not supported, by design.