Per-table INDEX-hint existence validation — Msg 307 (unknown INDEX(N) id) + Msg 308 (unknown INDEX(name) / INDEX = name) ship verbatim. Both fire only on FROM-source / JOIN-RHS heap-table positions — DML targets already short-circuit on Msg 1069 first (ValidateDmlTargetHints runs before per-index validation, matching probe: UPDATE t WITH (INDEX(name)) raises 1069 not 308 on real SQL Server 2025). TableHintInfo gains a nullable List<IndexHintArgument> IndexArguments field and a companion IndexHintArgument readonly struct (Id? xor Name?); the INDEX-name case in ConsumeOneTableHint now dispatches to a dedicated ConsumeIndexHintArguments walker rather than SkipBalancedParens. The walker accepts both INDEX(arg [, …]) and INDEX = arg forms, captures each numeric-literal arg as IndexHintArgument.ForId(value.AsInt32) and each identifier (Name-token) arg as IndexHintArgument.ForName(source.ToString()), and surfaces negative-integer / other-shape inputs as generic Msg 102 (probe-confirmed: real SQL Server rejects INDEX(-1) the same way). FORCESEEK / FORCESCAN keep the existing parse-and-discard posture via the SkipBalancedParens fall-through. New ValidateIndexHintArguments(TableHintInfo, HeapTable, string qualifiedTableName) walks the captured args and raises on the first failure: integer form valid if id == 0 (the "heap scan" reference, accepted even on clustered tables — probe-confirmed INDEX(0) works on every shape) or 1 <= id <= KeyConstraints.Count + Indexes.Count (matches sys.indexes row-count for the table excluding the synthetic HEAP row); name form valid if matches any KeyConstraints[].Name (PRIMARY KEY / UNIQUE) or Indexes[].Name case-insensitively via Collation.Default.Equals. Wired at the heap-table FROM-source path in Selection.cs:1052 (immediately after ParseOptionalTableHints returns); the call site builds the qualifier as $"{objectName.ImmediateQualifier ?? Database.DefaultSchemaName}.{heapTable.Name}" so 2-part au.t references surface as 'au.t' in the message and 1-part t surfaces as 'dbo.t'. New error factories IndexHintIdNotFound(int, string) and IndexHintNameNotFound(string, string) in SimulatedSqlException.ConcurrencyErrors.cs carry the probe-confirmed verbatim wording (single-quote convention, (specified in the FROM clause) suffix hard-coded even on JOIN-RHS per real-server behavior). 13 new QueryHintTests cover: known/unknown named-arg pairs, PRIMARY KEY constraint name, UNIQUE constraint name, case-insensitive name match, =-form known/unknown name, out-of-range int on PK-table (Msg 307), INDEX(1) on heap-only table (Msg 307), INDEX(0) always-valid, multi-arg INDEX(bad, good) raising 308 on first failing arg, schema-qualified table name embedded in error, negative-int rejected as Msg 102 at parse. The previously-passing Select_IndexHint_NamedArg_ReturnsRows test (parse-and-ignore stance) becomes Select_IndexHint_UnknownNamedArg_RaisesMsg308. CLAUDE.md "Query-hint gaps" section rewritten: the "hint-conflict and DML-target-specific rejections aren't enforced" claim removed (Msg 1047 / 1065 / 1069 were already shipped — doc was stale); replaced with explicit "Hint-conflict + DML-target rejections ship verbatim" and "Per-table index-hint validation ships" paragraphs documenting Msg 307 / 308 with their validation rules. Remaining hint-surface gaps now narrow to the FROM-source (unknown) Msg 102-vs-207/321 divergence and the FORCESEEK(name(cols)) nested-form name validation. docs/claude/query-hints.md "Not enforced" section split into "Enforced rejections" (with detailed Msg 307 / 308 / 1047 / 1065 / 1069 wording + rule docs) and a shrunken "Not enforced" (FORCESEEK nested-form name validation + Msg 8622 plan rejection + INDEX = (value-list) equals-form); probe-artifacts list at the doc tail updated with the new Msg 307 / 308 / INDEX(0) / INDEX(-1) findings.

Author: RyanLamansky

CLAUDE.md

