@qoretechnologies/reqraft 0.10.66-pr.145.gcb1e59d → 0.10.66

package/.tasks/SCHEMA_DEFINITION_FIELD.md

@@ -1,250 +0,0 @@
-# DataSchema editor — migrate `schema-definition` to Reqraft
-
-Phase 2 of the field migration (see
-[`design/FORM_ENGINE_FIELD_MIGRATION.md`](../design/FORM_ENGINE_FIELD_MIGRATION.md)).
-Ports qorus-ide's `SchemaDefinitionEditor` into the Reqraft form engine
-as the first complex, server-catalogue-driven field. **Depends on
-phase 1** ([`REQRAFT_AUTO_FIELD.md`](./REQRAFT_AUTO_FIELD.md)) — the
-catalogue's leaf adapter emits `auto` for non-primitive fields.
-
-**Status:** done pending user verify — implemented 2026-06-09 (still
-uncommitted, on top of the also-uncommitted phase 1). 8/8 story play
-tests pass via `test-storybook` (was 5/5; Sandboxed + WithValidationBanner
-added via FIELD_STACK phase 3, the ReadOnly zero-inputs play restored in the
-remediation batch); prod typecheck + eslint clean. Verified
-live: catalogue-driven tabs, the Tables inline panels, the table editor
-with sub-tabs + `ReqoreTable`, and the **column drawer rendering the
-`FormEngine`-driven leaf form** (the `<Options>`→`FormEngine` seam) — name
-field, allowed-value select, bool toggle, comment, "More Options 5".
-No runtime errors reference the ported code.
-
-**Scope:** copy the generic catalogue machinery near-verbatim; the real
-work is the one integration seam (`<Options>` → Reqraft `FormEngine`)
-plus porting two bespoke layout tabs and swapping qorus-ide-only deps.
-**Estimated size:** 16 source files (~3,280 lines, incl. mocks) ported;
-net new Reqraft code modest because most is copy + import-repoint.
-~1 week incl. tests/iteration.
-
-## Reference
-
-Source dir: `qorus-frontend/qorus-ide/src/components/Field/schemaDefinition/`
-
-| File | Role | Port difficulty |
-|---|---|---|
-| `types.ts` (185) | `ISchemaOptionCatalog`, `ICatalogNode`, `IDataSchemaDefinition` | copy verbatim |
-| `catalog.ts` (238) | node discriminators + `catalogLeafToFieldSchema` | copy verbatim |
-| `helpers.ts` (110) | `SECTION_ICONS`, `sectionCount` | copy verbatim |
-| `useSchemaOptionCatalog.ts` (49) | `useFetch('schemas?action=options')` | repoint `useFetch` import |
-| `referenceSuggestions.tsx` (151) | FK/PK contextual suggestion resolvers | copy verbatim (self-contained) |
-| `catalogContext.tsx` (32) | catalogue provider | copy verbatim |
-| `CatalogLeafForm.tsx` (242) | **leaf renderer → `<Options>`** | **rewrite leaf render to `FormEngine`** |
-| `CatalogNodeEditor.tsx` (730) | group/map/list dispatch + drawer editors | port; swap `QorusTable`, `Hint` |
-| `TablesTab.tsx` (138) + `TableEditor.tsx` (155) | inline-panel tables, nested tabs | port (bespoke layout) |
-| `MigrationsTab.tsx` (187) | version timeline | port (bespoke layout) |
-| `InlineValidationBanner.tsx` (138) | name-mismatch / version hints | port |
-| `starterTemplate.ts` (68) | `createEmptyDefinition` | copy verbatim |
-| `mockCatalog.ts` (325) + `mockDefinition.ts` (111) | story/test fixtures | copy verbatim |
-
-Server contract: `GET schemas?action=options` → `ISchemaOptionCatalog`
-(`{ fields, definition, actions }`; editor uses `definition`). 100%
-server-driven, no FE field fallbacks. Catalogue → tabs mapping is
-hardcoded `PRIMARY_SECTIONS = [schema, tables, sequences,
-reference_data, migrations]` + an Advanced bucket for trusted users
-(`index.tsx:65-71, 156-174`).
-
-## Surface area
-
-| File | Change |
-|---|---|
-| `src/components/form/fields/schema-definition/*` | **new** — ported dir (see Reference table) |
-| `src/components/form/fields/schema-definition/CatalogLeafForm.tsx` | leaf render uses Reqraft `FormEngine`, not `<Options>` |
-| `src/components/form/fields/schema-definition/SchemaDefinitionField.stories.tsx` | **new** — mock-catalogue stories |
-| `src/components/form/fields/Field.tsx` | add `case 'schema-definition':` (+ `ui_type === 'schema-definition'`) → editor |
-| `src/components/form/index.tsx` | export `SchemaDefinitionField` |
-| `__tests__/form/schemaDefinition/*` | **new** — catalogue walk + leaf adapter |
-
-## Items
-
-### 1. Port the catalogue-generic machinery
-
-**Decision.** Copy `types.ts`, `catalog.ts`, `helpers.ts`,
-`referenceSuggestions.tsx`, `catalogContext.tsx`, `starterTemplate.ts`,
-`mockCatalog.ts`, `mockDefinition.ts` into
-`src/components/form/fields/schema-definition/` with no logic changes.
-These have **zero qorus-ide coupling** (only `react`, `react-use`,
-`@qoretechnologies/reqore`, `@qoretechnologies/ts-toolkit`,
-`styled-components`).
-
-**Surface area.** New files; import paths only.
-
-**Tests.** Unit-test the node discriminators (`isCatalogLeaf/Group/
-Map/List`) and `catalogLeafToFieldSchema` against `mockCatalog`.
-
-### 2. Repoint the catalogue fetch hook
-
-**Decision.** `useSchemaOptionCatalog` already imports `useFetch` from
-`@qoretechnologies/reqraft`; inside Reqraft it imports from the local
-barrel/`hooks/useFetch`. Keep the `override` / `errorOverride` props
-(stories inject a mock catalogue without a server).
-
-**Surface area.** `useSchemaOptionCatalog.ts` import line.
-
-**Tests.** Story passing `override={mockCatalog}` renders without a
-network call.
-
-### 3. Leaf renderer → `FormEngine` (the integration seam)
-
-**Decision.** This is the crux. In `CatalogLeafForm`, the per-leaf
-options schema (built by `catalogLeafToFieldSchema`, already an
-`IOptionsSchema`) is currently rendered by qorus-ide's `<Options>`. We
-**do not port `<Options>`** (`systemOptions.tsx`, 1500+ lines, heavily
-IDE-coupled). Instead render with Reqraft `FormEngine`:
-
-```tsx
-// CatalogLeafForm.tsx (Reqraft)
-<FormEngine
-  name={name}
-  options={schema}          // IOptionsSchema from catalogLeafToFieldSchema
-  value={optionsValue}
-  onChange={handleChange}
-  flat
-  wrapperPadding='none'
-  minColumnWidth='300px'
-  size='small'
-/>
-```
-
-The phase-1 `auto` field is what makes this correct: leaves typed
-`auto` (the catalogue's catch-all) now render the type-picker instead
-of a textarea. Verify the read-only branch (`ReqoreDescriptionList`)
-and the reference-suggestion injection (allowed-values + `_creatable`)
-still apply — both are independent of the renderer choice.
-
-**Surface area.** `CatalogLeafForm.tsx` edit-mode render (~30 lines
-changed). Confirm `FormEngine`'s `onChange(name, value)` signature maps
-cleanly to the leaf `handleChange`.
-
-**Tests.** Story with a leaf catalogue including `string`, `int`,
-`select-string` (allowed_values), `list<string>`, and an `auto`
-fallback leaf — all render correct fields; editing emits the right
-value shape.
-
-### 4. Port `CatalogNodeEditor` (group/map/list + drawers)
-
-**Decision.** Port the recursive dispatcher and the map/list overview +
-drawer editors. Swap two qorus-ide deps:
-- `QorusTable` → `ReqoreTable` directly (see design Open question;
-  re-add search/sort only if a section is routinely large).
-- `Hint` → Reqraft equivalent or drop (cosmetic).
-
-**Surface area.** `CatalogNodeEditor.tsx` (~730 lines, mostly copy).
-
-**Tests.** Map section (e.g. `tables`) renders an entry table + opens
-a drawer; list section (e.g. `migrations`) supports add/reorder.
-
-### 5. Port the bespoke tabs + validation banner
-
-**Decision.** Port `TablesTab` + `TableEditor` (inline-expandable
-panels, nested `ReqoreTabs` per table section, wrapped in the
-suggestion provider), `MigrationsTab` (version timeline of
-`CatalogGroupBody` blocks), and `InlineValidationBanner`
-(name-mismatch / version-bump / save-error hints). These are
-presentation wrappers around the generic renderer.
-
-**Surface area.** `TablesTab.tsx`, `TableEditor.tsx`,
-`MigrationsTab.tsx`, `InlineValidationBanner.tsx`.
-
-**Tests.** Visual stories per tab against `mockCatalog` +
-`mockDefinition`.
-
-### 6. Expose as a Reqraft field type
-
-**Decision.** Add `case 'schema-definition':` to `FormField` (and the
-`ui_type === 'schema-definition'` alias), mirroring qorus-ide's
-`auto.tsx` ui_type branch — `value` is the `definition` hash,
-`onChange(definition)`. Export `SchemaDefinitionField` from the form
-barrel.
-
-**Surface area.** `Field.tsx`, `form/index.tsx`.
-
-**Tests.** `FormEngine` story embedding a `schema-definition` field
-round-trips a full `IDataSchemaDefinition`.
-
-## Sequencing
-
-1. Item 1 (generic machinery) + Item 2 (fetch hook) — no UI yet
-2. Item 3 (leaf → `FormEngine`) — unblocks everything visual; **needs
-   phase 1 merged**
-3. Item 4 (node editor) — groups/maps/lists render
-4. Item 5 (bespoke tabs + banner) — full editor
-5. Item 6 (field-type exposure) — wire into the dispatcher
-6. Stories + tests throughout; full pass at the end
-
-## Tasks
-
-- [x] Copy generic machinery (`types`, `catalog`, `helpers`,
-      `referenceSuggestions`, `catalogContext`, `starterTemplate`,
-      `mockCatalog`, `mockDefinition`); fix imports. **Copied the whole
-      dir verbatim** — sibling `./` imports stayed valid; only ~7 files
-      had outside deps to repoint.
-- [x] Repoint `useSchemaOptionCatalog` to Reqraft `useFetch`
-      (`../../../../hooks/useFetch/useFetch`); kept `override`/`errorOverride`
-- [x] `CatalogLeafForm` edit render → Reqraft `FormEngine`. Reqraft's
-      `FormEngine` exports the **same** `flattenOptions` / `IOptionsSchema`
-      / value+onChange contract as qorus-ide `<Options>`, so the seam was
-      a near drop-in (`Options` default import → `FormEngine` named).
-      Read-only viewer + suggestion-injection branches untouched (copied
-      verbatim; drawer leaf form verified live).
-- [x] Port `CatalogNodeEditor`; `QorusTable`→`ReqoreTable` (both map +
-      list editors), `DRAWER_STYLE` inlined as a local const
-- [x] Port `TablesTab` + `TableEditor`, `MigrationsTab`,
-      `InlineValidationBanner` (verbatim; `Hint` repointed to a local shim)
-- [x] `Hint`/`Loader` local shims (`Hint.tsx` → `ReqoreMessage`,
-      `Loader.tsx` → `ReqoreSpinner`) replacing qorus-ide `../../Help` /
-      `../../Loader`
-- [x] `index.tsx` editor shell — tabs (`PRIMARY_SECTIONS` + Advanced),
-      catalogue-load error callout, providers (verbatim; shim imports)
-- [x] `case 'schema-definition':` in `FormField`; export
-      `SchemaDefinitionEditor` from the form barrel. Both the direct `type`
-      path AND the `ui_type` (FormEngine option) path are wired — the latter
-      via the `schema-definition` pass-through in both
-      `mapQorusTypeToFormFieldType` copies.
-- [x] Stories: `Empty`, `Populated`, `ReadOnly`, `CatalogError`,
-      `ViaFormField`, `ViaFormEngineUiType` (`SchemaDefinitionField.stories.tsx`).
-      6/6 play tests pass; `Populated` opens Tables → asserts both table
-      panels; `ViaFormField` is the direct dispatcher round-trip;
-      `ViaFormEngineUiType` is the FormEngine `ui_type` round-trip.
-- [x] Resolve the `QorusTable` open question — **used `ReqoreTable`
-      directly**; search/sort not re-added (acceptable; revisit if a
-      section grows large).
-- [x] Tests: 5/5 story play tests pass via `test-storybook`; prod
-      typecheck + eslint clean. (No separate jest file — fields are
-      tested via stories here.)
-- [x] 2026-06-11 follow-ups: now 8/8 plays (Sandboxed +
-      WithValidationBanner via FIELD_STACK phase 3; ReadOnly zero-inputs
-      play restored); the IDE's 3 schemaDefinition jest suites ported to
-      `__tests__/schemaDefinition/` (~37 tests) — the "no separate jest
-      file" note above is superseded.
-- [ ] **STOP — user verifies in browser** before commit
-
-## Out of scope
-
-- ~~`ui_type: 'schema-definition'` via the FormEngine/TemplateField path.~~
-  **Done** (2026-06-09 follow-up): both `mapQorusTypeToFormFieldType` copies
-  pass `schema-definition` through (cast past `TQorusType`), so a `FormEngine`
-  option declared `ui_type: 'schema-definition'` renders the editor.
-  `catalogOverride` rides through `fieldProps` (FormEngine spreads the option
-  → TemplateField `{...rest}` → FormField). Story: `ViaFormEngineUiType`
-  (verified live — the value round-trips, populated schema renders).
-- Suggestion-injection (FK/PK contextual `allowed_values`) is ported
-  verbatim and **verified live** (2026-06-09): a table's Primary Key
-  `columns` field offers the table's own columns as "Saved & Suggested
-  Values". Not asserted by an automated play test (fiddly to drive), but
-  confirmed by hand.
-- Porting qorus-ide's `<Options>` / `systemOptions.tsx` (we use
-  `FormEngine` instead)
-- The `schema` *interface-selector* type (bucket 3 — app-coupled)
-- Schema `actions` (validate/diff/align/drop) — the catalogue exposes
-  them but the editor doesn't drive them; out of scope here
-- Server-side catalogue changes — consume `schemas?action=options`
-  as-is

