# Configuration and execution lifecycle

Status: normative platform lifecycle contract, expanded 2026-09-08. This
L0/Core document owns the generic boundaries between application installation,
online configuration, request execution and durable work. It extends the former
online configuration/Catalog boundary in place; there is one normative read
path, not a separate lifecycle standard in each delivery repository.

[L0/L1 ownership](l0-l1-standard.md) governs who authors each fact. L0 owns the
generic storage, interpretation, versioning and execution mechanisms; L1 owns
product grammar and shipped defaults; L2 owns administrator-authored tenant
configuration and delivery composition; L3 owns user records and applicable
personal configuration. A fact's authoring layer is distinct from the L0 module
that stores and interprets it. L1 and L2 documents consume this contract and own
their product or deployment details. This contract does not redefine the
metamodel floor, workload admission, release topology or security authority.

## Rule

Any configuration editable through a product UI must be saved, activated and
observed through its domain owner without publishing, refreshing or upgrading
Catalog/AppRelease. The same rule applies to equivalent API and import entry
points; moving a save behind an API does not change its ownership.

This includes object/field definitions, picklists, RecordTypes, validation
rules, Flow and Approval definitions, Layouts/assignments, navigation, business
application settings, reports, list views and permission configuration. This
list defines the boundary, not a claim that all these authoring APIs exist.
Personal/user-authored configuration may be L3; administrator-authored metadata
is L2. L1 owns product grammar and shipped defaults, not subsequent org edits.

Catalog owns package identity, immutable release content, installation,
workload/capability admission and deployment selection. These remain legitimate
security and deployment checks. They must not become the revision authority for
mutable configuration or the step that makes an ordinary configuration edit
visible. Installing/removing executable applications is a release operation,
even if initiated through an administration UI; editing a business workspace,
menu or application label is configuration, not executable installation.

## Keep the consistency guarantees; separate their authority

- Each domain has one canonical fact owner and one effective read path. Its
  concurrency token or definition version belongs to that owner. Do not use
  CatalogRevision, AppReleaseDigest, HandlerBinding ownership or a compatibility
  receipt as that token.
- Request-local stable views and immutable executable definition versions are
  valid. Select them from the configuration owner's committed state; their
  existence does not imply Catalog publication. Durable work retains exact
  definitions until completion or an explicit migration, not whatever is live
  after restart.
- Schema changes still require identity/version conflict checks, physical DDL
  preparation, recovery and honest completion results. Schema/Persistence owns
  this evidence. Renaming CatalogRevision to a new number without changing the
  read/write authority is not a cutover.
- Permission edits still use the existing Permission State authority, grants,
  revocation and convergence rules. Do not freeze or bypass security changes
  required by the security owner merely to keep Catalog unchanged. Presentation
  edits must not manufacture security changes as a refresh signal.
- A cache or compiled artifact is derived, never a competing configuration
  registry. Do not retain a Catalog-first/live-fallback path for the same fact.
- Pack installation may seed managed defaults through their domain owner.
  Upgrades follow explicit managed/customized ownership and conflict rules;
  unrelated release publication must not sample live edits back into release
  truth or overwrite customized state, including intentional empty values.

## Separate code, runtime and lifecycle dependencies

Code dependencies point down: L2 consumes L1 and L1 consumes public L0
contracts; L0 must not import product or tenant implementations. Runtime
configuration can reference other domain facts: a Flow references fields,
subflows and installed actions; a Layout references schema and RecordTypes.
Those references require identity and compatibility validation, not a shared
release revision.

An ordinary edit using installed capabilities must not require Catalog or
AppRelease publication. An edit requiring a new, uninstalled capability may
require installation or upgrade first. Report that prerequisite explicitly;
an unrelated Catalog refresh is not a substitute for dependency validation.

## Facts, owners and effective state

| Fact | Canonical owner and authoring source | Effective state and retention |
|---|---|---|
| Package identity, immutable contents, dependencies and installed selection | Package publisher supplies release content; Catalog owns release/install selection. L1 supplies product defaults; L2 delivery may assemble permitted overlays. | Installation and upgrade select compatible releases. Preserve package provenance; current org configuration is owned below. |
| Service and frontend artifacts | Their build/deployment owners under the applicable release contract | Ordinary configuration editing does not rebuild these artifacts or introduce new deployment axes. |
| Objects, fields, relationships, RecordTypes and scoped picklist facts | Metadata/Schema owns canonical definitions; inputs are shipped defaults or authorized org edits. | Adopt committed definitions only after required physical preparation; retain the history needed by supported consumers. |
| Flow, Approval and validation definitions | Their domain definition/activation owner | Domain-defined save and activation rules select effective immutable versions; existing work retains its selected executable definition. |
| Layouts, navigation, reports and list views | Their domain owner, with product defaults and admin/user authorship as appropriate | Domain completion makes edits effective. Validate referenced schema through its owner, not a release copy. |
| Grants, revocation, session and workload authorization | Permissions / Permission State / Runtime Identity according to existing contracts | Security transitions keep their own current-state and revocation rules. A historical business definition is not an authorization receipt. |
| Queue records, interviews and execution bindings | Work owner, referencing definitions retained by their domain owners | Commit the binding with the work; restore exactly on retry or restart. |
| Caches and compiled artifacts | Derived by the source fact's owner | Key by source identity/version, scope and compatibility; never become an independent editable registry. |

