Skip to content

Initial full release

Latest
Latest

Choose a tag to compare

View all tags
@abforman abforman released this 14 Jul 21:38
Immutable release. Only release title and notes can be modified.
v1.0
6d4473e
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Vellis — v1.0

This release transforms Vellis from a developer-oriented RTG beta into an installable local knowledge system with guided onboarding, automatic recovery, a built-in Everyday Life ontology, and a formally validated SysML v2 design foundation.

Highlights

  • One-command setup for Codex, Claude Code, Claude Desktop, and generic MCP clients.
  • Automatic durable-state recovery across MCP process restarts.
  • Built-in, extensible Everyday Life ontology with no invented user data.
  • Textual SysML v2 established as the normative design authority.
  • Expanded RTG querying, validation, compact responses, and recovery evidence.
  • Native Windows onboarding and MCP smoke-test coverage.
  • Test suite expanded from 161 to 324 passing tests.

Simplified Installation and Onboarding

Ordinary users can now install and connect Vellis with:

git clone https://github.com/volantlabs/vellis.git
cd vellis
uv run vellis setup

Setup now:

  • Detects Codex, Claude Code, Claude Desktop, or a generic JSON MCP client.
  • Shows the exact launch, configuration, and data paths before making changes.
  • Requests one confirmation before modifying user-wide MCP configuration.
  • Generates cwd-independent configuration with absolute executable and storage paths.
  • Recovers an existing durable graph before accepting connections.
  • Installs the starter ontology only when the graph is genuinely empty.
  • Preserves unrelated MCP registrations and is idempotent when repeated.
  • Fails closed without changing client configuration when recovery or validation fails.

A new non-destructive diagnostic command is available:

uv run vellis doctor

For scripts and agents, setup --json and doctor --json emit exactly one JSON document and never prompt. Non-interactive setup requires explicit authorization through --yes.

The shorter vellis console command is now available while vellis-rtg-knowledge-graph remains supported for compatibility.

Everyday Life Ontology

New installations include a modeled, schema-only Everyday Life ontology for organizing personal, household or family, and work information.

It includes anchors for:

  • People and groups.
  • Areas of responsibility.
  • Goals, projects, and tasks.
  • Events and routines.
  • Decisions and notes.
  • Resources and places.

Typed relationships cover responsibility, membership, support, location, documentation, mentions, dependencies, and other common connections.

The ontology:

  • Contains no people, tasks, or other user facts.
  • Requires only a name or title, allowing incomplete but truthful records.
  • Uses deterministic identities and an idempotent installation process.
  • Can be extended after installation.
  • Never overlays a recovered custom schema merely because type names overlap.
  • Rejects incompatible identity collisions and partial installations without mutation.
  • Is generated from the normative Vellis model rather than maintained as a separate hand-authored contract.

Automatic Recovery and Safer Upgrades

Ordinary startup now reconstructs live graph, schema, constraint, and migration state from the durable SQL ledger before the MCP server accepts connections.

Recovery improvements include:

  • Automatic ledger replay after process restarts.
  • Post-replay validation with fail-closed startup behavior.
  • Exact domain-state equivalence checks using digests, not counts alone.
  • Separate reporting of domain-state and ledger-cursor equivalence.
  • Detailed replay accounting for scanned, eligible, replayed, administrative, rejected, and terminal records.
  • Durable migration history for applied, abandoned, failed, and rejected schema proposals.
  • Preservation of custom schemas from earlier beta installations.

Explicit recovery remains available for evaluation and audit workflows through --manual-recovery. The --empty option disables starter-schema installation without rejecting healthy recovered custom state.

RTG Query and Validation Improvements

The query engine now supports:

  • Deterministic limit and offset pagination.
  • Distinct projected rows.
  • Grouped count aggregation over distinct UUID bindings.
  • Optional and chained optional link requirements.
  • Exact, kind-sensitive recursive JSON equality.
  • Arbitrary-precision JSON integer ordering and grouping.
  • Expanded comparison, membership, string, and regular-expression predicates.
  • Explicit case-sensitivity and regular-expression flags.
  • RE2-compatible regular expressions for predictable execution.
  • Stronger validation of ambiguous bindings, return paths, aggregation names, and incompatible options.

Schema and change validation now cover:

  • Recursive object and array field definitions.
  • Required fields and nested strictness.
  • Allowed values, numeric bounds, string lengths, and RE2 patterns.
  • Coherent and unique field-kind combinations.
  • Grouped and global cardinality constraints.
  • Distinct-target counting.
  • Canonical set handling and duplicate rejection.
  • Boundary-specific failures and structured corrective diagnostics.
  • Atomic snapshot import and stronger no-effect guarantees on rejection.

More Efficient MCP Responses

The 27-tool MCP surface remains intact while response shaping is more efficient and predictable.

