@fossil-lang/wasm 0.3.0-alpha.2 → 0.3.0-alpha.20

package/README.md

@@ -2,51 +2,119 @@
 
 JS/TS wrapper around the `fossil-wasm` Rust crate's wasm-bindgen artefacts. Provides:
 
-- `initFossilWasm({ wasmUrl })` — consumer-controlled `.wasm` URL loader (memoised).
-- `tokenize(text)` — calls the Rust lexer, returns `TokenRow[]` (ADR-0030).
-- `semanticLegend()` — returns the LSP semantic-tokens legend (Phase 6 plan 06-07).
-- `FossilPlayground` — the Workspace API class (ADR-0024) for LSP + compile.
+- `openProgram(uri, { host, text })` — one program open for an editor, and the
+  call a host with an editor makes. See below.
+- `initFossilWasm()` — boots the module, within 60 s (`module/unreachable` when it
+  cannot be fetched); a boot that failed is forgotten, so the next call tries again. Its `.wasm` ships in this
+  package and the host's bundler emits it as an asset; the host copies nothing.
+- `tokenize(text)` — calls the Rust lexer, returns `TokenRow[]`. The Rust lexer
+  is the only lexer: no host reimplements one and drifts from the grammar.
+- `FossilWorkspace` — the Workspace API class for LSP + compile. `fossil-lsp`
+  itself is native-only (stdio over crossbeam), so the browser gets this
+  equivalent dispatch surface over the same `fossil-ide` functions.
+
+## One program in one editor: `openProgram`
 
-## Why explicit `init({ wasmUrl })` and not auto-load?
+```typescript
+import { openProgram } from '@fossil-lang/wasm';
+import { fossil } from '@fossil-lang/codemirror-fossil';
 
-We use `wasm-bindgen --target web` (NOT `--target bundler`). This means consumers
-control the `.wasm` URL resolution — works in Vite, Next.js, Webpack, Rspack, or
-plain `new URL(...)` in a Web Worker context. See `08-RESEARCH.md` Pitfall 1
-(this monorepo's phase-8 research) for why `--target bundler` was rejected.
+const program = await openProgram('job.fossil', { host, text });   // host: Host
+const extensions = fossil({ ...program, onNavigate });
 
-## Consumer patterns
+program.registerDescriptor(descriptor);        // a host-introspected source, before a check
+const sources = await program.sources(text);   // what introspection DESCRIBEs
+```
 
-### Vite host
+It boots the module, opens `uri` in its own workspace, and reads the documents
+the text names through `host`. The answer carries `fossil()`'s option names —
+`uri`, `tokenize`, `tokenKinds`, `check`, `hover`, `complete`, `definition` —
+and every one that answers about the program takes the text and pushes it
+first, comparing against what it last pushed so the common case costs a string
+comparison. `check` and `sources` also run `resolveDocuments`, which reads
+nothing when nothing is missing. That is the whole protocol an editor host used
+to write by hand; `workspace` is the `FossilWorkspace` underneath, for a
+question this surface does not ask, and `close()` frees it.
+
+## Documents and sources: fossil resolves, the host reads
+
+A program names shape documents (`io.shex("@vocab/person.shex")`) and data
+sources (`io.csv("@lake/users.csv")`). The checker reads no file and no
+network: it reports what it is missing, and `resolveDocuments`
+(`@fossil-lang/storage`) reads it under the credentials the `Host`
+(`@fossil-lang/types`) vends — `connections()` and `credentials(scope, access)`.
+A document under a connection is read by a GET signed with that connection's
+`read` credential; one with no connection only when it is a public `http(s)` URL.
+A host that already holds a document's text calls `registerDocument` itself.
 
 ```typescript
-import { initFossilWasm, tokenize } from '@fossil-lang/wasm';
-import wasmUrl from '@fossil-lang/wasm/pkg/fossil_wasm_bg.wasm?url';
+import { resolveDocuments } from '@fossil-lang/storage';
 
-await initFossilWasm({ wasmUrl });
-const tokens = tokenize('prefix ex: <https://example.org/>');
+const ws = new FossilWorkspace();
+const h = ws.openFile('prog.fossil', text); // edited buffers only
+const { unread } = await resolveDocuments(ws.workspace(h), host); // sets the connections too
+const rows = ws.check();
 ```
 