@@ -181,7 +181,7 @@ Per-feature deep-dives live under `docs/claude/`. Each entry below is a trigger:
 - **Public `InfoMessage` event** — `SimulatedDbConnection.InfoMessage` ships as an `internal` event (with `internal SimulatedInfoMessageEventArgs` carrying `Message`, `LineNumber`, `Source`) and a `BatchContext`-side buffer that coalesces multiple `PRINT`s per command into one firing (joined with `\n`, line number = first contributing `PRINT`'s line). The internal surface is exercised through `SqlServerSimulator.Tests.Internal/PrintInfoMessageTests.cs`. Going *public* — exposing the event on the `SimulatedDbConnection` consumer surface for application use — is deferred pending the public-API shape decision (mirror SqlClient's `SqlInfoMessageEventArgs` exactly? trim to a minimal shape? add a `DbConnection`-compatible extension method instead of a typed event?). Subquery-in-operand still silently evaluates instead of raising Msg 1046 ("Subqueries are not allowed in this context"); non-string-value formatting routes through `SqlValue.CoerceTo(varchar(8000))` rather than SQL Server's PRINT-specific style 0 conventions (datetime → ISO instead of `"May 14 2026 12:00AM"`; money → `F4` instead of 2-decimal). The 8000-byte ANSI / 4000-character Unicode PRINT truncation isn't enforced — long strings pass through verbatim.
 - **`ALTER TABLE` grammar beyond SET / ADD / DROP / ALTER COLUMN / CHECK / NOCHECK CONSTRAINT** — `SET (SYSTEM_VERSIONING = OFF)` (see [`docs/claude/temporal-tables.md`](docs/claude/temporal-tables.md)), `[WITH CHECK | WITH NOCHECK] ADD [CONSTRAINT name] (PRIMARY KEY | UNIQUE | FOREIGN KEY | CHECK | DEFAULT) …`, `DROP CONSTRAINT [IF EXISTS] name [, …]`, `[WITH CHECK | WITH NOCHECK] (CHECK | NOCHECK) CONSTRAINT (ALL | name [, …])` (trust toggling for bulk imports — sets / clears `is_disabled` + `is_not_trusted`), `ADD [COLUMN] col TYPE [, …]` (multi-column add — inline DEFAULT / IDENTITY / CHECK / FK / computed all supported; Msg 4901 on NOT NULL without DEFAULT on non-empty table; eager row rewrite with NULL backfill for nullable adds and constant-snapshot DEFAULT for NOT NULL), `DROP COLUMN [IF EXISTS] col [, …]` (Msg 4924 missing column, Msg 5074 dependency rejection with multi-blocker enumeration across PK/UQ/FK/CHECK/DEFAULT/index, atomic multi-drop), and `ALTER COLUMN col TYPE[(prec[,scale])] [COLLATE coll] [NULL|NOT NULL]` (single-column shape — type widening / narrowing routed through `SqlValue.CoerceTo` so Msg 220 / 245 / 241 / 8115 / 2628 surface verbatim; nullability flip raises Msg 515 on existing NULL; Msg 4928 for COMPUTED / rowversion; Msg 5074 multi-blocker enumeration across PK / UQ / FK both directions / computed-column dependencies / type-changing index references — length widening within the same `SqlType` family allowed under an index; COLLATE clause parse-accepted then ignored; identity / DEFAULT / inline CHECK preserve through the column instance swap) all ship (see [`docs/claude/alter-table.md`](docs/claude/alter-table.md)). DROP PERIOD FOR SYSTEM_TIME, REBUILD, SWITCH PARTITION, the SET-versioning-on direction, the `ALTER COLUMN col ADD/DROP {PERSISTED|MASKED|ROWGUIDCOL|SPARSE}` sub-clause forms, ALTER COLUMN on an identity column targeting a non-integer type, and every other shape raise `NotSupportedException`. Multi-constraint ADD (`ADD CONSTRAINT pk1 PK (a), CONSTRAINT fk1 FK …`) also raises.
 - `hierarchyid`, `geography`, `geometry`.
