package gudusoft.gsqlparser.dlineage.dynamicsql;

import gudusoft.gsqlparser.EDbVendor;
import gudusoft.gsqlparser.TCustomSqlStatement;
import gudusoft.gsqlparser.nodes.TObjectName;
import gudusoft.gsqlparser.sqlenv.ESQLDataObjectType;
import gudusoft.gsqlparser.util.SQLUtil;

import java.util.ArrayList;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;

/**
 * B3 (design {@code routine-summary-scc-design.md} §2.1b/§2.3): the catalog-
 * backed {@link RoutineCallBinder}. Resolution is a function over the
 * candidate DEFINITION set — never identity field-equality against a single
 * key — and the binding maps follow the inline engine's semantics exactly
 * (arch-F8: SHADOW must not diff):
 *
 * <ul>
 * <li>expression actual ⇒ fan-in of all leaf source references + the
 *     expression text as transform carrier;</li>
 * <li>literal actual ⇒ no source (omitted from the inputs map);</li>
 * <li>OUT/INOUT target must be a bare writable lvalue — an expression,
 *     literal, or caller pure-IN formal is diagnosed with
 *     {@code PROC_CALL_OUT_TARGET_NOT_WRITABLE}; summary application then
 *     quarantines the whole non-executable call;</li>
 * <li>no unique candidate ⇒ AMBIGUOUS with the candidate list, nothing
 *     bound (codex-C5: duplicate definitions of one identity never
 *     overwrite each other).</li>
 * </ul>
 *
 * <p>Overload resolution in B3 is the structural subset of §2.1b: named /
 * positional binding plus default-fill over the candidate set. The vendor
 * type-family ranking (§2.1b step 2) arrives with the SCC slice — until
 * then two same-name candidates that both survive arity/name binding are
 * AMBIGUOUS, which is the conservative direction.
 */
public final class CatalogRoutineCallBinder implements RoutineCallBinder {

    /** One resolvable candidate: identity + defining unit provenance. */
    static final class Candidate {
        final RoutineCatalog.Definition definition;
        final String unitText;

        Candidate(RoutineCatalog.Definition definition, String unitText) {
            this.definition = definition;
            this.unitText = unitText;
        }
    }

    /**
     * Binder output enriched with what the SHADOW composition step needs
     * beyond the B0 contract: the formal-position → actual-position map
     * (named notation makes the two diverge) and the winning candidate's
     * defining unit.
     */
    public static final class BoundCall {
        private final BindingResult result;
        private final Map<Integer, Integer> actualPositionByFormal;
        private final String calleeUnitText;

        BoundCall(BindingResult result, Map<Integer, Integer> actualPositionByFormal,
                String calleeUnitText) {
            this.result = result;
            this.actualPositionByFormal = actualPositionByFormal == null
                    ? Collections.<Integer, Integer>emptyMap()
                    : Collections.unmodifiableMap(actualPositionByFormal);
            this.calleeUnitText = calleeUnitText;
        }

        public BindingResult getResult() { return result; }
        /** Declaration position of a formal → call-site position of its actual. */
        public Map<Integer, Integer> getActualPositionByFormal() {
            return actualPositionByFormal;
        }
        /** Unit text defining the resolved callee (identity-first lookups key
         *  summaries by identity; this is provenance for diagnostics). */
        public String getCalleeUnitText() { return calleeUnitText; }
    }

    private final EDbVendor vendor;
    private final RoutineCatalog catalog;

    public CatalogRoutineCallBinder(EDbVendor vendor, RoutineCatalog catalog) {
        this.vendor = vendor;
        this.catalog = catalog;
    }

