Vlajmaji

(Re)Lojban dictionaries, schemas, libraries, and command-line tools

Vlajmaji is a growing dictionary workbench for exploring words, their sources, and the possibilities of combining them. Its aim is to bring multiple lexicons together without losing who said what, then make that material useful for language study, word creation, poetry, and song.

Current 0.3 development checkout

The capabilities below describe the current workspace checkout, not the published 0.2.0 packages. The latest published release is 0.2.0.

The Rust workspace already provides:

• A lexical archive that preserves source snapshots, raw records, provenance, and alternative assertions, keeping computed analyses and user proposals separate.
• A validated source registry for exact aliases, lineage, contributors, and attribution of preserved occurrences (guide).
• An immutable, versioned dictionary model with explicit source, owned, editorial, and computed evidence, plus an explicit legacy archive adapter (model guide, standards mapping limits).
• SQLite persistence for that dictionary model, with a minimum-header read-only open and separately requested schema, metadata, hash, model, foreign-key, and projection verification (schema guide).
• Source-grouped exact lookup with source selection, complete pre-page totals, occurrence-based paging, and stable local/catalogue reference resolution (query guide).
• Explicit immutable mixed workbench views over selected installed packs and an optional owned-journal revision, with Full/Compact queries bound to captured dependency identities and an additive named-profile refresh/history workflow, plus explicit Local/Catalog reference admission for direct and configured views. The current workspace also exposes literal reverse-definition and stored-Form queries with content-bound Form detail (integrated workbench guide).
• Six source-backed computed lexical query families—spelling distance, prosody, nuclei, contrast, components, and composition—plus separate caller-proposal identity and morphology-generation operations. Full and Compact results retain typed source evidence separately from derived analyses and generated values. The optional morphology feature gates Components and Generate.
• Rebuildable SQLite indexes and an optional Oxigraph backend for research comparisons.
• Exact and reverse-definition lookup, source-link traversal, spelling distance, and bounded phonological and prosodic filters.
• Optional compound decomposition and generation through latkerlo-jvotci.
• A JSON CLI, vlajmaji, including dictionary-build and dictionary-query alongside the existing archive/search commands. Grouped commands can use a default store under XDG data home or the standard HOME data directory, while the legacy archive commands remain explicit.
• An explicit local collection catalogue: collections register records source/reference metadata, while collections install builds one verified Unified generation. These commands do not configure the default store or select sources (collection guide).
• An explicit append-only journal for complete user-owned dictionaries, with persisted-head compare-and-swap and historical typed-state reconstruction (vlajmaji owned init|edit|head|history|show; see owned dictionary guide).
• An opt-in owned-curation sidecar for pinned context and reviewed Link/Sense records, explicit schema migration, and materialization to a separate normalized view (owned migrate-curation|curate|curation-show|materialize). Missing context stays unavailable until the caller supplies its exact input.
• An opt-in vlajmaji-data-owned package for a locally embedded, sealed whole owned history, including historical dictionary and curation states. Direct consumers need only this package and lexicon; the umbrella exposes it through data-owned. It remains separate from the four upstream pack identities.
• A strict sealed snapshot codec and explicit full-history import/export for schema-one and migrated schema-two owned journals, including retained curation history and exact replay checks (sealed-history guide).
• A lossless local jbotci export normalizer with jbotci-import and read-only jbotci-check commands and an explicit pinned acquire/replay/check/ update workflow (import guide).
• An optional unpublished Lensisku/jbotci data package with strict local seals and consuming pure composition. data-pack fixture jbotci OUTPUT prepares synthetic CI/local data; data-pack materialize jbotci RAW METADATA OUTPUT prepares a full local pack from caller-provided pinned inputs. Neither command fetches data or writes a default store. The optional pack is absent from default builds, and its seal is an integrity inventory rather than publisher authentication or licensing evidence.
• A lossless adapter for the complete LLG gismu, cmavo, and assigned rafsi lists, plus an optional unpublished vlajmaji-data-llg embedded package. data-pack fixture llg OUTPUT prepares a Synthetic payload; data-pack materialize llg GISMU CMAVO RAFSI NOTICE OUTPUT normalizes caller-supplied local bytes against pinned hashes. No command fetches or redistributes source data automatically; terms remain Held.
• A lossless adapter for the pinned La-Lojban English Lensisku export, plus an optional unpublished embedded package. data-pack fixture la-lojban OUTPUT prepares Synthetic CI/local bytes; data-pack materialize la-lojban RAW_JSON OUTPUT validates the local full-byte pin and writes a Full pack. The package is absent from default builds, and content redistribution remains Held because software licensing does not establish data rights.
• A lossless adapter for the pinned Sutysisku English JSON projection and an optional unpublished embedded package. data-pack fixture sutysisku OUTPUT prepares Synthetic CI/local bytes; data-pack materialize sutysisku RAW_JSON OUTPUT verifies the complete caller-provided pin and writes a Full pack. The package is absent from default builds, and content redistribution remains Held pending verified terms and lexical lineage.
• All four local packs share the normalized model and strict seal, enabling pure consuming composition before a SQLite store is built. The offline four-pack and owned-history guide shows the pinned original inputs, fresh catalogue, pure sealed-history load, and historical/current workbench commands.
• An umbrella library, vlajmaji, exposing lexicon, store, and search, with optional morphology and graph features.