The installation coordinator may orchestrate domain writes but must not become
a second writer of their canonical facts. A composite setup UI may coordinate
field creation, permission grants and layout changes; it must report each
owner's real completion instead of implying that one successful row insert
completed all three.

## Four lifecycles

### 1. Application publication and installation

Publish immutable package content → validate dependencies, namespaces and
capabilities → prepare installation/upgrade → apply permitted defaults and
migrations through domain APIs → verify readiness and compatibility → activate
the installed selection.

Installation operations need durable progress, idempotency and reconcilable
results. Do not pretend that DDL, domain transactions and external publication
form one rollbackable transaction. Package upgrade respects component/property
manageability: package-controlled facts follow their declared policy; editable
customizations survive according to the domain's explicit ownership rules.
Intentional empty values are not automatically missing defaults. Reuse the
existing managed/defaults policy rather than adding an overlay cache as a
second configuration authority.

A deployment rollback selects earlier compatible executable artifacts. It does
not automatically rewind tenant configuration or record data. Schema/data
reversal requires its own supported migration and evidence.

### 2. Online object and field changes

Authorize and check expected identity/version → durably claim the operation →
prepare physical storage → verify readiness → atomically commit canonical
metadata, its effective definition/version and the operation result → return
an honest completion receipt.

Preparation may span resumable steps. Accepted/in-progress is not success;
an ambiguous result is recovered through the original operation identity,
not retried as an unrelated create. New requests adopt the new definition only
when the owning completion condition holds. A normal supported Text field
addition changes the domain definition, not the installed AppRelease or
Catalog selection. Physical preparation and metadata publication must have a
recoverable boundary; a pointer swap alone does not prove DDL completion.

### 3. Executable configuration save and activation

Save draft → validate schema/subflow/action dependencies → produce an immutable
definition and any required compiled artifacts → atomically activate the
definition → select it for new execution.

Save is not necessarily activation. Each domain specifies its own authoring
surface; this sequence does not require a Flow-style draft API for every
validation rule. Activation checks that the validated dependency identities
and versions still hold, through suitable transaction constraints or expected
version checks. Asynchronous compilation may report progress; activation must
not report success before compilation and dependency preparation succeed.

An already-running Flow or Approval retains its promised definition. The
activation owner manages the effective pointer and retained history; publishing
Catalog is not its activation operation.

### 4. Requests and durable execution

A new request passes current identity and installed-capability admission,
selects compatible committed definitions from their domain owners, and keeps
that view stable for the request. Do not reselect latest in every getter or
mix Catalog and live authority for the same fact. Cross-domain consistency
comes from references, version preconditions and transaction boundaries; it
does not require a global configuration publication counter.

A producer commits required schema/executable definition references with durable
work. A consumer restores those same references, checks scope, integrity and
execution compatibility, and obtains current authorization under the existing
security protocol. Retry must not silently change the business definition;
retaining a definition must not bypass revoked access or credentials.

Definition retention does not preserve deleted physical columns or guarantee
access to an uninstalled action. Before field deletion, capability removal,
uninstall or history collection, inventory active requests, durable work and
other real consumers. Retain compatible execution conditions, explicitly
migrate/cancel affected work, or reject the destructive operation. Never delete
a referenced dependency and let the worker guess a replacement. Garbage
collection and backup restoration are not substitutes for this protocol.

## Independent version meanings

| Axis/reference | Meaning |
|---|---|
| AppRelease / package digest | Immutable release contents and declarations |
| Service/frontend release identities | Executable artifacts under their existing deployment contract |
| CatalogRevision | Release/install selection and its release-derived artifacts; not the current online configuration revision |
| Domain schema definition reference | Scope, lineage, revision and digest of the selected structure definition; an independent target authority, not a claim of a shipped wire type |
| Flow/Approval/other definition reference | The owning domain's immutable executable definition |
| SchemaGeneration | Existing physical-readiness/compatibility axis; do not redefine it as a per-edit schema counter or metamodel version |
| EngineGeneration | Interpreter semantics, distinct from schema content and physical readiness |
| Permission State / SecurityEpoch | Their existing distinct permission, identity and revocation protocols; do not merge them into schema or Catalog versions |