    /** B0 contract entry: bind a raw call statement. The extractor-produced
     *  {@link CallSiteRef} path below is the primary consumer; this entry
     *  serves callers that hold only the AST. */
    @Override
    public BindingResult bind(TCustomSqlStatement callSite, CallerContext callerContext) {
        RoutineSummaryExtractor extractor = new RoutineSummaryExtractor(vendor);
        // A nested INSERT…EXEC execute node must not lose its consuming
        // INSERT (codex-B3-r3 finding 4): reparse the ENCLOSING statement so
        // the column list / missing-list flag / positional mapping survive.
        TCustomSqlStatement toParse = callSite;
        if (callSite instanceof gudusoft.gsqlparser.stmt.mssql.TMssqlExecute
                && callSite.getParentStmt()
                        instanceof gudusoft.gsqlparser.stmt.TInsertSqlStatement) {
            gudusoft.gsqlparser.stmt.TInsertSqlStatement parent =
                    (gudusoft.gsqlparser.stmt.TInsertSqlStatement)
                            callSite.getParentStmt();
            if (parent.getExecuteStmt() != null) {
                toParse = parent;
            }
        }
        CallSiteRef ref = null;
        List<CallSiteRef> sites = extractor.callSitesOfStatementText(
                toParse.toString());
        if (!sites.isEmpty()) {
            ref = sites.get(0);
        }
        if (ref == null) {
            return new BindingResult(BindingStatus.UNRESOLVED, null, null, null,
                    null, null, null, BindingCompleteness.PARTIAL,
                    Collections.singletonList(new BindingDiagnostic(
                            BindingDiagnosticCode.PROC_CALL_UNRESOLVED,
                            "unsupported call statement shape")));
        }
        return bind(ref, callerContext == null ? null : callerContext.getDatabase())
                .getResult();
    }

    /**
     * Bind one extractor-produced call site against every definition the
     * catalog knows, under the caller's effective database context.
     */
    public BoundCall bind(CallSiteRef site, String callerDb) {
        List<BindingDiagnostic> diagnostics = new ArrayList<BindingDiagnostic>();
        List<Candidate> candidates = candidatesFor(site.getRaw().getRawName(),
                callerDb, site.getActuals());
        if (candidates.isEmpty()) {
            diagnostics.add(new BindingDiagnostic(
                    BindingDiagnosticCode.PROC_CALL_UNRESOLVED,
                    site.getRaw().getRawName()));
            return new BoundCall(new BindingResult(BindingStatus.UNRESOLVED, null,
                    null, null, null, null, null, BindingCompleteness.PARTIAL,
                    diagnostics), null, null);
        }
        if (candidates.size() > 1) {
            List<RoutineIdentity> ids = new ArrayList<RoutineIdentity>();
            for (Candidate c : candidates) {
                ids.add(c.definition.identity);
            }
            diagnostics.add(new BindingDiagnostic(
                    BindingDiagnosticCode.PROC_CALL_AMBIGUOUS_OVERLOAD,
                    site.getRaw().getRawName() + ": " + ids.size() + " candidates"));
            return new BoundCall(new BindingResult(BindingStatus.AMBIGUOUS, null,
                    ids, null, null, null, null, BindingCompleteness.PARTIAL,
                    diagnostics), null, null);
        }
        Candidate winner = candidates.get(0);
        RoutineIdentity identity = winner.definition.identity;
        Map<Integer, Integer> actualByFormal =
                mapActualsToFormals(site.getActuals(), identity);
        if (actualByFormal == null) {
            // structurally compatible earlier, but named binding failed —
            // treat as unresolved rather than guessing positions
            diagnostics.add(new BindingDiagnostic(
                    BindingDiagnosticCode.PROC_CALL_ARGUMENT_UNBOUND,
                    site.getRaw().getRawName() + ": named argument binding failed"));
            return new BoundCall(new BindingResult(BindingStatus.UNRESOLVED, null,
                    null, null, null, null, null, BindingCompleteness.PARTIAL,
                    diagnostics), null, null);
        }
        boolean partial = false;
        Map<Integer, ActualSources> inputs = new LinkedHashMap<Integer, ActualSources>();
        Map<Integer, WritableTarget> outputs = new LinkedHashMap<Integer, WritableTarget>();
        for (Map.Entry<Integer, Integer> e : actualByFormal.entrySet()) {
            int formalPos = e.getKey();
            CallSiteRef.Actual actual = site.getActuals().get(e.getValue());
            if (actual.isDefaultToken()) {
                continue; // declared default applies — no source, no target
            }
            // Oracle pure OUT formals receive NO input value (the callee
            // initializes them) — binding the actual's prior value would
            // fabricate flow (codex-B3-r2 finding 3). T-SQL OUTPUT and
            // INOUT stay input-capable.
            boolean pureOracleOut = vendor == EDbVendor.dbvoracle
                    && isPureOutMode(identity, formalPos);
            if (!actual.isLiteral() && !pureOracleOut) {
                List<TObjectName> leafs = actual.getBareReference() != null
                        ? Collections.singletonList(actual.getBareReference())
                        : actual.getLeafReferences();
                if (!leafs.isEmpty() || actual.getExpressionText() != null) {
                    inputs.put(formalPos, new ActualSources(
                            new ArrayList<TObjectName>(leafs),
                            actual.getExpressionText()));
                }
            }
            if (declaredOut(identity, formalPos)) {
                // T-SQL projects OUT only when the CALL SITE says OUTPUT too;
                // omitting it passes by value (codex-B3-r1 finding 3). PL/SQL
                // has no call-site marker — the declared mode alone decides.
                boolean callSiteWantsOut = vendor == EDbVendor.dbvoracle
                        || actual.isOutFlagged();
                if (!callSiteWantsOut) {
                    // no OUT projection, no diagnostic: passing a value into
                    // an OUTPUT-capable formal without OUTPUT is legal T-SQL
                } else if (actual.getBareReference() != null) {
                    outputs.put(formalPos,
                            new WritableTarget(actual.getBareReference()));
                } else {
                    // expression OR literal in an OUT position: dropped with
                    // the required diagnostic, never fabricated.
                    diagnostics.add(new BindingDiagnostic(
                            BindingDiagnosticCode.PROC_CALL_OUT_TARGET_NOT_WRITABLE,
                            "formal #" + formalPos + " of "
                                    + site.getRaw().getRawName()));
                    partial = true;
                }
            } else if (actual.isOutFlagged()) {
                diagnostics.add(new BindingDiagnostic(
                        BindingDiagnosticCode.PROC_CALL_OUTPUT_MODE_MISMATCH,
                        "call-site OUTPUT flag on non-OUT formal #" + formalPos
                                + " of " + site.getRaw().getRawName()));
                partial = true;
            }
        }
        ResultSetMapping resultSets = null;
        if (!site.getInsertColumnNames().isEmpty()) {
            resultSets = new ResultSetMapping(
                    new ArrayList<TObjectName>(site.getInsertColumnNames()));
        } else if (site.isInsertWithoutColumnList()) {
            // INSERT…EXEC without an explicit column list: positional
            // ordinals are unknowable without a catalog — reported, never
            // guessed (codex-B3-r1 finding 4).
            diagnostics.add(new BindingDiagnostic(
                    BindingDiagnosticCode.PROC_CALL_ARGUMENT_UNBOUND,
                    "INSERT...EXEC without column list consuming "
                            + site.getRaw().getRawName()));
            partial = true;
        }
        // @ret = EXEC p: the status capture is a validated writable lvalue.
        // Its VALUE lineage stays deferred (RETURN_ENDPOINT_DEFERRED keeps
        // callee summaries PARTIAL), so binding it never fabricates edges.
        WritableTarget returnTarget = site.getReturnStatusTarget() == null
                ? null : new WritableTarget(site.getReturnStatusTarget());
        return new BoundCall(new BindingResult(BindingStatus.RESOLVED, identity,
                null, inputs, outputs, returnTarget, resultSets,
                partial ? BindingCompleteness.PARTIAL : BindingCompleteness.COMPLETE,
                diagnostics), actualByFormal, winner.unitText);
    }

