package gudusoft.gsqlparser.sqlenv;

import gudusoft.gsqlparser.EDbVendor;

import java.util.Objects;

/**
 * Vendor-aware quote codec for database identifiers (U2a of the persistent
 * canonical-identity program).
 *
 * <p>This class is the ONE place that knows how each vendor delimits an
 * identifier and how delimiter characters are escaped inside it. It converts
 * between the two textual forms of an identifier:
 * <ul>
 * <li><b>lexical</b> — the spelling as it appears in SQL text, possibly
 *     wrapped in vendor delimiters (<code>"x"</code>, <code>[x]</code>,
 *     <code>`x`</code>, DAX <code>'x'</code>, Power&nbsp;Query
 *     <code>#"x"</code>, PostgreSQL <code>U&amp;"x"</code>);</li>
 * <li><b>stored</b> — the undelimited name as the catalog stores it.</li>
 * </ul>
 *
 * <p><b>Role context matters.</b> Every operation takes the
 * {@link IdentifierProfile} <i>and</i> the {@link ESQLDataObjectType}: quote
 * rules are not purely per-vendor. DAX quotes <i>table</i> names with
 * apostrophes while columns/measures use brackets; MySQL treats {@code "} as
 * an identifier delimiter only under {@code ANSI_QUOTES}
 * ({@link IdentifierProfile.VendorFlags#mysqlAnsiQuotes}); BigQuery backtick
 * identifiers use backslash escape sequences, not doubling.
 *
 * <p><b>Strictness.</b> {@link #decodeLexical} is strict: input that starts
 * with a recognized open delimiter but is not a well-formed quoted identifier
 * (unterminated, unescaped inner delimiter, trailing garbage, invalid escape)
 * throws {@link MalformedIdentifierException}. This is deliberate — the
 * legacy first/last-char strip ({@code TBaseType.getTextWithoutQuoted})
 * silently accepted malformed spellings like {@code [a.b[} and produced
 * corrupted stored names. An unrecognized escape sequence throws rather than
 * being passed through — silently decoding it as literal text would corrupt
 * the stored name — EXCEPT where the vendor itself defines unknown escapes
 * as literal: ClickHouse deliberately preserves an unknown escape verbatim
 * (backslash and character), and this codec follows that dialect behavior.
 *
 * <p><b>Transport totality.</b> {@link #encodeStored} is total: it accepts
 * ANY string — empty, embedded delimiters, NUL, supplementary characters,
 * unpaired surrogates — and always emits a spelling (quoted, except for
 * vendors like SOQL with no quoted-identifier syntax, where the bare name is
 * canonical) that {@link #decodeLexical} maps back to the exact input. Whether that spelling
 * is also legal SQL for the vendor is a stricter, separately queryable
 * property: {@link #isVendorValidSpelling}. (BigQuery forbids empty quoted
 * identifiers, MySQL forbids NUL — such spellings still round-trip through
 * the codec as transport encodings.)
 *
 * <p><b>Canonical encoding always quotes.</b> {@code encodeStored} does not
 * try to decide whether the name could be spelled bare; emitting the quoted
 * form is always semantically safe, total, and matches the internal
 * producers this codec repairs (U2b), which always wrapped.
 *
 * <p><b>Recognition set provenance.</b> Canonical delimiters follow the
 * legacy {@code TSQLEnv.delimitedChar} choice per vendor; additional accepted
 * delimiters come from vendor documentation. Deltas vs the legacy
 * {@code TSQLEnv.isDelimitedIdentifier} are deliberate corrections:
 * mismatched open/close pairs are fixed ({@code [}…{@code ]}), and vendors
 * the legacy switch mishandled get their documented forms (Spark/Databricks
 * backticks, PostgreSQL {@code U&"…"}, per-role DAX). SQL Server keeps
 * apostrophe RECOGNITION in the COLUMN role only: the U2a draft dropped
 * {@code 'x'} as "not an identifier delimiter", but the string-literal
 * column-alias form names a real column ({@code AS 'REGKEY'} creates column
 * {@code REGKEY}) and the U5 swap proved lineage edges are lost when the
 * spelling does not decode — see {@code RULES_MSSQL_COLUMN} (recognition
 * only: excluded from {@link #isVendorValidSpelling}, never emitted).
 *
 * <p><b>Contract for prefix forms.</b> A PostgreSQL {@code U&"…"} lexical is
 * decoded with the DEFAULT escape character {@code \}; a {@code UESCAPE}
 * clause is a separate token that can never be part of a single identifier
 * token, so it is outside this codec's contract (callers pass one token).
 *
 * <p><b>Versioning.</b> {@link #CODEC_REVISION} names the revision of the
 * delimiter/escape table ("codec/1"). It participates in the persistent-key
 * {@code policyId} (U3): a change to decoding behavior changes key payloads,
 * so it must rotate keys.
 *
 * @since 4.1.5.6
 */
public final class IdentifierCodec {

    /**
     * Revision of the per-vendor delimiter/escape table — the "1" of
     * "codec/1". Bump when any decode/encode mapping changes; the U3
     * persistent-key policyId includes this value, so a bump rotates keys.
     */
    public static final int CODEC_REVISION = 1;

    private IdentifierCodec() {
    }

    /**
     * Thrown by {@link #decodeLexical} when the input starts with a
     * recognized open delimiter but is not a well-formed quoted identifier.
     */
    public static final class MalformedIdentifierException extends IllegalArgumentException {
        private static final long serialVersionUID = 1L;

        public MalformedIdentifierException(String message) {
            super(message);
        }
    }

    // ===== The per-vendor delimiter/escape table (revision: CODEC_REVISION) =====

    /** The close delimiter is escaped by doubling it; no other escapes. */
    private static final int ESC_DOUBLING = 0;
    /** BigQuery backslash escape sequences (GoogleSQL string escapes). */
    private static final int ESC_BACKSLASH_BQ = 1;
    /** No escape mechanism: the first close delimiter terminates (SQLite brackets). */
    private static final int ESC_NONE = 2;
    /** ClickHouse: doubling AND backslash escapes both work. */
    private static final int ESC_CLICKHOUSE = 3;
    /** Power Query M: doubling for the quote, {@code #(...)} character escapes. */
    private static final int ESC_POWERQUERY = 4;
    /** PostgreSQL Unicode identifier: doubling for the quote, default {@code \} escapes. */
    private static final int ESC_PG_UNICODE = 5;

    private static final class QuoteRule {
        /** Opening delimiter; may be multi-character ({@code #"}, {@code U&"}). */
        final String open;
        final char close;
        final int escape;
        /** Recognized and decoded, but NOT a vendor-valid identifier spelling
         *  (MSSQL {@code 'alias'}: single quotes delimit string literals per
         *  SET QUOTED_IDENTIFIER; the deprecated string-literal alias form
         *  names a real column, so equality must decode it, but emitting or
         *  blessing it as an identifier spelling would be wrong). */
        final boolean recognitionOnly;

        QuoteRule(String open, char close, int escape) {
            this(open, close, escape, false);
        }

        QuoteRule(String open, char close, int escape, boolean recognitionOnly) {
            this.open = open;
            this.close = close;
            this.escape = escape;
            this.recognitionOnly = recognitionOnly;
        }
    }

