@salesforce/plugin-bre-to-cml 1.3.0 → 1.3.1

package/lib/shared/insurance/insurance-cml-merge.js

@@ -1,6 +1,6 @@
 import { CmlConstraint } from '../types/types.js';
 import { CONSTRAINT_TYPES } from '../constants/constants.js';
-import { buildConstraintDeclaration, collectAttributeTypes, collectEmittedAttributes, sanitizeName, buildStageTransition, } from './insurance-rule-generator.js';
+import { buildConstraintDeclaration, collectAttributeTypes, collectEmittedAttributes, collectEmittedContextTags, findUnconvertibleConditions, sanitizeName, buildStageTransition, } from './insurance-rule-generator.js';
 import { quoteSoqlIdList } from './insurance-org.js';
 /**
  * MERGE MODE (insurance-only): instead of building a fresh single-type CML and PATCH-replacing
@@ -13,8 +13,11 @@ import { quoteSoqlIdList } from './insurance-org.js';
  *
  * Why pathed keys: when a ProductSurcharge is persisted as ConstraintEngine the platform
  * auto-generates `RuleKey` as `SC` + sanitize(ProductCode) of every segment in ProductPath (in
- * order) + sanitize(apiName), joined by `__`. The Core surcharge engine matches the fired CML rule
- * key against that auto-generated RuleKey by exact string, so the CML rule key MUST be pathed too.
+ * order) + sanitize(leaf), joined by `__`. The leaf is the parent `Surcharge.Code` (resolved via
+ * ProductSurcharge.SurchargeId), NOT the rule apiName — see {@link fetchSurchargeCodes} and
+ * {@link buildPathedSurchargeRules}. The Core surcharge engine matches the fired CML rule key
+ * against that auto-generated RuleKey by exact string, so the CML rule key MUST be pathed and use
+ * the same Code-derived leaf.
  */
 export const SURCHARGE_RULE_ACTION = 'InsuranceSurchargeRule';
 /**
@@ -28,8 +31,17 @@ export function buildPathedRuleKey(prefix, pathProductCodes, apiName, stageTrans
     parts.push(sanitizeName(apiName));
     return parts.join('__');
 }
-/** Splits a `ProductPath` into its ordered Product2 ids (slash-separated). */
+/**
+ * Splits a `ProductPath` into its ordered Product2 ids (slash-separated).
+ *
+ * ProductPath is nullable in the org even on records that carry a rule, so nullish input yields an
+ * empty path rather than throwing. Callers rely on that: an empty path is already a recognized skip
+ * (see the empty-ProductPath guard in mergeSurchargeRules), whereas throwing here aborted the whole
+ * conversion run before any record could be skipped.
+ */
 export function splitProductPath(productPath) {
+    if (!productPath)
+        return [];
     return productPath
         .split('/')
         .map((s) => s.trim())
@@ -76,6 +88,32 @@ export async function fetchProductTypeTags(conn, productIds) {
     }
     return idToTag;
 }
+/**
+ * Resolves Surcharge id -> Surcharge.Code. The platform builds the LEAF segment of
+ * `ProductSurcharge.RuleKey` from the parent Surcharge's Code (e.g. `basictaxcode`), NOT from the
+ * rule apiName. `buildPathedSurchargeRules` uses this map so the emitted CML rule key matches the
+ * platform-generated RuleKey exactly; without it the surcharge imports cleanly but never fires
+ * ("No active rule model found"). Ids with no resolvable Code are omitted (caller warns + falls
+ * back to apiName).
+ */
+export async function fetchSurchargeCodes(conn, surchargeIds) {
+    const idToCode = new Map();
+    const idList = quoteSoqlIdList(surchargeIds);
+    if (!idList)
+        return idToCode;
+    const result = await conn.query(`SELECT Id, Code FROM Surcharge WHERE Id IN (${idList})`);
+    for (const r of result.records) {
+        if (!r.Id || !r.Code)
+            continue;
+        // SOQL always returns 18-char Ids, but a RuleDefinition blob could carry a 15-char surchargeId.
+        // Index under both the full and 15-char-prefix forms so the caller's verbatim lookup hits either
+        // way (SOQL `IN` is 15/18 tolerant, so the returned key would otherwise not match a 15-char id).
+        idToCode.set(r.Id, r.Code);
+        if (r.Id.length === 18)
+            idToCode.set(r.Id.slice(0, 15), r.Code);
+    }
+    return idToCode;
+}
 export function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -189,6 +227,28 @@ function findTypeBlock(cml, typeName, scan = blankComments(cml)) {
         return undefined;
     return { openIdx, closeIdx };
 }