    /**
     * Summary-composition binding with the caller signature available for
     * writable-lvalue validation. A PL/SQL pure-IN formal can be read inside
     * its routine but cannot receive a callee OUT value; treating its bare
     * spelling as writable publishes lineage for a call Oracle rejects.
     */
    public BoundCall bind(CallSiteRef site, String callerDb,
            RoutineIdentity callerIdentity) {
        BoundCall bound = bind(site, callerDb);
        BindingResult result = bound.getResult();
        if (vendor != EDbVendor.dbvoracle || callerIdentity == null
                || result.getStatus() != BindingStatus.RESOLVED
                || result.getOutputs().isEmpty()) {
            return bound;
        }
        Map<Integer, WritableTarget> outputs =
                new LinkedHashMap<Integer, WritableTarget>(result.getOutputs());
        List<BindingDiagnostic> diagnostics =
                new ArrayList<BindingDiagnostic>(result.getDiagnostics());
        boolean rejected = false;
        for (Map.Entry<Integer, WritableTarget> output
                : result.getOutputs().entrySet()) {
            Integer actualPos = bound.getActualPositionByFormal().get(
                    output.getKey());
            if (actualPos == null || actualPos < 0
                    || actualPos >= site.getActuals().size()) {
                continue;
            }
            CallSiteRef.Actual actual = site.getActuals().get(actualPos);
            int callerFormal = callerFormalPosition(actual.getBareReference(),
                    callerIdentity);
            if (callerFormal >= 0
                    && !declaredOut(callerIdentity, callerFormal)) {
                outputs.remove(output.getKey());
                diagnostics.add(new BindingDiagnostic(
                        BindingDiagnosticCode.PROC_CALL_OUT_TARGET_NOT_WRITABLE,
                        "caller pure-IN formal "
                                + callerIdentity.getRawParamNames().get(
                                        callerFormal)
                                + " bound to OUT formal #" + output.getKey()
                                + " of " + site.getRaw().getRawName()));
                rejected = true;
            }
        }
        if (!rejected) {
            return bound;
        }
        BindingResult filtered = new BindingResult(result.getStatus(),
                result.getResolved(), result.getCandidates(),
                result.getInputs(), outputs, result.getReturnTarget(),
                result.getResultSets(), BindingCompleteness.PARTIAL,
                diagnostics);
        return new BoundCall(filtered, bound.getActualPositionByFormal(),
                bound.getCalleeUnitText());
    }

