Design model

Platform spec article

Design model

Back to Snapshot and refresh contract ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (2)

1. 0001-hub-authority Hub authority Accepted

   Hub authority

   Context

   One authority.

   Decision

   Hub owns snapshot/refresh MUST/SHOULD.

   Consequences

   IDE parity.

   Verification anchors

   beskid_lsp tests.

   Open full ADR page

2. 0002-invalidation-on-focus-and-manifest Invalidation Accepted

   Invalidation

   Context

   Stale snapshots.

   Decision

   Invalidate on focus, manifest, lock; debounce watchers.

   Consequences

   Config notification.

   Verification anchors

   session store.

   Open full ADR page

Articles

• Contracts and edge cases Strict guarantees for LSP snapshot lifecycle and refresh behavior. article Standard
• Design model Conceptual model for `Snapshot and refresh contract` and its subsystem boundaries. article Standard
• Examples Observable LSP refresh scenarios for snapshots and diagnostics. article Standard
• FAQ and troubleshooting Common LSP snapshot and refresh issues. article Standard
• Flow and algorithm End-to-end refresh flow for LSP workspace snapshots and diagnostics. article Standard
• Verification and traceability Tests and traceability for the LSP snapshot and refresh contract. article Standard

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 3 SpecSection(s) · 0 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Area
  LSP

  Parent area

• Feature
  Snapshot and refresh contract

  Parent feature hub

• Feature
  Incremental scheduling and determinism

  Meta invalidation keys and replay

Purpose

The Beskid LSP maintains two cooperating caches: open document buffers (State.docs) and disk-backed workspace index entries (State.workspace_index), both carrying optional DocumentAnalysisSnapshot values versioned by ANALYSIS_CACHE_VERSION. A separate CompilationContext cache keys off resolved Project.proj paths plus workspace member defaults.

Snapshot stores

flowchart LR
  subgraph open [Open buffers]
    DidOpen[didOpen / didChange]
    Doc[Document + text_hash]
    Snap[DocumentAnalysisSnapshot]
    DidOpen --> Doc --> Snap
  end
  subgraph disk [Disk index]
    Scan[workspace_scan]
    Idx[workspace_index]
    Scan --> Idx
  end
  subgraph project [Project scope]
    Ctx[compilation_context_cache]
    Inv[invalidate_compilation_cache]
  end
  Snap --> Ctx
  Inv --> Ctx
  Inv --> Snap

Store	Key	Invalidation trigger
Open Document	LSP Uri	Text change, version bump, cache version mismatch
Disk snapshot	Uri (file not open)	Workspace scan, external file watcher refresh
CompilationContext	(Project.proj path, member default)	Manifest/lock/graph changes, explicit invalidation

Analysis snapshot contents

build_document_analysis calls beskid_analysis::services::build_document_analysis_with_context when a CompilationContext exists. Project manifest URIs (.proj) must not produce analysis snapshots—only Beskid sources.

Hard vs soft invalidation

Hard invalidation clears compilation_context_cache and bumps per-document analysis_cache_version so every open buffer re-analyzes:

• Project.proj, Workspace.proj, or lockfile writes affecting dependency roots
• project.mod changes on attached Mod projects
• Full workspace rescan after invalidate_compilation_cache (workspace_scan.rs, backend.rs)

Soft invalidation (re-run meta without full graph rebuild) is permitted only when capture keys remain valid; otherwise the server must hard-invalidate per Incremental scheduling and determinism.

Status reporting

Workspace scans emit BeskidStatusParams with phase: workspace_scan and throttled progress (STATUS_EMIT_INTERVAL 200ms) so the VS Code extension can mirror CLI-style progress in the status bar.

Implementation anchors

• Document lifecycle: compiler/crates/beskid_lsp/src/session/lifecycle.rs
• Project context cache: compiler/crates/beskid_lsp/src/session/project_context.rs
• Workspace scan: compiler/crates/beskid_lsp/src/workspace_scan.rs
• Server wiring: compiler/crates/beskid_lsp/src/server/backend.rs
• Diagnostics publish debounce: 120ms coalescing in schedule_publish_diagnostics