Contracts and edge cases

Platform spec article

Contracts and edge cases

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

• Feature
  Snapshot and refresh contract

  Parent feature hub

• Feature
  Diagnostics parity

  CLI and LSP share diagnostic codes

Contracts

• Open buffer wins — Disk index must not overwrite an open Document for the same Uri.
• Monotonic versions — Stale didChange versions must be ignored per LSP rules.
• Cache generation — When ANALYSIS_CACHE_VERSION increments, all snapshots must rebuild even if text is unchanged.
• Diagnostic debounce — Only the latest scheduled revision per URI may publish; superseded tasks must no-op.
• Manifest URIs — .proj files must not run Beskid semantic analysis snapshots.
• Parity — Diagnostic codes and severities must match beskid analyze for the same CompilationContext.

Edge cases

Case	Behavior
Source outside focused project tree	Fall back to focused Project.proj when path is under focus root (project_context.rs)
No resolvable manifest	Analysis snapshot is None; features degrade gracefully without fabricated graphs
Large workspace scan	Progress events must remain cancellable by subsequent invalidation
Rapid typing	Text-hash fast path avoids parse until pause; debounced diagnostics may lag one generation
Lockfile change during edit	Hard invalidation; user may see transient empty diagnostics until rescan completes

Meta invalidation

Changes to project.mod or mod AOT outputs must hard-invalidate compilation cache before re-running generators. Soft paths are opt-in and require proven stable capture keys.