+/**
+ * Prefix every merge skip raised by {@link findUnconvertibleConditions} carries, so the commands'
+ * skip breakdown can bucket it the way it buckets the other reasons.
+ */
+export const UNCONVERTIBLE_SKIP_PREFIX = 'cannot be expressed in CML';
+function joinReasons(reasons) {
+    return reasons.length > 0 ? `${UNCONVERTIBLE_SKIP_PREFIX}: ${reasons.join(' ')}` : undefined;
+}
+/**
+ * Whether a context tag title is safe to place verbatim inside the double-quoted slot of a
+ * `@(tagName = "...")` / `@(contextPath = "...")` annotation. Titles legitimately contain spaces
+ * ("Cause Of Loss"), but a quote, backslash or newline would break out of the literal and land raw
+ * in the curated model, so those are refused rather than escaped — the same reject-don't-escape
+ * stance {@link isSafeQuotableString} takes for condition values.
+ *
+ * A refused tag contributes no declaration, so the absent-reference gate withholds its rule. The
+ * fetch layer already declines to query such a title, making this defence in depth for a
+ * hand-constructed binding map.
+ */
+function isSafeCmlAnnotationValue(value) {
+    return value.trim().length > 0 && !/["\\\r\n]/.test(value);
+}
 /** Builds the `rule(...)` statement for a surcharge, using the same constraint generator as build mode. */
 export function buildSurchargeRuleStatement(declaration, ruleKey) {
     return CmlConstraint.createRuleConstraint(declaration, SURCHARGE_RULE_ACTION, ruleKey, 'True').generateCml();
@@ -196,22 +256,37 @@ export function buildSurchargeRuleStatement(declaration, ruleKey) {
 /**
  * Prepares the pathed-rule descriptors for a set of parsed surcharge records.
  * `productIdToCode` and `productIdToType` must already cover every ProductPath segment.
+ * `options.surchargeIdToCode` should map every rule's parent Surcharge id to its Code so the key
+ * leaf matches the platform-generated RuleKey (see {@link fetchSurchargeCodes}).
  */
-export function buildPathedSurchargeRules(prefix, ruleDefs, productIdToCode, productIdToType) {
+export function buildPathedSurchargeRules(prefix, ruleDefs, productIdToCode, productIdToType, options = {}) {
     return ruleDefs.map(({ record, ruleDef }) => {
         const apiName = ruleDef.apiName ?? record.Name;
+        // The platform builds the RuleKey leaf from the parent Surcharge.Code, not the rule apiName.
+        // Prefer the resolved Code; fall back to apiName (and warn) only when it can't be resolved.
+        const surchargeCode = ruleDef.surchargeId ? options.surchargeIdToCode?.get(ruleDef.surchargeId) : undefined;
+        const keyLeaf = surchargeCode ?? apiName;
+        if (!surchargeCode)
+            options.onSurchargeCodeFallback?.(record.Name);
         const segments = splitProductPath(record.ProductPath);
         const pathCodes = segments.map((id) => productIdToCode.get(id) ?? id);
         const stageTransition = buildStageTransition(ruleDef.underwritingRuleGroup);
-        const ruleKey = buildPathedRuleKey(prefix, pathCodes, apiName, stageTransition);
+        const ruleKey = buildPathedRuleKey(prefix, pathCodes, keyLeaf, stageTransition);
         const leafProductId = segments[segments.length - 1];
         const typeName = leafProductId ? productIdToType.get(leafProductId) : undefined;
-        const declaration = buildConstraintDeclaration(ruleDef);
+        const tagTypes = options.contextTagBindings;
+        const declaration = buildConstraintDeclaration(ruleDef, options.attributeDataTypes, tagTypes);
         const statement = buildSurchargeRuleStatement(declaration, ruleKey);
         // M7: only attributes from conditions that actually emitted CML (non-null buildConditionExpression)
         // count as "referenced". Attributes from conditions the safe-literal guard / unknown-operator
         // filter dropped never appear in the declaration, so warning about them would be spurious noise.
-        const referencedAttributes = Array.from(collectEmittedAttributes([{ ruleDef }]));
+        const referencedAttributes = Array.from(collectEmittedAttributes([{ ruleDef }], options.attributeDataTypes, tagTypes));
+        // Same discipline for tags, then narrowed to the ones that actually resolved: an unresolved tag
+        // contributes no declaration, so it stays absent from the model and its rule is withheld.
+        const contextTagDeclarations = Array.from(collectEmittedContextTags([{ ruleDef }], options.attributeDataTypes, tagTypes))
+            .map((tag) => options.contextTagBindings?.get(tag))
+            .filter((b) => b !== undefined && isSafeCmlAnnotationValue(b.tag))
+            .map((b) => ({ tag: b.tag, identifier: sanitizeName(b.tag), cmlType: b.cmlType, scope: b.scope }));
         return {
             recordId: record.Id,
             recordName: record.Name,
@@ -221,6 +296,8 @@ export function buildPathedSurchargeRules(prefix, ruleDefs, productIdToCode, pro
             typeName,
             statement,
             referencedAttributes,
+            contextTagDeclarations,
+            unconvertibleReason: joinReasons(findUnconvertibleConditions(ruleDef, options.attributeDataTypes, tagTypes)),
         };
     });
 }
@@ -240,7 +317,10 @@ export function buildUnderwritingConstraintStatement(constraintName, declaration
  * action statement. `productIdToCode` and `productIdToType` must already cover every ProductPath
  * segment.
  */
-export function buildUnderwritingConstraintRules(keyPrefix, constraintLabel, ruleDefs, productIdToCode, productIdToType) {
+export function buildUnderwritingConstraintRules(keyPrefix, constraintLabel, ruleDefs, productIdToCode, productIdToType, 
+// Org-resolved attribute types, so a picklist attribute is compared as the type behind the
+// picklist and declared with that same type in referencedAttributes.
+attributeDataTypes) {
     return ruleDefs.map(({ record, ruleDef }) => {
         const apiName = ruleDef.apiName ?? record.Name;
         const segments = splitProductPath(record.ProductPath);
@@ -249,7 +329,7 @@ export function buildUnderwritingConstraintRules(keyPrefix, constraintLabel, rul
         const ruleKey = buildPathedRuleKey(keyPrefix, pathCodes, apiName, stageTransition);
         const leafProductId = segments[segments.length - 1];
         const typeName = leafProductId ? productIdToType.get(leafProductId) : undefined;
-        const declaration = buildConstraintDeclaration(ruleDef);
+        const declaration = buildConstraintDeclaration(ruleDef, attributeDataTypes);
         // Mirrors buildCmlModel's constraint naming: sanitized apiName, with the stage transition
         // appended so two rules sharing an apiName under the same product (gated on different
         // transitions) don't collide.
@@ -260,8 +340,8 @@ export function buildUnderwritingConstraintRules(keyPrefix, constraintLabel, rul
         // collectAttributeTypes keys its map by the RAW attribute name, whereas
         // collectEmittedAttributes returns SANITIZED names, so we sanitize each raw key before
         // matching it against the emitted-name set.
-        const emittedSanitized = collectEmittedAttributes([{ ruleDef }]);
-        const attrTypesByRawName = collectAttributeTypes([{ ruleDef }]);
+        const emittedSanitized = collectEmittedAttributes([{ ruleDef }], attributeDataTypes);
+        const attrTypesByRawName = collectAttributeTypes([{ ruleDef }], attributeDataTypes);
         const referencedAttributes = [];
         for (const [rawName, cmlType] of attrTypesByRawName) {
             const sanitized = sanitizeName(rawName);
@@ -279,6 +359,7 @@ export function buildUnderwritingConstraintRules(keyPrefix, constraintLabel, rul
             constraintName,
             statement,
             referencedAttributes,
+            unconvertibleReason: joinReasons(findUnconvertibleConditions(ruleDef, attributeDataTypes)),
         };
     });
 }
@@ -313,6 +394,12 @@ export function mergeSurchargeRules(existingCml, rules) {
     // just-inserted statement (which would silently drop the second record's distinct declaration).
     const placedKeys = new Set();
     for (const rule of rules) {
+        // Checked first: a rule CML cannot express must not be placed on any path, and placing it
+        // would mean placing a declaration its dropped conditions had already emptied to `true`.
+        if (rule.unconvertibleReason) {
+            skips.push({ rule, reason: rule.unconvertibleReason });
+            continue;
+        }
         if (placedKeys.has(rule.ruleKey)) {
             skips.push({
                 rule,
@@ -340,7 +427,73 @@ export function mergeSurchargeRules(existingCml, rules) {
         // [Fix #1] One comment-blanked view of the current `cml` reused by both the replace-anchor
         // search and the type-block search this iteration. Recomputed per-iteration because a prior
         // rule's splice may have mutated `cml`.
-        const scan = blankComments(cml);
+        let scan = blankComments(cml);
+        // Resolved BEFORE the replace path, for two reasons. It lets the attribute gate below report an
+        // accurate cause (an unresolvable leaf scope makes every attribute look absent, so running the
+        // gate first would blame a missing attribute for what is really a missing type block, sending
+        // the operator off to declare an attribute in a type that does not exist). And a rule whose
+        // leaf type we cannot pin down must not rewrite a curated statement on the strength of a key
+        // match alone.
+        let block = findTypeBlock(cml, rule.typeName, scan);
+        if (!block) {
+            skips.push({ rule, reason: `type block '${rule.typeName}' not found in existing model` });
+            continue;
+        }
+        if ('ambiguous' in block) {
+            skips.push({
+                rule,
+                reason: `type block '${rule.typeName}' is ambiguous (multiple/duplicate declarations) in existing model; skipping ${rule.recordName} rather than guessing`,
+            });
+            continue;
+        }
+        // Runs BEFORE both the replace splice and the insert, so a rule we are going to withhold can
+        // never clobber a curated statement on its way out. Emitting an undeclared reference does not
+        // just produce a dead rule: the solver refuses to deploy the whole model, taking every other
+        // rule in the ExpressionSet down with it.
+        const absent = findAbsentAttributes(baseCml, rule, baseScan);
+        if (absent.length > 0) {
+            const names = absent.map((a) => `'${a}'`).join(', ');
+            attributeWarnings.push(`${rule.recordName}: declaration references ${names}, absent from the model`);
+            skips.push({
+                rule,
+                reason: `undeclared attribute ${names} referenced by ${rule.recordName}; withheld because the solver rejects the whole model at deploy, disabling every rule in it`,
+            });
+            continue;
+        }
+        // The replace path below finds the statement by key ANYWHERE in the model, so a statement that
+        // was previously written into the wrong type block gets rewritten there again, cementing the
+        // misplacement. Worse, the attribute gate above proved visibility against the RESOLVED block,
+        // not wherever the statement actually lives — so a mismatch can smuggle a reference that does
+        // not resolve at the real location past the gate, which is the failure that takes the whole
+        // model down. Refuse to rewrite a statement that sits outside the block it resolves to, and
+        // report it; relocating it would mean deleting a curated line, which is the operator's call.
+        // Checked before any declaration is spliced so a rule we withhold leaves no orphan behind.
+        const misplaced = findSurchargeStatement(cml, rule.ruleKey, scan);
+        if (misplaced && (misplaced.start < block.openIdx || misplaced.end > block.closeIdx)) {
+            skips.push({
+                rule,
+                reason: `misplaced statement for ${rule.recordName}: '${rule.ruleKey}' already exists outside its resolved type block '${rule.typeName}'; refusing to rewrite it where it stands`,
+            });
+            continue;
+        }
+        // The rule is going to be placed, so its resolved context tags must be declared first — the gate
+        // above passed them precisely because this runs. Declaring here (rather than after placement)
+        // also means a later rule sees the declaration and does not add a second one.
+        const withDeclarations = applyContextTagDeclarations(cml, rule, eol);
+        if (withDeclarations !== cml) {
+            // Every offset computed above is now stale, so re-derive them against the spliced text before
+            // the replace/insert below uses them.
+            cml = withDeclarations;
+            scan = blankComments(cml);
+            block = findTypeBlock(cml, rule.typeName, scan);
+            if (!block || 'ambiguous' in block) {
+                skips.push({
+                    rule,
+                    reason: `type block '${rule.typeName}' could not be re-resolved after declaring context tags for ${rule.recordName}`,
+                });
+                continue;
+            }
+        }
         // C2/M4/L1: only a REAL surcharge `rule(...)` statement carrying this exact key in the
         // action-scope slot counts as "present". A bare quoted-key substring inside an unrelated rule's
         // value, a longer key, or a comment must NOT trigger a destructive line replace.
@@ -355,19 +508,6 @@ export function mergeSurchargeRules(existingCml, rules) {
             cml = cml.slice(0, stmt.start) + rule.statement + cml.slice(stmt.end);
             placements.push({ rule, status: 'replaced' });
             placedKeys.add(rule.ruleKey);
-            collectAttributeWarning(baseCml, rule, attributeWarnings, baseScan);
-            continue;
-        }
-        const block = findTypeBlock(cml, rule.typeName, scan);
-        if (!block) {
-            skips.push({ rule, reason: `type block '${rule.typeName}' not found in existing model` });
-            continue;
-        }
-        if ('ambiguous' in block) {
-            skips.push({
-                rule,
-                reason: `type block '${rule.typeName}' is ambiguous (multiple/duplicate declarations) in existing model; skipping ${rule.recordName} rather than guessing`,
-            });
             continue;
         }
         // Insert before the closing brace, indented one level (4 spaces), with a leading blank line.
@@ -376,7 +516,6 @@ export function mergeSurchargeRules(existingCml, rules) {
         cml = cml.slice(0, block.closeIdx) + insertion + cml.slice(block.closeIdx);
         placements.push({ rule, status: 'inserted' });
         placedKeys.add(rule.ruleKey);
-        collectAttributeWarning(baseCml, rule, attributeWarnings, baseScan);
     }
     return { mergedCml: cml, placements, skips, attributeWarnings };
 }
@@ -389,13 +528,11 @@ export function mergeSurchargeRules(existingCml, rules) {
  * statement (from the `constraint` keyword through the terminating `;`) is replaced in place
  * (idempotent — re-running the merge with the same input reproduces the same output).
  * - Otherwise the statement is inserted just before the closing brace of the leaf `type` block.
- * - Before placing a rule's constraint, any of its `referencedAttributes` not already declared
- * anywhere in the leaf `type` block are auto-inserted (as `<cmlType> <attrName>;`) right after
- * the block's opening brace, and reported via `attributeWarnings` so the caller can log them —
- * unlike surcharge merge (which only WARNS about missing attributes, since injecting into the
- * curated model there was judged too risky for a `rule(...)` action statement), underwriting
- * constraints reference attributes that must resolve for the constraint to compile, so the
- * declaration is added rather than merely flagged.
+ * - Any of a rule's `referencedAttributes` not already declared anywhere in the leaf `type` block
+ * are reported via `attributeWarnings`; the curated model is never mutated to add them. NOTE: this
+ * is weaker than the surcharge merge, which WITHHOLDS such a rule outright — an unresolvable
+ * reference makes the solver reject the whole model at deploy, so warning here still lets a
+ * model-wide outage through. See findAbsentAttributes.
  *
  * Rules with a blank ProductPath, no resolved leaf type tag, an ambiguous/duplicate type block, or
  * an intra-run duplicate (typeName, constraintName) pair are skipped (reported, never silently
@@ -407,11 +544,21 @@ export function mergeUnderwritingConstraints(existingCml, rules) {
     const skips = [];
     const attributeWarnings = [];
     const eol = detectDominantLineEnding(existingCml);
+    // Baseline snapshot for the attribute gate below. `cml` is mutated as rules are placed, and a
+    // placed constraint mentions the attributes it references — scanning the mutated text would let
+    // a rule vouch for its own references, which is the bug the gate exists to prevent.
+    const baseCml = existingCml;
+    const baseScan = blankComments(existingCml);
     // Mirrors mergeSurchargeRules' placedKeys guard: a second rule resolving to the same
     // (typeName, constraintName) pair must be reported as a collision skip, not treated as an
     // idempotent replace of the first rule's just-placed statement.
     const placedNames = new Set();
     for (const rule of rules) {
+        // Checked first, for the same reason as in mergeSurchargeRules.
+        if (rule.unconvertibleReason) {
+            skips.push({ rule, reason: rule.unconvertibleReason });
+            continue;
+        }
         if (rule.pathProductCodes.length === 0) {
             skips.push({
                 rule,
@@ -446,15 +593,23 @@ export function mergeUnderwritingConstraints(existingCml, rules) {
             });
             continue;
         }
-        // Warn (but do not auto-insert) when a referenced attribute is not declared in the type
-        // block — matching the surcharge merge's behavior. The curated model is not mutated for
-        // attributes; the operator must add them manually before import.
-        for (const attr of rule.referencedAttributes) {
-            const bodyScan = scan.slice(block.openIdx, block.closeIdx + 1);
-            const declRe = new RegExp(`\\b${escapeRegExp(attr.cmlType)}\\s+${escapeRegExp(attr.name)}\\b`);
-            if (declRe.test(bodyScan))
-                continue;
-            attributeWarnings.push(`${rule.recordName}: declaration references '${attr.name}' which is absent from type '${rule.typeName}'`);
+        // Withhold — not warn — when a referenced attribute cannot be resolved from this type. An
+        // unresolvable reference makes the solver reject the ENTIRE model at deploy, disabling every
+        // other rule in the same ExpressionSet, and neither import nor activation catches it first.
+        // Uses the same hierarchy-aware scoping as the surcharge gate (leaf block plus its `: Parent`
+        // ancestry, plus top-level externs) rather than the leaf block body alone: an attribute
+        // declared on a parent type is genuinely visible here, and withholding it would be a false
+        // positive. Checked against the BASELINE text, since a rule's own spliced-in constraint
+        // contains the very names being looked for.
+        const absent = findUnresolvableReferences(baseCml, rule.typeName, rule.referencedAttributes.map((a) => a.name), baseScan);
+        if (absent.length > 0) {
+            const names = absent.map((a) => `'${a}'`).join(', ');
+            attributeWarnings.push(`${rule.recordName}: declaration references ${names}, absent from type '${rule.typeName}'`);
+            skips.push({
+                rule,
+                reason: `undeclared attribute ${names} referenced by ${rule.recordName}; withheld because the solver rejects the whole model at deploy, disabling every rule in it`,
+            });
+            continue;
         }
         const stmt = findConstraintStatement(cml, block, rule.constraintName, scan);
         if (stmt) {
@@ -629,16 +784,153 @@ export function blankComments(cml) {
     return out.join('');
 }
 /**
- * Surfaces (does not auto-fix) rule declarations that reference an attribute not present anywhere in
- * the curated model. In merge mode we never inject `string <attr>;` into the curated model, so an
- * unknown attribute would fail to compile on import — better to warn the engineer than to mangle the
- * Gold Standard. Attributes already present are trusted to be visible via the coverage type hierarchy.
+ * Returns the attributes a rule's declaration references that are not present anywhere in the
+ * curated model. In merge mode we never inject `string <attr>;` into the curated model, so an
+ * unknown attribute cannot resolve. Attributes already present are trusted to be visible via the
+ * coverage type hierarchy.
+ *
+ * The caller withholds any rule this reports on. Measured in sdb38-ins on 12 Aug 2026: a bare
+ * undeclared reference is not merely a rule that fails to fire — the solver rejects the ENTIRE
+ * model at deploy (`Couldn't find attribute 'TotalAmount' in AutoSilver`), which disables every
+ * other rule in the same ExpressionSet and makes the surcharge API return 500. Import and
+ * activation do not validate, so nothing catches it before first use in production.
  *
  * IMPORTANT: `baseCml` must be the ORIGINAL model text, captured before any surcharge statement was
  * spliced in. Checking the post-insertion text would always find the attribute inside the rule's own
  * just-inserted declaration (which sanitizes attribute names identically), suppressing every warning.
  */
-function collectAttributeWarning(baseCml, rule, warnings, baseScan) {
+/**
+ * A length-preserving view of `scan` with the BODY of every `type ... { ... }` block blanked, so a
+ * search can be restricted to the model's top level (where `extern` declarations live). Offsets are
+ * preserved, so an index found in this view still slices the real cml correctly.
+ *
+ * `matchClosingBrace` runs against the raw cml because it is comment-aware; the returned span is
+ * then blanked in the scan view. `lastIndex` is advanced past each block so a `type` nested inside
+ * another block is not scanned as a second top-level declaration.
+ */
+function blankTypeBlockBodies(cml, scan) {
+    const out = scan.split('');
+    const re = /(^|\n)[ \t]*type[ \t]+[A-Za-z_]\w*\b[^{;]*\{/g;
+    let m;
+    while ((m = re.exec(scan)) !== null) {
+        const openIdx = scan.indexOf('{', m.index);
+        if (openIdx < 0)
+            continue;
+        const closeIdx = matchClosingBrace(cml, openIdx);
+        if (closeIdx === undefined)
+            continue;
+        for (let i = openIdx; i <= closeIdx; i++)
+            out[i] = ' ';
+        re.lastIndex = closeIdx;
+    }
+    return out.join('');
+}
+/**
+ * Matches a real top-level `extern <type> <identifier>;` declaration. Deliberately anchored on the
+ * `extern` keyword rather than accepting any bare mention: this pattern is what lets the
+ * absent-reference gate treat an identifier as visible, and a false positive there would let an
+ * undeclared reference through — which takes the whole model down at deploy. `<type>` may carry a
+ * scale (`decimal(2)`) or be an array (`string[]`).
+ */
+function externDeclarationPattern(identifier) {
+    return new RegExp(`\\bextern\\s+[A-Za-z_]\\w*\\s*(?:\\(\\s*\\d+\\s*\\)|\\[\\s*\\])?\\s+${escapeRegExp(identifier)}\\s*;`);
+}
+/**
+ * Matches a declaration of `identifier` in any CML slot — `<type> <identifier>;` or
+ * `<type> <identifier> = ...`. Used ONLY for idempotency (do not emit a second declaration of
+ * something already declared), never to satisfy the absent-reference gate, so the looser shape is
+ * safe: at worst it suppresses a duplicate the model did not need.
+ */
+function declarationPattern(identifier) {
+    return new RegExp(`\\b[A-Za-z_]\\w*\\s*(?:\\(\\s*\\d+\\s*\\)|\\[\\s*\\])?\\s+${escapeRegExp(identifier)}\\s*[;=]`);
+}
+/**
+ * Where a new top-level `extern` belongs: immediately after the last existing top-level extern (so
+ * the bindings stay grouped as the curated models write them), else immediately before the first
+ * top-level `type` header, else at end of file. Returns an index into `cml`.
+ */
+function findExternInsertIndex(cml, scan) {
+    const topLevel = blankTypeBlockBodies(cml, scan);
+    const externRe = /\bextern\b[^;]*;/g;
+    let lastExternEnd = -1;
+    let m;
+    while ((m = externRe.exec(topLevel)) !== null)
+        lastExternEnd = m.index + m[0].length;
+    if (lastExternEnd >= 0)
+        return lastExternEnd;
+    const typeMatch = /(^|\n)[ \t]*type[ \t]+[A-Za-z_]\w*/.exec(topLevel);
+    if (typeMatch)
+        return typeMatch.index + (typeMatch[1] ? typeMatch[1].length : 0);
+    return cml.length;
+}
+/**
+ * Declares every context-tag reference this rule needs that the model does not already carry, and
+ * returns the updated CML.
+ *
+ * Two binding forms, chosen by the tag's position in the context tree (see
+ * insurance-context-tags.ts). Both mirror declarations a human already hand-wrote into the curated
+ * Auto_Silver model, which is the only evidence available that each form is correct.
+ *
+ * A transaction-level tag becomes a top-level
+ * `@(contextPath = "SalesTransaction.<Tag>", attributeSource = "ST") extern <type> <identifier>;`.
+ * An item-level tag becomes `@(tagName = "<Tag>") <type> <identifier>;` inside the leaf type block.
+ *
+ * The item-level declaration is placed just after the leaf block's opening brace rather than before
+ * its closing one (where rule statements go), so a declaration always precedes the statements that
+ * use it and the two insert paths cannot interleave confusingly.
+ *
+ * Idempotent: an identifier already declared — as a top-level extern for the transaction form, or
+ * anywhere in the leaf type block's own scope INCLUDING its `: Parent` ancestry for the item form —
+ * is left alone, so re-running the converter reproduces the same file.
+ */
+function applyContextTagDeclarations(cml, rule, eol) {
+    let out = cml;
+    for (const decl of rule.contextTagDeclarations) {
+        // Recomputed per declaration: each splice moves every offset after it.
+        const scan = blankComments(out);
+        if (decl.scope === 'transaction') {
+            if (externDeclarationPattern(decl.identifier).test(blankTypeBlockBodies(out, scan)))
+                continue;
+            const at = findExternInsertIndex(out, scan);
+            const annotation = `@(contextPath = "SalesTransaction.${decl.tag}", attributeSource = "ST")`;
+            const statement = `${annotation}${eol}extern ${decl.cmlType} ${decl.identifier};`;
+            // Appending after an existing extern only needs a leading newline; landing before a `type`
+            // header or at EOF needs to keep the following text on its own line.
+            const insertion = at > 0 && out[at - 1] === ';' ? `${eol}${statement}` : `${statement}${eol}${eol}`;
+            out = out.slice(0, at) + insertion + out.slice(at);
+            continue;
+        }
+        // Item scope. The caller has already resolved and validated the leaf type block, so a failure
+        // to re-find it here can only mean the model changed under us; skip rather than guess a home.
+        if (!rule.typeName)
+            continue;
+        const block = findTypeBlock(out, rule.typeName, scan);
+        if (!block || 'ambiguous' in block)
+            continue;
+        const visible = collectTypeScopeText(out, rule.typeName, undefined, scan) ?? '';
+        if (declarationPattern(decl.identifier).test(visible))
+            continue;
+        const at = block.openIdx + 1;
+        const statement = `${eol}    @(tagName = "${decl.tag}")${eol}    ${decl.cmlType} ${decl.identifier};`;
+        out = out.slice(0, at) + statement + out.slice(at);
+    }
+    return out;
+}
+function findAbsentAttributes(baseCml, rule, baseScan) {
+    // A context tag that resolved against the org is about to be DECLARED by
+    // {@link applyContextTagDeclarations}, so it counts as visible even though the baseline text does
+    // not mention it yet. Only RESOLVED tags appear here — an unresolved one is deliberately absent
+    // from the set, so it still fails the check and its rule is still withheld.
+    const willDeclare = new Set(rule.contextTagDeclarations.map((d) => d.identifier));
+    return findUnresolvableReferences(baseCml, rule.typeName, rule.referencedAttributes, baseScan, willDeclare);
+}
+/**
+ * Shared by both merges: returns the names, out of `names`, that cannot be resolved from inside
+ * type `typeName`. See {@link findAbsentAttributes} for why an unresolvable name is withheld rather
+ * than warned about.
+ */
+function findUnresolvableReferences(baseCml, typeName, names, baseScan, willDeclare = new Set()) {
+    const absent = [];
     // H5/M3: scope the presence check to the leaf type block plus its `: Parent` ancestry, with
     // comments and string literals stripped. CML attribute visibility is hierarchy-scoped, so an
     // unscoped whole-file `\battr\b` test gives false negatives (an attribute named only in a comment,
@@ -651,13 +943,22 @@ function collectAttributeWarning(baseCml, rule, warnings, baseScan) {
     // (that re-introduces the sibling-type false negative on exactly the records that hit the replace
     // path before type resolution). Fail VISIBLE instead: treat the scope as empty so an attribute we
     // cannot prove visible is reported, never silently suppressed.
-    const scope = rule.typeName ? collectTypeScopeText(baseCml, rule.typeName, undefined, baseScan) ?? '' : '';
-    for (const attr of rule.referencedAttributes) {
-        const present = new RegExp(`\\b${escapeRegExp(attr)}\\b`).test(scope);
-        if (!present) {
-            warnings.push(`${rule.recordName}: declaration references '${attr}' which is absent from the model`);
-        }
+    const scope = typeName ? collectTypeScopeText(baseCml, typeName, undefined, baseScan) ?? '' : '';
+    // Type-scoped visibility misses a TOP-LEVEL `extern`, which lives outside every type block yet is
+    // referable from inside one (the curated model's own `extern string UserProfile` is used inside
+    // `type AutoSilver`). Without this, a rule referencing an already-correctly-bound tag would be
+    // withheld for an attribute that is in fact declared. Matched on the anchored `extern` form only.
+    const topLevel = blankTypeBlockBodies(baseCml, baseScan ?? blankComments(baseCml));
+    for (const attr of names) {
+        if (willDeclare.has(attr))
+            continue;
+        if (new RegExp(`\\b${escapeRegExp(attr)}\\b`).test(scope))
+            continue;
+        if (externDeclarationPattern(attr).test(topLevel))
+            continue;
+        absent.push(attr);
     }
+    return absent;
 }
 /**
  * Removes `//` line comments, `/* *\/` block comments, and double-quoted string-literal CONTENTS