    private static final QuoteRule DQUOTE = new QuoteRule("\"", '"', ESC_DOUBLING);
    private static final QuoteRule BRACKET = new QuoteRule("[", ']', ESC_DOUBLING);
    private static final QuoteRule BACKTICK = new QuoteRule("`", '`', ESC_DOUBLING);
    private static final QuoteRule SQUOTE = new QuoteRule("'", '\'', ESC_DOUBLING);
    private static final QuoteRule BQ_BACKTICK = new QuoteRule("`", '`', ESC_BACKSLASH_BQ);
    private static final QuoteRule SQLITE_BRACKET = new QuoteRule("[", ']', ESC_NONE);
    private static final QuoteRule CH_DQUOTE = new QuoteRule("\"", '"', ESC_CLICKHOUSE);
    private static final QuoteRule CH_BACKTICK = new QuoteRule("`", '`', ESC_CLICKHOUSE);
    private static final QuoteRule PQ_QUOTE = new QuoteRule("#\"", '"', ESC_POWERQUERY);
    private static final QuoteRule PG_UNICODE_UPPER = new QuoteRule("U&\"", '"', ESC_PG_UNICODE);
    private static final QuoteRule PG_UNICODE_LOWER = new QuoteRule("u&\"", '"', ESC_PG_UNICODE);

    /** ANSI default: double quotes, doubling. */
    private static final QuoteRule[] RULES_ANSI = {DQUOTE};
    /** PostgreSQL / EDB: double quotes canonical; {@code U&"…"} Unicode form accepted. */
    private static final QuoteRule[] RULES_PG = {DQUOTE, PG_UNICODE_UPPER, PG_UNICODE_LOWER};
    /** MSSQL string-literal alias form: recognized/decoded, never valid or emitted. */
    private static final QuoteRule SQUOTE_ALIAS = new QuoteRule("'", '\'', ESC_DOUBLING, true);

    /**
     * SQL Server / Azure SQL: brackets canonical (QUOTENAME default), double
     * quotes under QUOTED_IDENTIFIER ON (the server default).
     */
    private static final QuoteRule[] RULES_MSSQL = {BRACKET, DQUOTE};
    /**
     * SQL Server / Azure SQL COLUMN role additionally accepts the apostrophe
     * form for RECOGNITION/DECODE only: {@code 'x'} is the deprecated-but-
     * supported string-literal COLUMN-alias syntax, and the identifier it
     * names is the unquoted inner text — {@code SELECT c AS 'REGKEY'} creates
     * column {@code REGKEY}, so the alias spelling must decode to meet its
     * references (the U5 dataflow-golden gate lost real lineage edges without
     * this; the U2a draft dropped the form entirely and was wrong). Scoped to
     * the column role — single quotes are string-literal delimiters in every
     * other identifier position (SET QUOTED_IDENTIFIER) — and excluded from
     * {@link #isVendorValidSpelling} via {@code recognitionOnly}. Never the
     * canonical encoding — {@code encodeStored} still emits brackets
     * (rules[0]).
     */
    private static final QuoteRule[] RULES_MSSQL_COLUMN = {BRACKET, DQUOTE, SQUOTE_ALIAS};
    /** MySQL family, default sql_mode: backtick only. */
    private static final QuoteRule[] RULES_MYSQL = {BACKTICK};
    /** MySQL / OceanBase with ANSI_QUOTES: double quotes also delimit identifiers. */
    private static final QuoteRule[] RULES_MYSQL_ANSI = {BACKTICK, DQUOTE};
    /** Hive / Impala / Flink / Couchbase: backtick, doubling. */
    private static final QuoteRule[] RULES_BACKTICK = {BACKTICK};
    /**
     * SparkSQL / Databricks: backtick canonical; double quotes also accepted —
     * both engines have ANSI modes where {@code "x"} delimits an identifier
     * (Spark requires BOTH {@code spark.sql.ansi.enabled} AND
     * {@code spark.sql.ansi.doubleQuotedIdentifiers}; Databricks
     * {@code double_quoted_identifiers}), and a double-quoted spelling that
     * reaches an identifier position denotes the inner name. Also preserves
     * the legacy recognizer's behavior for these two vendors (it accepted
     * {@code "x"} — U5 found display names regress without it).
     */
    private static final QuoteRule[] RULES_SPARK = {BACKTICK, DQUOTE};
    /** BigQuery: backtick with backslash escape sequences. */
    private static final QuoteRule[] RULES_BIGQUERY = {BQ_BACKTICK};
    /**
     * Athena: backtick canonical (matches legacy {@code delimitedChar} and
     * Hive-style DDL); double quotes accepted (the Presto/Trino DML engine).
     */
    private static final QuoteRule[] RULES_ATHENA = {BACKTICK, DQUOTE};
    /** DAX table names: apostrophes, doubling. */
    private static final QuoteRule[] RULES_DAX_TABLE = {SQUOTE};
    /** DAX columns/measures: brackets, {@code ]]} doubling. */
    private static final QuoteRule[] RULES_DAX_COLUMN = {BRACKET};
    /**
     * SQLite: double quotes canonical; brackets and backticks accepted
     * (documented compatibility forms). SQLite brackets have NO escape —
     * the first {@code ]} terminates the identifier.
     */
    private static final QuoteRule[] RULES_SQLITE = {DQUOTE, SQLITE_BRACKET, BACKTICK};
    /** Sybase ASE: double quotes canonical (quoted_identifier), T-SQL brackets accepted. */
    private static final QuoteRule[] RULES_SYBASE = {DQUOTE, BRACKET};
    /** ClickHouse: double quotes canonical, backticks accepted; doubling OR backslash escapes. */
    private static final QuoteRule[] RULES_CLICKHOUSE = {CH_DQUOTE, CH_BACKTICK};
    /** MDX: brackets with {@code ]]} doubling. */
    private static final QuoteRule[] RULES_MDX = {BRACKET};
    /** Power Query M: {@code #"…"} with doubling and {@code #(...)} escapes. */
    private static final QuoteRule[] RULES_POWERQUERY = {PQ_QUOTE};
    /**
     * Salesforce SOQL has NO quoted-identifier syntax at all: nothing is
     * recognized as quoted, and the canonical encoding of a stored name is
     * the bare name itself (decode is the identity, so transport round-trip
     * still holds exactly).
     */
    private static final QuoteRule[] RULES_NONE = {};

    /**
     * 128-bit set of the first character of every open delimiter across ALL
     * vendor rule tables — a one-branch rejection gate for {@link #isQuoted}'s
     * dominant input (an unquoted identifier, U5 gate-3 hot path). Computed
     * from the tables themselves so it can never drift from them; construction
     * fails if a future rule ever starts with a non-ASCII character (the gate
     * would then need widening).
     */
    private static final long[] OPEN_FIRST = buildOpenFirst();

    private static long[] buildOpenFirst() {
        QuoteRule[][] all = {RULES_ANSI, RULES_PG, RULES_MSSQL, RULES_MSSQL_COLUMN,
                RULES_MYSQL, RULES_MYSQL_ANSI, RULES_BACKTICK, RULES_SPARK,
                RULES_BIGQUERY, RULES_ATHENA, RULES_DAX_TABLE, RULES_DAX_COLUMN,
                RULES_SQLITE, RULES_SYBASE, RULES_CLICKHOUSE, RULES_MDX,
                RULES_POWERQUERY};
        long[] bits = new long[2];
        for (QuoteRule[] rules : all) {
            for (QuoteRule r : rules) {
                char c = r.open.charAt(0);
                if (c >= 128) {
                    throw new IllegalStateException("Non-ASCII open delimiter '"
                            + r.open + "' - widen the isQuoted first-char gate");
                }
                bits[c >>> 6] |= 1L << (c & 63);
            }
        }
        return bits;
    }

    /**
     * Whether this vendor's quote recognition/decoding consults
     * {@link IdentifierProfile.VendorFlags#mysqlAnsiQuotes} — i.e. exactly the
     * vendors whose {@link #rulesFor} branch reads the flag. Consumed by the
     * V1 policy descriptor ({@code IdentifierPolicyV1}): the flag is part of
     * payload-producing behavior only where it is honored, so including it
     * elsewhere would rotate keys it cannot affect. Keep in sync with
     * {@link #rulesFor}.
     */
    static boolean consultsAnsiQuotes(EDbVendor vendor) {
        return vendor == EDbVendor.dbvmysql || vendor == EDbVendor.dbvoceanbase;
    }