-- **Query-hint gaps** — table hints (`WITH (NOLOCK [, …])` on FROM sources / JOIN-RHS / INSERT / UPDATE / DELETE / MERGE targets) and statement-level `OPTION (…)` hints ship via parse-and-discard (see [`docs/claude/query-hints.md`](docs/claude/query-hints.md)). The legacy bare-paren `(hint)` form is FROM / JOIN-RHS only — INSERT treats `(` as the column-list opener (probe-confirmed Msg 207 on the would-be hint name), and UPDATE / DELETE / MERGE all raise Msg 102 on the bare-paren form (controlled via `allowLegacyParenForm: false` at those call sites). **MERGE target uses hint-then-alias placement** — opposite of FROM / UPDATE / DELETE — and alias-then-hint raises Msg 156 there (probe-confirmed). **INSERT / MERGE on a `@t` target rejects WITH outright** (Msg 156 on real SQL Server; the simulator falls through to its generic Msg 102 since hint parsing is skipped for `@t`). Closed accept-list raises `Msg 321` for unknown table hints (verbatim probe wording), `Msg 102` for unknown OPTION hints (probe-confirmed: SQL Server has no dedicated unknown-OPTION-hint code). `MAXRECURSION N` retains its runtime effect on in-scope CTE bindings; every other recognized hint is a pure no-op. Remaining gaps: **hint-conflict and DML-target-specific rejections** (`Msg 1047` for `NOLOCK + XLOCK`, `Msg 1065` for `NOLOCK` / `READUNCOMMITTED` on any DML target, `Msg 1069` for `INDEX(…)` on any DML target, `Msg 308` for unknown `INDEX(name)`) aren't enforced — the simulator has no lock state or index dispatch to conflict over. **FROM-source `(unknown)` without alias** diverges minorly: real SQL Server raises Msg 207 (parses the paren as a TVF-arg-list attempt) while the simulator's peek-and-restore falls through to Msg 102; with-alias FROM/JOIN-RHS `alias (unknown)` also raises Msg 102 instead of real SQL Server's Msg 321 (commit-on-paren is wired only on MERGE bare-table source, not on FROM-source). (The shape `FROM t NOLOCK` without parens is not a deprecated hint form — `nolock` / `readpast` / etc. aren't reserved keywords, so it parses as the bare-alias form `FROM t <alias>` on both the simulator and real SQL Server; identical behavior, no gap.)
+- **Query-hint gaps** — table hints (`WITH (NOLOCK [, …])` on FROM sources / JOIN-RHS / INSERT / UPDATE / DELETE / MERGE targets) and statement-level `OPTION (…)` hints ship via parse-and-discard (see [`docs/claude/query-hints.md`](docs/claude/query-hints.md)). The legacy bare-paren `(hint)` form is FROM / JOIN-RHS only — INSERT treats `(` as the column-list opener (probe-confirmed Msg 207 on the would-be hint name), and UPDATE / DELETE / MERGE all raise Msg 102 on the bare-paren form (controlled via `allowLegacyParenForm: false` at those call sites). **MERGE target uses hint-then-alias placement** — opposite of FROM / UPDATE / DELETE — and alias-then-hint raises Msg 156 there (probe-confirmed). **INSERT / MERGE on a `@t` target rejects WITH outright** (Msg 156 on real SQL Server; the simulator falls through to its generic Msg 102 since hint parsing is skipped for `@t`). Closed accept-list raises `Msg 321` for unknown table hints (verbatim probe wording), `Msg 102` for unknown OPTION hints (probe-confirmed: SQL Server has no dedicated unknown-OPTION-hint code). `MAXRECURSION N` retains its runtime effect on in-scope CTE bindings; every other recognized hint is a pure no-op. **Hint-conflict + DML-target rejections ship verbatim**: `Msg 1047` ("Conflicting locking hints specified.") for `NOLOCK` paired with any of `XLOCK / UPDLOCK / HOLDLOCK / SERIALIZABLE / REPEATABLEREAD / TABLOCKX`; `Msg 1065` for `NOLOCK` / `READUNCOMMITTED` on any DML target (INSERT / UPDATE / DELETE / MERGE); `Msg 1069` for `INDEX(…) / FORCESEEK / FORCESCAN` on any DML target. **Per-table index-hint validation ships**: `Msg 307` for an out-of-range `INDEX(N)` id (`N == 0` always valid; `N >= 1` valid iff `N <= KeyConstraints.Count + Indexes.Count`); `Msg 308` for an unknown `INDEX(name)` / `INDEX = name` (matched case-insensitively against PRIMARY KEY / UNIQUE constraint names and `HeapTable.Indexes`). Both fire only on FROM-source / JOIN-RHS positions — DML targets short-circuit on `Msg 1069` first per probe (`UPDATE t WITH (INDEX(name))` raises 1069 not 308 on real SQL Server). Remaining gaps: **FROM-source `(unknown)` without alias** diverges minorly — real SQL Server raises Msg 207 (parses the paren as a TVF-arg-list attempt) while the simulator's peek-and-restore falls through to Msg 102; with-alias FROM/JOIN-RHS `alias (unknown)` also raises Msg 102 instead of real SQL Server's Msg 321 (commit-on-paren is wired only on MERGE bare-table source, not on FROM-source). **`FORCESEEK(name(cols))` nested-form index-name validation** isn't run — the simulator skip-parses the nested syntax via `SkipBalancedParens` rather than capturing the leading name, so a `FORCESEEK(bad_name(c))` parses silently where real SQL Server raises Msg 308 (deferred since the nested-paren shape requires its own grammar path; the common bare `FORCESEEK` ships unaffected). (The shape `FROM t NOLOCK` without parens is not a deprecated hint form — `nolock` / `readpast` / etc. aren't reserved keywords, so it parses as the bare-alias form `FROM t <alias>` on both the simulator and real SQL Server; identical behavior, no gap.)
 
 ## Quirks (modeled, not byte-identical to SQL Server)
 

