Build and export a Perl package

Desktop build—the normal route

1. Open a Chronicle workspace and finish its projects, sources, embedded mounts, and active profiles in Design federation.
2. Choose Build & export on Home, Build on the toolbar for an image only, or Export Perl Package for both outputs.
3. Choose a .vfsbin destination. For Perl export, also set the package parent, module namespace, and version.
4. Choose Build VFS or Build + Export Perl. A separate bounded process reports its output in the log.

The build reads the saved workspace—not unsaved widget state. It recursively builds embedded children before parents, stages the root image, verifies its digest, and then atomically commits the destination. A successful build becomes the active VFS for Path Resolution Lens and Rule Lab.

Equivalent workspace command

Use this route for automation or to reproduce the desktop build. The workspace supplies mappings, namespaces, profiles, mounts, collision policies, and history retention.

py -m vfs_federation_studio.tools.build_cli `
  .\build\federation.vfsbin `
  --workspace .\federation.vfsworkspace.json `
  --perl-package .\dist `
  --perl-module Example::First `
  --perl-version 1.0.0

On success the command prints one JSON result containing the output path, image SHA-256, image size, workspace fingerprint, number of projects built, and Perl package path. A nonzero exit means the output is not a qualified build.

Independently verify and trace

py -m vfs_federation_studio.tools.inspect_cli `
  .\build\federation.vfsbin --deep-verify

py -m vfs_federation_studio.tools.inspect_cli `
  .\build\federation.vfsbin --resolve /plugins/demo/plugin.txt --trace

Require verify  PASS. The trace identifies whether the root or an embedded child owns the resolved path. Deep verification recursively reopens embedded images rather than trusting only their outer bytes.

Verify the generated Perl distribution

Set-Location .\dist\Example-First-1.0.0
prove -Ilib -r t
perl .\bin\vfs-perl-assistant --ask "How do I open the packaged VFS?" --explain

Require Result: PASS or All tests successful. Keep lib, share, bin, docs, examples, and t together. Read the root README.md first, then the assistant-specific share\example-first\assistant\README.md and specialist examples\branch_agent\README.md. The distribution runs with Perl alone and does not require Studio, Python, or network access.

Operating system and newline behavior

Help → About VFS Federation Studio displays the detected host from Python’s platform information. Studio uses that host only where behavior genuinely differs—for example Windows workspace locking—and generated Perl uses $^O plus File::Spec for runtime platform and host paths. VFS virtual paths and image bytes do not change with the host OS.

Generated Perl source, README, Help, CSV, JSON, and manifest files use LF (0x0A) line endings on Windows, Linux, and macOS so the same inputs have reproducible package hashes. Do not convert a package tree to CRLF before digest comparison. VFS payload APIs are byte-exact: read() and write() never translate newlines, while read_text() and write_text() only apply the selected encoding. Use "\r\n" explicitly for application data that requires CRLF.

Replay the exported assistant checkpoint

perl .\bin\plnn-text-evaluate `
  --model .\share\example-first\assistant\model.json `
  --data .\share\example-first\assistant\benchmark.csv `
  --json `
  --output .\assistant-replay-metrics.json `
  --predictions .\assistant-replay-predictions.csv

The assistant README states this exact export’s expected row count and accuracy. Require those values to match and retain the replay files with release evidence. This evaluator verifies model behavior; it does not replace package digests, agent signatures, Chronicle review, or image verification.

What the workspace builder accepts

Advanced: direct mappings without a workspace

For a small one-off image, each positional argument is VIRTUAL_PATH=SOURCE_FILE. Quote the whole mapping when a path contains spaces.

py -m vfs_federation_studio.tools.build_cli `
  .\output\root.vfsbin `
  "/docs/readme.txt=C:\My Project\README.txt" `
  --namespace my.product.root `
  --profile release `
  --perl-package .\packages `
  --perl-module VFS::MyProduct `
  --perl-version 1.0.0

Direct mode also supports explicit --embed, --collision, Monk profile, and Monk neural attachment options. Do not combine those mapping options with --workspace; the workspace is authoritative when selected.

Package an approved custom assistant

The desktop workspace route currently includes the reviewed bundled assistant. For an approved custom candidate, reproduce the build at the command line and add --assistant-bundle .\candidates\approved-main. The candidate must pass dataset, digest, quality, and explicit-approval validation; otherwise export stops.

Build after an agent plan

An applied agent plan changes only the Chronicle workspace. Reopen Design federation, inspect every resulting row, and then start Build or Export yourself. The builder receives no special AI privilege: it reads the saved workspace and runs the same discovery, staging, deep verification, Perl syntax, and test gates used after manual edits. See Train an agent to propose workspace changes for the complete route.

Common build stops