-### Next.js host (in a Client Component)
+- `missingDocuments(h)` — `{ key, locator, connection? }` rows. The key is what
+  the program wrote, so repointing a connection invalidates nothing; the locator
+  is that key through the map, and `connection` is the one it goes through.
+- `registerDocument(key, text)` — what `resolveDocuments` calls for each
+  fetched document, until nothing new is missing (a document can name another).
+  It is the one loop; a host does not write a second.
+- `openFile` is for buffers the user edits. An open `.shex` is the document
+  every program naming it reads; opening a program registers nothing it names.
+- `setConnections(map)` — name → base; re-checks nothing. `resolveDocuments`
+  calls it with `host.connections()`, so a host never does.
+- `sources(h)` — the `ProgramSource[]` the program reads, through the map the
+  last `resolveDocuments` set: binding, key,
+  locator, connection, catalogue row, reader option. Introspection DESCRIBEs these and
+  registers each descriptor under `key` with `registerInferredDescriptor`.
+
+## Loading: the `.wasm` is an asset of this package
 
 ```typescript
-'use client';
 import { initFossilWasm, tokenize } from '@fossil-lang/wasm';
 
-// Put fossil_wasm_bg.wasm in public/wasm/ at build time (next.config.mjs copies it)
-useEffect(() => {
-  void initFossilWasm({ wasmUrl: '/wasm/fossil_wasm_bg.wasm' });
-}, []);
+await initFossilWasm();
+const tokens = tokenize('User := io.csv("data/people.csv")');
 ```
 
-### Web Worker
+That is the whole host flow, in Vite, Next.js (webpack or Turbopack), a Web
+Worker or any bundler that understands `new URL('…', import.meta.url)`. The glue
+(`wasm-bindgen --target web`) locates `fossil_wasm_bg.wasm` with exactly that
+expression, the bundler copies the file into its output under a hashed name and
+rewrites the URL, and the browser fetches it from there. No copy script, no
+`public/` directory, no URL to keep in sync with a version.
+
+**Vite dev server, package installed from npm:** Vite's dependency optimizer
+pre-bundles the package into `node_modules/.vite/deps/` without its `.wasm`, and
+the URL then answers with `index.html`. Keep the three packages out of it —
+`vite build` needs nothing:
+
+```js
+// vite.config.js
+export default { optimizeDeps: { exclude: ['@fossil-lang/wasm', '@fossil-lang/executor', '@fossil-lang/corpus'] } };
+```
+
+A workspace-linked package is never pre-bundled, which is why a host inside this
+repository would need no such line. Next.js needs none in either `next dev` or `next build`, webpack or
+Turbopack.
+
+`--target bundler` was rejected because it emits `import … from '*.wasm'` (the
+ESM-integration proposal), which each bundler gates behind its own experimental
+flag. `new URL(…, import.meta.url)` is the pattern they all support by default.
+
+**Without a bundler**, pass the module yourself — `initFossilWasm(wasm)` takes the
+glue's `InitInput` (`BufferSource`, `Response`, `URL`, `WebAssembly.Module`). Node
+is the case: its `fetch` rejects `file://`, so hand it the bytes:
 
 ```typescript
-// inside a Worker module:
-import { initFossilWasm, FossilPlayground } from '@fossil-lang/wasm';
-import wasmUrl from '@fossil-lang/wasm/pkg/fossil_wasm_bg.wasm?url';
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
 
-await initFossilWasm({ wasmUrl });
-const pg = new FossilPlayground();
+const path = createRequire(import.meta.url).resolve('@fossil-lang/wasm/pkg/fossil_wasm_bg.wasm');
+await initFossilWasm(await readFile(path));
 ```
 
 ## Build
