Object Model

The object model has two planes that describe the same things from opposite directions: editable metadata you author and deploy, and the read-only describe layer the org exposes so it can be queried about itself. Getting this split right is a foundational decision, so it is documented up front. But before the two planes, the catalog itself: the bounded set of metadata types the kernel is generic over.

The metadata universe — a bounded set of types

The kernel is generic over a fixed catalog of metadata types. It never hard-codes “Quote” or “Account”; it knows only these types, and every org is some combination of instances of them. Bounded types, virtually-infinite combinations — that is the whole game. Adding a genuinely new kind of thing to the platform is not a bespoke feature; it is a new schema plus an interpreter. It’s schemas all the way down: each row below is itself described by a schema (“an Object has a key, a label, a table, and a list of Fields”).

Some of these types exist in the prior working system already; some are future-state; and a handful are new under this architecture — introduced precisely because the engine and the interface are now separated, so the things that used to be compiled into the app must become metadata the kernel interprets.

Metadata type	What it is	Salesforce analogue
App	A named surface in the App Launcher — a bundle of tabs plus branding	CustomApplication
Tab	A pointer to an object (or a page) that appears in an app’s navigation	CustomTab
Object	A business entity — a database table	CustomObject / SObject
Field	A typed attribute on an object — a column	CustomField
Field Type	The bounded set of data types a field may be	field type set
Record Type	A variant of an object that shows/hides fields and drives layout. Every object has one real default; variants layer on top (no “Master” placeholder)	RecordType
Picklist / Value Set	A constrained, retire-able set of choices for a field	GlobalValueSet
Page Layout	Which fields and sections show on a record page, and in what order	PageLayout
List View	A saved, filtered, columned view of an object’s records	ListView
Page Template	A named-region blueprint pages are built from — the open single-container is one	Lightning page template
Page	A composed screen — a template plus components placed in its regions	FlexiPage
Web Component	A pixel-precise custom UI bundle placed on a page; inherits the host org’s design system	Lightning Web Component
Report	A saved query over one or more objects — columns, filters, groupings, aggregates; runs at the viewer’s access	Report
Dashboard	A composition of widget components, each bound to a report	Dashboard
Custom Metadata + Records	Admin-editable config deployed as metadata (rates, parameters, rules)	CustomMetadataType
Permission Set / Group	Additive grants of object / field / app / tab access	PermissionSet
Role (capability)	Coarse capability identity from the IdP claim; seeds base permission sets	Profile / Role
Identity Provider / Auth	An IdP the org trusts and how its claims map to users and roles	Auth. Provider / SAML SSO
Formula Field	A field computed from other fields on the same record	Formula field
Roll-Up Summary Field	A field that aggregates a child field onto its parent — sum, count, min, max	Roll-Up Summary Field
Calc Function (code)	Registered, versioned procedural code the platform invokes — the escape hatch for logic no formula expresses	Apex
Lifecycle (Process / Path)	The stages a record moves through, plus transition rules and gates	Flow / Path / Approval
Queue	A shared work bucket a lifecycle stage is owned by, or a gate routes to	Queue
Validation Rule	Save-time constraints on a record	ValidationRule
Automation / Flow	Declarative “when X, do Y” logic	Flow
Design System	The org’s whole look — tokens, component style variants, icons, wordmark. A deployable skin over the base	Lightning DS + Themes
AI Config	The org’s assistant grounding, actions, prompts, guardrails	Einstein / Agentforce
Package ⁘	A versioned distribution of metadata plus its capability registrations — optionally namespaced, optionally locked	Managed / Unlocked Package
Capability Registration ⁘	A package’s claim to be a platform capability (the shell, the setup app) or to extend one via an injection point; enforces one-master-per-capability	(no direct analogue)
Guidance Recipe + Anchor ⁘	Intent-based guidance steps referencing UI anchors by capability role, never by pixels — the metadata the Guidance Center and AI both read	(no direct analogue)

⁘ New under this architecture. The Package and Capability Registration types exist because UI is now installed rather than compiled — they are how a shell, a setup app, or an app arrives and claims its role. The Guidance Recipe + Anchor type exists because guidance must be a projection of the same metadata that renders the UI (see the Guidance Center). The describe layer below is likewise new: the org must be able to be queried about itself.

How the metadata plugs together — the five lanes

The catalog is long, but every type sits in one of five lanes, grouped by the role it plays. Read the map top-down: an org owns apps; an app is a set of tabs; a tab opens a page — a list view or a record page; a page is composed from a template and components and (when it’s a record or list page) bound to an object, which owns everything describing how it looks and behaves. A final lane cross-cuts all of it.