SqlServerSimulator.Tests/QueryHintTests.cs

@@ -117,19 +117,125 @@ public void Select_IndexHint_NumericArg_ReturnsRows()
             select count(*) from t with (index(0))
             """));
 
-    /// <summary>
-    /// Simulator doesn't model indexes, so the named-index reference parses
-    /// and is discarded. Real SQL Server raises Msg 308 on a wrong name;
-    /// the parse-and-ignore stance is the consistent posture for hints.
-    /// </summary>
     [TestMethod]
-    public void Select_IndexHint_NamedArg_ReturnsRows()
+    public void Select_IndexHint_KnownNamedArg_ReturnsRows()
         => AreEqual(3, new Simulation().ExecuteScalar("""
+            create table t (id int primary key, v int);
+            create index ix_v on t(v);
+            insert t values (1, 10), (2, 20), (3, 30);
+            select count(*) from t with (index(ix_v))
+            """));
+
+    [TestMethod]
+    public void Select_IndexHint_UnknownNamedArg_RaisesMsg308()
+        => new Simulation().AssertSqlError("""
             create table t (id int primary key);
+            insert t values (1);
+            select * from t with (index(IX_does_not_exist))
+            """, 308, "Index 'IX_does_not_exist' on table 'dbo.t' (specified in the FROM clause) does not exist.");
+
+    [TestMethod]
+    public void Select_IndexHint_PkConstraintName_ReturnsRows()
+        => AreEqual(3, new Simulation().ExecuteScalar("""
+            create table t (id int constraint pk_t primary key);
             insert t values (1), (2), (3);