@@ -63,8 +131,6 @@ Optionally `wasm-opt` (binaryen) for size reduction.
 
 ## Source of truth
 
-- Rust crate: `crates/fossil-wasm/`
-- tokenize ADR: `decisions/0030-wasm-exported-tokenizer.md`
-- Workspace API ADR: `decisions/0024-fossil-wasm-workspace-api.md`
-- Distribution pattern: `decisions/0028-playground-as-react-library.md`
-  (this package is one of the six in the `@fossil-lang/*` family)
+- Rust crate: `crates/fossil-wasm/` — everything here is a wrapper over its
+  wasm-bindgen exports, and nothing in this package reimplements it.
+- The grammar the tokenizer follows: `grammar.bnf` at the repo root.

package/dist/client.d.ts

@@ -0,0 +1,206 @@
+/**
+ * The wasm-bindgen-backed runtime surface (lexer, LSP worker, Workspace API) of
+ * @fossil-lang/wasm.
+ *
+ * Kept in its OWN module (NOT the package entry) so the wasm-bindgen glue
+ * (`../pkg/fossil_wasm.js`) is imported only from leaf modules — `load.ts` (for
+ * `init`) and here. Under a bundler with `"sideEffects": false`, importing the
+ * stateful glue from the entry chunk can duplicate it: `init()` then populates
+ * the `wasm` binding in one instance while these functions read `undefined` from
+ * another (→ `Cannot read properties of undefined (reading '__wbindgen_malloc…')`,
+ * seen when the codemirror tokenizer calls `tokenize` on the main thread).
+ * Mirrors `@fossil-lang/corpus`'s `client.ts` split, the known-good shape.
+ */
+import { FileHandle as RawFileHandle } from '../pkg/fossil_wasm.js';
+import type { DocumentWorkspace, MissingDocument, ProgramSource, TokenKindLegend, TokenRow } from '@fossil-lang/types';
+import type { CheckRow, CompletionRow, DefinitionRow, HoverRow, InferredDescriptorJson, SemanticTokenRow, SourceRefInfo, ProviderInfo } from './index.js';
+/**
+ * Opaque file-handle returned by {@link FossilWorkspace.openFile}. Pass it
+ * back into the matching `updateFile` / `closeFile` / `diagnosticsFor`
+ * calls. JS code cannot construct one directly (the wasm-bindgen class has a
+ * private constructor) — handles are minted only by `openFile` on the Rust
+ * side, where they index a `HashMap<FileHandle, SourceFile>` keyed by a `u32`.
+ */
+export type FileHandle = RawFileHandle;
+/**
+ * Tokenize a Fossil source string. Returns the byte-range tokens from the
+ * canonical Rust lexer (`fossil_syntax::lexer::raw_lex`) — the single grammar
+ * source of truth, so no editor ever reimplements the lexer in TS and drifts.
+ *
+ * MUST be called after {@link initFossilWasm} has resolved; otherwise the
+ * underlying wasm-bindgen function throws (the wasm module is not yet
+ * instantiated).
+ */
+export declare function tokenize(text: string): TokenRow[];
+/**
+ * The legend for {@link TokenRow.kind}: every lexer variant NAME, indexed by the
+ * discriminant a row carries. `tokenKinds()[row.kind]` is `"Comment"`,
+ * `"KwFrom"`, `"String"`, …
+ *
+ * **This is the contract, and the numbers are not.** `kind` is a variant
+ * discriminant of `fossil_syntax::lexer::Token`, so any reorder of that enum
+ * remaps every value with nothing going red. The predecessor of this package
+ * hard-coded the table (`enum FossilKind { Whitespace = 0, … }`) under a comment
+ * saying it had to be updated in lockstep; it was wrong in nine places by the
+ * time it was deleted. Keying on the name is what makes a reorder a non-event.
+ *
+ * An index past the end of the legend is a variant appended by a compiler newer
+ * than this host: `undefined`, and a host styles it as plain text.
+ *
+ * MUST be called after {@link initFossilWasm} has resolved.
+ */
+export declare function tokenKinds(): TokenKindLegend;
+/**
+ * Parse a Fossil program and return its external references — the typed lineage
+ * (every data URI + `schema =` argument, each tagged with its `@conn` alias and
+ * role). keasy's client-compute job runner reads this to derive a job's
+ * connections WITHOUT subprocessing `fossil` / a server round-trip. Identical
+ * shape to the native `fossil refs` (the SAME `fossil_lineage::SourceRefInfo`
+ * struct), so the browser and the CLI never diverge.
+ *
+ * MUST be called after {@link initFossilWasm} has resolved.
+ */
+export declare function refs(program: string): SourceRefInfo[];
+/**
+ * List the data-source providers fossil supports (`io.csv`, `io.rdf`, …) — the
+ * provider name, the extensions it reads, and how it can be used. Identical
+ * shape to the native `fossil providers`.
+ *
+ * MUST be called after {@link initFossilWasm} has resolved.
+ */
+export declare function providers(): ProviderInfo[];
+/**
+ * Workspace API class. Thin TS wrapper around the wasm-bindgen
+ * `FossilWorkspace` that exposes camelCase method names for JS idiom + better
+ * TS inference (the raw bindings use snake_case from the Rust impl block).
+ *
+ * One instance per browser tab / Node process — the instance owns the Salsa
+ * store + `Arc<OutputDescriptorKind>` for the schema slot.
+ *
+ * NOTE: {@link FileHandle} is opaque — JS cannot construct one. Callers receive
+ * a handle from `openFile` and pass it back to subsequent operations.
+ */
+export declare class FossilWorkspace {
+    private _inner;
+    constructor();
+    /**
+     * Free the underlying WASM-side Salsa store. Call when the workspace is no
+     * longer needed (e.g. component unmount).
+     */
+    free(): void;
+    /**
+     * Open a file in the workspace. Returns the {@link FileHandle} subsequent
+     * `updateFile` / `closeFile` / `diagnosticsFor` calls key on.
+     */
+    openFile(path: string, contents: string): FileHandle;
+    /**
+     * Apply an edit to an open file. Mutates the SAME `SourceFile` via the Salsa
+     * `Setter` (`set_text`) — bumps the revision for incremental
+     * invalidation rather than a full recompute, and that revision bump is also
+     * what cancels any analysis still running on an older snapshot.
+     */
+    updateFile(handle: FileHandle, contents: string): void;
+    /**
+     * Close a file in the workspace. Strict: closing an unknown / already-closed
+     * handle throws so JS-side bugs surface loudly.
+     */
+    closeFile(handle: FileHandle): void;
+    /**
+     * The connection map `@name/…` expands against — what
+     * `Host.connections()` answers. It reaches locators only, so setting it
+     * re-checks nothing.
+     */
+    setConnections(connections: Record<string, string>): void;
+    /**
+     * The documents the file at `handle` names and nothing has registered, each
+     * with the key to register it under and the locator to read it from.
+     */
+    missingDocuments(handle: FileHandle): MissingDocument[];
+    /** Register a fetched document's text under the key {@link missingDocuments} reported. */
+    registerDocument(key: string, text: string): void;
+    /**
+     * The data sources the file at `handle` reads, as fossil resolved them: the
+     * binding, the URI as written, its locator through the connection map, the
+     * catalogue row and the reader option.
+     */
+    sources(handle: FileHandle): ProgramSource[];
+    /**
+     * The file at `handle` as a {@link DocumentWorkspace}, for
+     * `resolveDocuments(workspace.workspace(handle), host)`.
+     */
+    workspace(handle: FileHandle): DocumentWorkspace;
+    /**
+     * Workspace-wide diagnostic drain. Runs `parse → def_map → typecheck_mapping`
+     * across every open file and returns a flat array of {@link CheckRow}.
+     */
+    check(): CheckRow[];
+    /**
+     * Per-file diagnostic drain: one file's rows of {@link check}.
+     */
+    diagnosticsFor(handle: FileHandle): CheckRow[];
+    /**
+     * What is under the cursor — `{ markdown, range }`, or `null` when nothing
+     * there has a type.
+     *
+     * `line` / `character` are LSP: zero-based, `character` in UTF-16 code units.
+     * A CodeMirror or Monaco host already counts in those units, so a document
+     * offset converts with `doc.lineAt(pos)` and no byte arithmetic — unlike
+     * {@link tokenize}, whose offsets ARE bytes.
+     *
+     * ## Push the buffer before you ask
+     *
+     * This reads the text of the last {@link updateFile}. Hover fires on
+     * mouse-move and the checker is debounced, so a hover mid-debounce answers
+     * about text one keystroke old and its range lands one keystroke wrong. The
+     * three read-only methods take a SHARED borrow on the Rust side and cannot
+     * poison the workspace the way a re-entered `updateFile` once could — see the
+     * `ide` module in `crates/fossil-wasm` — but staleness is not a borrow
+     * problem and nothing here can fix it for you.
+     */
+    hover(handle: FileHandle, line: number, character: number): HoverRow | null;
+    /**
+     * The completion candidates at a position, already narrowed by the receiver:
+     * `str.` offers string members and no reader, a property-key position offers
+     * the target shape's predicates and no catalogue row at all.
+     *
+     * `kind` is the LSP `CompletionItemKind` **by name** (`"function"`,
+     * `"field"`) rather than by number. The numbers never cross this boundary —
+     * `packages/codemirror-fossil`'s deleted predecessor is what happens when
+     * they do.
+     *
+     * The same staleness note as {@link hover} applies, and harder: completion
+     * fires on nearly every keystroke.
+     */
+    completions(handle: FileHandle, line: number, character: number): CompletionRow[];
+    /**
+     * Where the name under the cursor is defined. Empty when nothing there has a
+     * definition.
+     *
+     * `uri` is the key the buffer was opened under, verbatim — and two of the
+     * four positions this recognises resolve into the **shape document**, so a
+     * host with a single editor pane has to read `uri` before it moves a cursor.
+     */
+    gotoDefinition(handle: FileHandle, line: number, character: number): DefinitionRow[];
+    /**
+     * Every classified span of the file at `handle`, in source order — the
+     * semantic layer an editor lays over {@link tokenize}'s lexical one. Ranges
+     * are LSP (UTF-16), like {@link hover}'s, and the same staleness note
+     * applies: push the buffer before you ask.
+     */
+    semanticTokens(handle: FileHandle): SemanticTokenRow[];
+    /**
+     * Register an {@link InferredDescriptorJson} under the source URI the program
+     * wrote, BEFORE invoking {@link check}. The Rust compiler reads from this
+     * during forward type propagation.
+     *
+     * The compiler never introspects a source itself: it performs no network or
+     * file IO — that would break the WASM gate and Salsa's determinism alike —
+     * so a host that wants column types must run the `DESCRIBE` and push the
+     * result in here.
+     *
+     * @throws {FossilError} `api/invalid-argument` if the descriptor fails to deserialise on the Rust
+     *   side, the `serde_json` error as its cause.
+     */
+    registerInferredDescriptor(descriptor: InferredDescriptorJson): void;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAEL,UAAU,IAAI,aAAa,EAK5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,eAAe,EACf,QAAQ,EACT,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,QAAQ,EACR,aAAa,EACb,aAAa,EACb,QAAQ,EACR,sBAAsB,EACtB,gBAAgB,EAChB,aAAa,EACb,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,aAAa,CAAC;AAEvC;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE,CAMjD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,IAAI,eAAe,CAE5C;AAED;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,EAAE,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,IAAI,YAAY,EAAE,CAE1C;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAqB;;IAMnC;;;OAGG;IACH,IAAI,IAAI,IAAI;IAIZ;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU;IAIpD;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAItD;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAInC;;;;OAIG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAIzD;;;OAGG;IACH,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,eAAe,EAAE;IAIvD,0FAA0F;IAC1F,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIjD;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,EAAE;IAI5C;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,iBAAiB;IAQhD;;;OAGG;IACH,KAAK,IAAI,QAAQ,EAAE;IAInB;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,QAAQ,EAAE;IAI9C;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAM3E;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,EAAE;IAIjF;;;;;;;OAOG;IACH,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,EAAE;IAIpF;;;;;OAKG;IACH,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,gBAAgB,EAAE;IAItD;;;;;;;;;;;;OAYG;IACH,0BAA0B,CAAC,UAAU,EAAE,sBAAsB,GAAG,IAAI;CAKrE"}

package/dist/client.js

@@ -0,0 +1,250 @@
+/**
+ * The wasm-bindgen-backed runtime surface (lexer, LSP worker, Workspace API) of
+ * @fossil-lang/wasm.
+ *
+ * Kept in its OWN module (NOT the package entry) so the wasm-bindgen glue
+ * (`../pkg/fossil_wasm.js`) is imported only from leaf modules — `load.ts` (for
+ * `init`) and here. Under a bundler with `"sideEffects": false`, importing the
+ * stateful glue from the entry chunk can duplicate it: `init()` then populates
+ * the `wasm` binding in one instance while these functions read `undefined` from
+ * another (→ `Cannot read properties of undefined (reading '__wbindgen_malloc…')`,
+ * seen when the codemirror tokenizer calls `tokenize` on the main thread).
+ * Mirrors `@fossil-lang/corpus`'s `client.ts` split, the known-good shape.
+ */
+import { FossilWorkspace as RawFossilWorkspace, FileHandle as RawFileHandle, tokenize as rawTokenize, tokenKinds as rawTokenKinds, refs as rawRefs, providers as rawProviders, } from '../pkg/fossil_wasm.js';
+/**
+ * Tokenize a Fossil source string. Returns the byte-range tokens from the
+ * canonical Rust lexer (`fossil_syntax::lexer::raw_lex`) — the single grammar
+ * source of truth, so no editor ever reimplements the lexer in TS and drifts.
+ *
+ * MUST be called after {@link initFossilWasm} has resolved; otherwise the
+ * underlying wasm-bindgen function throws (the wasm module is not yet
+ * instantiated).
+ */
+export function tokenize(text) {
+    // The wasm-bindgen wrapper returns a `JsValue` typed as `any`; the Rust side
+    // (crates/fossil-wasm/src/tokenize.rs) serializes `Vec<TokenRow>` via
+    // `serde_wasm_bindgen::to_value`, so the shape matches `{ kind, start, end }`
+    // exactly. Cast is safe because the Rust ↔ JS contract is enforced upstream.
+    return rawTokenize(text);
+}
+/**
+ * The legend for {@link TokenRow.kind}: every lexer variant NAME, indexed by the
+ * discriminant a row carries. `tokenKinds()[row.kind]` is `"Comment"`,
+ * `"KwFrom"`, `"String"`, …
+ *
+ * **This is the contract, and the numbers are not.** `kind` is a variant
+ * discriminant of `fossil_syntax::lexer::Token`, so any reorder of that enum
+ * remaps every value with nothing going red. The predecessor of this package
+ * hard-coded the table (`enum FossilKind { Whitespace = 0, … }`) under a comment
+ * saying it had to be updated in lockstep; it was wrong in nine places by the
+ * time it was deleted. Keying on the name is what makes a reorder a non-event.
+ *
+ * An index past the end of the legend is a variant appended by a compiler newer
+ * than this host: `undefined`, and a host styles it as plain text.
+ *
+ * MUST be called after {@link initFossilWasm} has resolved.
+ */
+export function tokenKinds() {
+    return rawTokenKinds();
+}
+/**
+ * Parse a Fossil program and return its external references — the typed lineage
+ * (every data URI + `schema =` argument, each tagged with its `@conn` alias and
+ * role). keasy's client-compute job runner reads this to derive a job's
+ * connections WITHOUT subprocessing `fossil` / a server round-trip. Identical
+ * shape to the native `fossil refs` (the SAME `fossil_lineage::SourceRefInfo`
+ * struct), so the browser and the CLI never diverge.
+ *
+ * MUST be called after {@link initFossilWasm} has resolved.
+ */
+export function refs(program) {
+    return rawRefs(program);
+}
+/**
+ * List the data-source providers fossil supports (`io.csv`, `io.rdf`, …) — the
+ * provider name, the extensions it reads, and how it can be used. Identical
+ * shape to the native `fossil providers`.
+ *
+ * MUST be called after {@link initFossilWasm} has resolved.
+ */
+export function providers() {
+    return rawProviders();
+}
+/**
+ * Workspace API class. Thin TS wrapper around the wasm-bindgen
+ * `FossilWorkspace` that exposes camelCase method names for JS idiom + better
+ * TS inference (the raw bindings use snake_case from the Rust impl block).
+ *
+ * One instance per browser tab / Node process — the instance owns the Salsa
+ * store + `Arc<OutputDescriptorKind>` for the schema slot.
+ *
+ * NOTE: {@link FileHandle} is opaque — JS cannot construct one. Callers receive
+ * a handle from `openFile` and pass it back to subsequent operations.
+ */
+export class FossilWorkspace {
+    _inner;
+    constructor() {
+        this._inner = new RawFossilWorkspace();
+    }
+    /**
+     * Free the underlying WASM-side Salsa store. Call when the workspace is no
+     * longer needed (e.g. component unmount).
+     */
+    free() {
+        this._inner.free();
+    }
+    /**
+     * Open a file in the workspace. Returns the {@link FileHandle} subsequent
+     * `updateFile` / `closeFile` / `diagnosticsFor` calls key on.
+     */
+    openFile(path, contents) {
+        return this._inner.open_file(path, contents);
+    }
+    /**
+     * Apply an edit to an open file. Mutates the SAME `SourceFile` via the Salsa
+     * `Setter` (`set_text`) — bumps the revision for incremental
+     * invalidation rather than a full recompute, and that revision bump is also
+     * what cancels any analysis still running on an older snapshot.
+     */
+    updateFile(handle, contents) {
+        this._inner.update_file(handle, contents);
+    }
+    /**
+     * Close a file in the workspace. Strict: closing an unknown / already-closed
+     * handle throws so JS-side bugs surface loudly.
+     */
+    closeFile(handle) {
+        this._inner.close_file(handle);
+    }
+    /**
+     * The connection map `@name/…` expands against — what
+     * `Host.connections()` answers. It reaches locators only, so setting it
+     * re-checks nothing.
+     */
+    setConnections(connections) {
+        this._inner.setConnections(connections);
+    }
+    /**
+     * The documents the file at `handle` names and nothing has registered, each
+     * with the key to register it under and the locator to read it from.
+     */
+    missingDocuments(handle) {
+        return this._inner.missingDocuments(handle);
+    }
+    /** Register a fetched document's text under the key {@link missingDocuments} reported. */
+    registerDocument(key, text) {
+        this._inner.registerDocument(key, text);
+    }
+    /**
+     * The data sources the file at `handle` reads, as fossil resolved them: the
+     * binding, the URI as written, its locator through the connection map, the
+     * catalogue row and the reader option.
+     */
+    sources(handle) {
+        return this._inner.sources(handle);
+    }
+    /**
+     * The file at `handle` as a {@link DocumentWorkspace}, for
+     * `resolveDocuments(workspace.workspace(handle), host)`.
+     */
+    workspace(handle) {
+        return {
+            setConnections: (connections) => this.setConnections(connections),
+            missingDocuments: () => this.missingDocuments(handle),
+            registerDocument: (key, text) => this.registerDocument(key, text),
+        };
+    }
+    /**
+     * Workspace-wide diagnostic drain. Runs `parse → def_map → typecheck_mapping`
+     * across every open file and returns a flat array of {@link CheckRow}.
+     */
+    check() {
+        return this._inner.check();
+    }
+    /**
+     * Per-file diagnostic drain: one file's rows of {@link check}.
+     */
+    diagnosticsFor(handle) {
+        return this._inner.diagnostics_for(handle);
+    }
+    /**
+     * What is under the cursor — `{ markdown, range }`, or `null` when nothing
+     * there has a type.
+     *
+     * `line` / `character` are LSP: zero-based, `character` in UTF-16 code units.
+     * A CodeMirror or Monaco host already counts in those units, so a document
+     * offset converts with `doc.lineAt(pos)` and no byte arithmetic — unlike
+     * {@link tokenize}, whose offsets ARE bytes.
+     *
+     * ## Push the buffer before you ask
+     *
+     * This reads the text of the last {@link updateFile}. Hover fires on
+     * mouse-move and the checker is debounced, so a hover mid-debounce answers
+     * about text one keystroke old and its range lands one keystroke wrong. The
+     * three read-only methods take a SHARED borrow on the Rust side and cannot
+     * poison the workspace the way a re-entered `updateFile` once could — see the
+     * `ide` module in `crates/fossil-wasm` — but staleness is not a borrow
+     * problem and nothing here can fix it for you.
+     */
+    hover(handle, line, character) {
+        // `serde_wasm_bindgen` writes `None` as `undefined`; a host reading this
+        // should have one falsy answer to check, not two.
+        return this._inner.hover(handle, line, character) ?? null;
+    }
+    /**
+     * The completion candidates at a position, already narrowed by the receiver:
+     * `str.` offers string members and no reader, a property-key position offers
+     * the target shape's predicates and no catalogue row at all.
+     *
+     * `kind` is the LSP `CompletionItemKind` **by name** (`"function"`,
+     * `"field"`) rather than by number. The numbers never cross this boundary —
+     * `packages/codemirror-fossil`'s deleted predecessor is what happens when
+     * they do.
+     *
+     * The same staleness note as {@link hover} applies, and harder: completion
+     * fires on nearly every keystroke.
+     */
+    completions(handle, line, character) {
+        return this._inner.completions(handle, line, character);
+    }
+    /**
+     * Where the name under the cursor is defined. Empty when nothing there has a
+     * definition.
+     *
+     * `uri` is the key the buffer was opened under, verbatim — and two of the
+     * four positions this recognises resolve into the **shape document**, so a
+     * host with a single editor pane has to read `uri` before it moves a cursor.
+     */
+    gotoDefinition(handle, line, character) {
+        return this._inner.gotoDefinition(handle, line, character);
+    }
+    /**
+     * Every classified span of the file at `handle`, in source order — the
+     * semantic layer an editor lays over {@link tokenize}'s lexical one. Ranges
+     * are LSP (UTF-16), like {@link hover}'s, and the same staleness note
+     * applies: push the buffer before you ask.
+     */
+    semanticTokens(handle) {
+        return this._inner.semanticTokens(handle);
+    }
+    /**
+     * Register an {@link InferredDescriptorJson} under the source URI the program
+     * wrote, BEFORE invoking {@link check}. The Rust compiler reads from this
+     * during forward type propagation.
+     *
+     * The compiler never introspects a source itself: it performs no network or
+     * file IO — that would break the WASM gate and Salsa's determinism alike —
+     * so a host that wants column types must run the `DESCRIBE` and push the
+     * result in here.
+     *
+     * @throws {FossilError} `api/invalid-argument` if the descriptor fails to deserialise on the Rust
+     *   side, the `serde_json` error as its cause.
+     */
+    registerInferredDescriptor(descriptor) {
+        // The wasm-bindgen wrapper accepts a JSON string; serialise here so callers
+        // pass a typed object.
+        this._inner.registerInferredDescriptor(JSON.stringify(descriptor));
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}