The earlier archive/search PoC was exercised against 21,241 records from 16 source snapshots. The new grouped-dictionary path has a reproducible fixture and public API/CLI examples. Four pinned local adapters now cover Lensisku/ jbotci, LLG, La-Lojban, and Sutysisku; adapters for other sources remain future work. Search scores and generated compounds are experimental aids; they do not establish attested usage, semantic equivalence, or poetic merit.

Package	Role
vlajmaji	Umbrella library re-exporting lexicon, store, and search, with opt-in morphology and graph features
vlajmaji-lexicon	Source-preserving lexical data and archives
vlajmaji-store	Persistence and native indexes
vlajmaji-search	Reusable queries and computed analyses
vlajmaji-data-lensisku-jbotci	Optional unpublished Lensisku/jbotci embedded data package (local payload only)
vlajmaji-data-llg	Optional unpublished LLG embedded data package (local payload only)
vlajmaji-data-la-lojban	Optional unpublished La-Lojban embedded data package (local payload only)
vlajmaji-data-sutysisku	Optional unpublished Sutysisku embedded data package (local payload only)
vlajmaji-data-owned	Optional unpublished sealed owned-history package (local payload only)
vlajmaji-cli	The vlajmaji executable

Published 0.2.0 packages

Use Rust 1.98.0 or newer. Install the published 0.2.0 CLI with:

cargo +1.98.0 install vlajmaji-cli --version 0.2.0 --locked
vlajmaji --help

For a Rust library using the published release, add vlajmaji = "0.2.0" to your dependencies and use vlajmaji::{lexicon, store, search}. The umbrella crate README links the component crates and describes the opt-in features.

Build and try the current development checkout

For a source checkout, place Bauske alongside this repository: phonology currently resolves through ../bauske/crates/phonology.

From this repository:

cargo +1.98.0 test --locked --workspace
cargo +1.98.0 run --locked -p vlajmaji-cli -- --help

Try the grouped-dictionary commands with a fresh fixture and store. The subshell keeps the temporary data-home setting local to this example:

(
  set -eu
  run_dir=$(mktemp -d)
  export XDG_DATA_HOME="$run_dir/data"
  cargo +1.98.0 run --locked -p vlajmaji-lexicon --example dictionary_fixture -- "$run_dir/dictionary.json"
  cargo +1.98.0 run --locked -p vlajmaji-cli -- dictionary-build "$run_dir/dictionary.json"
  cargo +1.98.0 run --locked -p vlajmaji-cli -- dictionary-query \
    --request '{"operation":"exact","spelling":"farvi","options":{"page_size":2}}'
  cargo +1.98.0 run --locked -p vlajmaji-cli -- info
  cargo +1.98.0 run --locked -p vlajmaji-cli -- verify all
)