    private static QuoteRule[] rulesFor(IdentifierProfile profile, ESQLDataObjectType objectType) {
        EDbVendor vendor = profile.getVendor();
        switch (vendor) {
            case dbvmssql:
            case dbvazuresql:
                return objectType == ESQLDataObjectType.dotColumn
                        ? RULES_MSSQL_COLUMN : RULES_MSSQL;

            case dbvaccess:
                // Access names are delimited with brackets, and Access SQL goes through the
                // MSSQL lexer (TGSqlParser), which also reads a double-quoted name as one.
                return RULES_MSSQL;

            case dbvmysql:
            case dbvoceanbase:  // Phase 1 mirrors MySQL, like its IdentifierRules seeding
                return profile.getFlags().mysqlAnsiQuotes ? RULES_MYSQL_ANSI : RULES_MYSQL;

            case dbvdoris:
            case dbvstarrocks:
                // MySQL-compatible engines WITHOUT documented ANSI_QUOTES
                // support: the flag is deliberately not honored here.
                return RULES_MYSQL;

            case dbvbigquery:
                return RULES_BIGQUERY;

            case dbvhive:
            case dbvimpala:
            case dbvflink:
            case dbvcouchbase:
                return RULES_BACKTICK;

            case dbvsparksql:
            case dbvdatabricks:
                return RULES_SPARK;

            case dbvathena:
                return RULES_ATHENA;

            case dbvdax:
                // Explicit per-role table (round 3 of the plan review requires
                // quoting to depend on the actual syntactic role, not the
                // fold-policy group): columns and measures are bracketed;
                // table names are apostrophe-quoted. Roles the DAX object
                // model does not have (schema, catalog, procedure, ...) are
                // treated as table-style names — DAX has no quoted spelling
                // for them, and table rules are the only name-position form.
                switch (objectType) {
                    case dotColumn:
                    case dotFunction:
                    case dotRoutine:
                        return RULES_DAX_COLUMN;
                    case dotTable:
                    default:
                        return RULES_DAX_TABLE;
                }

            case dbvsqlite:
                return RULES_SQLITE;

            case dbvsybase:
                return RULES_SYBASE;

            case dbvsybasease:
                // Identical rules to the base by design (HC-9): the fork
                // must resolve names exactly as dbvsybase does, or every
                // downstream comparison changes meaning.
                return RULES_SYBASE;

            case dbvsqlanywhere:
                // Same reasoning, independent block per HC-5.
                return RULES_SYBASE;

            case dbvsybaseiq:
                // Same again, independent block per HC-5.
                return RULES_SYBASE;

            case dbvclickhouse:
                return RULES_CLICKHOUSE;

            case dbvmdx:
                return RULES_MDX;

            case dbvpowerquery:
                return RULES_POWERQUERY;

            case dbvpostgresql:
            case dbvedb:
                return RULES_PG;

            case dbvsoql:
                return RULES_NONE;

            default:
                return RULES_ANSI;
        }
    }

    private static QuoteRule ruleForOpen(QuoteRule[] rules, String s) {
        for (QuoteRule r : rules) {
            if (s.startsWith(r.open)) {
                return r;
            }
        }
        return null;
    }

    // ===== Public API =====

    /**
     * Decode one lexical identifier to its stored text.
     *
     * <p>If the input does not start with a delimiter this vendor/role
     * recognizes, it is an unquoted identifier and is returned unchanged
     * (case folding is NOT this codec's job — see
     * {@link IdentifierRules.CaseFold}). If it does start with a recognized
     * open delimiter, it must be a complete well-formed quoted identifier;
     * anything else throws.
     *
     * @param profile vendor identifier profile (non-null)
     * @param objectType syntactic role of the identifier (non-null; DAX
     *                   quote rules depend on it)
     * @param lexical the identifier spelling as written in SQL (non-null)
     * @return the stored (undelimited, unescaped) text
     * @throws MalformedIdentifierException if {@code lexical} starts with a
     *         recognized open delimiter but is not well-formed
     */
    public static String decodeLexical(IdentifierProfile profile,
                                       ESQLDataObjectType objectType,
                                       String lexical) {
        Objects.requireNonNull(profile, "profile");
        Objects.requireNonNull(objectType, "objectType");
        Objects.requireNonNull(lexical, "lexical");
        if (lexical.isEmpty()) {
            return lexical;
        }
        QuoteRule rule = ruleForOpen(rulesFor(profile, objectType), lexical);
        if (rule == null) {
            return lexical;
        }
        switch (rule.escape) {
            case ESC_BACKSLASH_BQ:
                return decodeBigQuery(lexical, rule);
            case ESC_NONE:
                return decodeNoEscape(lexical, rule);
            case ESC_CLICKHOUSE:
                return decodeClickHouse(lexical, rule);
            case ESC_POWERQUERY:
                return decodePowerQuery(lexical, rule);
            case ESC_PG_UNICODE:
                return decodePgUnicode(lexical, rule);
            default:
                return decodeDoubling(lexical, rule);
        }
    }

    /**
     * Encode stored text to a canonical lexical spelling.
     *
     * <p>Total as a TRANSPORT encoding: any string — empty, delimiters, NUL,
     * supplementary, unpaired surrogates — round-trips exactly through
     * {@link #decodeLexical}. The result is quoted with the vendor's
     * canonical delimiter for the role; for a vendor with no
     * quoted-identifier syntax at all (SOQL) the bare name is the canonical
     * spelling and encode is the identity. Vendor-valid-SQL is a stricter,
     * separately queryable property: {@link #isVendorValidSpelling}.
     *
     * @param profile vendor identifier profile (non-null)
     * @param objectType syntactic role of the identifier (non-null)
     * @param stored the stored (undelimited) text (non-null)
     * @return the canonical quoted spelling
     */
    public static String encodeStored(IdentifierProfile profile,
                                      ESQLDataObjectType objectType,
                                      String stored) {
        Objects.requireNonNull(profile, "profile");
        Objects.requireNonNull(objectType, "objectType");
        Objects.requireNonNull(stored, "stored");
        QuoteRule[] rules = rulesFor(profile, objectType);
        if (rules.length == 0) {
            // no quoted-identifier syntax (SOQL): the bare name IS the
            // canonical lexical spelling; decode is the identity
            return stored;
        }
        QuoteRule rule = rules[0];
        StringBuilder sb = new StringBuilder(stored.length() + rule.open.length() + 1);
        sb.append(rule.open);
        for (int i = 0; i < stored.length(); i++) {
            char c = stored.charAt(i);
            switch (rule.escape) {
                case ESC_BACKSLASH_BQ:
                    // GoogleSQL's lexer excludes raw CR/LF from backtick
                    // identifiers: emit their escape forms
                    if (c == (char) 0x0D) {
                        sb.append('\\').append('r');
                        break;
                    }
                    if (c == (char) 0x0A) {
                        sb.append('\\').append('n');
                        break;
                    }
                    if (c == '\\' || c == rule.close) {
                        sb.append('\\');
                    }
                    sb.append(c);
                    break;
                case ESC_CLICKHOUSE:
                    // backslash is escape-significant on decode, so escape it;
                    // the close delimiter is doubled
                    if (c == '\\') {
                        sb.append('\\').append('\\');
                    } else if (c == rule.close) {
                        sb.append(rule.close).append(rule.close);
                    } else {
                        sb.append(c);
                    }
                    break;
                case ESC_POWERQUERY:
                    // '#' could begin a '#(' escape on decode, so always
                    // escape it as #(#); the quote is doubled
                    if (c == '#') {
                        sb.append("#(#)");
                    } else if (c == rule.close) {
                        sb.append(rule.close).append(rule.close);
                    } else {
                        sb.append(c);
                    }
                    break;
                default:
                    // ESC_DOUBLING (canonical rules are never ESC_NONE or
                    // ESC_PG_UNICODE: those are recognition/decode-only forms)
                    if (c == rule.close) {
                        sb.append(rule.close);
                    }
                    sb.append(c);
                    break;
            }
        }
        sb.append(rule.close);
        return sb.toString();
    }

