feat: shared pseudoscript-lsp-core — stdio + LSP-over-wasm, one API

.claude/skills/pseudocode/SKILL.md

@@ -20,10 +20,11 @@ data provenance are written as high-level pseudocode, infrastructure is declared
 the whole thing compiles to C4 diagrams, sequence diagrams, and a doc site (`pds doc`).
 
 This skill is the **method**, not the grammar. For any syntax question — keywords, `Result`
-handling, `from` composition, macros, modules, visibility, the EBNF — read **`references/LANG.md`**
-(the language specification) and follow it exactly. Do **not** invent syntax; if the spec doesn't
-support a form (e.g. comparison operators in conditions — see its Open Questions), model around it
-with a call that returns a `Result` or `bool` instead.
+handling, `from` composition, macros, modules, visibility, the EBNF — run **`pds lang`** to print
+the full language reference (spec + patterns + the conformance/grammar suite) and follow it exactly.
+Do **not** invent syntax; if the spec doesn't support a form (e.g. comparison operators in
+conditions — see its Open Questions), model around it with a call that returns a `Result` or `bool`
+instead.
 
 Two jobs only:
 - **Map** an existing application into a `.pds` model (reverse).
@@ -57,14 +58,14 @@ disclose it as a branch. *How the JWT is parsed* is plumbing → omit it.
 ## Concern → construct map
 
 Read it top-to-bottom when mapping an existing app; read it right-to-left when reconstituting code
-from a model. (Constructs and call syntax are defined in `references/LANG.md`.)
+from a model. (Constructs and call syntax are defined in the language reference — run `pds lang`.)
 
 | App concern | PseudoScript | Disclosed? |
 |---|---|---|
 | HTTP route / controller / RPC handler | callable with `#[http("VERB /path")]` | body disclosed only for the orchestration that carries meaning; routing/serialization is the macro, not the body |
 | Use case / application service / interactor | disclosed callable | **disclose** |
 | Domain rule, validation, **authorization** decision | `if (r.isErr) { return Err(...) }` branches | **disclose** |
-| Calculation / assembling a result from parts | `x = T from { a, b }` + the calls feeding it | **disclose** (provenance) |
+| Calculation / assembling a result from parts | `x: T = T from { a, b }` + the calls feeding it | **disclose** (provenance) |
 | Repository / DAO / ORM mapper | black-box `component` (or `container`) with `fetch`/`save`/… signatures | black box |
 | Database / cache / queue infrastructure | black-box `container`, often tagged `#critical` | black box |
 | DTO / entity / domain event / message | `data` record; events as a discriminated union | fields disclosed when they matter; `data X;` otherwise |
@@ -90,7 +91,8 @@ from a model. (Constructs and call syntax are defined in `references/LANG.md`.)
 5. **Disclose the use cases.** Translate each service/interactor method into a disclosed callable,
    tracing the **business logic line for line**: every guard becomes an `if (…isErr) { return Err }`,
    every assembled value becomes `from { … }`, every dependency call becomes a `Target.method(args)`.
-   Keep bodies at flow-and-provenance level — never field-level arithmetic.
+   Every binding states its type (`x: T = …`). Keep bodies at flow-and-provenance level — never
+   field-level arithmetic.
 6. **Mark the entry points.** Attach the trigger macro that matches how each callable is actually
    initiated: `#[http]`, `#[onevent]`, `#[schedule]`, `#[manual]`. These become inbound edges and
    sequence-diagram entry points.
