Metadata-Version: 2.4
Name: vfs-federation-studio
Version: 1.1.5
Summary: Design, verify, and export governed VFS federations and self-contained Perl runtimes
Author: VFS Federation Studio
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://pypi.org/project/vfs-federation-studio/
Project-URL: Download, https://pypi.org/project/vfs-federation-studio/#files
Keywords: vfs,perl,neural-network,pyside6,qt6,desktop
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Win32 (MS Windows)
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: PySide6<7,>=6.8
Requires-Dist: cryptography>=42
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# 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

| Area | What VFS Federation Studio provides |
| --- | --- |
| Federation design | Projects, source files and folders, embedded child images, mount points, collision policies, and build profiles in one workspace |
| Chronicle workspaces | Saved configuration, history, undo/redo, recovery review, proposals, and named human decisions |
| Path inspection | Path Resolution Lens traces which project or mounted child owns a virtual path and why |
| Policy inspection | Monk Rule Lab evaluates operations against the active policy before a package is changed |
| Build and verification | Deterministic `.vfsbin` output, atomic commits, recursive child verification, and explicit integrity checks |
| Perl export | A portable, writable pure-Perl distribution with runtime modules, command-line tools, tests, documentation, and optional assistant assets |
| AI Workbench | Dataset preflight, pure-Perl training, independent evaluation, candidate review, approval, and package selection |
| Signed agent proposals | Ed25519-signed specialist bundles, workspace trust and revocation, quality gates, dry-run validation, and separate review/application |
| Offline help | 29 searchable, task-oriented topics available from the Help Center and contextual F1 help |

## 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:

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

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

```powershell
py -m vfs_federation.ide
```

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

| Requirement | How it is supplied |
| --- | --- |
| Python 3.12+ | Installed by the user |
| PySide6 6.8 or newer, below 7 | Installed automatically by `pip` |
| `cryptography` 42 or newer | Installed automatically by `pip` |
| 64-bit Perl, such as Strawberry Perl | Needed for Perl export, Perl training, and generated-package tools |

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:

```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:

```powershell
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.

| Perspective | Exported capability | What matters at runtime |
| --- | --- | --- |
| Application developer | Deterministic `.vfsbin` image plus a namespaced Perl distribution | Stable virtual paths, embedded-child routing, collision handling, and writable transactions |
| Perl operator | Modules and command-line programs for read, list, search, stat, update, inspection, and assistant queries | Core Perl modules only; no Python or network dependency |
| Package reviewer | Tests, build report, manifests, SHA-256 digests, configuration, and package-specific documentation | The package can be verified and tested from an unrelated directory |
| Assistant maintainer | Model, reviewed knowledge, training and benchmark data, metrics, history, and evaluation tools | The exact packaged model can be replayed against its independent benchmark |
| Specialist-agent maintainer | Named branch-agent tools and bundles published under `/agents/ID` | An agent may propose a bounded workspace recipe but cannot execute or approve it |

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

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

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

```powershell
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.

| Stage | Action | Evidence or gate |
| ---: | --- | --- |
| 1. Configure | Choose training, knowledge, and benchmark sources; architecture; thresholds; worker limits; and packaging settings | A typed configuration is validated and saved atomically |
| 2. Dataset preflight | Validate paths, formats, sizes, row limits, labels, knowledge coverage, sensitive text, and train/benchmark separation | Invalid, incomplete, or overlapping corpora stop before training |
| 3. Train and evaluate | Run pure-Perl backpropagation with bounded workers, then evaluate on the independent benchmark | Accuracy, macro-F1, minimum per-intent recall, confusion data, and training history are recorded |
| 4. Review candidate | Inspect the architecture, ordered intent labels, metrics, manifest, and candidate fingerprint | The reviewed files must match their recorded digests |
| 5. Human approval | Record a named reviewer and review note for the exact candidate | Approval is bound to the candidate fingerprint and cannot start a build |
| 6. Select for packaging | Recheck integrity and approval, then select the candidate for a later export | Only the approved candidate is copied into the generated Perl package |

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:

```powershell
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

| Command | Purpose |
| --- | --- |
| `vfs-federation-studio` | Launch the desktop application |
| `vfs-federation-build` | Build a VFS image and optionally export a Perl distribution |
| `vfs-federation-inspect` | Verify, resolve, trace, and list VFS content |
| `vfs-federation-workspace` | Manage Chronicle workspace operations |
| `vfs-federation-assistant` | Configure, preflight, train, inspect, and approve assistant candidates |
| `vfs-federation-agent-actions` | Manage signer trust and governed agent proposals |
| `vfs-federation-help` | Open the packaged offline documentation |

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.