    /**
     * Does this lexical spelling denote a QUOTED identifier for the
     * vendor/role — i.e. does it start with a recognized open delimiter
     * (which may be a multi-character prefix such as {@code #"} or
     * {@code U&"})?
     *
     * <p>Recognition only: a {@code true} result does NOT imply the spelling
     * is well-formed ({@code [a.b[} is recognized as quoted, and
     * {@link #decodeLexical} then rejects it). {@code null} and the empty
     * string are not quoted.
     *
     * @param profile vendor identifier profile (non-null)
     * @param objectType syntactic role of the identifier (non-null; DAX
     *                   quote RECOGNITION is role-dependent — apostrophes
     *                   open quoted table names only)
     * @param s the spelling to test (may be null)
     * @return true iff {@code s} starts with a recognized open delimiter
     */
    public static boolean isQuoted(IdentifierProfile profile,
                                   ESQLDataObjectType objectType,
                                   String s) {
        Objects.requireNonNull(profile, "profile");
        Objects.requireNonNull(objectType, "objectType");
        if (s == null || s.isEmpty()) {
            return false;
        }
        // Fast rejection for the dominant case (unquoted identifier): no vendor's
        // open delimiter starts with this character, so skip the rule-table walk.
        char c0 = s.charAt(0);
        if (c0 >= 128 || (OPEN_FIRST[c0 >>> 6] & (1L << (c0 & 63))) == 0) {
            return false;
        }
        return ruleForOpen(rulesFor(profile, objectType), s) != null;
    }

    /**
     * Must a name in this role always be written delimited? True only where the delimiters are
     * the syntax of the reference rather than optional quoting: a DAX column is always written
     * {@code [Name]}, and a bare word in that position is a table or a function. A renderer must
     * keep such delimiters even when the name would denote the same object without them.
     *
     * @param profile vendor identifier profile (non-null)
     * @param objectType syntactic role of the identifier (non-null)
     * @return true iff no bare spelling exists for the role
     */
    public static boolean requiresDelimiters(IdentifierProfile profile, ESQLDataObjectType objectType) {
        Objects.requireNonNull(profile, "profile");
        Objects.requireNonNull(objectType, "objectType");
        return profile.getVendor() == EDbVendor.dbvdax && objectType == ESQLDataObjectType.dotColumn;
    }

    /**
     * Does this vendor/role have ANY quoted-identifier syntax? {@code false}
     * only for vendors like SOQL where {@link #encodeStored} is the identity
     * — callers that need a delimiter for internal-key purposes (protecting
     * dots from qualified-name splitting) must supply their own fallback.
     *
     * @param profile vendor identifier profile (non-null)
     * @param objectType syntactic role of the identifier (non-null)
     * @return true iff at least one quote form exists for the vendor/role
     */
    public static boolean hasQuotedForm(IdentifierProfile profile,
                                        ESQLDataObjectType objectType) {
        Objects.requireNonNull(profile, "profile");
        Objects.requireNonNull(objectType, "objectType");
        return rulesFor(profile, objectType).length > 0;
    }

    /**
     * Is this lexical spelling valid SQL for the vendor — a stricter
     * property than being transport-decodable?
     *
     * <p><b>Scope: character- and delimiter-level validity only.</b> The
     * check affirms spellings whose delimiter form and character content are
     * valid under the vendor's documented identifier grammar. Reserved-word
     * status, length limits, and semantic restrictions (e.g. a name being
     * taken) are explicitly OUT of scope — a {@code true} result does not
     * promise the bare word {@code SELECT} is usable unquoted. Within its
     * scope the check is conservative: it may return {@code false} for an
     * exotic-but-valid spelling, never {@code true} for a spelling whose
     * characters or delimiters are known-invalid. Enforced facts:
     * <ul>
     * <li>a quoted spelling must be well-formed ({@link #decodeLexical}
     *     accepts it) and — except for SQLite and Power&nbsp;Query M, which
     *     both document zero-length quoted identifiers as legal — its
     *     payload must be non-empty (BigQuery documents the empty-backtick
     *     ban explicitly);</li>
     * <li>no payload may contain an unpaired surrogate (not a character,
     *     so no vendor identifier grammar admits it) or NUL (MySQL documents
     *     the ban explicitly; no vendor's native interface transports NUL
     *     inside a name, so the conservative answer is {@code false}
     *     everywhere);</li>
     * <li>MySQL family: identifier characters are limited to the BMP
     *     (U+0001..U+FFFF) — supplementary characters are invalid even
     *     quoted; an unquoted identifier may not consist solely of
     *     digits;</li>
     * <li>an unquoted spelling must match the vendor's (and role's)
     *     unquoted-identifier grammar as modeled per vendor: the strictest
     *     core (first code point an ASCII letter; then ASCII letters,
     *     digits, {@code _}) plus only documented vendor extensions —
     *     e.g. {@code _} start for PostgreSQL/BigQuery/SQL Server but NOT
     *     Oracle or Doris table names; {@code $}/{@code #} body characters
     *     where documented; MySQL's extended U+0080..U+FFFF range;
     *     non-ASCII letters only where unconditionally documented
     *     (charset-dependent vendors like Oracle stay conservative).</li>
     * </ul>
     *
     * @param profile vendor identifier profile (non-null)
     * @param objectType syntactic role of the identifier (non-null)
     * @param lexical the spelling to test (may be null; null/empty is invalid)
     * @return true iff the spelling is known-valid at the character/delimiter level
     */
    public static boolean isVendorValidSpelling(IdentifierProfile profile,
                                                ESQLDataObjectType objectType,
                                                String lexical) {
        Objects.requireNonNull(profile, "profile");
        Objects.requireNonNull(objectType, "objectType");
        if (lexical == null || lexical.isEmpty()) {
            return false;
        }
        EDbVendor vendor = profile.getVendor();
        if (isQuoted(profile, objectType, lexical)) {
            QuoteRule rule = ruleForOpen(rulesFor(profile, objectType), lexical);
            if (rule != null && rule.recognitionOnly) {
                // Recognized for equality/decoding only (MSSQL 'alias' form) —
                // not a valid identifier spelling for the vendor.
                return false;
            }
            String payload;
            try {
                payload = decodeLexical(profile, objectType, lexical);
            } catch (IllegalArgumentException e) {
                return false;
            }
            if (payload.isEmpty() && !allowsEmptyQuoted(vendor)) {
                return false;
            }
            if (hasUnpairedSurrogate(payload)) {
                return false;
            }
            if (payload.indexOf(0x0000) >= 0) {
                return false;
            }
            if (hasSupplementary(payload) && isBmpOnlyVendor(vendor)) {
                // MySQL documents BMP-only identifier characters; SQL Server
                // does not support supplementary characters in metadata names
                return false;
            }
            if (vendor == EDbVendor.dbvpowerquery && hasRawControlChar(lexical)) {
                // M requires non-graphic characters (tab/CR/LF/...) to be
                // written as #(...) escapes; RAW control characters in the
                // lexical body are invalid even though transport decode
                // preserves them
                return false;
            }
            if (vendor == EDbVendor.dbvbigquery
                    && (lexical.indexOf(0x0D) >= 0 || lexical.indexOf(0x0A) >= 0)) {
                // GoogleSQL's lexer excludes raw CR/LF from backtick
                // identifiers — they must be spelled \r / \n
                return false;
            }
            return true;
        }
        return isValidUnquoted(vendor, profile.groupOf(objectType), lexical);
    }