    /** Caller formal position of one bare actual, or -1 for a local/table
     *  reference. Matching uses raw declaration spellings through the vendor
     *  equality facade; stored canonical text is never folded twice. */
    private int callerFormalPosition(TObjectName bare,
            RoutineIdentity callerIdentity) {
        if (bare == null) {
            return -1;
        }
        String actualName = bare.toString();
        List<String> parts = SQLUtil.parseNames(actualName);
        // Only an unqualified reference can be identified as the caller's
        // formal from spelling alone.  Suffix-matching a qualified reference
        // such as rec.p_in against formal p_in would reject a valid writable
        // record field as though it were the read-only formal.
        if (parts.size() != 1) {
            return -1;
        }
        actualName = parts.get(0);
        if (actualName.startsWith("@")) {
            actualName = actualName.substring(1);
        }
        for (int i = 0; i < callerIdentity.getRawParamNames().size(); i++) {
            String declared = callerIdentity.getRawParamNames().get(i);
            if (declared.startsWith("@")) {
                declared = declared.substring(1);
            }
            if (SQLUtil.sameName(vendor, ESQLDataObjectType.dotColumn,
                    actualName, declared)) {
                return i;
            }
        }
        return -1;
    }

    /** Pure OUT (not INOUT/OUTPUT) — Oracle's no-input-value mode. */
    private static boolean isPureOutMode(RoutineIdentity identity, int formalPos) {
        if (formalPos >= identity.getParamModes().size()) {
            return false;
        }
        String mode = identity.getParamModes().get(formalPos);
        if (mode == null) {
            return false;
        }
        String upper = mode.toUpperCase(java.util.Locale.ROOT); // non-identifier-compare: parameter-mode token vocabulary
        return upper.equals("OUT");
    }

    /** Declared OUT/OUTPUT/INOUT check over the identity's mode vocabulary. */
    private static boolean declaredOut(RoutineIdentity identity, int formalPos) {
        if (formalPos >= identity.getParamModes().size()) {
            return false;
        }
        String mode = identity.getParamModes().get(formalPos);
        if (mode == null) {
            return false;
        }
        String upper = mode.toUpperCase(java.util.Locale.ROOT); // non-identifier-compare: parameter-mode token vocabulary
        return upper.equals("OUT") || upper.equals("OUTPUT") || upper.equals("INOUT");
    }

    /**
     * The candidate definitions compatible with one call: name-matched under
     * the caller context, then named/positional + default-fill compatible.
     */
    private List<Candidate> candidatesFor(String callName, String callerDb,
            List<CallSiteRef.Actual> actuals) {
        List<Candidate> result = new ArrayList<Candidate>();
        for (String unitText : catalog.unitTexts()) {
            RoutineCatalog.UnitIndex index = catalog.indexOf(unitText);
            if (index == null) {
                continue;
            }
            for (RoutineCatalog.Definition def : index.definitions) {
                if (def.identity == null) {
                    continue;
                }
                if (!nameMatches(callName, callerDb, def)) {
                    continue;
                }
                if (!arityCompatible(actuals, def.identity)) {
                    continue;
                }
                result.add(new Candidate(def, unitText));
            }
            // Package members are PACKAGE_SCOPE_DEFERRED until B4: they share
            // one statement and cannot be summarized per definition yet, so
            // binding to them would compose against a summary that does not
            // exist. They are deliberately NOT candidates in B3.
        }
        return result;
    }

