Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
fix(search): converge OpenSearch mappings so tagged calls are searchable (#5396)
gbirmanae66ba5f7f3a
diff --git a/infra/stacks/opensearch/helpers/README.md b/infra/stacks/opensearch/helpers/README.mdindex e5a8af890b..c6ab7e3782 100644--- a/infra/stacks/opensearch/helpers/README.md+++ b/infra/stacks/opensearch/helpers/README.md@@ -35,12 +35,36 @@ that can be swapped without a code deploy.| Script | Purpose || ---------------------------- | ---------------------------------------------------------------------- || `verify_aliases.ts` | Pre/post-flight check: alias exists and points at the expected index. |+| `verify_mappings.ts` | Pre/post-flight check: live mappings carry every field the code declares. || `add_alias.ts` | Idempotent additive alias (no reindex). || `reindex_with_alias_swap.ts` | Reindex + atomic swap (handles `remove_index` for bare physical case). |-| `create_indices.ts` | Idempotent first-time creation of every versioned index + alias. |+| `create_indices.ts` | Creates every versioned index + alias, and converges existing mappings. |All migration scripts default to `DRY_RUN=true`; pass `DRY_RUN=false` to apply.+## Adding a field to an existing index++The index bodies in `create_indices.ts` are the source of truth for mappings.+Every body is `dynamic: 'false'`, so a field the service writes but the live+mapping lacks is dropped silently — and a search over it matches nothing+rather than erroring. That is how `call_records_v2` shipped without+`properties`/`name` and left tag filters on calls returning empty (macro-2731).++So the flow for a new field is:++1. Add it to the body in `create_indices.ts`.+2. Run `bun scripts/create_indices.ts` (dry-run) against each environment and+ read the plan, then `DRY_RUN=false` to apply. Existing indices keep their+ data and gain only the fields they're missing, via `_mapping` PUT.+3. Backfill the affected entity through `search_processing_service`+ (`POST /internal/backfill/<entity>`) so documents indexed before the+ mapping existed pick the field up.+4. Confirm with `bun scripts/verify_mappings.ts`.++Convergence is additive only. A field whose live `type` disagrees with the+body is reported, never rewritten — changing a live field's type needs the+reindex runbook below.+## Runbook: reindex with new mapping (zero downtime)Use when you need to change a mapping that requires a full reindex (e.g.diff --git a/infra/stacks/opensearch/helpers/package.json b/infra/stacks/opensearch/helpers/package.jsonindex 86180d07f4..c7cb6de157 100644--- a/infra/stacks/opensearch/helpers/package.json+++ b/infra/stacks/opensearch/helpers/package.json@@ -12,6 +12,7 @@"add_alias": "bun run scripts/add_alias.ts","reindex_with_alias_swap": "bun run scripts/reindex_with_alias_swap.ts","verify_aliases": "bun run scripts/verify_aliases.ts",+ "verify_mappings": "bun run scripts/verify_mappings.ts","set_refresh_interval": "bun run set_refresh_interval.ts"},"author": "Will Hutchinson",diff --git a/infra/stacks/opensearch/helpers/scripts/add_properties_field.ts b/infra/stacks/opensearch/helpers/scripts/add_properties_field.tsdeleted file mode 100644index 6d6717ba01..0000000000--- a/infra/stacks/opensearch/helpers/scripts/add_properties_field.ts+++ /dev/null@@ -1,100 +0,0 @@-require('dotenv').config();--import { client } from '../client';-import {- CALL_RECORDS_ALIAS,- CHATS_ALIAS,- EMAILS_ALIAS,- IS_DRY_RUN,-} from '../constants';--// Indexes that receive the nested entity-properties field additively-// (documents shipped with it; projects_v1 was created with it).-const SUPPORTED_INDEXES = [EMAILS_ALIAS, CHATS_ALIAS, CALL_RECORDS_ALIAS];--async function addPropertiesField(dryRun: boolean) {- const index = process.env.INDEX;- if (!index || !SUPPORTED_INDEXES.includes(index)) {- console.log(- `⚠️ Set INDEX to one of: ${SUPPORTED_INDEXES.join(', ')}. Aborting.`- );- return;- }-- const opensearchClient = client();-- console.log('\n' + '='.repeat(60));- console.log(- `Add nested properties field to "${index}" index ${dryRun ? '(DRY-RUN MODE)' : '(LIVE MODE)'}`- );- console.log('='.repeat(60));-- if (dryRun) {- console.log('\n⚠️ DRY-RUN MODE: No changes will be made');- }-- const indexExists = (await opensearchClient.indices.exists({ index })).body;-- if (!indexExists) {- console.log(`⚠️ Index "${index}" does not exist. Aborting.`);- return;- }-- console.log('\nAdding nested properties field mapping...');- const fields: Record<string, unknown> = {- // Entity properties (e.g. tags), same nested shape as the documents- // index so the shared property/tag filters apply unchanged. Emails:- // thread-level values denormalized onto every message doc. Chats and- // calls: values live on the parent doc only.- properties: {- type: 'nested' as const,- properties: {- definition_id: { type: 'keyword' as const },- values: { type: 'keyword' as const },- number_value: { type: 'double' as const },- date_value: { type: 'date' as const },- },- },- };- // Calls also gain a searchable `name` field (custom name, falling back to- // the channel name). Existing indexes only got channel_name; the calls- // backfill re-populates `name` on every parent doc.- if (index === CALL_RECORDS_ALIAS) {- fields.name = {- type: 'text' as const,- fields: { keyword: { type: 'keyword' as const, ignore_above: 128 } },- };- }- const mappingUpdate = { properties: fields };-- if (dryRun) {- console.log('[DRY-RUN] Would add nested properties field mapping');- } else {- const putMappingResponse = await opensearchClient.indices.putMapping({- index,- body: mappingUpdate,- });-- if (!putMappingResponse.body.acknowledged) {- throw new Error('Failed to add field mapping');- }- console.log('✓ nested properties field mapping added');- }-- console.log('\n' + '='.repeat(60));- console.log('Done!');- console.log('='.repeat(60));-- if (dryRun) {- console.log('\nTo run for real, set DRY_RUN=false environment variable\n');- } else {- console.log(- `\n✓ properties field has been added to the "${index}" index mapping.`- );- console.log(- '✓ To backfill existing tags, POST /internal/backfill/properties with the matching entity_type.\n'- );- }-}--addPropertiesField(IS_DRY_RUN);diff --git a/infra/stacks/opensearch/helpers/scripts/create_indices.test.ts b/infra/stacks/opensearch/helpers/scripts/create_indices.test.tsindex df300e1822..788788045e 100644--- a/infra/stacks/opensearch/helpers/scripts/create_indices.test.ts+++ b/infra/stacks/opensearch/helpers/scripts/create_indices.test.ts@@ -1,5 +1,10 @@import { describe, expect, test } from 'bun:test';-import { planCreateIndex } from './create_indices';+import {+ INDEX_SPECS,+ planCreateIndex,+ planMappingConvergence,+ selectIndexSpecs,+} from './create_indices';describe('planCreateIndex', () => {test('fresh env — index missing, alias free → create with alias', () => {@@ -78,3 +83,147 @@ describe('planCreateIndex', () => {expect(plan.kind).toBe('defer_alias');});});++describe('planMappingConvergence', () => {+ const TAG_PROPERTIES = {+ type: 'nested',+ properties: {+ definition_id: { type: 'keyword' },+ values: { type: 'keyword' },+ },+ };++ test('live mapping matches the body → nothing to do', () => {+ const plan = planMappingConvergence({+ desired: { entity_id: { type: 'keyword' }, properties: TAG_PROPERTIES },+ live: { entity_id: { type: 'keyword' }, properties: TAG_PROPERTIES },+ });+ expect(plan.missingPaths).toEqual([]);+ expect(plan.conflictPaths).toEqual([]);+ expect(plan.updates).toEqual({});+ });++ test('macro-2731: index predates the nested properties + name fields → add both', () => {+ const plan = planMappingConvergence({+ desired: {+ entity_id: { type: 'keyword' },+ name: {+ type: 'text',+ fields: { keyword: { type: 'keyword', ignore_above: 128 } },+ },+ properties: TAG_PROPERTIES,+ },+ live: { entity_id: { type: 'keyword' } },+ });+ expect(plan.missingPaths).toEqual(['name', 'properties']);+ expect(plan.conflictPaths).toEqual([]);+ expect(Object.keys(plan.updates)).toEqual(['name', 'properties']);+ expect(plan.updates.properties).toEqual(TAG_PROPERTIES);+ });++ test('a new member of an existing nested field is additive', () => {+ const plan = planMappingConvergence({+ desired: {+ properties: {+ type: 'nested',+ properties: {+ definition_id: { type: 'keyword' },+ values: { type: 'keyword' },+ date_value: { type: 'date' },+ },+ },+ },+ live: { properties: TAG_PROPERTIES },+ });+ expect(plan.missingPaths).toEqual(['properties.date_value']);+ expect(Object.keys(plan.updates)).toEqual(['properties']);+ });++ test('a new multi-field under an existing field is additive', () => {+ const plan = planMappingConvergence({+ desired: {+ channel_name: {+ type: 'text',+ fields: { keyword: { type: 'keyword', ignore_above: 128 } },+ },+ },+ live: { channel_name: { type: 'text' } },+ });+ expect(plan.missingPaths).toEqual(['channel_name.keyword']);+ expect(Object.keys(plan.updates)).toEqual(['channel_name']);+ });++ test('parameter-only differences are ignored so runs stay quiet', () => {+ const plan = planMappingConvergence({+ // OpenSearch echoes a normalized mapping: defaults like `index: true`+ // and `doc_values: true` come back omitted.+ desired: {+ channel_id: { type: 'keyword', index: true, doc_values: true },+ },+ live: { channel_id: { type: 'keyword' } },+ });+ expect(plan.missingPaths).toEqual([]);+ expect(plan.updates).toEqual({});+ });++ test('a changed type is reported, never applied', () => {+ const plan = planMappingConvergence({+ desired: { started_at_millis: { type: 'date', format: 'epoch_millis' } },+ live: { started_at_millis: { type: 'long' } },+ });+ expect(plan.conflictPaths).toEqual(['started_at_millis']);+ expect(plan.updates).toEqual({});+ });++ test('a conflict keeps its whole top-level field out of the update', () => {+ const plan = planMappingConvergence({+ desired: {+ properties: {+ type: 'nested',+ properties: {+ values: { type: 'keyword' },+ number_value: { type: 'double' },+ },+ },+ },+ live: {+ properties: {+ type: 'nested',+ properties: { values: { type: 'text' } },+ },+ },+ });+ expect(plan.missingPaths).toEqual(['properties.number_value']);+ expect(plan.conflictPaths).toEqual(['properties.values']);+ expect(plan.updates).toEqual({});+ });++ test('an index with no live mapping yet takes every field', () => {+ const plan = planMappingConvergence({+ desired: { entity_id: { type: 'keyword' } },+ live: undefined,+ });+ expect(plan.missingPaths).toEqual(['entity_id']);+ expect(Object.keys(plan.updates)).toEqual(['entity_id']);+ });+});++describe('selectIndexSpecs', () => {+ test('no filter runs every index', () => {+ expect(selectIndexSpecs(INDEX_SPECS, undefined)).toEqual(INDEX_SPECS);+ });++ test('filters by alias', () => {+ const selected = selectIndexSpecs(INDEX_SPECS, 'call_records');+ expect(selected.map((s) => s.indexName)).toEqual(['call_records_v2']);+ });++ test('filters by physical index name', () => {+ const selected = selectIndexSpecs(INDEX_SPECS, 'call_records_v2');+ expect(selected.map((s) => s.aliasName)).toEqual(['call_records']);+ });++ test('an unknown filter selects nothing so the caller can abort', () => {+ expect(selectIndexSpecs(INDEX_SPECS, 'nope')).toEqual([]);+ });+});diff --git a/infra/stacks/opensearch/helpers/scripts/create_indices.ts b/infra/stacks/opensearch/helpers/scripts/create_indices.tsindex 30bb304f70..a588fd7932 100644--- a/infra/stacks/opensearch/helpers/scripts/create_indices.ts+++ b/infra/stacks/opensearch/helpers/scripts/create_indices.ts@@ -18,7 +18,7 @@ import {SLOWLOG_SETTINGS,} from '../constants';-type CreateIndexArgs = {+export type CreateIndexArgs = {indexName: string;aliasName: string;body: Record<string, unknown>;@@ -95,6 +95,196 @@ export function planCreateIndex(state: CreateIndexState): CreatePlan {return { kind: 'create_with_alias' };}+/**+ * Field-level drift between an index body in this file and the mapping that is+ * actually live on the cluster.+ *+ * `updates` is the `properties` payload of a `_mapping` PUT: the full desired+ * definition of every top-level field that is missing fields, which OpenSearch+ * merges additively. `missingPaths` and `conflictPaths` are dotted field paths+ * for the operator log.+ */+export type MappingConvergencePlan = {+ updates: Record<string, unknown>;+ missingPaths: string[];+ conflictPaths: string[];+};++const isRecord = (value: unknown): value is Record<string, unknown> =>+ typeof value === 'object' && value !== null && !Array.isArray(value);++const fieldType = (definition: unknown): string | undefined => {+ if (!isRecord(definition)) return undefined;+ return typeof definition.type === 'string' ? definition.type : undefined;+};++/**+ * Sub-fields of one field definition: object/nested members under+ * `properties`, plus multi-fields under `fields`. A field can never have both,+ * so flattening them into one namespace can't collide.+ */+const subFields = (definition: unknown): Record<string, unknown> => {+ if (!isRecord(definition)) return {};+ return {+ ...(isRecord(definition.properties) ? definition.properties : {}),+ ...(isRecord(definition.fields) ? definition.fields : {}),+ };+};++function collectFieldDrift(+ path: string,+ desired: unknown,+ live: unknown,+ missingPaths: string[],+ conflictPaths: string[]+) {+ const desiredType = fieldType(desired);+ const liveType = fieldType(live);+ // A type change can't be applied additively — it needs a reindex, so record+ // it and stop descending (children of a differently-typed field are moot).+ if (desiredType && liveType && desiredType !== liveType) {+ conflictPaths.push(path);+ return;+ }++ const desiredSubFields = subFields(desired);+ const liveSubFields = subFields(live);+ for (const [name, desiredSubField] of Object.entries(desiredSubFields)) {+ const subPath = `${path}.${name}`;+ if (!(name in liveSubFields)) {+ missingPaths.push(subPath);+ continue;+ }+ collectFieldDrift(+ subPath,+ desiredSubField,+ liveSubFields[name],+ missingPaths,+ conflictPaths+ );+ }+}++/**+ * Pure decision: which fields does the live mapping lack, and which of them+ * can be added without a reindex?+ *+ * Only field *presence* is compared, never per-field parameters: OpenSearch+ * echoes back a normalized mapping (defaults omitted, some values rewritten),+ * so diffing parameters would report drift on every index forever. A field+ * whose `type` disagrees lands in `conflictPaths` and is left alone — changing+ * a live field's type requires `reindex_with_alias_swap.ts`. Anything else+ * missing is additive, so the whole top-level definition goes into `updates`+ * for OpenSearch to merge.+ */+export function planMappingConvergence(args: {+ desired: Record<string, unknown> | undefined;+ live: Record<string, unknown> | undefined;+}): MappingConvergencePlan {+ const desired = args.desired ?? {};+ const live = args.live ?? {};++ const updates: Record<string, unknown> = {};+ const missingPaths: string[] = [];+ const conflictPaths: string[] = [];++ for (const [name, desiredDefinition] of Object.entries(desired)) {+ if (!(name in live)) {+ missingPaths.push(name);+ updates[name] = desiredDefinition;+ continue;+ }++ const fieldMissing: string[] = [];+ const fieldConflicts: string[] = [];+ collectFieldDrift(+ name,+ desiredDefinition,+ live[name],+ fieldMissing,+ fieldConflicts+ );+ missingPaths.push(...fieldMissing);+ conflictPaths.push(...fieldConflicts);+ // Sending a definition that carries a conflict would be rejected wholesale,+ // taking the additive sub-fields down with it.+ if (fieldMissing.length > 0 && fieldConflicts.length === 0) {+ updates[name] = desiredDefinition;+ }+ }++ return { updates, missingPaths, conflictPaths };+}++/**+ * Bring an existing index's mapping up to the body declared above by adding+ * whatever fields it is missing.+ *+ * Index creation is one-shot, so a field added to a body here never reaches an+ * index that already exists — and because every body is `dynamic: 'false'`,+ * writes of the new field are dropped silently and searches over it match+ * nothing (macro-2731: `call_records_v2` never got `properties`/`name`, so tag+ * filters and name matches on calls returned empty). Converging on every run+ * makes the body the single source of truth instead of a one-off script.+ */+async function convergeMapping(+ opensearchClient: Client,+ indexName: string,+ body: Record<string, unknown>+) {+ const desiredMappings = isRecord(body.mappings) ? body.mappings : undefined;+ const desired = isRecord(desiredMappings?.properties)+ ? (desiredMappings?.properties as Record<string, unknown>)+ : undefined;++ const response = await opensearchClient.indices.getMapping({+ index: indexName,+ });+ const liveMappings = (response.body ?? {})[indexName]?.mappings;+ const live = isRecord(liveMappings?.properties)+ ? (liveMappings?.properties as Record<string, unknown>)+ : undefined;++ const plan = planMappingConvergence({ desired, live });++ for (const path of plan.conflictPaths) {+ console.log(+ `${indexName}: ⚠️ "${path}" has a different type live than in this file. ` ++ `A type change needs a reindex — run reindex_with_alias_swap.ts.`+ );+ }++ if (Object.keys(plan.updates).length === 0) {+ if (plan.conflictPaths.length === 0) {+ console.log(`${indexName}: mapping matches this file`);+ }+ return;+ }++ console.log(+ `${indexName}: mapping is missing ${plan.missingPaths.length} field(s): ${plan.missingPaths.join(', ')}`+ );++ if (IS_DRY_RUN) {+ console.log(+ `[DRY-RUN] Would add ${Object.keys(plan.updates).join(', ')} to ${indexName}`+ );+ return;+ }++ const putMappingResponse = await opensearchClient.indices.putMapping({+ index: indexName,+ body: { properties: plan.updates },+ });+ if (!putMappingResponse.body.acknowledged) {+ throw new Error(`Failed to add mapping fields to ${indexName}`);+ }+ console.log(+ `✓ ${indexName}: added ${Object.keys(plan.updates).join(', ')}. ` ++ `Backfill the affected entity to populate existing docs.`+ );+}+async function createIndexWithAlias(opensearchClient: Client,{ indexName, aliasName, body }: CreateIndexArgs@@ -142,17 +332,19 @@ async function createIndexWithAlias(switch (plan.kind) {case 'noop':console.log(`${indexName}: ${plan.reason}`);+ await convergeMapping(opensearchClient, indexName, body);return;case 'add_alias':if (IS_DRY_RUN) {console.log(`[DRY-RUN] Would add alias ${aliasName} -> ${indexName}`);- return;+ } else {+ console.log(`Adding alias ${aliasName} -> ${indexName}`);+ await opensearchClient.indices.putAlias({+ index: indexName,+ name: aliasName,+ });}- console.log(`Adding alias ${aliasName} -> ${indexName}`);- await opensearchClient.indices.putAlias({- index: indexName,- name: aliasName,- });+ await convergeMapping(opensearchClient, indexName, body);return;case 'create_with_alias':if (IS_DRY_RUN) {@@ -182,6 +374,7 @@ async function createIndexWithAlias(return;case 'defer_alias':console.log(`${indexName}: ${plan.nextStep}`);+ await convergeMapping(opensearchClient, indexName, body);return;}}@@ -718,46 +911,72 @@ const CALL_RECORDS_V2_BODY = {},};+/**+ * Every index this repo owns, with the mapping it is supposed to have.+ * `verify_mappings.ts` reads the same list so a drift check and a converging+ * run can never disagree about what the desired mapping is.+ *+ * chats and call_records use parent/child join mappings (bodies inlined above+ * as CHATS_V2_BODY / CALL_RECORDS_V2_BODY).+ */+export const INDEX_SPECS: CreateIndexArgs[] = [+ {+ indexName: DOCUMENTS_INDEX,+ aliasName: DOCUMENTS_ALIAS,+ body: DOCUMENT_BODY,+ },+ { indexName: EMAILS_INDEX, aliasName: EMAILS_ALIAS, body: EMAIL_BODY },+ { indexName: CHANNELS_INDEX, aliasName: CHANNELS_ALIAS, body: CHANNEL_BODY },+ { indexName: CHATS_INDEX, aliasName: CHATS_ALIAS, body: CHATS_V2_BODY },+ {+ indexName: CALL_RECORDS_INDEX,+ aliasName: CALL_RECORDS_ALIAS,+ body: CALL_RECORDS_V2_BODY,+ },+ { indexName: PROJECTS_INDEX, aliasName: PROJECTS_ALIAS, body: PROJECTS_BODY },+];++/**+ * Narrow a run to one index by alias or physical name (`INDEX=call_records`).+ *+ * An environment can sit mid-migration on one index while another needs a+ * field added — prod held `emails` on `emails_v1` while `call_records_v2` was+ * missing its `properties` mapping, and an unscoped run there would have+ * created an empty `emails_v2` as a side effect. Scoping keeps a mapping fix+ * from touching an unrelated migration.+ */+export function selectIndexSpecs(+ specs: CreateIndexArgs[],+ filter: string | undefined+): CreateIndexArgs[] {+ if (!filter) return specs;+ return specs.filter(+ (spec) => spec.indexName === filter || spec.aliasName === filter+ );+}+async function createIndices() {const opensearchClient = client();+ const filter = process.env.INDEX;+ const specs = selectIndexSpecs(INDEX_SPECS, filter);+ if (specs.length === 0) {+ console.log(+ `⚠️ INDEX="${filter}" matches no index. Known: ` ++ `${INDEX_SPECS.map((s) => s.aliasName).join(', ')}. Aborting.`+ );+ return;+ }+console.log(- `Creating indices... ${IS_DRY_RUN ? '(DRY-RUN MODE — set DRY_RUN=false to apply)' : '(LIVE MODE)'}`+ `Creating indices and converging mappings${filter ? ` for "${filter}"` : ''}... ${IS_DRY_RUN ? '(DRY-RUN MODE — set DRY_RUN=false to apply)' : '(LIVE MODE)'}`);try {- await createIndexWithAlias(opensearchClient, {- indexName: DOCUMENTS_INDEX,- aliasName: DOCUMENTS_ALIAS,- body: DOCUMENT_BODY,- });- await createIndexWithAlias(opensearchClient, {- indexName: EMAILS_INDEX,- aliasName: EMAILS_ALIAS,- body: EMAIL_BODY,- });- await createIndexWithAlias(opensearchClient, {- indexName: CHANNELS_INDEX,- aliasName: CHANNELS_ALIAS,- body: CHANNEL_BODY,- });- // chats and call_records use parent/child join mappings (bodies inlined- // above as CHATS_V2_BODY / CALL_RECORDS_V2_BODY). Idempotent — no-ops where- // they already exist.- await createIndexWithAlias(opensearchClient, {- indexName: CHATS_INDEX,- aliasName: CHATS_ALIAS,- body: CHATS_V2_BODY,- });- await createIndexWithAlias(opensearchClient, {- indexName: CALL_RECORDS_INDEX,- aliasName: CALL_RECORDS_ALIAS,- body: CALL_RECORDS_V2_BODY,- });- await createIndexWithAlias(opensearchClient, {- indexName: PROJECTS_INDEX,- aliasName: PROJECTS_ALIAS,- body: PROJECTS_BODY,- });+ // Idempotent — indices that already exist keep their data and only gain+ // fields this file declares that they are missing.+ for (const spec of specs) {+ await createIndexWithAlias(opensearchClient, spec);+ }console.log('done');} catch (error) {console.error('Error', error);diff --git a/infra/stacks/opensearch/helpers/scripts/verify_mappings.ts b/infra/stacks/opensearch/helpers/scripts/verify_mappings.tsnew file mode 100644index 0000000000..da9d7aa47e--- /dev/null+++ b/infra/stacks/opensearch/helpers/scripts/verify_mappings.ts@@ -0,0 +1,113 @@+/**+ * Pre/post-flight check: compare every live index mapping against the body+ * declared for it in create_indices.ts. Exits non-zero when an index is+ * missing fields the code expects, or when a field's type disagrees.+ *+ * Every index body is `dynamic: 'false'`, so a field that exists in code but+ * not on the cluster fails silently: the service writes it, OpenSearch drops+ * it, and searches over it match nothing. Run this after deploying code that+ * indexes a new field, and after `create_indices.ts` to confirm convergence.+ *+ * Usage:+ * bun scripts/verify_mappings.ts+ * INDEX=call_records bun scripts/verify_mappings.ts # one index only+ */+import type { Client } from '@opensearch-project/opensearch';+import {+ INDEX_SPECS,+ type MappingConvergencePlan,+ planMappingConvergence,+ selectIndexSpecs,+} from './create_indices';++const isRecord = (value: unknown): value is Record<string, unknown> =>+ typeof value === 'object' && value !== null && !Array.isArray(value);++const mappingProperties = (+ mappings: unknown+): Record<string, unknown> | undefined => {+ if (!isRecord(mappings)) return undefined;+ return isRecord(mappings.properties) ? mappings.properties : undefined;+};++async function livePropertiesFor(+ opensearchClient: Client,+ indexName: string+): Promise<Record<string, unknown> | undefined> {+ const response = await opensearchClient.indices.getMapping({+ index: indexName,+ });+ return mappingProperties((response.body ?? {})[indexName]?.mappings);+}++function describe(indexName: string, plan: MappingConvergencePlan): boolean {+ const drifted = plan.missingPaths.length > 0 || plan.conflictPaths.length > 0;+ const status = drifted ? 'FAIL' : 'OK';+ console.log(`${indexName.padEnd(20)} [${status}]`);+ if (plan.missingPaths.length > 0) {+ console.log(` missing: ${plan.missingPaths.join(', ')}`);+ console.log(+ ` fix: DRY_RUN=false bun scripts/create_indices.ts, then backfill the entity`+ );+ }+ for (const path of plan.conflictPaths) {+ console.log(+ ` type conflict: "${path}" — needs reindex_with_alias_swap.ts`+ );+ }+ return !drifted;+}++async function main() {+ await import('dotenv').then((m) => m.config());+ const { client } = await import('../client');++ const opensearchClient = client();+ const filter = process.env.INDEX;+ const specs = selectIndexSpecs(INDEX_SPECS, filter);+ if (specs.length === 0) {+ console.error(+ `INDEX="${filter}" matches no index. Known: ` ++ `${INDEX_SPECS.map((s) => s.aliasName).join(', ')}.`+ );+ process.exit(1);+ }++ let allOk = true;+ console.log('index [status]');+ console.log('-'.repeat(70));++ for (const { indexName, body } of specs) {+ const exists = (await opensearchClient.indices.exists({ index: indexName }))+ .body;+ if (!exists) {+ console.log(`${indexName.padEnd(20)} [FAIL]`);+ console.log(+ ` missing index — run DRY_RUN=false bun scripts/create_indices.ts`+ );+ allOk = false;+ continue;+ }++ const plan = planMappingConvergence({+ desired: mappingProperties(body.mappings),+ live: await livePropertiesFor(opensearchClient, indexName),+ });+ if (!describe(indexName, plan)) {+ allOk = false;+ }+ }++ if (!allOk) {+ console.error('\nMapping verification failed.');+ process.exit(1);+ }+ console.log('\nEvery index mapping matches create_indices.ts.');+}++if (import.meta.main) {+ main().catch((err) => {+ console.error('Error', err);+ process.exit(1);+ });+}