    private static boolean isBmpOnlyVendor(EDbVendor vendor) {
        return isMySqlFamily(vendor)
                || vendor == EDbVendor.dbvmssql
                || vendor == EDbVendor.dbvazuresql;
    }

    /** Any raw ISO control character in the spelling (escaped forms like {@code #(tab)} contain none). */
    private static boolean hasRawControlChar(String lexical) {
        for (int i = 0; i < lexical.length(); i++) {
            if (Character.isISOControl(lexical.charAt(i))) {
                return true;
            }
        }
        return false;
    }

    /** SQLite and Power Query M document zero-length quoted identifiers as legal. */
    private static boolean allowsEmptyQuoted(EDbVendor vendor) {
        return vendor == EDbVendor.dbvsqlite || vendor == EDbVendor.dbvpowerquery;
    }

    // ===== Decoding =====

    private static String decodeDoubling(String lexical, QuoteRule rule) {
        int n = lexical.length();
        int start = rule.open.length();
        if (n < start + 1 || lexical.charAt(n - 1) != rule.close) {
            throw new MalformedIdentifierException(
                    "Quoted identifier is not terminated by '" + rule.close + "': " + lexical);
        }
        int end = n - 1;
        StringBuilder sb = new StringBuilder(end - start);
        int i = start;
        while (i < end) {
            char c = lexical.charAt(i);
            if (c == rule.close) {
                if (i + 1 < end && lexical.charAt(i + 1) == rule.close) {
                    sb.append(rule.close);
                    i += 2;
                } else {
                    throw new MalformedIdentifierException(
                            "Unescaped close delimiter '" + rule.close + "' at index " + i
                                    + " in quoted identifier: " + lexical);
                }
            } else {
                sb.append(c);
                i++;
            }
        }
        return sb.toString();
    }

    /** SQLite bracket form: no escape exists; the FIRST close bracket must be the last char. */
    private static String decodeNoEscape(String lexical, QuoteRule rule) {
        int n = lexical.length();
        int start = rule.open.length();
        int idx = lexical.indexOf(rule.close, start);
        if (idx < 0) {
            throw new MalformedIdentifierException(
                    "Quoted identifier is not terminated by '" + rule.close + "': " + lexical);
        }
        if (idx != n - 1) {
            throw new MalformedIdentifierException(
                    "Content after closing delimiter at index " + idx
                            + " in quoted identifier (this form has no escape): " + lexical);
        }
        return lexical.substring(start, n - 1);
    }

    private static String decodeBigQuery(String lexical, QuoteRule rule) {
        int n = lexical.length();
        int start = rule.open.length();
        StringBuilder sb = new StringBuilder(Math.max(0, n - start - 1));
        int i = start;
        while (i < n) {
            char c = lexical.charAt(i);
            if (c == rule.close) {
                if (i == n - 1) {
                    return sb.toString();
                }
                throw new MalformedIdentifierException(
                        "Content after closing delimiter at index " + i
                                + " in quoted identifier: " + lexical);
            }
            if (c == '\\') {
                i = decodeBigQueryEscape(lexical, i, sb);
            } else {
                sb.append(c);
                i++;
            }
        }
        throw new MalformedIdentifierException(
                "Quoted identifier is not terminated by '" + rule.close + "': " + lexical);
    }

    /**
     * Decode one BigQuery escape sequence starting at {@code start} (which
     * points at the backslash). Appends the decoded character(s) to
     * {@code sb} and returns the index just past the sequence.
     *
     * <p>GoogleSQL escape set: {@code \a \b \f \n \r \t \v \\ \? \" \' \`},
     * {@code \ooo} (exactly 3 octal digits, max {@code \377}),
     * {@code \xhh}/{@code \Xhh} (exactly 2 ASCII hex digits),
     * <code>&#92;uhhhh</code> (exactly 4 ASCII hex digits, no surrogates),
     * {@code \Uhhhhhhhh} (exactly 8 ASCII hex digits, valid non-surrogate
     * code point).
     */
    private static int decodeBigQueryEscape(String lexical, int start, StringBuilder sb) {
        int n = lexical.length();
        if (start + 1 >= n) {
            throw new MalformedIdentifierException(
                    "Dangling backslash at index " + start + " in quoted identifier: " + lexical);
        }
        char e = lexical.charAt(start + 1);
        switch (e) {
            case 'a': sb.append((char) 0x07); return start + 2;
            case 'b': sb.append((char) 0x08); return start + 2;
            case 'f': sb.append((char) 0x0C); return start + 2;
            case 'n': sb.append((char) 0x0A); return start + 2;
            case 'r': sb.append((char) 0x0D); return start + 2;
            case 't': sb.append((char) 0x09); return start + 2;
            case 'v': sb.append((char) 0x0B); return start + 2;
            case '\\':
            case '?':
            case '"':
            case '\'':
            case '`':
                sb.append(e);
                return start + 2;
            case 'x':
            case 'X': {
                int v = (int) parseAsciiHex(lexical, start + 2, 2);
                sb.append((char) v);
                return start + 4;
            }
            case 'u': {
                int v = (int) parseAsciiHex(lexical, start + 2, 4);
                if (v >= 0xD800 && v <= 0xDFFF) {
                    throw new MalformedIdentifierException(
                            "Unicode escape encodes a surrogate at index " + start
                                    + " in quoted identifier: " + lexical);
                }
                sb.append((char) v);
                return start + 6;
            }
            case 'U': {
                // 8 hex digits can exceed Integer.MAX_VALUE: accumulate in long
                long v = parseAsciiHex(lexical, start + 2, 8);
                if (v > 0x10FFFFL || (v >= 0xD800L && v <= 0xDFFFL)) {
                    throw new MalformedIdentifierException(
                            "Unicode escape is not a valid code point at index " + start
                                    + " in quoted identifier: " + lexical);
                }
                sb.appendCodePoint((int) v);
                return start + 10;
            }
            default:
                if (e >= '0' && e <= '7') {
                    int v = parseOctal(lexical, start + 1);
                    sb.append((char) v);
                    return start + 4;
                }
                throw new MalformedIdentifierException(
                        "Invalid escape sequence '\\" + e + "' at index " + start
                                + " in quoted identifier: " + lexical);
        }
    }