    /** Name match under caller context — EXACTLY the P5 resolver rules
     *  ({@code DynamicSqlLineageResolver.callMatchesProc}): a one-part call
     *  matches by simple name under database agreement; equal part counts
     *  compare fully; the 2↔3 part asymmetric pairs match only with the
     *  documented database checks; every other arity combination REFUSES —
     *  schema/database defaulting is environment-dependent and an unknown
     *  segment is never treated as a wildcard (codex-B3-r1 finding 1). */
    private boolean nameMatches(String callName, String callerDb,
            RoutineCatalog.Definition def) {
        List<String> callParts = SQLUtil.parseNames(callName);
        if (callParts.isEmpty()) {
            return false;
        }
        String callSimple = callParts.get(callParts.size() - 1);
        String defSimple = def.simple;
        if (vendor == EDbVendor.dbvmssql) {
            // Numbered procedures: base names must match AND the ;N group
            // must agree (";1" ≡ unnumbered) — codex-B3-r1 finding 6. The
            // definition's group lives on its IDENTITY (token-scanned at
            // catalog time; the parser drops ";N" from the AST name text).
            String callGroup = RoutineCatalog.mssqlNumberedSuffixOf(callSimple);
            String defGroup = def.identity.getOverloadDiscriminator();
            if (defGroup != null && (defGroup.length() == 0 || "1".equals(defGroup))) { // non-identifier-compare: numeric group suffix
                defGroup = null;
            }
            String textGroup = RoutineCatalog.mssqlNumberedSuffixOf(defSimple);
            if (defGroup == null && textGroup != null) {
                defGroup = textGroup;
            }
            if (callGroup == null ? defGroup != null : !callGroup.equals(defGroup)) { // non-identifier-compare: numeric group suffix
                return false;
            }
            callSimple = RoutineCatalog.stripMssqlNumberedSuffix(callSimple);
            defSimple = RoutineCatalog.stripMssqlNumberedSuffix(defSimple);
        }
        if (!SQLUtil.sameName(vendor, ESQLDataObjectType.dotProcedure,
                callSimple, defSimple)) {
            return false;
        }
        if (vendor == EDbVendor.dbvmssql) {
            // Database agreement first (a 3-part call carries its own db).
            if (callParts.size() < 3 && !sameEffectiveDb(def.db, callerDb)) {
                return false;
            }
            List<String> defParts = definitionNameParts(def);
            if (callParts.size() == 1) {
                return true; // simple-name rule under db agreement (P5)
            }
            if (callParts.size() == defParts.size()) {
                // The simple name (last segment) was already compared above
                // with the ;N group stripped — compare the container
                // segments only.
                for (int i = 2; i <= callParts.size(); i++) {
                    ESQLDataObjectType type = i == 2
                            ? ESQLDataObjectType.dotSchema
                            : ESQLDataObjectType.dotCatalog;
                    if (!SQLUtil.sameName(vendor, type,
                            callParts.get(callParts.size() - i),
                            defParts.get(defParts.size() - i))) {
                        return false;
                    }
                }
                return true;
            }
            if (callParts.size() == 2 && defParts.size() == 3) {
                // db agreement already established; compare schema.name
                return SQLUtil.sameName(vendor, ESQLDataObjectType.dotSchema,
                        callParts.get(0), defParts.get(1));
            }
            if (callParts.size() == 3 && defParts.size() == 2) {
                // explicit call catalog must equal the KNOWN effective db
                return def.db != null
                        && SQLUtil.sameName(vendor, ESQLDataObjectType.dotCatalog,
                                callParts.get(0), def.db)
                        && SQLUtil.sameName(vendor, ESQLDataObjectType.dotSchema,
                                callParts.get(1), defParts.get(0));
            }
            // Other combinations (e.g. qualified call vs one-part definition):
            // conservative no-match, exactly like the P5 resolver.
            return false;
        }
        // Oracle: one-part call matches by simple name; a schema-qualified
        // call requires the definition's schema KNOWN and equal (an unknown
        // definition schema is not a wildcard).
        if (callParts.size() == 1) {
            return true;
        }
        if (callParts.size() == 2) {
            return def.schema != null
                    && SQLUtil.sameName(vendor, ESQLDataObjectType.dotSchema,
                            callParts.get(0), def.schema);
        }
        return false;
    }