Notable improvements include:

  • Compact mutation responses are now the default for anchor-record ingestion.
  • Compact responses preserve generated anchor, fact, and link UUID mappings.
  • Beta-scale compact mutations are verified to be at least 60% smaller than full responses.
  • Full canonical mutation payloads remain available through format: "full".
  • Query responses explicitly identify full and properties_only result kinds.
  • Snapshot operations can return compact summaries without embedding the complete snapshot.
  • Schema staging correlates generated UUIDs by kind:type_key.
  • Capability guidance describes tool lanes, dry-run predecessors, mutation behavior, and intended audiences.
  • MCP tool metadata is generated from the application model and kept within defined size limits.

SysML v2 Design Authority

Textual SysML v2 under model/ is now the normative black-box design for the repository.

The repository explicitly separates three model products:

  • Software Component Modeling Foundation — reusable lifecycle, realization, state-access, failure, and evidence vocabulary.
  • Bibliotek — the reusable AI-native component library.
  • Vellis — the application composition, façade, actor-visible use cases, ontology, and Python/MCP realizations.

Foundation and Bibliotek are independently packageable library products. Vellis consumes Bibliotek, while Bibliotek remains independent of Vellis.

The model now captures:

  • Typed public actions and values.
  • Collaborator roles and application composition.
  • Abstract owned and derived state.
  • Action effects and no-effect failure behavior.
  • Component and application invariants.
  • Actor-visible use cases.
  • Python and MCP realization mappings.
  • Requirements, asserted satisfiers, verification objectives, and concrete evidence bindings.
  • The canonical 27-tool Vellis façade.

Formal Model Validation and Generated Evidence

New model tooling provides:

  • Independently packaged Foundation, Bibliotek, and Vellis KPAR products.
  • Validation through a checksum-pinned official Java SysML v2 validator.
  • Architecture and dependency-direction checks.
  • Public-contract and implementation-binding checks.
  • Generated-artifact freshness validation.
  • Human-readable Bibliotek component and Vellis application references.
  • Machine-readable parser inventories, conformance objectives, and verification-evidence indexes.
  • A generated runtime MCP manifest.
  • Model-to-implementation handoff reports.
  • Read-only model/implementation hygiene audits.

The repository also includes a searchable, checksum-verified Markdown projection of the pinned SysML and KerML specifications. The official PDFs remain authoritative.

Agent and Contributor Tooling

Repository-local agent skills have expanded from four to seven and now cover:

  • Component authoring.
  • Python component implementation.
  • Documentation synchronization.
  • RTG Knowledge Graph MCP operation.
  • RTG schema design.
  • SysML/KerML reference research.
  • Model/implementation hygiene review.

Generated documentation replaces the previous hand-authored component-contract pages, eliminating a parallel source of truth.

Cross-Platform and CI Improvements

  • Added native Windows MCP configuration and onboarding smoke tests.
  • Added PowerShell-safe path and argument quoting.
  • Added focused MCP configuration output for Codex and JSON-based clients.
  • Added repository-layout and documentation-link validation.
  • Added formal model setup and validation to CI.
  • Updated FastMCP from 3.4.3 to 3.4.4.
  • Updated Ruff from 0.15.20 to 0.15.21.
  • Added the pinned google-re2 runtime dependency.
  • Added locked Windows wheels for supported RE2 platforms.

Upgrade Notes

Existing v0.1 or Private-Beta Data

Existing graphs do not require a logical data migration. Preserve the exact --storage-root and --sql-database-path values from the current MCP registration and run:

uv run vellis setup \
  --storage-root /absolute/path/from/the-existing-registration \
  --sql-database-path /absolute/path/from/the-existing-registration/controller.sqlite

Then run vellis doctor with the same arguments, restart the MCP client, and verify system state and graph validation before moving or deleting the original data.

Do not substitute --data-dir for a legacy flat --storage-root; the two options describe different layouts.

Startup Behavior

Normal startup now performs automatic replay and installs the Everyday Life ontology only for a genuinely empty graph. Evaluation workflows that require the previous blank, explicitly recovered behavior should use:

--empty --manual-recovery

Response Shapes

Anchor-record mutations now return compact responses by default. Consumers that require the submitted canonical payload should request:

{
  "response_options": {
    "format": "full"
  }
}

Regular Expressions

Schema and query regular expressions now use the RE2 dialect. Patterns relying on unsupported backtracking or lookaround constructs must be revised.

Security and Data Boundaries

  • Vellis remains beta software.
  • Graph state is stored locally and unencrypted.
  • Connected AI agents or models can receive graph contents when invoking Vellis tools.
  • Vellis does not yet provide encryption, authentication, user accounts, or multi-user authorization.
  • Ordinary stdio operation opens no network service.
  • Advanced HTTP mode remains unauthenticated and must stay bound to 127.0.0.1.
  • Back up the complete .data/rtg_knowledge_graph/ directory while Vellis is stopped.

Verification

Current main was verified with:

  • 324 passing tests.
  • Ruff lint checks.
  • BasedPyright with zero errors, warnings, or notes.
  • All seven repository-local skills and Claude skill links validated.
  • Foundation, Bibliotek, and Vellis packaged and formally validated.
  • SysML/KerML reference corpus freshness checks.
  • Generated model, reference, evidence, ontology, and runtime artifacts validated.
  • Successful source-distribution and wheel builds.

Full Changelog: v0.1...v1.0

Assets 3
Loading