    /**
     * ClickHouse quoted identifiers: the close delimiter may be doubled, and
     * backslash escapes work with ClickHouse's parser semantics
     * (ReadHelpers.cpp {@code parseComplexEscapeSequence}): lowercase
     * {@code \xHH} only (uppercase {@code \X} is NOT an escape introducer),
     * {@code \N} decodes to NOTHING, the mapped set is
     * {@code \a \b \e \f \n \r \t \v \0 \\ \' \" \` \/ \=}, and an UNKNOWN
     * escape keeps both the backslash and the character (so {@code \q}
     * decodes to {@code \q}, and {@code \X41} to {@code \X41}).
     */
    /**
     * ClickHouse STRING LITERAL decoder (single- or double-quoted), sharing
     * the escape semantics of {@link #decodeClickHouse} (ReadHelpers.cpp
     * {@code parseComplexEscapeSequence}): doubled quotes, lowercase
     * {@code \xHH} only, {@code \N} decodes to nothing, the mapped set is
     * {@code \a \b \e \f \n \r \t \v \0 \\ \' \" \` \/ \=},
     * and an unknown escape keeps both characters. {@code \xHH} sequences
     * are BYTES: the decoded stream is recombined as UTF-8, so
     * {@code '\xC3\xA9'} is {@code é}, not two mojibake characters.
     *
     * @return the decoded value, or null when the literal is malformed or
     *         its bytes are not valid UTF-8 — callers must treat null as
     *         "identity cannot be represented safely" and fall back.
     */
    public static String decodeClickHouseStringLiteral(String rawLiteral) {
        if (rawLiteral == null || rawLiteral.length() < 2) {
            return null;
        }
        char quote = rawLiteral.charAt(0);
        if ((quote != '\'' && quote != '"') || rawLiteral.charAt(rawLiteral.length() - 1) != quote) {
            return null;
        }
        java.io.ByteArrayOutputStream out = new java.io.ByteArrayOutputStream(rawLiteral.length());
        // Literal characters accumulate in spans and are encoded as COMPLETE
        // code points with a REPORT-strict encoder: encoding one char at a
        // time splits surrogate pairs into isolated surrogates ('db.😀'
        // became db.?? — a false identity), and an isolated surrogate must
        // reject the literal rather than corrupt it.
        StringBuilder span = new StringBuilder();
        int n = rawLiteral.length() - 1; // exclusive of closing quote
        int i = 1;
        while (i < n) {
            char c = rawLiteral.charAt(i);
            if (c == quote) {
                if (i + 1 < n && rawLiteral.charAt(i + 1) == quote) {
                    span.append(quote);
                    i += 2;
                    continue;
                }
                return null; // stray quote inside the body
            }
            if (c != '\\') {
                span.append(c);
                i++;
                continue;
            }
            if (i + 1 >= n) {
                return null; // dangling backslash
            }
            char e = rawLiteral.charAt(i + 1);
            switch (e) {
                case 'a': if (!flushSpan(span, out)) return null; out.write(0x07); break;
                case 'b': if (!flushSpan(span, out)) return null; out.write(0x08); break;
                case 'e': if (!flushSpan(span, out)) return null; out.write(0x1B); break;
                case 'f': if (!flushSpan(span, out)) return null; out.write(0x0C); break;
                case 'n': if (!flushSpan(span, out)) return null; out.write(0x0A); break;
                case 'r': if (!flushSpan(span, out)) return null; out.write(0x0D); break;
                case 't': if (!flushSpan(span, out)) return null; out.write(0x09); break;
                case 'v': if (!flushSpan(span, out)) return null; out.write(0x0B); break;
                case '0': if (!flushSpan(span, out)) return null; out.write(0x00); break;
                case 'N': break; // \N decodes to nothing
                case '\\':
                case '\'':
                case '"':
                case '`':
                case '/':
                case '=':
                    span.append(e);
                    break;
                case 'x': {
                    if (i + 3 > n) {
                        return null;
                    }
                    if (!flushSpan(span, out)) return null;
                    try {
                        out.write((int) parseAsciiHex(rawLiteral, i + 2, 2));
                    } catch (Exception malformed) {
                        return null;
                    }
                    i += 4;
                    continue;
                }
                default:
                    // unknown escape keeps BOTH characters; the escaped char
                    // joins the span so a following low surrogate stays
                    // adjacent to its pair
                    span.append('\\').append(e);
                    break;
            }
            i += 2;
        }
        if (!flushSpan(span, out)) {
            return null;
        }
        try {
            return java.nio.charset.StandardCharsets.UTF_8.newDecoder()
                    .onMalformedInput(java.nio.charset.CodingErrorAction.REPORT)
                    .onUnmappableCharacter(java.nio.charset.CodingErrorAction.REPORT)
                    .decode(java.nio.ByteBuffer.wrap(out.toByteArray())).toString();
        } catch (java.nio.charset.CharacterCodingException notUtf8) {
            return null; // \xHH bytes are not a representable identity
        }
    }

    /** Strict-encodes the pending literal span (complete code points) into
     *  the byte stream; false when the span is not well-formed UTF-16
     *  (isolated surrogate) — the literal has no safe identity. */
    private static boolean flushSpan(StringBuilder span, java.io.ByteArrayOutputStream out) {
        if (span.length() == 0) {
            return true;
        }
        try {
            java.nio.ByteBuffer encoded = java.nio.charset.StandardCharsets.UTF_8.newEncoder()
                    .onMalformedInput(java.nio.charset.CodingErrorAction.REPORT)
                    .onUnmappableCharacter(java.nio.charset.CodingErrorAction.REPORT)
                    .encode(java.nio.CharBuffer.wrap(span));
            out.write(encoded.array(), encoded.arrayOffset() + encoded.position(),
                    encoded.remaining());
            span.setLength(0);
            return true;
        } catch (Exception malformed) {
            return false;
        }
    }

    private static String decodeClickHouse(String lexical, QuoteRule rule) {
        int n = lexical.length();
        int start = rule.open.length();
        StringBuilder sb = new StringBuilder(Math.max(0, n - start - 1));
        int i = start;
        while (i < n) {
            char c = lexical.charAt(i);
            if (c == rule.close) {
                if (i + 1 < n && lexical.charAt(i + 1) == rule.close) {
                    sb.append(rule.close);
                    i += 2;
                } else if (i == n - 1) {
                    return sb.toString();
                } else {
                    throw new MalformedIdentifierException(
                            "Content after closing delimiter at index " + i
                                    + " in quoted identifier: " + lexical);
                }
            } else if (c == '\\') {
                if (i + 1 >= n) {
                    throw new MalformedIdentifierException(
                            "Dangling backslash at index " + i + " in quoted identifier: " + lexical);
                }
                char e = lexical.charAt(i + 1);
                switch (e) {
                    case 'a': sb.append((char) 0x07); break;
                    case 'b': sb.append((char) 0x08); break;
                    case 'e': sb.append((char) 0x1B); break;
                    case 'f': sb.append((char) 0x0C); break;
                    case 'n': sb.append((char) 0x0A); break;
                    case 'r': sb.append((char) 0x0D); break;
                    case 't': sb.append((char) 0x09); break;
                    case 'v': sb.append((char) 0x0B); break;
                    case '0': sb.append((char) 0x00); break;
                    case 'N': break;   // \N decodes to nothing
                    case '\\':
                    case '\'':
                    case '"':
                    case '`':
                    case '/':
                    case '=':
                        sb.append(e);
                        break;
                    case 'x': {   // lowercase introducer only; hex DIGITS are either case
                        int v = (int) parseAsciiHex(lexical, i + 2, 2);
                        sb.append((char) v);
                        i += 4;
                        continue;
                    }
                    default:
                        // ClickHouse keeps unknown escapes verbatim: backslash AND char
                        sb.append('\\').append(e);
                        break;
                }
                i += 2;
            } else {
                sb.append(c);
                i++;
            }
        }
        throw new MalformedIdentifierException(
                "Quoted identifier is not terminated by '" + rule.close + "': " + lexical);
    }

    /**
     * Power Query M quoted identifier {@code #"…"}: the quote is escaped by
     * doubling; {@code #(item,item,...)} escape sequences encode characters,
     * where an item is {@code cr}, {@code lf}, {@code tab}, {@code #}, or a
     * code point as exactly 4 or 8 ASCII hex digits. A bare {@code #} not
     * followed by {@code (} is literal.
     */
    private static String decodePowerQuery(String lexical, QuoteRule rule) {
        int n = lexical.length();
        int start = rule.open.length();
        StringBuilder sb = new StringBuilder(Math.max(0, n - start - 1));
        int i = start;
        while (i < n) {
            char c = lexical.charAt(i);
            if (c == rule.close) {
                if (i + 1 < n && lexical.charAt(i + 1) == rule.close) {
                    sb.append(rule.close);
                    i += 2;
                } else if (i == n - 1) {
                    return sb.toString();
                } else {
                    throw new MalformedIdentifierException(
                            "Content after closing delimiter at index " + i
                                    + " in quoted identifier: " + lexical);
                }
            } else if (c == '#' && i + 1 < n && lexical.charAt(i + 1) == '(') {
                i = decodePowerQueryEscape(lexical, i, sb);
            } else {
                sb.append(c);
                i++;
            }
        }
        throw new MalformedIdentifierException(
                "Quoted identifier is not terminated by '" + rule.close + "': " + lexical);
    }

