VFS Federation Studio

Version 1.1.5

VFS Federation Studio is a Windows 11 desktop application for designing, inspecting, building, and exporting federated virtual file systems. It brings local sources and mounted child VFS images into one governed workspace, makes path and policy behavior visible before a build, and produces verifiable VFS images with optional self-contained Perl runtimes.

The Studio also includes a supervised AI workflow for training and packaging pure-Perl assistants. Dataset checks, independent evaluation, human approval, and package selection remain separate steps, so a trained model cannot approve itself or silently alter a workspace.

Highlights

Typical workflow

1. Create or open a Chronicle workspace.
2. Add projects, local sources, embedded VFS images, and mount policies.
3. Inspect important paths and Monk rules before building.
4. Build the federation into a deterministic VFS image.
5. Run deep verification and review the build evidence.
6. Export a pure-Perl package when the VFS must run independently of Studio.

Workspace edits, AI approval, and build/export are independent actions. A review decision never starts a build automatically.

Install and launch

VFS Federation Studio requires 64-bit Python 3.12 or newer. Install it from PyPI in PowerShell:

py -m pip install vfs-federation-studio
vfs-federation-studio

The desktop application can also be launched as a Python module:

py -m vfs_federation.ide

The wheel keeps the same installation requirements as the reviewed 1.0.0a4 build:

No non-core Perl module is required by the generated distribution. Once exported, the Perl package does not require Python, PySide6, Studio, or network access.

Build a federation

The desktop route is Design federation followed by Build & export. The same workspace can be built reproducibly from PowerShell:

vfs-federation-build .\build\federation.vfsbin `
  --workspace .\federation.vfsworkspace.json `
  --perl-package .\packages `
  --perl-module Example::Federation `
  --perl-version 1.0.0

Verify the completed image independently:

vfs-federation-inspect .\build\federation.vfsbin --deep-verify

The inspector can also resolve a path with a trace, list a virtual directory, or evaluate an embedded advisory Monk Loom attachment.

Perl export perspectives

A single export can serve application developers, Perl operators, reviewers, and assistant maintainers without requiring them to use the same toolchain.

Generated packages include a root README, assistant documentation, branch-agent guidance, offline HTML help, and a test suite. Run the package tests with:

Set-Location .\packages\Example-Federation-1.0.0
prove -Ilib -r t

The bundled assistant is available immediately when no custom candidate is selected:

perl .\bin\vfs-perl-assistant `
  --ask "How does longest-prefix VFS routing work?" `
  --explain

AI training and packaging

The AI Workbench presents one controlled process from data preparation to package selection. It accepts UTF-8 CSV, JSON, JSONL, and NDJSON datasets and keeps training data separate from the independent benchmark.

Training cancellation is cooperative: workers stop, staging data is removed, and a partial model is not promoted. Automatic worker selection is capped at four by default and remains subject to the configured security limit.

The same lifecycle is available from the command line:

vfs-federation-assistant init .\assistant-config.json
vfs-federation-assistant preflight .\assistant-config.json
vfs-federation-assistant train .\assistant-config.json .\candidates\main-v2
vfs-federation-assistant inspect .\candidates\main-v2
vfs-federation-assistant approve .\candidates\main-v2 `
  --authority "Package owner" `
  --note "Reviewed independent benchmark and per-intent results"

Pass the approved candidate to vfs-federation-build with --assistant-bundle .\candidates\main-v2 when the package is ready to be created.

Governed specialist agents

Specialist Perl agents can be trained for a narrow task and retained as signed review bundles. Before Studio accepts a bundle, it checks the real model, training corpus, independent benchmark, manifest, signature, signer status, label coverage, dataset separation, and workspace quality policy.

The trust workflow supports:

• password-encrypted Ed25519 private keys kept outside the workspace;
• workspace-scoped public-key trust with expiration;
• permanent signer revocation;
• minimum accuracy, maximum regression, and benchmark-size requirements;
• dry-run validation of every proposed workspace operation;
• separate named decisions for proposal review and application.

Agent output is advisory. It cannot execute answer text, write arbitrary files, change Monk policy, grant trust, approve itself, commit a VFS image, or publish a release.

Integrity and operational boundaries

• Build commits use locked compare-and-swap checks so a stale source image is not silently overwritten.
• Deep verification reopens embedded children and checks their complete digests.
• Generated assistant assets are covered by a manifest with byte lengths and SHA-256 digests.
• Signed specialist bundles use Ed25519 identity and workspace-managed trust.
• Local digests prove integrity; they do not by themselves prove third-party authorship or that an AI answer is correct.
• Private signing keys are never stored in a workspace or exported package.

Included commands

Use COMMAND --help for the complete options available to each tool.

Documentation

Open Help Center in the application or press F1 for the topic related to the active window. The packaged guide covers first-time setup, workspace authoring, path and policy inspection, build/export, Perl packages, AI training, signed-agent trust, troubleshooting, and expected results. The help is local and does not require a web server or internet connection.

Release history and engineering evidence remain available in RELEASE_NOTES.md and docs/ for maintainers without crowding this product overview.