# Activated App metadata selection

AppMetadata and IntegrationBinding readers consume the immutable snapshot selected
by the App's activated operation. The existing org revision allocator is unchanged;
another App's publication does not relabel this App's content. Current permissions
and committed security receipts are still checked. A full Layout publication is
not a substitute for this selection.

Normal Reconcile callers already commit the selection. Direct Authority callers
must call `CommitOperationMetadataSelection` (or the variant with complete effective
components for AppMetadata V2/V3) before `CommitServingArtifacts`. A missing selection
returns `ErrNotReady` while the same candidate is still repairable. Activation
checks the invariant again. No new table or fallback read path is introduced.

## Before upgrading an existing deployment

First complete or recover any in-flight upgrade/rollback through its existing
operation. A new same-release refresh requires an idle ACTIVE installation; do
not start a second operation while its writer is occupied.

Run this read-only inventory against its Catalog database. It locates current
activated consumer operations with no unique metadata selection, including
states created by older direct Authority callers that omitted the commit:

```sql
SELECT i.OrgId, i.AppInstallationId, i.AppId, i.ActiveReleaseDigest,
       i.CatalogRevision, COUNT(j.OperationId) AS SelectionCount
FROM _System_CatalogAppInstallation AS i
LEFT JOIN _System_CatalogAppOperation AS o
  ON o.AppInstallationId = i.AppInstallationId
 AND o.State = 'ACTIVE' AND o.Step = 'ACTIVATED'
 AND o.TargetReleaseDigest = i.ActiveReleaseDigest
 AND o.ExpectedCatalogRevision = i.CatalogRevision
LEFT JOIN _System_CatalogAppOperationJournal AS j
  ON j.OperationId = o.OperationId AND j.Step = 'METADATA_SELECTION_COMMITTED'
WHERE i.State = 'ACTIVE' AND i.ActiveOperationId IS NULL
  AND EXISTS (SELECT 1 FROM _System_CatalogConsumerGrant AS g
              WHERE g.OperationId = o.OperationId)
GROUP BY i.OrgId, i.AppInstallationId, i.AppId, i.ActiveReleaseDigest, i.CatalogRevision
HAVING COUNT(j.OperationId) <> 1;
```

A zero-row result clears the missing-selection preflight, not every integrity
check: the actual reader also verifies snapshot digest/org/revision, complete
grants, the unique activated operation, effective components, and security lineage. Duplicate selections or
operations are corruption to investigate, not permission to choose an arbitrary row.

For a missing selection, use the deployment's existing App publication producer
before promoting the new reader:

1. Start the existing `OperationUpgrade` with the same installation and active
   release, `RefreshActiveRelease: true`, an immutable continuation-intent digest,
   and fresh expected org revision/security epoch. Preserve the complete workload,
   capability, handler, frontend, integration and grant selection.
2. Run its normal snapshot producer/store and commit the new operation's exact
   metadata selection, with complete effective components when required. Stage the
   serving artifacts through their existing APIs, commit serving, publish/acknowledge
   security, and complete the operation. Reuse the same request for retries.
3. Verify the unchanged release is now active at the new revision, read its exact
   AppMetadata/IntegrationBinding view, and rerun the inventory before promotion.

This is the existing same-release refresh API, not an instruction to alter journal
rows or reuse another App's snapshot. An activated operation is immutable; its missing
history is retained while the new operation supplies the current selection. Do not
automatically invent metadata from a digest-only journal entry.

`TestCatalogConsumerViewsTiDBReadOneAuthorizedRevision` exercises V1's missing
selection rejection, completion of the same candidate, distinct App A/B selections,
and recovery of a persisted missing-selection shape using this refresh, with a real
TiDB and snapshot store. `TestCatalogAppTiDB/IdentityReleaseNamespaceAndGrantConflicts`
also exercises the complete V2/Integration grant set and the pre-serving fence.