    /** Decode one {@code #(...)} sequence; {@code start} points at {@code #}. Returns the index past {@code )}. */
    private static int decodePowerQueryEscape(String lexical, int start, StringBuilder sb) {
        int n = lexical.length();
        int i = start + 2;   // past "#("
        while (true) {
            int itemStart = i;
            while (i < n && lexical.charAt(i) != ',' && lexical.charAt(i) != ')') {
                i++;
            }
            if (i >= n) {
                throw new MalformedIdentifierException(
                        "Unterminated #( escape at index " + start + " in quoted identifier: " + lexical);
            }
            String item = lexical.substring(itemStart, i);
            if ("cr".equals(item)) {
                sb.append((char) 0x0D);
            } else if ("lf".equals(item)) {
                sb.append((char) 0x0A);
            } else if ("tab".equals(item)) {
                sb.append((char) 0x09);
            } else if ("#".equals(item)) {
                sb.append('#');
            } else if (item.length() == 4 || item.length() == 8) {
                long v = parseAsciiHex(lexical, itemStart, item.length());
                if (v > 0x10FFFFL) {
                    throw new MalformedIdentifierException(
                            "Escape is not a valid code point at index " + itemStart
                                    + " in quoted identifier: " + lexical);
                }
                if (v <= 0xFFFFL) {
                    sb.append((char) v);   // UTF-16 unit; pairs may be spelled as two items
                } else {
                    sb.appendCodePoint((int) v);
                }
            } else {
                throw new MalformedIdentifierException(
                        "Invalid #( escape item '" + item + "' at index " + itemStart
                                + " in quoted identifier: " + lexical);
            }
            char sep = lexical.charAt(i);
            i++;
            if (sep == ')') {
                return i;
            }
            // sep == ',': next item
        }
    }

    /**
     * PostgreSQL {@code U&"…"} Unicode identifier with the DEFAULT escape
     * character {@code \}: {@code ""} doubling for the quote, {@code \\} for
     * a literal backslash, {@code \XXXX} (4 ASCII hex) for a UTF-16 unit
     * (surrogate pairs may be spelled as two consecutive escapes), and
     * {@code \+XXXXXX} (6 ASCII hex) for a code point. Unpaired surrogates
     * in the decoded result are rejected, as PostgreSQL rejects them.
     */
    private static String decodePgUnicode(String lexical, QuoteRule rule) {
        int n = lexical.length();
        int start = rule.open.length();
        StringBuilder sb = new StringBuilder(Math.max(0, n - start - 1));
        int i = start;
        while (i < n) {
            char c = lexical.charAt(i);
            if (c == rule.close) {
                if (i + 1 < n && lexical.charAt(i + 1) == rule.close) {
                    sb.append(rule.close);
                    i += 2;
                } else if (i == n - 1) {
                    String payload = sb.toString();
                    if (hasUnpairedSurrogate(payload)) {
                        throw new MalformedIdentifierException(
                                "Unicode escapes form an unpaired surrogate in quoted identifier: "
                                        + lexical);
                    }
                    return payload;
                } else {
                    throw new MalformedIdentifierException(
                            "Content after closing delimiter at index " + i
                                    + " in quoted identifier: " + lexical);
                }
            } else if (c == '\\') {
                if (i + 1 >= n) {
                    throw new MalformedIdentifierException(
                            "Dangling escape character at index " + i + " in quoted identifier: " + lexical);
                }
                char e = lexical.charAt(i + 1);
                if (e == '\\') {
                    sb.append('\\');
                    i += 2;
                } else if (e == '+') {
                    long v = parseAsciiHex(lexical, i + 2, 6);
                    if (v > 0x10FFFFL) {
                        throw new MalformedIdentifierException(
                                "Unicode escape is not a valid code point at index " + i
                                        + " in quoted identifier: " + lexical);
                    }
                    if (v <= 0xFFFFL) {
                        sb.append((char) v);
                    } else {
                        sb.appendCodePoint((int) v);
                    }
                    i += 8;
                } else if (asciiHexValue(e) >= 0) {
                    int v = (int) parseAsciiHex(lexical, i + 1, 4);
                    sb.append((char) v);
                    i += 5;
                } else {
                    throw new MalformedIdentifierException(
                            "Invalid escape sequence '\\" + e + "' at index " + i
                                    + " in quoted identifier: " + lexical);
                }
            } else {
                sb.append(c);
                i++;
            }
        }
        throw new MalformedIdentifierException(
                "Quoted identifier is not terminated by '" + rule.close + "': " + lexical);
    }

    // ===== Hex/octal helpers (ASCII-only — Character.digit would accept
    // non-ASCII Unicode digits, which no vendor's escape grammar does) =====

    private static int asciiHexValue(char c) {
        if (c >= '0' && c <= '9') return c - '0';
        if (c >= 'a' && c <= 'f') return c - 'a' + 10;
        if (c >= 'A' && c <= 'F') return c - 'A' + 10;
        return -1;
    }

    private static long parseAsciiHex(String s, int from, int digits) {
        if (from + digits > s.length()) {
            throw new MalformedIdentifierException(
                    "Truncated escape sequence at index " + from + " in quoted identifier: " + s);
        }
        long v = 0;
        for (int i = from; i < from + digits; i++) {
            int d = asciiHexValue(s.charAt(i));
            if (d < 0) {
                throw new MalformedIdentifierException(
                        "Invalid hex digit at index " + i + " in quoted identifier: " + s);
            }
            v = (v << 4) | d;
        }
        return v;
    }

    /** Exactly three octal digits, value at most \377 (255). */
    private static int parseOctal(String s, int from) {
        if (from + 3 > s.length()) {
            throw new MalformedIdentifierException(
                    "Truncated octal escape at index " + (from - 1)
                            + " in quoted identifier: " + s);
        }
        int v = 0;
        for (int i = from; i < from + 3; i++) {
            char c = s.charAt(i);
            if (c < '0' || c > '7') {
                throw new MalformedIdentifierException(
                        "Invalid octal digit at index " + i + " in quoted identifier: " + s);
            }
            v = (v << 3) | (c - '0');
        }
        if (v > 0xFF) {
            throw new MalformedIdentifierException(
                    "Octal escape above \\377 at index " + (from - 1)
                            + " in quoted identifier: " + s);
        }
        return v;
    }

    // ===== Vendor-valid helpers =====

    private static boolean isMySqlFamily(EDbVendor vendor) {
        switch (vendor) {
            case dbvmysql:
            case dbvoceanbase:
            case dbvdoris:
            case dbvstarrocks:
                return true;
            default:
                return false;
        }
    }

    private static boolean hasUnpairedSurrogate(String s) {
        for (int i = 0; i < s.length(); i++) {
            char c = s.charAt(i);
            if (Character.isHighSurrogate(c)) {
                if (i + 1 >= s.length() || !Character.isLowSurrogate(s.charAt(i + 1))) {
                    return true;
                }
                i++;
            } else if (Character.isLowSurrogate(c)) {
                return true;
            }
        }
        return false;
    }

    private static boolean hasSupplementary(String s) {
        for (int i = 0; i < s.length(); i++) {
            if (Character.isHighSurrogate(s.charAt(i))) {
                return true;   // paired → supplementary; unpaired is rejected separately
            }
        }
        return false;
    }