• Root — the Org (tenant). The single container. One request resolves to exactly one org; everything else is scoped inside it.
• Surface — App, Tab, Page. What a user navigates. An app bundles tabs; a tab opens a page — a list view, a record page, or a standalone home page.
• Composes a page — Page Template, Web Component, Dashboard. How a page is built. A page picks a template (its named regions) and hosts components in those regions; a record page also renders the object’s page layout; a dashboard composes widgets bound to reports.
• Entity — the Object. The thing a list view or record page is bound to. The gravitational center of the model.
• Describes the object — Field, Field Type, Value Set, Record Type, Page Layout, List View, Report, Validation Rule, Lifecycle, Automation. Everything that defines an object’s shape and behavior. Select fields point at a retire-able value set; reference fields point at another object; record types select a layout; the list view and page layout feed the object’s pages.
• Cross-cutting (org-scoped) — Permission Sets, Custom Metadata, Capability Roles, Identity / Auth, Design System, AI Config, Packages, Capability Registrations, Guidance. These don’t belong to a single object or surface; they apply across the whole graph. Identity authenticates who gets in; permission sets grant access; the design system skins every surface; packages deliver and register capabilities; AI config is grounded on the entire graph.

This map grows exactly as the catalog grows — a new metadata type joins a lane, it does not create a new mechanism.

Standard by default — it works before you customize anything

Create an object, add its fields, and you immediately get a tab, a default list view, a default record type, and a record page on the standard template with an auto-generated layout — no customization required. Every object is also born with a set of standard fields before any custom one: a record Id, its Name, an Owner, and the created / last-modified by-and-date audit fields. Every metadata type ships a sensible default and a standard look, so a customer can use the OS without configuring a single view. Customizing is optional, never a prerequisite.

The two planes

• Editable metadata (authoring source). The custom objects, custom fields, layouts, list views, permission sets, and apps a customer creates and changes. These are deployed through the CLI/API and appear in the Object Manager because they are things you edit.
• Read-only describe rows (metadata of metadata). Queryable rows that describe the org’s shape — every object, every field, standard vs custom, every permission set and its object/field permissions, which packages are installed. These are queryable like any object but never editable and never appear in the Object Manager. They are the org describing itself.

The same conceptual thing can have both faces: a custom field is editable source (you deploy and change it) and a read-only describe row (it shows up when you query the org’s fields). The two are different views of one fact, and the platform keeps them distinct — one editable, one query-only.

The describe layer, enumerated

The describe layer is the org describing itself. Every editable metadata definition is simultaneously reflected as a read-only describe row — a queryable record that reports what the metadata universe currently contains. Describe rows are never authored directly; they are projected by the Kernel from the deployed metadata and served through the same query surface as data (see The API Surface). They answer questions of the form “what objects, fields, layouts, and permissions does this org have?” and they answer them at read time, always consistent with what the kernel would use to render.

Each describe object is modeled on a Salesforce analog so that the semantics are already familiar to an architect. The final column records which plane each object lives in: metadata that is only ever a reflection (describe-only) versus metadata that is authored source in the Object Manager and reflected here (both). A row marked both is a single fact seen from two directions — the definition an author deploys and the description the org reports are the same underlying record, not two copies to be reconciled.

CAOS describe object	What it exposes	Salesforce analog	Editable source / describe-only / both
object_definition	Every object in the org — API name, label, key prefix, standard-vs-custom flag, enablement (history, audit)	EntityDefinition	both — custom objects are authored source; standard objects are platform-shipped and describe-only
field_definition	Every field on every object — API name, data type, length/scale, required, defaulting	FieldDefinition	both — custom fields are authored source; standard/system fields are describe-only
relationship_info	For a reference field, its target object, relationship name, and cascade/restrict behavior	RelationshipInfo (child relationships / FieldDefinition.ReferenceTo)	describe-only — projected from the reference field’s definition
record_type	The record types defined on an object and their picklist/layout bindings	RecordType	both
layout	Page layouts and the field/section arrangement each assigns	Layout	both
list_view	List views defined on an object — columns, filters, scope	ListView	both
value_set / picklist	Value sets and picklist entries, including active/retired state	GlobalValueSet / PicklistValue	both
permission_set	Permission sets in the org and their metadata	PermissionSet	both
permission_set_group	Permission set groups and their member sets, plus the resolved (calculated) permission surface	PermissionSetGroup	both
object_permission	Per–permission-set object CRUD grants (create/read/edit/delete/view-all/modify-all)	ObjectPermissions	describe-only — projected from permission-set metadata
field_permission	Per–permission-set field-level security (readable/editable)	FieldPermissions (FLS)	describe-only — projected from permission-set metadata
package_install	Installed packages — namespace, version, install state, provenance	InstalledSubscriberPackage	describe-only — reflects the install ledger
capability_registration	For each capability, which package masters it and which packages inject into it	(none — CAOS-specific)	describe-only
api_version / org_info	Org identity, edition/feature enablement, current API version, home instance and region	Organization / API-version resource	describe-only