package/.tasks/SMART_EDITOR_CONTEXT_AND_POLISH.md

@@ -1,340 +0,0 @@
-# SmartEditor — context handling, debounced loader, README
-
-Follow-up to the `0.10.0` UX batch (see
-[`SMART_EDITOR_UX_POLISH.md`](./SMART_EDITOR_UX_POLISH.md)). This is
-the catch-all for smaller correctness / polish items surfaced by the
-post-`0.10.0` audit: a startup race in DPQL context binding, a
-loader-flash on fast LSP responses, the missing FSM and Alert-payload
-context props (required for the upcoming Alert Rule editor in
-qorus-ide), and the README drift across this batch.
-
-**Status:** items 1/2/4 done — committed in `5e94fd7` (item 1, `isContextReady` race), `8e6fe0f` (item 2, debounced loader), `2a53a1a` (item 4, FSM + alert-payload props). Item 3 (README catch-up) deferred to the final release-prep step at the end of the full batch — single README pass against the complete post-batch API. **Awaiting browser verification.**
-
-**Scope:** four items, all small-to-medium. README update is
-non-optional given how many props have been added.
-**Estimated size:** ~150 lines, 1 day.
-
-## Items
-
-### 1. Initial DPQL context race
-
-**Symptom.** `session.isReady` flips true when the LSP `initialize`
-and `didOpen` complete (`useLspSession.ts:106`). `useDpqlSession`
-THEN fires `dpql/setContext` in a separate effect — adding a second
-roundtrip before the document has its provider context bound. If
-the user types `@` in the first ~50–200ms after mount, the
-completion request hits the server context-less; server returns
-zero items; dropdown opens then closes silently.
-
-**Server behaviour.** Tolerates context-less requests structurally
-(no error), but returns empty results — exactly what makes the bug
-hard to diagnose.
-
-**Decision.** Add a `isContextReady?: boolean` field to
-`IUseLspSessionResult`, defaulting to `true` (generic primitive has
-no context concept). `useDpqlSession` overrides it: starts `false`,
-flips `true` only after the `dpql/setContext` promise resolves, OR
-flips `true` immediately if no `provider` is configured (no context
-binding to do).
-
-In SmartEditor, gate LSP-driven hooks
-(`useLspAutocomplete`, `useLspHover`, `useLspSemanticTokens`) on the
-combined signal `session.isReady && (session.isContextReady ?? true)`.
-The loading overlay's copy becomes "Loading schema…" when
-`isReady && !isContextReady`.
-
-**Edge cases:**
-- `provider` is set but `dpql/setContext` ERRORS — flip `isContextReady` true anyway (best-effort; the editor still works without provider-driven completions).
-- `provider` changes after initial mount — flip `isContextReady` back
-  to `false` until the new context resolves.
-
-**Surface area:**
-- `src/components/smartEditor/useLspSession.ts` — add `isContextReady` (default `true`)
-- `src/components/dpqlEditor/useDpqlSession.ts` — track and expose
-- `src/components/smartEditor/SmartEditor.tsx` — combined gate; loading-overlay copy switch
-- `src/components/smartEditor/useLspAutocomplete.ts` — accept `isReady` (no API change; the caller passes the combined gate)
-
-**Tests:** Storybook story that delays the mock's `dpql/setContext`
-response by 500ms; play test types `@` in first 200ms and asserts
-the dropdown does NOT appear; assert overlay copy is "Loading schema…".
-
-**Complexity:** small.
-
----
-
-### 2. `isFetching` loader debouncing (anti-flash)
-
-**Symptom.** `useLspAutocomplete.ts:335` sets `isFetching=true`
-synchronously when the LSP request fires. For sub-100ms mock
-responses the user never sees the "Loading completions…" stub.
-For ~200–500ms live responses, the stub flashes briefly then swaps
-for items — visible jitter.
-
-**Decision.** Mirror VS Code's "delay progress" pattern. Don't set
-`isFetching=true` synchronously; schedule it via
-`setTimeout(() => setIsFetching(true), LOADER_DELAY_MS)` where
-`LOADER_DELAY_MS = 250`. Clear in the `finally` of the request and
-in `close()`. Net effect: fast responses never set the flag; only
-genuinely slow roundtrips do.
-
-`setIsOpen(true)` stays synchronous — opening an items-less popover
-is fine for ~250ms; renders nothing visible until either items
-arrive (popover populates) or the timer elapses (loading stub shows).
-
-**Surface area:**
-- `src/components/smartEditor/useLspAutocomplete.ts` —
-  `performCompletionRequest`, add a `fetchingTimerRef`, clear in
-  `close()` and in the unmount-cancel effect
-- Named constant `LOADER_DELAY_MS = 250` next to `DEBOUNCE_MS = 150`
-
-**Tests:** Unit test with `jest.useFakeTimers()`:
-- Fire request → advance 240ms → `isFetching === false`
-- Advance to 260ms → `isFetching === true`
-- Resolve request → `isFetching === false`
-- Fire request, resolve in 80ms → `isFetching` never sets true
-
-**Complexity:** small.
-
----
-
-### 3. README drift across the `0.10.0` batch
-
-**Symptom.** The published README (`toolkit-react/README.md`) hasn't
-been updated since `0.9.0`. Six new SmartEditor / DpqlEditor props
-landed across phases 4–7, none documented. The Components section
-also doesn't mention diagnostics, hover, semantic tokens, or the
-chip-replace flow.
-
-**Missing — DpqlEditor:**
-- `useServerParse` (Phase 6)
-
-**Missing — SmartEditor:**
-- `loadingIndicator?: React.ReactNode` (Phase 4)
-- `enableHover?: boolean` (Phase 5)
-- `isLoading?: boolean` (Phase 6)
-- (After item 4 in this task) `alertPayloadContext?: boolean`,
-  `fsmContext?: ...` on DpqlEditor
-- (After SMART_EDITOR_LSP_FEATURES item 1)
-  `enableSignatureHelp?: boolean`
-
-**Missing behaviours:**
-- LSP-driven syntax highlighting (semantic tokens) — referenced in
-  the features list but no API documentation. Add an "LSP methods
-  supported" subsection
-- Diagnostics surface (inline wavy underlines + ReqoreMessage panel)
-- Markdown documentation on completion rows (hover-tooltip)
-- Chip click → Replace mode flow
-- Loading overlay states (connecting, parsing, fetching)
-
-**Wrong:**
-- `triggerCharacters` is described as "Characters that open the
-  completion dropdown" with no mention of language defaults or that
-  the generic SmartEditor's default (`{., :, space}`) differs from
-  both DPQL (`@$.:`) and Qonsole (`/-.:=` + space)
-
-**Decision.** A focused README update that documents every prop
-landed since `0.9.0`, adds an "LSP methods supported" section, and
-corrects the misleading trigger-characters description.
-
-**Surface area:** `README.md` only.
-
-**Complexity:** small (writing time).
-
----
-
-### 4. `dpql/setFsmContext` + `dpql/setAlertPayloadContext` props
-
-**Background.** The server supports two additional context-binding
-methods we don't expose:
-
-- **`dpql/setAlertPayloadContext`** — binds the document's field set
-  to the canonical alert-payload schema (severity, alert_type,
-  alert_code, alert_class, interface_type, interface_name,
-  alert_object, …). Required for the Alert Rule / Silence editor to
-  produce correct completions and diagnostics on `@payload.field`
-  references.
-- **`dpql/setFsmContext`** — binds an FSM context (by inline
-  definition, draft id, or published fsm id) so `$data:` /
-  `$fsminput:` template namespaces resolve against the FSM's state
-  graph. Required for FSM-state-aware completions when DpqlEditor is
-  used inside an FSM state editor.
-
-**Source confirmation.** `qorus-ide/.tasks/ALERT_RULES_AND_SILENCES.md`
-explicitly calls out the alert-rule editor's `match` field as
-"DPQL completions — genuinely new". This task is the gating piece
-of Reqraft work.
-
-**Decision.** Two new props on `DpqlEditor`:
-
-```ts
-interface IDpqlEditorProps {
-  // ...
-  /**
-   * When true, bind the document's field set to the canonical
-   * alert-payload schema instead of (or in addition to) the
-   * `provider`/`recordType` context. Required for the Alert Rule
-   * / Silence editor. Sends `metadata.dpql_context: "alert-payload"`
-   * on `didOpen` so the binding lands at open-time without an
-   * extra roundtrip. When toggled off later, falls back to the
-   * `provider` / `recordType` context via `dpql/setContext`.
-   */
-  alertPayloadContext?: boolean;
-
-  /**
-   * FSM context for state-aware template completions. Exactly one
-   * of `fsm` / `draftId` / `fsmId` must be provided; pass
-   * `undefined` (or no FSM source) to clear. Fires
-   * `dpql/setFsmContext` whenever the object identity changes.
-   */
-  fsmContext?:
-    | { fsm: Record<string, any>; currentState?: string }
-    | { draftId: string; currentState?: string }
-    | { fsmId: number; currentState?: string };
-}
-```
-
-These compose with each other: a DPQL editor can have BOTH a
-provider context AND an FSM context. Provider gives field
-completions, FSM gives template completions. `alertPayloadContext`
-REPLACES the provider context (server treats them as mutually
-exclusive — one binding per URI).
-
-`isContextReady` (from item 1) covers all three context types — we
-flip it false until whichever binding the editor is configured for
-resolves.
-
-**Surface area:**
-- `src/components/dpqlEditor/types.ts` — `IDpqlEditorProps` gains
-  `alertPayloadContext`, `fsmContext` (discriminated union)
-- `src/components/dpqlEditor/useDpqlSession.ts` — new effects firing
-  `dpql/setAlertPayloadContext` / `dpql/setFsmContext`; update
-  `isContextReady` logic
-- `src/components/dpqlEditor/DpqlEditor.tsx` — pass through
-- `src/components/dpqlEditor/DpqlEditor.stories.tsx` — mock handlers
-  for both methods; new stories `WithAlertPayloadContext`,
-  `WithFsmContext`
-- `README.md` — document both props (done via item 3)
-
-**Tests:** Storybook play tests:
-- `WithAlertPayloadContext` — asserts `didOpen` metadata includes
-  `dpql_context: "alert-payload"` and a `dpql/setAlertPayloadContext`
-  call happens
-- `WithFsmContext` — asserts `dpql/setFsmContext` fires with the
-  configured `fsmId` and `currentState`; asserts that switching
-  `fsmId` re-fires
-- Both should assert `isContextReady` gates correctly
-
-**Complexity:** medium (multiple new effects, type discriminated
-union, two new stories with mock handlers).
-
----
-
-## Sequencing
-
-Land in this order so each builds on the previous:
-
-1. Item 1 (`isContextReady`) — establishes the readiness gate that
-   item 4 reuses
-2. Item 2 (debounced loader) — independent; can be parallel with 1
-3. Item 4 (FSM + alert-payload props) — depends on item 1
-4. Item 3 (README) — last, so it documents everything that just
-   landed
-
-## Surface area summary
-
-| File | Items |
-|---|---|
-| `src/components/smartEditor/useLspSession.ts` | 1 |
-| `src/components/smartEditor/SmartEditor.tsx` | 1 |
-| `src/components/smartEditor/useLspAutocomplete.ts` | 1, 2 |
-| `src/components/dpqlEditor/useDpqlSession.ts` | 1, 4 |
-| `src/components/dpqlEditor/types.ts` | 4 |
-| `src/components/dpqlEditor/DpqlEditor.tsx` | 4 |
-| `src/components/dpqlEditor/DpqlEditor.stories.tsx` | 4 |
-| `__tests__/smartEditor/loaderDebounce.test.ts` | 2 (new) |
-| `__tests__/dpqlEditor/contextReady.test.ts` | 1 (new) |
-| `README.md` | 3 |
-| `QONSOLE_LSP_REFERENCE.md` | (covered by QONSOLE_ASSIST_FEATURES) |
-
-## Tasks
-
-### 1. `isContextReady`
-
-- [ ] `useLspSession` — add `isContextReady: boolean` to result,
-      default `true`
-- [ ] `useDpqlSession` — track and expose. `false` initially, flips
-      `true` after first context-binding resolves (or immediately if
-      no context is configured)
-- [ ] `SmartEditor` — combine `isReady && isContextReady` for the
-      LSP-driven hooks
-- [ ] Loading-overlay copy switches to "Loading schema…" when
-      `isReady && !isContextReady`
-- [ ] Storybook story with delayed-context mock; play test confirms
-      no dropdown opens during the delay
-- [ ] Unit-test the context-ready combinator
-
-### 2. Loader debouncing
-
-- [ ] `LOADER_DELAY_MS = 250` constant
-- [ ] `performCompletionRequest` schedules `setIsFetching(true)` via
-      `setTimeout`; clears in `finally`
-- [ ] `close()` clears the pending timer
-- [ ] Unit test the four timing cases (fast / slow / cancelled / on
-      error)
-
-### 4. FSM + Alert-payload props (land before 3, depend on 1)
-
-- [ ] `IDpqlEditorProps` extended with `alertPayloadContext`,
-      `fsmContext` (discriminated union)
-- [ ] `useDpqlSession` — new effect for alert-payload: when
-      `alertPayloadContext === true`, include
-      `dpql_context: 'alert-payload'` in `initialMetadata` (no
-      separate call needed); when it flips false later, fire
-      `dpql/setContext` with the provider context to restore
-- [ ] `useDpqlSession` — new effect for FSM context: fire
-      `dpql/setFsmContext` whenever the `fsmContext` object identity
-      changes (including identity-changed-to-undefined → clear)
-- [ ] `isContextReady` flips false on context-config change, true
-      when the resolution resolves
-- [ ] Type-level enforcement: `fsmContext` is a discriminated union
-      so consumers can't provide multiple sources
-- [ ] Storybook mocks for both server methods
-- [ ] Stories `WithAlertPayloadContext` and `WithFsmContext`
-- [ ] Play tests verify the right requests fire
-
-### 3. README update (land last)
-
-- [ ] Update DpqlEditor props table: add `useServerParse`,
-      `alertPayloadContext`, `fsmContext`
-- [ ] Update SmartEditor props table: add `loadingIndicator`,
-      `enableHover`, `isLoading`, `enableSignatureHelp` (if
-      SMART_EDITOR_LSP_FEATURES landed)
-- [ ] New section "LSP methods supported" — what's wired, with a
-      one-line "why not X" pointer to each deferred method per
-      `SMART_EDITOR_LSP_FEATURES.md`
-- [ ] Fix the `triggerCharacters` description: clarify it's a
-      per-wrapper concern with sensible language-specific defaults;
-      show DPQL and Qonsole defaults
-- [ ] Mention behaviours: semantic-token highlighting, diagnostics,
-      hover, markdown docs, Replace-mode chip click, loading states
-- [ ] Code example for `alertPayloadContext` use in an Alert Rule
-      context
-
-### Checks (final)
-
-- [ ] Typecheck, lint, jest, storybook play tests all pass
-- [ ] **STOP — user verifies in browser** before commit (per the
-      design doc's workflow rule)
-
-## Out of scope
-
-- Hover-popover replacement of the native `title=` browser tooltip
-  on inline diagnostic underlines (separate visual-polish concern)
-- Editor body's own scroll behaviour when content exceeds height
-  (Reqore-side)
-- Schema reload triggers when provider changes — already handled by
-  the existing `useDpqlSession` effect; no work
-- Server-side bug: when no `provider` is set AND no
-  `alertPayloadContext`, completions are effectively dead — this is
-  expected per the server contract; the editor displays no
-  completions and that's correct