T-Q38X-editor-contract-validation-hint

State: open/ready · Impact: medium · Complexity: medium

Goal

Once SDF can edit entity bodies, an author should see contract findings (a missing required H2, a malformed table) while typing, without the editor ever refusing a save. This task adds that hint as an EditorPlugin in SDF, running markdown-contract’s browser-safe core entry through the same alias the determined shell already uses.

Today

Location	Role today
vendor/markdown-contract-0.2.1.tgz	Vendored package; root package.json installs it by file:
solutions/determined/packages/shell/nuxt.config.ts	Resolves markdown-contract’s core entry and sets vite.resolve.alias['markdown-contract'] for browser builds
solutions/ontological/lib/model/ops/validate.ts	Node-side entity validation; the oracle the hint mirrors
solutions/ontological/desktop/src-nuxt/nuxt.config.ts	No markdown-contract alias
solutions/ontological/desktop/src-nuxt/package.json	No markdown-contract dependency
packages/ts/obsidian-editor/src/	Engine; EditorPlugin seam from T-4TE2-md-engine-plugin-contract

Proposed

solutions/ontological/desktop/src-nuxt/app/composables/useEntityContractHint.ts exports an EditorPlugin that debounces body changes (300 ms), runs the core validator for the entity’s body contract off the keystroke path, and publishes findings as gutter markers plus a compact list under the toolbar. Save never consults it. SDF’s nuxt.config.ts gains the alias mirroring the shell’s, and src-nuxt/package.json adds markdown-contract by file: to the vendored archive. EntityBodyEditor.vue passes the plugin to MdSurface.

Approach

1. src-nuxt/package.json: add markdown-contract (file:../../../../vendor/markdown-contract-0.2.1.tgz).
2. src-nuxt/nuxt.config.ts: resolve the core entry with createRequire and set vite.resolve.alias['markdown-contract'], as packages/shell/nuxt.config.ts does.
3. useEntityContractHint.ts: the plugin; findings typed { line, message, severity }; a requestIdleCallback (fallback setTimeout) hop after the debounce so validation never runs inside the input handler.
4. EntityBodyEditor.vue: pass :plugins="[contractHint]"; render the finding list.
5. Unit test the plugin’s debounce and finding mapping against a fixture body missing ## Goal.
6. Verify: moon run sdf:check sdf:test; bun run build in src-nuxt; type in a 2 000-line body with the Performance panel recording and confirm no long task over 50 ms attributable to the hint; save with findings present; moon run :check :test --affected.

Areas

Area	Note
solutions/ontological/desktop/src-nuxt/package.json	markdown-contract by file:
solutions/ontological/desktop/src-nuxt/nuxt.config.ts	core alias
solutions/ontological/desktop/src-nuxt/app/composables/useEntityContractHint.ts	The EditorPlugin
solutions/ontological/desktop/src-nuxt/app/composables/useEntityContractHint.test.ts	Debounce and mapping tests
solutions/ontological/desktop/src-nuxt/app/components/entities/EntityBodyEditor.vue	Created by T-WUVP-sdf-entity-body-swap-write; gains the plugin pass and finding list
solutions/ontological/desktop/bun.lock	Regenerated

Acceptance criteria

• AC-1: Deleting the ## Goal heading from a task body shows a finding within 500 ms of the last keystroke; restoring it clears the finding.
• AC-2: Saving with findings present writes the body (the save path has no reference to the plugin’s state).
• AC-3: nuxt.config.ts in SDF sets vite.resolve.alias['markdown-contract'] and bun run build passes in src-nuxt.
• AC-4: A Performance recording while typing in a 2 000-line body shows no long task over 50 ms whose stack includes the hint plugin (trace attached to the PR).
• AC-5: useEntityContractHint.test.ts passes under moon run sdf:test.
• AC-6: bun install --frozen-lockfile passes in solutions/ontological/desktop.

Out of scope

• Blocking saves or auto-fixing findings.
• Hints for suspenders skill bodies.
• Moving the alias into the markdown-ui layer; the contract is SDLC-specific and stays in the SDF host.

Dependencies

• T-WUVP-sdf-entity-body-swap-write: the edit surface the hint attaches to.
• T-4TE2-md-engine-plugin-contract: the EditorPlugin seam.
• D-7VMX-markdown-ecosystem-strategy d.4 and d.7: advisory validation, delivered through the plugin seam.

Discovery context

Member of milestone M-931L; wave 5c of D-K3EM-markdown-editor-chrome-and-plugin-environment.

Depends on

T-WUVP-sdf-entity-body-swap-write

---

← Back to Tasks