Grouped build, query, info, and verify share the optional explicit STORE or default resolution: $XDG_DATA_HOME/vlajmaji/stores/default when XDG_DATA_HOME is an absolute nonempty path, otherwise $HOME/.local/share/vlajmaji/stores/default. This location is intended for a future dictionary-of-dictionaries; the initial Lensisku-only store is provisional. Build creates missing default parent directories and refuses to replace an existing store. Query, info, and verify open only an existing store; they never create or download one. Store creation completes full verification before returning, while ordinary store open checks only the minimum readable header. info reads counts and source summaries from SQL; query still decodes the complete typed dictionary and builds its search indexes.

verify accepts six selective checks—schema, metadata, hashes, model, fks, and projection—or all to attempt every check. The schema guide and query guide cover the persisted structure, lookup behavior, default resolution, and errors. The debug commands above demonstrate the fixture workflow; use the optimized release CLI for representative runtime measurements, for example cargo +1.98.0 build --release --locked -p vlajmaji-cli.

The response keeps competing definitions under their named sources, reports complete totals before paging, and returns a continuation cursor when needed. The query guide covers source filters, paging, availability, stable references, and structured errors.

Compact exact/reference output is opt-in with dictionary-query STORE --format compact --request JSON; configured lookup uses lookup --format compact --request JSON. Both retain full output by default. Compact hits carry strict detail keys that can be expanded with dictionary-detail STORE --reference JSON, or lookup-detail --reference JSON for managed results. The collection guide documents snapshot checking and the compact/detail fields. Pass --format readable to dictionary-query or configured lookup for deterministic source-grouped text, or to either detail command for a readable complete-hit view. Full JSON remains the default; compact JSON keeps its existing response shape.

Try an owned dictionary and its history

After building the checkout, this self-contained synthetic example creates five revisions, records reviewed curation, exports a sealed history, and imports it into a separate journal. All paths are fresh and explicit:

(
  set -eu
  run_dir="$(mktemp -d)"
  cargo +1.98.0 run --locked --offline -p vlajmaji-store --example owned_snapshot -- \
    "$run_dir/inputs" "$run_dir/journal" "$run_dir/imported"
  cargo +1.98.0 run --locked --offline -p vlajmaji-cli -- owned history "$run_dir/imported"
  cargo +1.98.0 run --locked --offline -p vlajmaji-cli -- owned show "$run_dir/imported" \
    --revision owned-r1
  cargo +1.98.0 run --locked --offline -p vlajmaji-cli -- owned check \
    --input "$run_dir/inputs/snapshot.json" --seal "$run_dir/inputs/seal.json"
)

The historical read reconstructs owned-r1 from the imported history. The snapshot retains curation definitions and context pins; resolving external members still requires the caller's matching context. See the owned dictionary guide for editing, conflict handling, materialization, derived queries, and preparing the optional embedded package. The example uses neither the default store nor external corpus inputs.

Corpus data is not bundled. The migration and replay guide describes importing research inputs, building a store, querying it, and running the separately gated full-corpus test.

Where this is going

Independent corpus packages, explicit composition, owned dictionaries, and configured mixed workbench refreshes now have Rust and CLI workflows. The longer aim is a practical vocabulary laboratory connected to Bauske's linguistic tools.

The workspace is on the 0.3.0 development cycle; its APIs remain experimental.

Development and releases

Run make help for build, test, lint, documentation, and publishing targets. make check runs the core quality gates. The Make helpers require Bash 3.2 or newer and Git; Python is not needed. make test-tools runs the Bash tooling suite with disposable local Git remotes and a Cargo stub, without building Rust or accessing the network.

make build builds and copies vlajmaji to ./bin; make build-release does the same for an optimized build. Set INSTALL_DIR=./local-bin to choose another destination. To copy an existing build, run make install (or make install MODE=release for release artifacts).

make planning sets up .worktrees/planning on the separate planning branch. It fetches an existing branch from origin, or creates and pushes an empty orphan branch if none exists. Later updates are fast-forward only; local planning work is preserved.

Use make publish-dry-run to verify the workspace packages and make publish to upload them to crates.io. Publish the Bauske dependency first. The packaged crates include their own READMEs and licenses.

License

Apache License, Version 2.0