@@ -188,18 +190,18 @@ public container Checkout for Shop {
   /// Reserve stock, price it, charge, persist, announce.
   #[http("POST /orders")]
   public PlaceOrder(cmd: PlaceOrder): Result<Order, OrderError> {
-    reserved = Inventory::Reservations.reserve(cmd.sku, cmd.qty)
+    reserved: Result<void, OutOfStock> = Inventory::Reservations.reserve(cmd.sku, cmd.qty)
     if (reserved.isErr) {
       return Err(reserved.error)
     }
-    quote = self.Quote(cmd.sku, cmd.qty)
-    order = Order from { cmd, quote }
-    paid = Payments.charge(order)
+    quote: number = self.Quote(cmd.sku, cmd.qty)
+    order: Order = Order from { cmd, quote }
+    paid: Result<void, Declined> = Payments.charge(order)
     if (paid.isErr) {
       return Err(paid.error)
     }
     OrderStore::Orders.save(order)
-    evt = OrderPlaced from { order }
+    evt: OrderPlaced = OrderPlaced from { order }
     Bus.publish(evt)
     return Ok(order)
   }
@@ -264,4 +266,4 @@ Before declaring a model done, confirm:
 - [ ] **Features cover the behaviour** — one `feature` per acceptance scenario, each `for` a real
   node, given/when/then in order, steps phrased as observable behaviour.
 - [ ] **Spec-faithful syntax** — names are fully qualified or aliased; visibility is correct; nothing
-  uses a form `references/LANG.md` doesn't define.
+  uses a form the language reference (`pds lang`) doesn't define.

.github/workflows/test.yml

@@ -0,0 +1,72 @@
+name: test
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: test-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  rust:
+    name: Rust (fmt, clippy, test)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+      - uses: Swatinem/rust-cache@v2
+      # The dependency-install tests shell out to `git commit`, which needs an
+      # author identity the bare runner lacks.
+      - name: Configure git identity for tests
+        run: |
+          git config --global user.email "ci@flying-dice.test"
+          git config --global user.name "pseudoscript CI"
+      - run: cargo fmt --all --check
+      - run: cargo clippy --workspace --all-targets -- -D warnings
+      - run: cargo test --workspace
+
+  web:
+    name: Web IDE (vitest, build, e2e, storybook)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: web-ide
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: web-ide/package-lock.json
+      - run: npm ci
+      # The wasm bundle is vendored under src/lib/pds-wasm, so no Rust build here.
+      - run: npm run check
+      - run: npm run test
+      - run: npm run build
+      - run: npx playwright install --with-deps chromium
+      - run: npm run test:e2e
+      - run: npm run build-storybook
+
+  landing:
+    name: Landing (svelte-check, build)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: web-landing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: web-landing/package-lock.json
+      - run: npm ci
+      - run: npm run check
+      - run: npm run build

.gitignore

@@ -3,3 +3,4 @@ target/
 .DS_Store
 .idea/
 .playwright-mcp/
+node_modules/

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What this repository is
 
-This is the specification for **PseudoScript** (file extension `.pds`), an architecture-modeling language where the model *is* the source: it reads like high-level pseudocode, expresses C4-style structure (system / container / component / person), and compiles to SVG diagrams. The deliverable right now is the **spec and its conformance suite**, not an implementation — the Rust crate is a stub (`crates/pseudoscript/src/main.rs` prints "Hello, world!"). Most work here is writing and refining spec prose, conformance cases, and decision records.
+This is the specification for **PseudoScript** (file extension `.pds`), an architecture-modeling language where the model *is* the source: it reads like high-level pseudocode, expresses C4-style structure (system / container / component / person), and compiles to SVG diagrams. The **spec and its conformance suite lead**: `LANG.md` and the cases under `CONFORMANCE/` are the source of truth, and expected outputs are hand-written, never copied from the implementation. The toolchain is now implemented — a Cargo workspace under `crates/` (lexer/parser, model/checker, formatter, diagram emitter, doc-site generator, LSP) driven by the `pds` binary — but it follows the spec, not the other way round. Much of the work here is still writing and refining spec prose, conformance cases, and decision records.
 
 ## Source of truth and its layers
 
@@ -36,4 +36,13 @@ A `PreToolUse` hook in `.claude/settings.json` **denies any `git commit`** until
 
 ## Rust crate
 
-A Cargo workspace (`resolver = "3"`, edition 2024) with one member, `crates/pseudoscript`, whose binary is named `pds`. Standard commands: `cargo build`, `cargo test`, `cargo run -p pseudoscript`, `cargo test <name>` for a single test. The implementation is not started; when writing Rust, the `idiomatic-rust` skill is required.
+A Cargo workspace (`resolver = "3"`, edition 2024) with several members under `crates/` — `pseudoscript-syntax` (lexer/parser), `pseudoscript-model` (resolution + checks), `pseudoscript-format`, `pseudoscript-emit` (diagrams), `pseudoscript-doc`, `pseudoscript-lsp` / `pseudoscript-lsp-core`, `pseudoscript-wasm` — plus `crates/pseudoscript`, whose binary is `pds`. Standard commands: `cargo build`, `cargo test`, `cargo test -p pseudoscript <name>` for a single test. The `pds` binary wraps the libraries: `check`/`eval` (diagnostics — `eval` reads stdin so an agent can check a snippet without a file), `fmt`, `tokens`, `doc`, `outline`, `svg`, `lsp`, `lang`/`skill`, and the `add`/`install`/`update` dependency commands. When writing Rust, the `idiomatic-rust` skill is required.
+
+## One LSP API, two transports — do not fork it
+
+Language intelligence has a single source of truth: **`crates/pseudoscript-lsp-core`** — transport-neutral `text + position -> lsp_types value` handlers (completion, hover, definition, references, semantic tokens, folding, symbols, diagnostics, formatting). It depends on `pseudoscript-model` + the standalone `lsp-types` (pinned to tower-lsp 0.20's `=0.94.1`, WASM-safe), **not** `tower-lsp`. Two thin edges share it:
+
+- **`crates/pseudoscript-lsp`** — the stdio server (`server.rs` + `workspace.rs`): tower-lsp transport over `lsp-core`. What native editors (e.g. `pseudoscript-jetbrains`) get.
+- **`crates/pseudoscript-wasm`** — the browser bridge: each language export calls the same `lsp-core` handler and serialises its `lsp_types` result to JSON, so the WASM API is byte-for-byte the LSP API. The web IDE (`web-ide/src/lib/pds.js` + `pseudoscript-language.js`) is an LSP client — it decodes delta-encoded semantic tokens, integer `CompletionItemKind`, line-based `FoldingRange`, Markdown `Hover`. `definition`/`references` stay WASM-ergonomic (fqn-based, with previews) because LSP `Location` is URL-centric and the browser has no file URLs; they still route through `model::resolve`, so no logic forks. Diagram/doc exports (`emit_scene`, `symbol_scene`, …) are WASM-only — no LSP equivalent.
+
+To change a language feature, edit it once in `lsp-core` (or its `model` primitive). After a *wasm-exported* surface changes, rebuild: `npm run build:wasm` in `web-ide`, then commit the regenerated `pds-wasm/` artifacts. Highlight **colours** and pure editor UX stay client-side.

CONFORMANCE/generation/9-sequence.pds

@@ -16,7 +16,7 @@ public container Inventory for Shop;
 public container Orders for Shop {
   #[manual]
   public Place(order: Order): Result<Order, Rejected> {
-    r = Inventory.reserve(order)
+    r: Result<Order, Rejected> = Inventory.reserve(order)
     if (r.isErr) {
       return Err(r.error)
     }

CONFORMANCE/static/0-ok-worked-example.pds

@@ -16,7 +16,7 @@ public system Banking;
 
 public container Mainframe for Banking {
   public GetBankingInfo(id: number): Result<BankingInfo, NotFound> {
-    r = AccountStore::Repository.fetch(id)
+    r: Result<BankingInfo, NotFound> = AccountStore::Repository.fetch(id)
     if (r.isErr) {
       return Err(r.error)
     }

CONFORMANCE/static/5-missing-return.pds

@@ -10,7 +10,7 @@ public system Banking;
 
 public container Mainframe for Banking {
   Get(): Result<Info, Missing> {
-    r = self.Fetch()
+    r: Result<Info, Missing> = self.Fetch()
     if (r.isErr) {
       return Err(r.error)
     }

CONFORMANCE/static/6-accessor-on-non-optional.diagnostics

@@ -0,0 +1 @@
+no field `isSome` on `Ref`; `.isSome` is an `Option` accessor (§6.2) — type the value `Option<Ref>` to use it

CONFORMANCE/static/6-accessor-on-non-optional.pds

@@ -0,0 +1,18 @@
+// LANG.md §6.2: `.isSome` is an `Option` accessor. `mv` is a plain record, not
+// an `Option`, so the read names no field — the diagnostic points at typing the
+// value `Option<...>`.
+
+//! example
+
+public data Ref { id: number }
+
+public system S;
+
+public container C for S {
+  pick(mv: Ref): number {
+    if (mv.isSome) {
+      return 1
+    }
+    return 0
+  }
+}

CONFORMANCE/static/6-call-method-on-data-value.diagnostics

@@ -0,0 +1 @@
+no method `doThing` on `Conv`

CONFORMANCE/static/6-call-method-on-data-value.pds

@@ -0,0 +1,13 @@
+// LANG.md §6: a `.name(args)` call's member MUST exist on the receiver's type.
+// `c` is a `Conv` record (fields only); a `data` value has no callables, so any
+// method call on one is rejected.
+
+//! example
+
+public data Conv { id: uuid }
+
+public system S;
+
+public container C for S {
+  run(c: Conv): void { c.doThing() }
+}

CONFORMANCE/static/6-call-unknown-method-on-node.diagnostics

@@ -0,0 +1 @@
+no method `nope` on `Store`

CONFORMANCE/static/6-call-unknown-method-on-node.pds

@@ -0,0 +1,16 @@
+// LANG.md §6: a `.name(args)` call's member MUST exist on the receiver's type.
+// `Store` resolves to a component node; `nope` is not one of its callables.
+
+//! example
+
+public system S;
+
+public container Db for S;
+
+public component Store for Db {
+  get(): void;
+}
+
+public container C for S {
+  run(): void { Store.nope() }
+}

CONFORMANCE/static/6-option-value-on-none.pds

@@ -10,7 +10,7 @@ public system Registry;
 
 public container Directory for Registry {
   public find(id: number): Option<Person> {
-    o = self.lookup(id)
+    o: Option<Person> = self.lookup(id)
     if (o.isNone) {
       return Some(o.value)
     }

CONFORMANCE/static/6-result-wrong-accessor.pds

@@ -11,7 +11,7 @@ public system Banking;
 
 public container Mainframe for Banking {
   public GetBankingInfo(id: number): Result<BankingInfo, NotFound> {
-    r = AccountStore::Repository.fetch(id)
+    r: Result<BankingInfo, NotFound> = AccountStore::Repository.fetch(id)
     if (r.isErr) {
       return Err(r.value)
     }

CONFORMANCE/static/6-void-as-value.diagnostics

@@ -0,0 +1 @@
+unresolved reference `void`; `void` is a type, not a value — a void result returns bare `Ok` (§6.1)

CONFORMANCE/static/6-void-as-value.pds

@@ -0,0 +1,15 @@
+// LANG.md §6.1: `void` is a type, not a value. A void-returning callable returns
+// with a bare `Ok`; `Ok(void)` reads `void` as a value, which resolves to no
+// parameter, binding, node, alias, or variant.
+
+//! example
+
+public data Failure { reason: string }
+
+public system S;
+
+public container C for S {
+  run(): Result<void, Failure> {
+    return Ok(void)
+  }
+}

CONFORMANCE/static/7-1-binding-type-mismatch.diagnostics

@@ -0,0 +1 @@
+binding `n` is annotated `number` but its value is `string`

CONFORMANCE/static/7-1-binding-type-mismatch.pds

@@ -0,0 +1,12 @@
+// LANG.md §7.1 (ADR-027): a binding's annotation must match a determinable
+// initialiser. A `number`-annotated binding initialised with a string literal
+// is rejected.
+
+//! example
+
+public system S;
+public container C for S {
+  run(): void {
+    n: number = ""
+  }
+}

CONFORMANCE/static/7-rebind-rejected.pds

@@ -9,8 +9,8 @@ public system Banking;
 
 public container Mainframe for Banking {
   Run(): void {
-    r = self.Make()
-    r = self.Make()
+    r: Info = self.Make()
+    r: Info = self.Make()
   }
   Make(): Info;
 }

CONFORMANCE/syntax/3-option.pds

@@ -10,7 +10,7 @@ public system Registry;
 public container Directory for Registry {
   /// The optional person on file for an id.
   public find(id: number): Option<Person> {
-    o = self.lookup(id)
+    o: Option<Person> = self.lookup(id)
     if (o.isNone) {
       return None
     }

CONFORMANCE/syntax/7-1-untyped-assignment-rejected.reject

@@ -0,0 +1,10 @@
+// LANG.md §7.1 (ADR-027): a binding states its type. An unannotated
+// `x = Expr` no longer parses.
+
+public system S;
+public container C for S {
+  run(): void {
+    x = self.make()
+  }
+  make(): number;
+}

CONFORMANCE/syntax/7-1-untyped-assignment-rejected.reject.expected

@@ -0,0 +1 @@
+assignment requires a type annotation: write `name: Type = …`

CONFORMANCE/syntax/7-chaining.pds

@@ -7,7 +7,7 @@ data Info { owner: string }
 
 public container Mainframe for Banking {
   Run(): void {
-    a = Store::Repo.fetch(1).value.owner
-    b = self.Pick().first().tag
+    a: string = Store::Repo.fetch(1).value.owner
+    b: string = self.Pick().first().tag
   }
 }

CONFORMANCE/syntax/7-from-labelled-source.reject

@@ -0,0 +1,14 @@
+// LANG.md §7.2: a `from` source set holds bare references (bindings, field
+// accesses, or calls), separated by `,` and closed by `}`. A `key: value`
+// label is not a source — `data` is never constructed with field values
+// (ADR-003) — so the `:` is rejected at the source set.
+
+//! example
+
+public data Thing { name: string }
+
+public system S;
+
+public container C for S {
+  make(): Thing { return Thing from { name: "x" } }
+}

CONFORMANCE/syntax/7-from-labelled-source.reject.expected

@@ -0,0 +1 @@
+`from` takes bare references, not `field: value` — bind the value to a name and list the name (§7.2)

CONFORMANCE/syntax/7-statements.pds

@@ -8,13 +8,13 @@ data BankingInfo { id: number }
 
 public container Mainframe for Banking {
   Run(): void {
-    a = Foo.getThing()
-    b = Bar.getOther()
-    c = BankingInfo from { a, b }
+    a: Result<BankingInfo, void> = Foo.getThing()
+    b: BankingInfo = Bar.getOther()
+    c: BankingInfo = BankingInfo from { a, b }
     if (a.isErr) {
       return
     } else {
-      x = a.value
+      x: BankingInfo = a.value
     }
     while (cond) {
       self.step()