-            select count(*) from t with (index(IX_does_not_exist))
+            select count(*) from t with (index(pk_t))
+            """));
+
+    [TestMethod]
+    public void Select_IndexHint_UqConstraintName_ReturnsRows()
+        => AreEqual(3, new Simulation().ExecuteScalar("""
+            create table t (id int primary key, u int constraint uq_u unique);
+            insert t values (1, 10), (2, 20), (3, 30);
+            select count(*) from t with (index(uq_u))
             """));
 
+    [TestMethod]
+    public void Select_IndexHint_NamedArg_CaseInsensitive_ReturnsRows()
+        => AreEqual(3, new Simulation().ExecuteScalar("""
+            create table t (id int primary key, v int);
+            create index ix_v on t(v);
+            insert t values (1, 10), (2, 20), (3, 30);
+            select count(*) from t with (index(IX_V))
+            """));
+
+    [TestMethod]
+    public void Select_IndexHint_EqForm_KnownName_ReturnsRows()
+        => AreEqual(3, new Simulation().ExecuteScalar("""
+            create table t (id int constraint pk_t primary key);
+            insert t values (1), (2), (3);
+            select count(*) from t with (index = pk_t)
+            """));
+
+    [TestMethod]
+    public void Select_IndexHint_EqForm_UnknownName_RaisesMsg308()
+        => new Simulation().AssertSqlError("""
+            create table t (id int primary key);
+            insert t values (1);
+            select * from t with (index = nope)
+            """, 308, "Index 'nope' on table 'dbo.t' (specified in the FROM clause) does not exist.");
+
+    [TestMethod]
+    public void Select_IndexHint_BadIdOnPkTable_RaisesMsg307()
+        => new Simulation().AssertSqlError("""
+            create table t (id int primary key);
+            insert t values (1);
+            select * from t with (index(99))
+            """, 307, "Index ID 99 on table 'dbo.t' (specified in the FROM clause) does not exist.");
+
+    [TestMethod]
+    public void Select_IndexHint_Id1OnHeapTable_RaisesMsg307()
+        => new Simulation().AssertSqlError("""
+            create table t (id int, v int);
+            insert t values (1, 10);
+            select * from t with (index(1))
+            """, 307, "Index ID 1 on table 'dbo.t' (specified in the FROM clause) does not exist.");
+
+    [TestMethod]
+    public void Select_IndexHint_Id0OnHeapTable_ReturnsRows()
+        => AreEqual(2, new Simulation().ExecuteScalar("""
+            create table t (id int, v int);
+            insert t values (1, 10), (2, 20);
+            select count(*) from t with (index(0))
+            """));
+
+    [TestMethod]
+    public void Select_IndexHint_MixedGoodBadInOneList_RaisesMsg308_OnFirstBad()
+        => new Simulation().AssertSqlError("""
+            create table t (id int constraint pk_t primary key);
+            insert t values (1);
+            select * from t with (index(nope, pk_t))
+            """, 308, "Index 'nope' on table 'dbo.t' (specified in the FROM clause) does not exist.");
+
+    [TestMethod]
+    public void Select_IndexHint_MultipleKnown_ReturnsRows()
+        => AreEqual(3, new Simulation().ExecuteScalar("""
+            create table t (id int constraint pk_t primary key, v int);
+            create index ix_v on t(v);
+            insert t values (1, 10), (2, 20), (3, 30);
+            select count(*) from t with (index(pk_t, ix_v))
+            """));
+
+    [TestMethod]
+    public void Select_IndexHint_SchemaQualified_ErrorEmbedsQualifier()
+    {
+        var sim = new Simulation();
+        _ = sim.ExecuteNonQuery("""
+            create schema au;
+            create table au.t (id int primary key);
+            """);
+        sim.AssertSqlError(
+            "select * from au.t with (index(nope))",
+            308, "Index 'nope' on table 'au.t' (specified in the FROM clause) does not exist.");
+    }
+
+    [TestMethod]
+    public void Select_IndexHint_NegativeIntegerArg_RaisesMsg102()
+        => new Simulation().AssertSqlError("""
+            create table t (id int primary key);
+            select * from t with (index(-1))
+            """, 102);
+
     [TestMethod]
     public void Select_ForceSeek_BareForm_ReturnsRows()
         => AreEqual(3, new Simulation().ExecuteScalar("""

SqlServerSimulator/Errors/SimulatedSqlException.ConcurrencyErrors.cs

@@ -55,6 +55,30 @@ internal static SimulatedSqlException NoLockHintNotAllowedOnDmlTarget() =>
     internal static SimulatedSqlException IndexHintsOnlyInFromOrOption() =>
         new("Index hints are only allowed in a FROM or OPTION clause.", 1069, 15, 1);
 
+    /// <summary>
+    /// Msg 307 — raised when an <c>INDEX(N)</c> hint references an
+    /// <c>index_id</c> that doesn't exist on the target table. Probe-confirmed
+    /// verbatim wording against SQL Server 2025 (2026-05-14): the message
+    /// embeds the (decimal) id and the qualified table name, both 1-part /
+    /// 2-part qualified consistently with the <c>FROM</c>-clause spelling. The
+    /// rejection only fires for <c>FROM</c>-source / JOIN-RHS positions
+    /// because DML targets short-circuit on <see cref="IndexHintsOnlyInFromOrOption"/>
+    /// (Msg 1069) before any per-index validation runs.
+    /// </summary>
+    internal static SimulatedSqlException IndexHintIdNotFound(int indexId, string qualifiedTableName) =>
+        new($"Index ID {indexId} on table '{qualifiedTableName}' (specified in the FROM clause) does not exist.", 307, 16, 1);
+
+    /// <summary>
+    /// Msg 308 — raised when an <c>INDEX(name)</c> or <c>INDEX = name</c>
+    /// hint references an index name that doesn't exist on the target table.
+    /// Matched case-insensitively against PRIMARY KEY / UNIQUE constraint
+    /// names plus the table's <c>Indexes</c> list. Probe-confirmed verbatim
+    /// wording — same single-quote convention and "(specified in the FROM
+    /// clause)" suffix as Msg 307.
+    /// </summary>
+    internal static SimulatedSqlException IndexHintNameNotFound(string indexName, string qualifiedTableName) =>
+        new($"Index '{indexName}' on table '{qualifiedTableName}' (specified in the FROM clause) does not exist.", 308, 16, 1);
+
     /// <summary>
     /// Msg 3952 — raised when a session whose
     /// <see cref="SimulatedDbConnection.SessionIsolationLevel"/> is