    // ===== Per-vendor unquoted-identifier grammar =====
    //
    // The strictest core — first code point an ASCII letter, then ASCII
    // letters/digits/'_' — is valid for every supported vendor. Everything
    // beyond it is a DOCUMENTED vendor extension, enabled per vendor (and
    // role: Doris table and column grammars differ). Unknown vendors get the
    // bare core, which can only under-affirm, never over-affirm.

    /** {@code _} may start an identifier. NOT Oracle, NOT Doris table names, NOT the unknown-vendor core. */
    private static final int UG_UNDERSCORE_START = 1;
    /** {@code @}/{@code #} may start an identifier (T-SQL variables / temp objects). */
    private static final int UG_AT_HASH_START = 2;
    /** A digit may start an identifier (MySQL; the spelling may still not be all digits). */
    private static final int UG_DIGIT_START = 4;
    /** {@code $} allowed in body positions. */
    private static final int UG_DOLLAR_PART = 8;
    /** {@code #} allowed in body positions. */
    private static final int UG_HASH_PART = 16;
    /** Non-ASCII Unicode LETTERS allowed (only where unconditionally documented, e.g. PostgreSQL). */
    private static final int UG_UNICODE_LETTERS = 32;
    /** MySQL extended range: ANY character U+0080..U+FFFF is allowed (start and body). */
    private static final int UG_MYSQL_EXTENDED = 64;
    /** Non-ASCII Unicode letters restricted to the BMP (SQL Server: no supplementary characters in names). */
    private static final int UG_UNICODE_LETTERS_BMP = 128;

    private static int unquotedGrammar(EDbVendor vendor, IdentifierProfile.ObjectGroup group) {
        switch (vendor) {
            case dbvoracle:
            case dbvdameng:
            case dbvdb2:
            case dbvnetezza:
            case dbvexasol:
            case dbvhana:
                // letter start only (Oracle: "must begin with an alphabetic
                // character"); $ and # documented in body; non-ASCII letters
                // are database-charset-dependent → conservative false
                return UG_DOLLAR_PART | UG_HASH_PART;

            case dbvsnowflake:
                // Snowflake: start with a letter or underscore; body letters,
                // underscores, digits, $ — NO #
                return UG_UNDERSCORE_START | UG_DOLLAR_PART;

            case dbvpostgresql:
            case dbvduckdb:
            case dbvgreenplum:
            case dbvgaussdb:
            case dbvedb:
            case dbvredshift:
            case dbvsqlite:
                // PostgreSQL: letters (incl. non-Latin), _, digits, $
                return UG_UNDERSCORE_START | UG_DOLLAR_PART | UG_UNICODE_LETTERS;

            case dbvmysql:
            case dbvoceanbase:
                // MySQL: ASCII [0-9a-zA-Z$_] plus ANY char U+0080..U+FFFF;
                // digit-first legal but not all-digits
                return UG_UNDERSCORE_START | UG_DIGIT_START | UG_DOLLAR_PART | UG_MYSQL_EXTENDED;

            case dbvdoris:
            case dbvstarrocks:
                // Doris: table names must BEGIN WITH A LETTER; column names
                // may also begin with an underscore — the role changes the
                // grammar, which is why objectType flows into this check
                return group == IdentifierProfile.ObjectGroup.COLUMN_GROUP
                        ? UG_UNDERSCORE_START
                        : 0;

            case dbvmssql:
            case dbvazuresql:
            case dbvsybase:
                // T-SQL: letters "as defined in Unicode", _ @ # start,
                // @ $ # _ in body; SQL Server does not support supplementary
                // characters in metadata names → BMP-only letters
                return UG_UNDERSCORE_START | UG_AT_HASH_START | UG_DOLLAR_PART
                        | UG_HASH_PART | UG_UNICODE_LETTERS_BMP;

            case dbvsybasease:
                // Same T-SQL identifier character classes as the base.
                return UG_UNDERSCORE_START | UG_AT_HASH_START | UG_DOLLAR_PART
                        | UG_HASH_PART | UG_UNICODE_LETTERS_BMP;

            case dbvsqlanywhere:
                // Same classes again, independent block per HC-5.
                return UG_UNDERSCORE_START | UG_AT_HASH_START | UG_DOLLAR_PART
                        | UG_HASH_PART | UG_UNICODE_LETTERS_BMP;

            case dbvsybaseiq:
                // Same again, independent block per HC-5.
                return UG_UNDERSCORE_START | UG_AT_HASH_START | UG_DOLLAR_PART
                        | UG_HASH_PART | UG_UNICODE_LETTERS_BMP;

            case dbvbigquery:
                // GoogleSQL: [A-Za-z_][A-Za-z_0-9]* — ASCII only, no $
                return UG_UNDERSCORE_START;

            case dbvhive:
            case dbvsparksql:
            case dbvimpala:
            case dbvdatabricks:
            case dbvflink:
                return UG_UNDERSCORE_START;

            default:
                return 0;   // strictest core only
        }
    }

    private static boolean isValidUnquoted(EDbVendor vendor,
                                           IdentifierProfile.ObjectGroup group,
                                           String lexical) {
        if (hasUnpairedSurrogate(lexical)) {
            return false;
        }
        int g = unquotedGrammar(vendor, group);
        boolean mysqlFamily = isMySqlFamily(vendor);
        int first = lexical.codePointAt(0);
        if (!isUnquotedStart(first, g)) {
            return false;
        }
        boolean allDigits = isAsciiDigit(first);
        int i = Character.charCount(first);
        while (i < lexical.length()) {
            int cp = lexical.codePointAt(i);
            if (!isUnquotedPart(cp, g)) {
                return false;
            }
            if (!isAsciiDigit(cp)) {
                allDigits = false;
            }
            i += Character.charCount(cp);
        }
        if (mysqlFamily && allDigits) {
            // MySQL: an unquoted identifier may not consist solely of digits
            return false;
        }
        return true;
    }

    private static boolean isAsciiDigit(int cp) {
        return cp >= '0' && cp <= '9';
    }

    private static boolean isAsciiLetter(int cp) {
        return (cp >= 'a' && cp <= 'z') || (cp >= 'A' && cp <= 'Z');
    }

    private static boolean isUnquotedStart(int cp, int g) {
        if (isAsciiLetter(cp)) {
            return true;
        }
        if (cp == '_') {
            return (g & UG_UNDERSCORE_START) != 0;
        }
        if (cp == '@' || cp == '#') {
            return (g & UG_AT_HASH_START) != 0;
        }
        if (isAsciiDigit(cp)) {
            return (g & UG_DIGIT_START) != 0;
        }
        if ((g & UG_MYSQL_EXTENDED) != 0 && cp >= 0x80 && cp <= 0xFFFF) {
            return true;
        }
        return nonAsciiLetterAllowed(cp, g);
    }

    private static boolean nonAsciiLetterAllowed(int cp, int g) {
        if (cp <= 0x7F || !Character.isLetter(cp)) {
            return false;
        }
        if ((g & UG_UNICODE_LETTERS) != 0) {
            return true;
        }
        return (g & UG_UNICODE_LETTERS_BMP) != 0 && cp <= 0xFFFF;
    }

    private static boolean isUnquotedPart(int cp, int g) {
        if (isAsciiLetter(cp) || isAsciiDigit(cp) || cp == '_') {
            return true;
        }
        if (cp == '$') {
            return (g & UG_DOLLAR_PART) != 0;
        }
        if (cp == '#') {
            return (g & UG_HASH_PART) != 0;
        }
        if (cp == '@') {
            // T-SQL documents @ in body positions as well as at the start
            return (g & UG_AT_HASH_START) != 0;
        }
        if ((g & UG_MYSQL_EXTENDED) != 0 && cp >= 0x80 && cp <= 0xFFFF) {
            return true;
        }
        return nonAsciiLetterAllowed(cp, g);
    }
}