capability_registration has no Salesforce analog because it describes a mechanism unique to the CAOS packaging model: capabilities are declared by a mastering package and extended by injecting packages, and the describe layer reports that ownership graph so the resolved behavior of any capability is queryable without inspecting package internals.

What appears in the Object Manager, and what does not

The Object Manager is an editing surface. It manages editable metadata — the custom objects, fields, record types, page layouts, list views, permission sets, and apps that an org deploys and subsequently changes. Everything an author can create, alter, or retire is reachable there, and every change made there is a change to the deployed metadata the kernel interprets.

Describe rows do not appear in the Object Manager. They are query-only reflections of that same metadata, not independent things to edit, and surfacing them in an editing surface would misrepresent their nature. object_permission and field_permission, for example, are projected from permission-set definitions; the authored source of those grants is the permission set, and that is where the Object Manager exposes them. Presenting the projected object_permission row as an Object Manager entry would invite the illusion that it can be edited in place, when in fact it can only change by editing the permission set it derives from.

The split is therefore deliberate rather than incidental. Authored source belongs to the editing surface; the org’s description of itself belongs to the query surface. A definition that is authored source and a describe row (an object_definition, a field_definition) is edited in exactly one place — the Object Manager — and read in the other — a describe query. Standard, platform-shipped definitions have no authored source in the org at all and so appear only as describe rows.

Query semantics

Describe rows are retrieved through the same query language and Data API that serve record data (see The API Surface). An org asks “what objects do I have?”, “what fields are on this object?”, or “which permission sets grant edit on this field?” with the same query mechanics used to ask “which records match this filter?” There is no separate describe protocol; the describe objects are queryable objects like any other, distinguished only by being projections of metadata rather than stored business records.

Describe queries are strictly read-only. The query surface exposes no insert, update, upsert, or delete path against a describe object — a describe row changes only when the underlying metadata is redeployed, never through a write to the describe object itself. Any mutation of the metadata universe flows through metadata deployment (the Object Manager or a package install), and the describe layer re-projects to match.

Reads of describe rows are subject to the access engine on the same terms as reads of data. A describe query resolves the caller’s permissions and returns only the objects, fields, and permission metadata the caller is authorized to see; describe access is not a privileged side channel. Describing the org is a read, and it is checked like every other read.

Provisioning objects

Provisioning metadata defines how a new org is brought into existence and what it contains at birth. Three constructs carry this:

• Org type — the classification of an org (for example, production, sandbox, scratch, or a partner/customer edition). The org type governs lifecycle policy, retention, and which feature sets are eligible.
• Org shape — a starter bundle: a named set of packages to install, the default metadata to seed, and the starting configuration to apply. A shape is the reusable definition of “what a fresh org of this kind looks like on day one,” so that provisioning is reproducible rather than hand-assembled.
• Feature set — the switchable capabilities an org type or shape enables or withholds, expressed as metadata so that entitlement is declarative and auditable.

A provisioning request is the act of instantiating a shape. To be complete, a request must capture: the region the org is homed in; the home instance that will own the org’s data and serving (see Instances & Trust, where an org’s home instance and region are the resolved outcome of provisioning); the initial administrator identity that receives the first permission grants; and the org’s brand/identity — its name, login configuration, and identity/auth binding. These inputs, applied to the shape’s package and metadata bundle, yield a fully formed, self-describing org.

Org types, shapes, and feature sets are configuration metadata: they are authored, versioned, and deployed like any other metadata, and platform-shipped shapes are standard. The resolved facts about a provisioned org — its home instance, its region, its install ledger — are describe-only, projected after provisioning resolves and queryable through the describe layer but never edited there.

Standard vs custom

Every metadata definition is marked as either standard (platform-shipped) or custom (customer-authored), and that distinction is visible in both planes.

In the describe plane, a boolean is_custom (equivalently is_standard) flag on each describe row reports the provenance of the definition — an object_definition or field_definition states plainly whether the platform shipped it or the org authored it. In the editable plane, the same distinction is carried by an API-name convention: customer-authored definitions bear a reserved marker on their API name — a namespace prefix and/or a __ suffix — so that a custom object or field is syntactically distinguishable from a standard one at every point it is referenced, in queries, layouts, formulas, and package manifests alike. The two signals agree: the flag on the describe row and the naming convention on the API name report the same fact.

The distinction is load-bearing for upgrade semantics. Standard objects and fields are owned by the platform: they are carried forward and evolved by platform releases, and an org receives their improvements without action. Custom metadata is owned by the org that authored it (or by the package that masters it): it is not touched by platform upgrades, it is the org’s to change and to migrate, and it is the unit that packaging and provisioning move between orgs. Keeping the boundary explicit in both planes is what lets the platform upgrade its own surface without disturbing customer-authored metadata, and lets an org reason about which parts of its metadata universe it controls.