# Connector 1000-Event Performance Learned

## 2026-07-08 object spec unique metadata loss

- Run: `pingcap-inc/nexuscrm-pingcap-pack/actions/runs/28906078892`.
- Runtime refs: NexusCRM `692f41df323a44593a06fa721f41f0c07abe526e`, downstream pack `649ae7967346c9367f8024b0f2ce6f3794ed02e5`, official app packs `9bcddf3c289aa1de28dd5c4bffe2a3dac8c6ceff`.
- Workload: 1000 inbound connector events, blocking simulation plus timing/profile artifacts.
- Profile result: `query_batch=0`, `flow_record_lookup_batch=0`, 1835 lookup profile events. Of those, 870 skipped batching with `batch_skip_reason=key_not_unique`; runtime diagnostics showed merged object specs and physical indexes had unique remote-id fields, while live `_System_Field.IsUnique` was `0`.
- What changed before this record: no code change yet; this entry records the evidence before the next fix.
- What failed: the object spec `unique` fact was not carried into the runtime metadata read path, so the Flow lookup batcher correctly failed closed instead of using physical indexes as a second source of truth.
- Learned: batching is blocked by a metadata SSoT loss, not by insufficient concurrency. The root fix belongs in generic object spec field conversion, preserving the declared unique fact into `ColumnDefinition` and `FieldMetadata`.
- Next hypothesis: after object spec `unique` propagation and a consumer pin update, matching lookups should show `batch_key_field_unique=true` and produce `flow_record_lookup_batch` / `query_batch` timing rows for unique-key lookup shapes.

## 2026-07-08 unique enforcement upgrade-safety loop

- Run: `pingcap-inc/nexuscrm-controlplane/actions/runs/28916953426`, PR `pingcap-inc/nexuscrm-controlplane#18`.
- Runtime refs: controlplane branch `codex/object-spec-field-unique-metadata` at `7c4d66d2939c67ff5f07a1bf9b93706d15b2b6aa`, base `da0e9d2dc5643116e24bdf026b5f545174e2177c`.
- Workload shape: pack apply/upgrade path that converts object specs into physical table definitions, reconciles unique indexes, verifies physical constraints, and publishes `_System_Field.IsUnique` used by Flow lookup batching.
- Profile/review result: publication ordering and stale unique-index downgrades were fixed, but reviewer evidence still showed legacy duplicate values could make apply fail before any migration/repair lane existed.
- What changed before this record: no code change in this loop yet; this records the evidence gap before adding the repair path.
- What failed: the preflight was correct for preventing false unique metadata, but it only failed closed. Existing orgs with duplicate values from the old inert `object_spec.unique` era still had no deterministic operator repair route.
- Learned: uniqueness enforcement needs a three-part contract: physical constraint before metadata, downgrade convergence, and explicit legacy duplicate remediation. A fail-closed preflight alone is not enough for upgrade safety.
- Next hypothesis: add an explicit repair option that clears non-canonical duplicate values on nullable physical columns before DDL, keeps readSource/non-null cases fail-closed, and proves the repair runs before schema mutation and metadata publication.

## 2026-09-05 Test2 AppRelease managed-lifecycle timeout

- Run: `pingcap-inc/nexuscrm-pingcap-pack/actions/runs/33977804897`; bounded SQL observation: `33978344894`.
- Runtime refs: NexusCRM `43241bd4e78c8e4b0d740348a7541b53aacabdf0`, Controlplane `v0.2.114`, signed BOM `sha256:1b3c7577587f9415084148a337c9bc02f526706643b6a1181c623a7d731de329`.
- Workload: stopped Test2 AppRelease upgrade through the standard pack followed by the Gmail companion pack; L0 remained in bootstrap and L1/Integration remained stopped.
- Profile result: the permission-set managed operation timed out after 30 seconds while resolving `_System_CustomPermission` schema. In the enclosing minute TiDB completed only 110 statements with 0.347 seconds total latency and zero resource-queue time; the canceled schema query never appeared as a completed TiDB statement.
- What changed before this record: no code change yet. The Rollup and Integration outbound columns and indexes were installed before this later failure.
- What failed: the host starts a semantic transaction but passes its pool-backed production catalog into the locked attempt. Schema discovery can therefore wait for a second pool connection instead of using the transaction connection; the same code already binds catalog reads to the transaction for ambient staging and fresh verification.
- Learned: the timeout is client-side connection acquisition on an inconsistent read path, not TiDB RU exhaustion. Schema discovery for a locked plan belongs to the same transaction as its row reads and writes.
- Next hypothesis: bind the production catalog to the semantic transaction and prove `ApplyItem` completes with a one-connection pool; then rerun only the interrupted AppRelease recovery on the frozen release.
- Result: the one-connection regression test completed in 0.66 seconds with the catalog bound to the semantic transaction. Temporarily restoring the old pool-backed path left the same test stuck beyond five seconds despite a one-second lifecycle budget, reproducing the unconfirmed-rollback failure class.