Execution bindings can carry several references and validate compatibility.
This does not prescribe a new central configuration catalog, table, service or
lock. Reusing a versioning primitive must not transfer fact ownership.

## External product evidence and its limits

Salesforce distinguishes package properties editable only by developers, by
both subscribers and developers, and by neither after release. For jointly
editable properties, the documented upgrade behavior preserves subscriber
customization. This supports separating default provenance from effective org
state; it does not imply that every property is editable. See the official
[package property manageability rules](https://developer.salesforce.com/docs/platform/pkg2-dev/guide/mdc-editable-property-definitions.html).

Salesforce documents that activating a Flow version deactivates the previous
active version while already-running interviews continue with the version on
which they started. See [Flow activation](https://help.salesforce.com/s/articleView?id=ls_activate_flow.htm&language=en_US&type=5)
and [Flow interviews](https://help.salesforce.com/s/articleView?id=platform.flow_interviews.htm&language=en_US&type=5).
That is evidence for executable-definition retention, not evidence that
Salesforce freezes the entire physical database schema for an interview.
NexusCRM's schema history and cross-domain binding design require their own
proof. Salesforce also documents a version-scoped release update requiring
flow access when resuming paused interviews; preserved versions are not
permanent access grants. See [resume access behavior](https://help.salesforce.com/s/articleView?id=release-notes.rn_automate_flow_release_update_resume_with_same_access.htm&language=en_US&release=246&type=5).

The mechanisms above are NexusCRM's normative design; the external references
support the specific product behaviors described, not a claim that Salesforce
uses this internal architecture.

## Recorded implementation audit and remaining coupling

The following audit records Core main `e013c59433219c8eb26d2bbc84055641b2cab974` and its consumed
Controlplane `v0.2.121`. This is a dated static producer/consumer audit, not a fresh claim about the
current deployed BOM. Re-derive the selected domain's consumer map before
implementation. Earlier local
TiDB investigation proved same-release Catalog refresh and request stability;
that proves current mechanism, not suitability for online authoring. No new
runtime behavior is claimed by this documentation change.

| Surface | Current evidence | Disposition under this rule |
|---|---|---|
| Object/field shape and validation | [GetSchema](../../nexuscrm-metadata/metadata_service.go), [validation reads](../../nexuscrm-metadata/metadata_objects.go), and the shared [API/worker view seam](../../nexuscrm-metadata/runtime_metadata_context.go) select request-bound Catalog RuntimeMetadataView content. Controlplane `catalogreconcile/metadata.go` reads effective schemas and validation rules into publication. | Confirmed content coupling. Schema authoring is incomplete; adding a current writer alone will not make execution observe it. Migrate shape/validation authority across the real consumer closure. |
| Flow definitions and execution | [metadata_flows.go](../../nexuscrm-metadata/metadata_flows.go) reads definitions/versions from the bound mutation view. [flow_server.go](../../backend/internal/runtimeapi/flow_server.go) also selects AppMetadata components through Catalog. | Confirmed definition/selection coupling. Separate editable Flow activation from installed action/capability admission; retain immutable run plans and handler identity checks. |
| Approval definitions | [approval_catalog_authority.go](../../backend/internal/runtimeapi/approval_catalog_authority.go) explicitly uses Catalog definitions/nodes for new work; live rows only anchor legacy identity. [approval_server.go](../../backend/internal/runtimeapi/approval_server.go) consumes this adapter. | Confirmed executable-content coupling. An online Approval author must own definition versions and activation; preserve old-work identity and retention during cutover. |
| Report definitions | [report_server.go](../../backend/internal/runtimeapi/report_server.go) loads ReportDefinition from the bound RuntimeMetadataView before execution. | Confirmed report-content coupling. Editable report definition selection must come from the analytics owner, while installed capability admission remains valid. Dashboard authoring was not traced to the same level. |
| Layout/assignment/ListFields | [Layout V2](layout-authoring-runtime-domain.md) writes current storage independently. [page_layout_resolution_server.go](../../backend/internal/runtimeapi/page_layout_resolution_server.go) reads current layouts but validates object/RecordType and related-list context against Catalog, with MinCatalogRevision. | Content already has its owner; context is still coupled. Do not republish Layouts. Newly edited schema/RecordType context must cease depending on release publication. |
| Private list views | [list_view_server.go](../../backend/internal/runtimeapi/list_view_server.go) calls current private-list reader/authoring ports, but checks object existence through the bound Catalog view and accepts MinCatalogRevision on reads. | Content is not proved release-owned. Record the schema-context dependency; do not misclassify the entire authoring path from a receipt field alone. |
| Navigation | [application_navigation_server.go](../../backend/internal/runtimeapi/application_navigation_server.go) explicitly serves current domain documents without claiming a Catalog revision. | Correct direction. Installed application/workload admission is allowed. New navigation targets must not inherit stale mutable-schema authority. See the domain plan for initializer/upgrade preservation. |
| Metadata administration read | [metadata_admin_read_admission.go](../../backend/internal/runtimeapi/metadata_admin_read_admission.go) uses workload admission; [metadata_admin_read_server.go](../../backend/internal/runtimeapi/metadata_admin_read_server.go) rejects a requested Catalog minimum instead of fabricating a receipt. | Current admin read is not Catalog configuration publication. It does not prove downstream records/worker adoption. |
| Permission authoring | Dedicated current-state owner and Permission State coordination remain required; runtime schema-dependent permission interpretation shares the shape boundary above. | Do not infer that permission grants themselves are frozen Catalog content. Audit the particular grant/shape fact; retain all current authorization and revocation guards. |

These findings identify owner work, not authorization to remove security gates
or every use of the word `catalog`. A formula function catalog, schema metamodel
catalog or Flow capability catalog can be a generic registry with a different
owner. Determine the fact and lifetime before classifying it. Likewise, package
release contents can legitimately contain initial templates and code-backed
capabilities; the error is making current UI configuration depend on republishing
them.

## Documentation corrections and precedence

- The App authority fact table and its JSON/owner guard previously assigned all
  L2 metadata/effective revisions to Catalog. That assignment is replaced with
  a domain-owned online-configuration fact; Catalog publication remains a
  separate release/deployment plane. The guard rejects Catalog as configuration
  authority. These are internal architecture manifests, not Runtime wire edits.
- The serviceification design now scopes its summary, diagram, Catalog owner,
  projection lineage, store/credential policy, version axes and publication
  state machine to release facts. Domain configuration has independent
  versions and completion. The former blanket ownership statements are removed
  from the body, not merely overridden by a header. Its remaining description
  of deployed Catalog-backed carriers is explicitly migration evidence.
- Layout's content independence does not make its remaining Catalog schema and
  RecordType checks the permanent target. The Layout document distinguishes
  current behavior from this boundary.
- The root agent guide's broad “L1 owns metadata/config” shorthand is narrowed
  to shipped defaults and product grammar. It must not override L2/L3 authorship.

This boundary does not silently delete published wire fields, stored artifact
formats or old durable-work references. Those require a supported-consumer and
retention migration in their owning repositories. A document correction is not
proof that implementation or released contracts have already migrated.

## Required proof for a configuration cutover

1. Inventory current writers, effective readers, caches/compilers, API and worker
   compositions, installed defaults and durable references for the selected
   domain. Separate the editable fact from executable capability admission.
2. Freeze Catalog/AppRelease publication and deployment bindings for an already
   installed app; disable publication/reconcile writes. Authorized save,
   activation, exact readback and the real user/record execution journey must
   still work. Security owner transitions required by a permission edit remain
   enabled.
3. Prove concurrent-edit conflicts, no-op behavior, ambiguous commit retry,
   restart, cross-replica adoption, and any physical schema preparation. Success
   must mean the documented domain completion condition, not “admin storage
   contains a row.”
4. Hold an old request or durable run across an edit; prove its promised stable
   version and that new work observes the committed configuration. No fallback
   to another authority is allowed.
5. Publish an unrelated AppRelease afterwards; prove customized configuration,
   including empty values, survives under explicit domain ownership rules.
6. Switch the complete selected consumer closure and remove the replaced
   authority path in one scoped delivery. Do not expose competing live and
   Catalog implementations as an indefinite compatibility mode.

## Bounded delivery and first schema proof

Deliver each selected fact through its complete writer/reader closure. For a
schema fact this includes its actual permission, Layout, query and worker
consumers; it does not automatically include migration of every Flow,
Approval or report definition. Keep a domain ledger of completed and remaining
cutovers. Documentation status is target documented, not implementation done.

The first schema walking slice freezes installed AppRelease, Catalog selection
and deployment; adds a supported Text field on an existing object; receives
real completion; grants appropriate access; and proves record read/write from
a second instance. Hold an old request across the edit and restart a worker
with previously bound work to prove the promised view and exact recovery.
Then publish an unrelated application update and prove org customizations,
including explicit empty values, survive. Permission-owner transitions remain
enabled throughout. Exercise the conflict, ambiguous-result and failure cases
in the required proof above; a skipped real path is not a pass.

Before implementation, decide the selected definition's field scope, all writer
coverage, dependency checks, supported old-work decoding/retention and
constraints on destructive changes. Close those decisions with evidence in the
owning domain. This document changes the contract and its references; it does
not assert that any remaining Catalog-backed implementation has migrated.