    /** P5 {@code sameEffectiveDatabase} for one/two-part calls: both unknown
     *  ⇒ same analysis default; one unknown ⇒ NOT provably same, refuse. */
    private boolean sameEffectiveDb(String defDb, String callerDb) {
        if (defDb == null && callerDb == null) {
            return true;
        }
        if (defDb == null || callerDb == null) {
            return false;
        }
        return SQLUtil.sameName(vendor, ESQLDataObjectType.dotCatalog,
                defDb, callerDb);
    }

    /** The definition's declared name segments (as written, catalog-first). */
    private List<String> definitionNameParts(RoutineCatalog.Definition def) {
        if (def.stmt instanceof gudusoft.gsqlparser.stmt.mssql.TMssqlCreateProcedure) {
            gudusoft.gsqlparser.stmt.mssql.TMssqlCreateProcedure proc =
                    (gudusoft.gsqlparser.stmt.mssql.TMssqlCreateProcedure) def.stmt;
            if (proc.getProcedureName() != null) {
                return SQLUtil.parseNames(proc.getProcedureName().toString());
            }
        }
        List<String> parts = new ArrayList<String>();
        if (def.schema != null) {
            parts.add(def.schema);
        }
        parts.add(def.simple);
        return parts;
    }

    /** Schema segment of an MSSQL definition name (identity carries it). */
    private String definitionSchema(RoutineCatalog.Definition def) {
        return def.identity == null || def.identity.getCanonSchema() == null
                || def.identity.getCanonSchema().length() == 0
                ? null : def.identity.getCanonSchema();
    }

    /** Named/positional + default-fill compatibility (§2.1b step 1). */
    private boolean arityCompatible(List<CallSiteRef.Actual> actuals,
            RoutineIdentity identity) {
        int paramCount = identity.getParamNames().size();
        if (actuals.size() > paramCount) {
            return false;
        }
        Map<Integer, Integer> mapped = mapActualsToFormals(actuals, identity);
        if (mapped == null) {
            return false;
        }
        for (int p = 0; p < paramCount; p++) {
            if (!mapped.containsKey(p) && !identity.getParamHasDefault().get(p)) {
                return false;
            }
        }
        // An explicit DEFAULT actual requires a DECLARED default on its
        // formal (codex-B3-r1 finding 11).
        for (Map.Entry<Integer, Integer> e : mapped.entrySet()) {
            if (actuals.get(e.getValue()).isDefaultToken()
                    && !identity.getParamHasDefault().get(e.getKey())) {
                return false;
            }
        }
        return true;
    }

    /** Formal position → actual position; null when a named actual matches no
     *  formal or positional/named mixing is inconsistent. */
    private Map<Integer, Integer> mapActualsToFormals(
            List<CallSiteRef.Actual> actuals, RoutineIdentity identity) {
        Map<Integer, Integer> result = new LinkedHashMap<Integer, Integer>();
        List<String> paramNames = identity.getParamNames();
        boolean namedSeen = false;
        for (CallSiteRef.Actual actual : actuals) {
            if (actual.getNamedFormal() != null) {
                namedSeen = true;
                int formal = formalPositionOf(actual.getNamedFormal(), identity);
                if (formal < 0 || result.containsKey(formal)) {
                    return null;
                }
                result.put(formal, actual.getPosition());
            } else {
                if (namedSeen) {
                    // positional after named is invalid in both vendors
                    return null;
                }
                int formal = actual.getPosition();
                if (formal >= paramNames.size()) {
                    return null;
                }
                result.put(formal, actual.getPosition());
            }
        }
        return result;
    }

    /** Position of a named actual's formal; -1 when absent. Compared over
     *  the RAW declared spellings via the equality facade — re-keying the
     *  stored canonical text would double-fold quoted names (a declared
     *  {@code "x"} stored as {@code x} must not re-fold to {@code X} —
     *  codex-B3-r2 finding 12). */
    private int formalPositionOf(String namedFormal, RoutineIdentity identity) {
        List<String> rawNames = identity.getRawParamNames();
        for (int i = 0; i < rawNames.size(); i++) {
            if (SQLUtil.sameName(vendor, ESQLDataObjectType.dotColumn,
                    stripAt(namedFormal), stripAt(rawNames.get(i)))) {
                return i;
            }
        }
        return -1;
    }

    /** Both call-site and declaration @-prefix variants occur; the prefix is
     *  not an identifier character, so it is stripped outside folding. */
    private static String stripAt(String name) {
        return name != null && name.startsWith("@") ? name.substring(1) : name;
    }
}