VFS FEDERATION STUDIO
PYSIDE6 PRESERVATION-FIRST IMPLEMENTATION ROADMAP

PySide6 + Python desktop engineering IDE
Spawn-safe multi-process build and verification engine
Operational pure-Perl VFS package output
Strong bundled, external, and embedded VFS-within-VFS federation

Document version: 2.1
Roadmap date: 2026-09-20
Status: Living implementation authority, conformance ledger, and phase-gate specification
Supersedes: Execution sequencing in roadmap version 2.0 and the Electron/React
            implementation direction in roadmap version 1.0
Preserves: Determinism, exact lookup, binary safety, independent Perl output,
           explicit federation, and executable release gates

VERSION 2.1 COURSE CORRECTION

Runtime research advanced faster than the Studio workspace. Federation Image v2,
embedded views, writable Pure-Perl operation, Monk policy, Monk Loom inference,
and direct VFS training now have evidence-backed implementations, while several
earlier workspace, editor, persistence, scheduler, recovery, and platform gates
remain partial.

This revision does not erase that work and does not pretend it completed the
numbered roadmap phases. It introduces an explicit milestone namespace:

    RM-P0 .. RM-P12
        The numbered product phases in this document.

    MONK-M1, MONK-M2, ...
        Cross-cutting Monk policy/Loom research milestones. Historical filenames
        containing "P4 neural" remain historical records; they never mean RM-P4.

    RELEASE 0.x
        Product snapshots. A release number is not proof that a roadmap phase
        passed.

The current restart point is RELEASE 1.0.0a4, CORPUS-HARDENED SIGNED AGENT
ADMISSION.
Chronicle now drives native project/source/mount/profile authoring, persistent
compensating undo/redo, recovery checkpoints, and a staged embedded workspace
build/export route. A trained pure-Perl specialist can additionally submit a
signed, fingerprint-bound, workspace-bound configuration plan through separate
trust, quality-admission, bundle-review, plan-review, and application gates.
Chronicle v4 persists bounded Ed25519 signer trust, permanent revocation, and
independent-benchmark regression policy. Admission now parses the actual
training, benchmark, and model label sets, rejects malformed or leaking
corpora, and exposes exact corpus evidence. Exported pure-Perl packages carry a
standalone metric replay command and layered operator/developer READMEs. The
agent still has no commit,
Monk-policy, build, export, or release authority. This advances—but does not
complete—RM-P2, RM-P3, RM-P6, RM-P11, RM-P12, MONK-M3, and MONK-M5. Graph
authoring, bundled/external providers, unified scheduling, remaining signature
instruments, direct signed in-VFS review, adversarial/platform qualification,
and final release signing remain explicit gates.

The signature identity of the application is now explicit:

    A preservation-first federation IDE that designs nested VFS packages,
    exports operational Pure-Perl runtimes, explains resolution and binary
    ownership, and can attach deterministic reviewable Monk intelligence
    without granting that intelligence commit authority.

===============================================================================
0. DOCUMENT PURPOSE AND THE NON-DESTRUCTIVE DIRECTIVE
===============================================================================

This document defines the replacement architecture and implementation sequence
for VFS Federation Studio as a native-feeling PySide6 desktop engineering
environment.

The phrase "non-homicide approach" is interpreted here as a precise technical
directive:

    - Do not destroy authoritative source bytes.
    - Do not mutate a valid VFS image in place.
    - Do not treat deletion as immediate physical erasure.
    - Do not let cancellation or worker failure corrupt a destination.
    - Do not kill a process as the first form of task control.
    - Do not allow an embedded child image to escape its declared byte bounds.
    - Do not make an unverified generated package look successfully completed.

The resulting architecture is preservation-first rather than merely
crash-resistant. Every mutation produces a new candidate generation. A
candidate becomes authoritative only after validation, independent reopening,
integrity verification, and an atomic commit. Old valid generations remain
available according to an explicit retention policy.

VFS Federation Studio is not a mock archive viewer, a diagram that merely
describes a build, or a code-preview toy. It is a deterministic package
laboratory and IDE that converts a validated visual design into an independently
usable Perl VFS distribution.

The central promise is:

    A federation designed in the Studio can be exported as a complete,
    reviewable, tested Perl package that still works when Python, PySide6, and
    the Studio are absent.

No screen, graph node, progress bar, or generated source preview is accepted as
proof of completion. Every phase has executable exit gates.

===============================================================================
1. PRODUCT DIRECTIVE
===============================================================================

Product name:

    VFS Federation Studio

Product category:

    Native desktop VFS architecture IDE, topology designer, binary package
    laboratory, and Perl distribution generator.

Primary user outcome:

    Build one VFS or a hierarchy of VFS packages mounted beneath explicit
    virtual paths; inspect every routing and binary-layout decision; export a
    deterministic Perl distribution; and prove that it opens, lists, seeks,
    reads, verifies, and resolves nested mounts independently.

Primary product identity:

    Part IDE.
    Part namespace and federation designer.
    Part binary image laboratory.
    Part deterministic Perl package factory.
    Part evidence instrument for explaining exactly why a path resolved.

The Studio succeeds when a developer can answer, from one coherent workspace:

    - What source bytes are included?
    - Which bytes changed since the prior generation?
    - Which VFS owns a virtual path?
    - Which child is mounted at each prefix?
    - What happens when parent and child namespaces collide?
    - Which exact index record serves a lookup?
    - Which bounded byte range represents an embedded child image?
    - Which integrity record proves that child?
    - What Perl modules and .vfsbin images will be exported?
    - Did the generated package pass its tests outside the Studio repository?
    - Can a failed build be cancelled without damaging the last good package?

The product must be equally credible when handling a tiny configuration package
and a deeply nested, binary-heavy federation.

===============================================================================
2. NON-NEGOTIABLE ENGINEERING PRINCIPLES
===============================================================================

2.1 Preservation before mutation

Authoritative sources are opened read-only. Project edits modify a design model
or an overlay, not source bytes. Builds write into isolated staging areas.
Commit replaces a destination only after validation succeeds.

2.2 Exact lookup is the hot path

Normal read, exists, stat, list, and open_file operations use exact indexed
access. Regex and policy rules may affect routing or exceptional behavior, but
an ordinary exact path must not scan every entry or every rule.

2.3 Federation is explicit

A child VFS is not merely a file hidden inside another archive. It has identity,
format version, mount point, delivery mode, collision policy, fingerprint,
compatibility declaration, lifecycle, and traceable resolution behavior.

2.4 Determinism is mandatory

The same source bytes, project snapshot, generator version, and build profile
must produce byte-identical artifacts. Wall-clock timestamps, unordered hash
iteration, process completion order, temporary paths, and host-specific metadata
must not leak into canonical output.

2.5 Binary safety is mandatory

Text and binary payloads are peers. No layer may silently decode, normalize,
line-convert, trim, re-encode, or truncate payload bytes.

2.6 The GUI process is never the build engine

The QApplication process owns widgets, models, actions, layout, and presentation
snapshots. It does not recursively scan large trees, hash gigabytes, compress
payloads, build indexes, write VFS images, or execute Perl tests.

2.7 Multi-processing is a correctness boundary

Workers receive immutable task descriptions and publish immutable results.
Workers do not own authoritative project state. A worker crash may lose a task,
never the user's last valid package.

2.8 Cooperative cancellation precedes forced termination

Every long-running stage exposes cancellation checkpoints and can abandon its
staging output. Escalation to process termination is permitted only after a
graceful cancellation deadline, and architecture must make forced termination
safe by ensuring workers never mutate authoritative files.

2.9 Generated Perl is readable and independent

Output is stable, formatted, documented, testable, and free from hidden Python,
Qt, Node.js, network, or Studio runtime dependencies. Generated source is never
minified, self-modifying, or assembled through arbitrary eval.

2.10 Embedded children are bounded images

Opening an embedded child creates a byte-range view with an absolute base,
declared length, independent header, and verified fingerprint. Child reads can
never address bytes before or after that range.

2.11 Safe defaults beat impressive defaults

Collision defaults to error. Untrusted workspaces do not execute code. Unknown
required sections fail clearly. Unsupported compression or encryption profiles
are rejected. Purge is separate from delete.

2.12 Diagnostics observe; they do not govern correctness

Progress, telemetry, and performance counters are bounded and disposable.
Overflow may drop an observation and increment a counter; it must not block or
change build output.

2.13 Product claims follow evidence

The Studio distinguishes designed, queued, built, structurally verified, Perl
syntax checked, Perl tests passed, independently reopened, and atomically
committed. A green visual state cannot skip a gate.

2.14 Compatibility is explicit

Project schemas, image formats, IPC messages, plugin contracts, and generated
Perl APIs are versioned. Unknown optional capabilities can be skipped; unknown
required capabilities fail with typed diagnostics.

2.15 Superb means controlled, not complicated

The architecture should expose sophisticated behavior without turning every
operation into a framework. Each dependency, worker class, visual instrument,
and binary section must have a narrow purpose and measurable value.

===============================================================================
3. CORE TERMINOLOGY
===============================================================================

WORKSPACE
    One versioned design container holding the root VFS project, child projects,
    source definitions, build profiles, layouts, history metadata, and prior
    artifact fingerprints.

VFS PROJECT
    One editable design describing sources, virtual paths, transforms, index
    profile, mount relationships, and one generated VFS image/package identity.

VFS IMAGE
    A deterministic binary image containing headers, section directory, strings,
    directories, exact indexes, mount records, payload blocks, integrity data,
    and optional embedded child images.

VFS PACKAGE
    An installable or copyable Perl distribution containing .pm modules, one or
    more .vfsbin images, tests, examples, metadata, and documentation.

FEDERATION
    A root VFS plus one or more child VFS packages connected by explicit mounts.

MOUNT
    A namespace relationship delegating a normalized path prefix from a parent
    to a child VFS.

BUNDLED CHILD
    A child image shipped beside the parent image in the same distribution.

EMBEDDED CHILD
    A complete child image stored inside a bounded range of its parent image.
    It remains independently structured and recursively mount-capable.

EXTERNAL CHILD
    A child resolved through a declared provider contract and delivered outside
    the root package.

IMAGE VIEW
    A read-only object representing [base_offset, base_offset + length) inside a
    backing file, mmap, scalar, or stream. All relative offsets are checked
    against the view before conversion to absolute offsets.

GENERATION
    An immutable candidate or committed project/build state identified by a
    monotonically increasing sequence and a content fingerprint.

OVERLAY
    A set of additions, replacements, metadata changes, and tombstones applied
    above immutable source content.

TOMBSTONE
    A logical deletion record. It hides a path in a new generation without
    physically erasing the prior generation.

COMMIT
    Promotion of a completely staged and verified candidate into the selected
    destination through an atomic replacement protocol.

RUNTIME GRAPH
    The validated minimal graph used for resolution and package generation.

PATH RESOLUTION TRACE
    An ordered explanation of normalization, parent lookup, longest-prefix mount
    matching, policy evaluation, child delegation, integrity checks, index
    access, and final byte-range selection.

ARTIFACT DESCRIPTOR
    An immutable record containing artifact identity, path or shared-buffer
    locator, size, fingerprint, producer task, generation, and verification
    state.

TASK GENERATION
    The workspace/project generation against which a worker result was produced.
    Results from an older generation are stale and cannot silently update the UI
    or become commit candidates.

===============================================================================
4. PLATFORM DECISION: PYSIDE6 DESKTOP STUDIO
===============================================================================

4.1 Desktop-first native Qt architecture

Use PySide6 and Qt Widgets for the primary desktop application. The product
needs native file dialogs, dockable engineering panels, large model/view trees,
binary inspectors, local process control, drag/drop, keyboard-heavy operation,
and reliable access to local files. A browser runtime is not required for the
core product.

4.2 Supported application baseline

    Python:
        Supported release line selected and pinned by the project.
        Initial engineering baseline: Python 3.12+ with qualification through
        the current supported Python 3.x matrix.

    Qt binding:
        PySide6 from the Qt 6 family, pinned in lockfiles and release manifests.

    Packaging:
        Wheel for developer installation.
        Platform-specific frozen application after multiprocessing and helper
        executable qualification.
        Source checkout remains a supported engineering mode.

    Perl output:
        Pure-Perl compatibility profile, preserving the earlier Perl 5.10+
        target unless a project explicitly chooses a newer profile.

No generated Perl package depends on Python or PySide6.

4.3 Why Qt Widgets

Qt Widgets provides a mature main-window and docking model, model/view data
presentation, graphics scenes, process integration, local IPC, undo stacks,
settings, accessibility hooks, and cross-platform behavior appropriate for a
professional IDE.

QML may later power an isolated visualization where measured value exists, but
the 1.0 application shell, trees, tables, editors, docks, and dialogs remain
Qt Widgets. This avoids splitting the product across two UI paradigms before the
core VFS runtime is complete.

4.4 Application bootstrap rule

Only the GUI entry point creates QApplication. Worker and supervisor modules
must import without constructing any QWidget, QPixmap, QOpenGLContext, or
application object.

Canonical entry points:

    vfs-federation-studio
        GUI bootstrap.

    vfs-federation-supervisor
        Headless supervisor bootstrap.

    vfs-federation-worker
        Spawn-safe worker bootstrap or frozen helper executable.

    vfs-federation-build
        Headless deterministic build CLI using the same domain/build services.

    vfs-federation-inspect
        Headless image/package inspector and verifier.

4.5 Browser inspection is secondary

A read-only exportable HTML report may be added later. It cannot become the
authoritative editor, builder, or verifier.

===============================================================================
5. VISUAL PRODUCT SYSTEM
===============================================================================

5.1 Visual character

The Studio should look like an engineering instrument rather than a generic
form application. The presentation language should combine:

    - Deep neutral work surfaces.
    - Crisp typography.
    - Clear spacing and hierarchy.
    - Professional custom SVG iconography.
    - Blue/cyan for selected paths and valid routing.
    - Purple/violet for federation and generated-code relationships.
    - Orange/amber for staged changes, policy intervention, and warnings.
    - Red only for corruption, invalidity, conflict, and failed gates.
    - Green only for completed evidence-backed verification.

Visual effects communicate state. Constant glow, decorative animation, and
dense gradients do not substitute for information.

5.2 Density modes

    COMFORTABLE
        Larger rows and controls for exploratory work.

    ENGINEERING
        Default balanced density.

    COMPACT
        High-information layout for large projects and expert operation.

Density changes layout metrics, not semantic content.

5.3 Typography

Use a readable UI family for labels and a true monospace family for paths,
offsets, hashes, Perl source, manifests, diagnostics, and binary values. Do not
ship proprietary font files as part of the project unless licensing is
explicitly reviewed.

5.4 Accessibility

    - Complete keyboard operation.
    - Stable tab order.
    - Visible focus indicators.
    - Accessible names for icon-only controls.
    - High-contrast mode.
    - Color never carries the only meaning.
    - Reduced-motion setting.
    - Scalable interface metrics.
    - Screen-reader-friendly models and diagnostics.
    - No essential interaction dependent on hover.

5.5 Saved layouts

QMainWindow state and geometry may be persisted per workspace and per named
layout. Layout restoration must validate available dock IDs and fall back
cleanly when plugins or panels are absent.

===============================================================================
6. THE SUPERB IDE WORKSPACE
===============================================================================

6.1 Main window

Use QMainWindow as the shell.

    TOP
        Menu bar, command toolbar, workspace selector, build profile, active
        generation, and trust status.

    LEFT
        Activity rail and Federation Explorer.

    CENTER
        Tabbed editors and visual instruments.

    RIGHT
        Context Inspector, properties, validation, and dependency information.

    BOTTOM
        Diagnostics, Build Queue, Test Results, Process Observatory, and
        Performance Lab.

    STATUS BAR
        Workspace state, active generation, worker health, build fingerprint,
        selected virtual path, and evidence gate.

6.2 Primary activity modes

    FEDERATION
        Root/child topology and mount ownership.

    SOURCES
        Read-only source inventory and overlays.

    BUILD
        Build graph, stages, cache, and artifacts.

    PACKAGE
        Generated Perl tree and image layout.

    TEST
        Fixture, syntax, runtime, and cross-platform evidence.

    HISTORY
        Generations, manifests, diffs, rollback, and retention.

    EXTENSIONS
        Installed plugin capabilities and trust state.

6.3 Federation Explorer

A lazy QAbstractItemModel-backed tree showing:

    Workspace
      Root VFS
        Sources
        Virtual tree
        Mounts
        Rules
        Build profile
        Generated package
      Child VFS projects
      External contracts
      Generations
      Diagnostics

The model exposes stable IDs, not raw object pointers. Large directories use
canFetchMore/fetchMore and snapshot paging. No per-row QWidget objects.

6.4 Central editors

    Federation Graph
        QGraphicsView/QGraphicsScene or equivalent custom scene.
        Nodes represent sources, transforms, indexes, images, emitters, outputs,
        and mount relationships.

    Virtual Namespace Editor
        Tree/table view of normalized virtual paths and ownership.

    Mount Table Editor
        Typed model for mount prefix, child identity, delivery mode, collision
        policy, compatibility, and lazy-loading options.

    Rule Lab
        Policy editor with explicit test cases and resolution-order preview.

    Generated Perl Preview
        Read-only generated source with QSyntaxHighlighter, line numbers, symbol
        navigation, source mapping, and diagnostic underlines.

    Manifest Editor
        Structured view of project/package metadata.

Generated source is not edited in place. User-defined extension points are
stored separately and merged through declared templates or hooks so regeneration
cannot silently erase hand edits.

6.5 Signature instruments

PATH RESOLUTION LENS
    Accepts one virtual path and animates a truthful, stepwise trace through
    normalization, root index, mount routing, child view opening, nested mounts,
    exact entry lookup, integrity verification, and returned byte range.

FEDERATION MAP
    Displays the root, bundled/embedded/external children, mount prefixes,
    dependency direction, depth, compatibility, and health.

PACKAGE X-RAY
    Decodes image headers, sections, tables, records, offsets, lengths, checksums,
    payload blocks, and embedded child ranges.

EMBEDDED IMAGE STACK
    Shows the ancestry of a nested lookup:
        root image view
        child image view
        grandchild image view
        final entry byte range

MANIFEST DIFF
    Compares committed generations by files, metadata, mounts, rules, binary
    sections, generated APIs, and package fingerprints.

PROCESS OBSERVATORY
    Shows supervisor and worker state, task ownership, memory, CPU, heartbeat,
    queue depth, and dropped diagnostic counts. It never controls build
    correctness beyond explicit cancel/restart commands.

RELEASE VIEW
    Shows only evidence required to export: validation, deterministic fingerprint,
    syntax checks, tests, independent reopen, artifact tree, destination, and
    commit status.

6.6 Command palette

Every major action has a stable command ID, label, shortcut, enablement rule,
trust requirement, and transaction behavior. The palette searches commands,
paths, mounts, symbols, diagnostics, and files without conflating them.

6.7 Integrated tool execution

The IDE may invoke known tools such as:

    perl -c
    prove
    generated package examples
    deterministic verifier
    benchmark harness

Arbitrary shell execution is not an implicit project-open behavior. Tool
arguments are passed as arrays, not concatenated shell strings.

===============================================================================
7. MODULAR REPOSITORY ARCHITECTURE
===============================================================================

Recommended repository layout:

    vfs-federation-studio/
      pyproject.toml
      README.md
      LICENSE
      src/
        vfs_federation_studio/
          __init__.py
          app/
            bootstrap.py
            commands.py
            settings.py
            workspace_session.py
          ui/
            main_window.py
            actions/
            docks/
            editors/
            dialogs/
            models/
            delegates/
            graph/
            icons/
            themes/
            accessibility/
          domain/
            ids.py
            paths.py
            project.py
            workspace.py
            sources.py
            mounts.py
            rules.py
            generations.py
            artifacts.py
            diagnostics.py
          application/
            command_bus.py
            query_bus.py
            undo.py
            autosave.py
            trust.py
          federation/
            compiler.py
            resolver.py
            validator.py
            trace.py
            cycle.py
            compatibility.py
          format/
            constants.py
            header.py
            sections.py
            records.py
            reader.py
            writer.py
            image_view.py
            integrity.py
          build/
            plan.py
            stages.py
            scheduler.py
            cache.py
            staging.py
            commit.py
            reproducibility.py
          emitters/
            base.py
            perl/
              emitter.py
              names.py
              templates.py
              package_tree.py
              tests.py
              docs.py
          ipc/
            protocol.py
            framing.py
            codecs.py
            local_client.py
            local_server.py
            shared_buffers.py
          supervisor/
            main.py
            service.py
            worker_pool.py
            task_registry.py
            cancellation.py
            health.py
            recovery.py
          workers/
            entrypoint.py
            scan_worker.py
            hash_worker.py
            image_worker.py
            verify_worker.py
            benchmark_worker.py
          tools/
            perl_runner.py
            verifier_cli.py
            build_cli.py
            inspect_cli.py
          plugins/
            api.py
            manifest.py
            host.py
            permissions.py
          diagnostics/
            store.py
            event_stream.py
            reports.py
      perl_runtime_templates/
        compatibility/
        modern/
      fixtures/
        tiny/
        binary-mix/
        unicode-paths/
        collisions/
        nested-mounts/
        deep-federation/
        embedded-children/
        malformed-images/
        hostile-lengths/
        large-index/
      tests/
        unit/
        contract/
        integration/
        ui/
        multiprocessing/
        generated_perl/
        fuzz/
        performance/
        packaging/
      docs/
        product/
        architecture/
        format/
        perl-api/
        multiprocessing/
        security/
        testing/
        release/
      packaging/
        pyinstaller/
        installers/
        signing/
      scripts/
        build_release.py
        update_golden.py
        verify_distribution.py

7.1 Dependency direction

    ui -> application + immutable presentation models
    application -> domain + service interfaces
    federation -> domain
    format -> domain IDs/value types only
    build -> domain + federation + format + emitter interfaces
    perl emitter -> validated runtime model + format contract
    supervisor -> build task interfaces + IPC
    workers -> headless stage implementations
    plugins -> public versioned API only

The domain, federation resolver, format reader/writer, Perl emitter, and build
planner must run in tests without QApplication.

7.2 Architectural enforcement

Continuous integration rejects:

    - Circular package dependencies.
    - QWidget imports below ui/.
    - multiprocessing process creation from ui/.
    - Qt object serialization across IPC.
    - direct final-destination writes from worker modules.
    - unversioned IPC message types.
    - generated Perl changes without golden diff and test evidence.
    - direct access from plugins into private application or supervisor modules.

7.3 One semantic backend

GUI actions, headless CLI actions, and future automation use the same command and
query services. The UI is an adapter, not a second implementation of project
semantics.

===============================================================================
8. MULTI-PROCESSING ARCHITECTURE
===============================================================================

8.1 Process topology

GUI PROCESS
    Owns QApplication, QMainWindow, widgets, Qt models, actions, editor state,
    immutable presentation snapshots, and local user interaction.

    It never:
        - performs large scans or hashes;
        - builds VFS images;
        - loads untrusted plugins in-process;
        - owns worker queues directly;
        - passes QObjects to another process;
        - blocks waiting for a long task.

SUPERVISOR PROCESS
    Launched and monitored by the GUI through QProcess.
    Owns task planning, process-pool lifecycle, cancellation state, deadlines,
    resource budgets, staging directories, artifact registry, cache coordination,
    validation sequencing, and commit eligibility.

    The supervisor is the only process permitted to promote a verified staged
    export into the final destination.

CPU WORKER POOL
    Persistent spawn-safe workers for:
        canonical path indexing
        hashing
        deterministic record preparation
        compression profiles
        index construction
        image section assembly
        integrity tree calculation
        benchmark kernels

I/O WORKER LANE
    Bounded workers for:
        directory discovery
        read-only source sampling
        staged artifact copy
        independent package reopening

VERIFICATION WORKER
    A logically separate role that reads generated artifacts as a consumer would.
    It does not trust in-memory builder objects.

PERL TOOL PROCESS
    Launched with QProcess or a supervisor-owned subprocess using argument arrays.
    Runs perl -c, prove, and selected generated examples in a controlled working
    directory with captured stdout/stderr and time/resource limits.

PLUGIN HOST PROCESS
    Optional and isolated. Loads approved plugins with a capability manifest.
    Plugin failure cannot take down the GUI or authoritative build supervisor.

8.2 Why a separate supervisor

Directly creating a process pool inside the GUI process makes lifecycle,
packaging, Qt-thread inheritance, stale callbacks, and crash recovery harder to
reason about. A dedicated supervisor creates a clean boundary:

    GUI presents.
    Supervisor schedules and commits.
    Workers compute.
    Verifier distrusts the builder.
    Perl proves the exported runtime.

8.3 Start method

Use an explicit multiprocessing context. The cross-platform baseline is:

    multiprocessing.get_context("spawn")

All worker targets are top-level importable callables in worker modules.
No lambda, nested function, bound QWidget method, open GUI object, or implicit
__main__ state is submitted.

A POSIX fork or forkserver optimization may be evaluated only as an explicit,
benchmarked profile after cross-platform correctness and frozen-app behavior are
proven. It is not the default architectural assumption.

8.4 Pool ownership

Only the supervisor creates and uses a pool. Worker processes do not create
unbounded child pools. Specialized nested parallelism is forbidden unless a
future ADR defines exact resource accounting.

8.5 Worker sizing

Default CPU worker count:

    max(1, min(user_limit, logical_cpu_count - reserved_ui_capacity))

The scheduler reserves capacity for the GUI, operating system, Perl validation,
and storage. It may lower concurrency under memory pressure. More workers are
not automatically faster when tasks compete for the same disk.

8.6 Task envelope

Every task contains:

    protocol_version
    task_id
    task_kind
    workspace_id
    project_id
    task_generation
    build_id
    immutable input descriptors
    declared output types
    priority
    deadline
    cancellation_id
    resource budget
    deterministic seed where required
    capability requirements

Every result contains:

    protocol_version
    task_id
    task_generation
    status
    immutable artifact descriptors
    structured diagnostics
    measured counters
    worker identity
    start/end monotonic times
    output fingerprints
    cancellation acknowledgement

8.7 Stale-result rejection

The GUI and supervisor compare task_generation with the active project
generation. A stale result may be retained for diagnostics or cache reuse when
its inputs match, but it cannot update current semantic state or become a commit
candidate merely because it arrived late.

8.8 Cooperative cancellation ladder

    STEP 1 - REQUEST
        Supervisor marks the cancellation token and stops scheduling dependent
        tasks.

    STEP 2 - CHECKPOINT
        Worker checks at safe boundaries: directory batches, hash chunks, record
        batches, section boundaries, compression blocks, and test boundaries.

    STEP 3 - CLEAN ABANDON
        Worker closes handles, removes or marks incomplete staging output, and
        returns CANCELLED.

    STEP 4 - GRACE DEADLINE
        Supervisor waits a bounded interval while continuing to service other
        tasks.

    STEP 5 - ISOLATE
        Unresponsive worker is removed from scheduling and its task artifacts are
        marked untrusted.

    STEP 6 - TERMINATE
        Process termination is a last-resort containment action. It is safe
        because authoritative sources are read-only and final output is committed
        only by the supervisor after independent verification.

No task holds a final-destination write lock while it is cancellable.

8.9 Crash recovery

Supervisor restarts are generation-aware. On startup it scans staging ledgers:

    COMPLETE + VERIFIED + NOT COMMITTED
        Offer safe resume/commit after re-verification.

    INCOMPLETE
        Quarantine or remove according to retention policy.

    COMMITTED
        Confirm destination fingerprint.

    UNKNOWN
        Never present as successful.

8.10 Process health

Heartbeats are small control messages. Missing heartbeat does not instantly imply
failure during a known long native operation; stages declare expected heartbeat
behavior. Health combines heartbeat age, process exit state, task progress, and
deadline.

8.11 No multiprocessing.Manager in the hot path

Authoritative coordination uses explicit messages, immutable descriptors, and
bounded shared buffers. Proxy dictionaries and lists are not used as a general
distributed object heap.

===============================================================================
9. IPC, BACKPRESSURE, AND LARGE-DATA TRANSPORT
===============================================================================

9.1 GUI-to-supervisor control channel

Use QLocalServer/QLocalSocket or an equivalent local-only framed transport.

On supported platforms this maps naturally to local operating-system IPC. The
GUI integrates socket readiness with the Qt event loop without polling or
blocking.

9.2 Framing

Messages use:

    fixed magic
    protocol major/minor
    message type
    flags
    payload length
    request/task ID
    payload
    frame checksum when selected

The default payload is a bounded, schema-validated representation such as
canonical JSON for control messages. A compact binary codec may be introduced
behind the same schema after benchmarks. No unbounded pickle stream crosses a
trust boundary.

9.3 Message classes

    HELLO / CAPABILITIES
    OPEN_WORKSPACE
    VALIDATE_PROJECT
    PLAN_BUILD
    START_BUILD
    CANCEL_TASK
    TASK_PROGRESS
    TASK_DIAGNOSTIC
    ARTIFACT_READY
    VERIFY_ARTIFACT
    BUILD_GATE_STATE
    COMMIT_REQUEST
    COMMIT_RESULT
    WORKER_HEALTH
    SUPERVISOR_SHUTDOWN

9.4 Backpressure

Every channel has bounded queues and declared overflow behavior.

    Control messages
        Never silently dropped. Sender receives backpressure or explicit failure.

    Progress updates
        Coalesced by task and stage.

    Telemetry samples
        May drop oldest or newest according to stream policy; dropped count is
        visible.

    Diagnostics
        Errors are retained. Repetitive warnings may be deduplicated with count
        and first/last occurrence.

9.5 Large immutable data

Do not pickle gigabyte payloads into queues.

Preferred order:

    1. Read-only source path plus offset/length/fingerprint descriptor.
    2. Memory-mapped staged artifact plus bounded view descriptor.
    3. Shared-memory segment for temporary dense tables where mmap files are not
       appropriate.
    4. Small inline bytes only below a strict threshold.

Shared-memory descriptors contain:

    owner process
    key/name
    generation
    byte length
    element/schema type
    read/write mode
    fingerprint or checksum
    acknowledgement count
    expiration/recovery metadata

The producer retains ownership until all declared consumers acknowledge detach.
Leaks are detected and cleaned through the supervisor ledger.

9.6 Shared-memory discipline

Shared memory is used for immutable or single-writer/sealed buffers. Multiple
processes do not casually mutate shared Python object graphs. Sealing changes a
buffer from producer-owned writable state to consumer-visible read-only state.

9.7 Security

Local IPC endpoints use unpredictable per-session names and an authentication
token inherited through a protected launch channel. Message size, nesting,
string length, count fields, and decompressed size are bounded before allocation.

===============================================================================
10. PROJECT, COMMAND, HISTORY, AND PERSISTENCE MODEL
===============================================================================

10.1 Project schema

Use a versioned, human-inspectable project representation containing:

    schema_version
    workspace identity
    root project identity
    child project identities
    source descriptors
    virtual path mappings
    transforms
    index profiles
    mount table
    collision policies
    rule definitions
    build profiles
    output package metadata
    saved UI layouts
    generation metadata
    prior committed fingerprints

Large caches, discovered file inventories, and build artifacts are not embedded
in the authoritative project file.

10.2 Stable identities

Every semantic object has a stable typed ID:

    WorkspaceId
    ProjectId
    SourceId
    EntryId
    MountId
    RuleId
    GenerationId
    BuildId
    ArtifactId
    DiagnosticId

Display names may change without changing identity.

10.3 Command transactions

All semantic edits are commands:

    AddSource
    RemoveSource
    MapVirtualPath
    AddChildProject
    AddMount
    ChangeCollisionPolicy
    AddRule
    ChangeBuildProfile
    AddOverlayEntry
    TombstonePath
    RestorePath
    RenamePackage
    PromoteExternalChild
    EmbedChild
    ExtractEmbeddedChildAsNewProject

A command declares:

    command ID
    target generation
    preconditions
    validation
    deterministic state transition
    inverse or compensating action
    affected semantic IDs
    dirty-set calculation
    audit description

10.4 Undo and redo

Use QUndoStack only as a presentation adapter over domain commands. The domain
command log remains testable without Qt. Undo never edits an already committed
VFS image in place; it creates a new project generation.

10.5 Safe project writes

Project files, settings, and small manifests use safe-write semantics:
write a replacement, flush, validate, and commit. A failed write leaves the
existing file intact.

10.6 Autosave

Autosave is an append-only recovery journal or a sequence of safe snapshots.
Opening recovery data never silently overwrites the user's selected project.
The Studio shows the recovered generation, base generation, command count, and
differences before promotion.

10.7 Schema migration

Migration reads an old project into an immutable model, produces a new candidate,
validates it, writes a new file, reopens it, and only then offers replacement.
The only original copy is never destroyed.

===============================================================================
11. PRESERVATION-FIRST VFS MUTATION MODEL
===============================================================================

11.1 Immutable source rule

Source directories, files, existing VFS images, and external child packages are
read-only build inputs. The Studio may cache fingerprints and metadata but does
not modify them.

11.2 Overlay rule

All intended changes are represented as overlay operations:

    ADD
    REPLACE
    METADATA_CHANGE
    TOMBSTONE
    MOUNT_CHANGE
    RULE_CHANGE

The resolved candidate namespace is:

    immutable base
    + ordered overlay
    + explicit mount semantics
    = candidate generation

11.3 No in-place image mutation

Even a one-byte change builds a new image generation. Incremental construction
may reuse unchanged blocks in staging or cache, but the final image is a new
coherent artifact.

11.4 Delete versus purge

DELETE
    Creates a tombstone in a new generation.

RESTORE
    Removes or compensates for the tombstone.

PURGE
    Physically removes unreferenced cached/staged content only after:
        reachability analysis
        retention-policy evaluation
        active-build check
        committed-generation check
        explicit report
        user-authorized operation where appropriate

A normal Delete key never performs irreversible garbage collection.

11.5 Staging transaction

Each build has a unique staging root:

    staging/<workspace>/<build-id>/

Workers may write only beneath their assigned staging subtree. The supervisor
owns the build ledger and final commit.

11.6 Commit protocol

    1. Freeze the project generation used for the build.
    2. Complete all required artifacts.
    3. Validate internal binary structure.
    4. Verify fingerprints and sizes.
    5. Reopen with an independent reader.
    6. Run generated Perl syntax/tests when enabled or required.
    7. Copy/test outside repository assumptions.
    8. Write a complete manifest and evidence ledger.
    9. Flush staged files.
    10. Atomically replace or install the destination.
    11. Reopen the committed destination and compare its fingerprint.
    12. Mark the generation committed.

Any failure before step 10 leaves the previous destination intact. A failure
after step 10 triggers verification and recovery logic; it does not claim success.

11.7 Retention

Keep at least the last known good committed generation until the new generation
has passed post-commit verification. Retention counts and storage limits are
explicit settings with visible consequences.

11.8 External tools

Perl tests and plugins receive staged copies or read-only paths. They do not
receive write authority over source inputs or the last known good destination.

===============================================================================
12. DETERMINISTIC DESIGN-TIME BUILD PIPELINE
===============================================================================

Canonical pipeline:

    PROJECT SNAPSHOT
        |
        v
    SOURCE DISCOVERY
        |
        v
    PATH CANONICALIZATION
        |
        v
    SOURCE INVENTORY + CONTENT IDENTITY
        |
        v
    OVERLAY APPLICATION
        |
        v
    FEDERATION GRAPH COMPILATION
        |
        v
    CYCLE / COLLISION / COMPATIBILITY VALIDATION
        |
        v
    CHILD BUILD ORDER (BOTTOM-UP)
        |
        v
    EXACT INDEX CONSTRUCTION
        |
        v
    VFS IMAGE ASSEMBLY
        |
        v
    EMBEDDED CHILD PACKING
        |
        v
    INTEGRITY CALCULATION
        |
        v
    PERL PACKAGE EMISSION
        |
        v
    STRUCTURAL VERIFICATION
        |
        v
    INDEPENDENT REOPEN
        |
        v
    PERL SYNTAX + GENERATED TESTS
        |
        v
    REPRODUCIBILITY CHECK
        |
        v
    ATOMIC EXPORT COMMIT

12.1 Source discovery

Discovery emits bounded batches of:

    source ID
    relative path bytes/text representation
    file type
    size
    stable platform metadata selected by policy
    symlink classification
    error state

Symlink following is off by default. When enabled, traversal remains within
declared roots unless an explicit trusted policy allows otherwise. Loops and
root escapes are detected.

12.2 Canonical virtual paths

Rules are platform-independent:

    - Forward slash separator.
    - Absolute virtual paths beginning with /.
    - No empty interior segment.
    - No . or .. segment after normalization.
    - NUL rejected.
    - Root escape impossible.
    - Unicode normalization policy recorded in the image.
    - Case policy explicit: sensitive, folded, or platform-compatibility profile.
    - Duplicate canonical path is an error unless a declared merge operation
      resolves it.

12.3 Content identity

Use a versioned cryptographic digest profile for payload identity. File metadata
may optimize rescan decisions, but metadata alone never proves unchanged bytes
when correctness requires content verification.

12.4 Deterministic parallelism

Workers may finish in any order. Canonical output order is determined only by
stable keys:

    project identity
    canonical virtual path
    entry type
    mount prefix
    child identity
    content fingerprint
    declared priority

Result merge sorts by those keys before serialization. Process IDs, task IDs,
completion order, and temporary paths are excluded from canonical artifacts.

12.5 Bottom-up federation build

A child must be validated and fingerprinted before a parent embeds or bundles it.
The dependency graph is topologically sorted. Independent siblings may build in
parallel. Parents wait only for declared child artifacts, not for unrelated
projects.

12.6 Incremental cache

Cache keys include:

    generator version
    format profile
    canonical source identity
    transform configuration
    child fingerprints
    index profile
    compression profile
    rule/policy fingerprint
    relevant compatibility flags

A cache hit returns immutable artifacts and evidence. Cache corruption is
detected by fingerprint verification and results in rebuild, not silent use.

12.7 Export transaction

Workers never stream directly into the final package directory. The staged
package tree is complete before commit.

===============================================================================
13. VFS BINARY FORMAT: FEDERATION IMAGE VERSION 2
===============================================================================

13.1 Goals

    - Exact random access.
    - Binary-safe payloads.
    - Deterministic serialization.
    - Independent section verification.
    - Strong nested embedded-child support.
    - Lazy bounded opening.
    - Forward-compatible optional sections.
    - Clear rejection of unknown required sections.
    - No serialized native pointers, compiler padding, or host ABI structures.

13.2 Byte order and widths

Canonical numeric encoding is little-endian with explicit fixed-width unsigned
and signed integers. Offsets and lengths use 64-bit fields unless a smaller
field is explicitly versioned. Arithmetic is checked before allocation or seek.

13.3 High-level image layout

    FIXED HEADER
    SECTION DIRECTORY
    STRING TABLE
    DIRECTORY TABLE
    ENTRY TABLE
    EXACT PATH INDEX
    MOUNT TABLE
    CHILD IMAGE DESCRIPTOR TABLE
    BLOCK TABLE
    DATA REGION
    EMBEDDED CHILD IMAGE REGION
    INTEGRITY TABLE
    OPTIONAL EXTENSION SECTIONS
    OPTIONAL FOOTER / WHOLE-IMAGE DIGEST

The section directory permits physical reordering while preserving logical
meaning.

13.4 Fixed header fields

    magic
    format major
    format minor
    header size
    flags
    image UUID
    package namespace ID
    build profile ID
    normalization policy ID
    case policy ID
    section directory offset
    section directory count
    root directory record ID
    entry count
    mount count
    embedded child count
    logical image size
    required capability bitmap
    optional capability bitmap
    header integrity reference

13.5 Section directory record

    section type
    section format major/minor
    flags
    absolute offset relative to image view
    stored length
    logical length
    record count
    alignment
    codec ID
    integrity reference

Unknown optional sections may be skipped. Unknown required sections cause a typed
compatibility failure.

13.6 Entry record

    stable entry ID
    parent directory ID
    canonical path string reference or index key reference
    basename string reference
    entry type
    flags
    mode/portable permissions policy
    logical length
    stored length
    data block reference
    data offset within block
    content digest reference
    metadata reference
    source provenance reference

13.7 Directory record

    directory ID
    parent directory ID
    basename reference
    first child range/reference
    child count
    first mount range/reference
    mount count
    flags
    metadata reference

13.8 Mount record

    mount ID
    parent image identity
    normalized mount prefix reference
    child identity
    child delivery mode
    child descriptor/external contract reference
    collision policy
    directory merge policy
    lazy/open policy
    compatibility requirement
    required capability bitmap
    expected child digest
    priority
    flags

13.9 Embedded child descriptor

    child descriptor ID
    child image UUID
    child package namespace ID
    parent-relative absolute offset
    stored length
    logical length
    child format major/minor
    required capabilities
    whole-child digest
    integrity reference
    compression/encryption profile IDs when permitted
    flags

The declared child range must lie wholly inside the parent's embedded-child
section and the parent image view. Integer overflow in base + offset + length is
a hard corruption error.

13.10 Exact index profiles

FAST
    Runtime loads a path-to-entry hash. Higher startup memory, fast repeated
    lookup.

COMPACT
    Runtime binary-searches a sorted fixed-record index and string table.

HYBRID
    Directory/prefix index plus bounded hot-entry cache.

No profile performs O(N) scanning for exact reads.

13.11 Payload blocks

Large payloads may be split into independently addressable blocks. A stream reads
only the required blocks. Block records include stored/logical lengths, codec,
digest, and data offset.

13.12 Compression

Baseline compatibility output is uncompressed. Optional codecs must declare the
exact Perl dependency required for decoding and must pass cross-language golden
vectors. A project cannot select a codec that its generated runtime profile
cannot read.

13.13 Encryption

Encryption is outside the initial baseline. It may be introduced only through a
reviewed authenticated-encryption design with key-management rules, dependency
contracts, test vectors, and threat model. Custom cryptography is forbidden.

13.14 Integrity

At minimum:

    header integrity
    section integrity
    payload content digests
    child-image whole-range digests
    package manifest fingerprint

A Merkle-style hierarchy may accelerate selective verification, but its exact
canonical encoding must be versioned and cross-language tested.

===============================================================================
14. FEDERATION RUNTIME MODEL
===============================================================================

14.1 Mount semantics

A mount delegates a normalized prefix from a parent to a child. The mount itself
may create virtual directory segments even when the parent has no physical entry
for those segments.

Example:

    Root
      /assets/logo.bin
      mount /plugins -> PluginVFS
      mount /tools   -> ToolVFS

A lookup of /plugins/editor/config.json is rewritten relative to PluginVFS as
/editor/config.json after the /plugins mount is selected.

14.2 Longest-prefix routing

At each image level:

    1. Normalize and validate the path once according to image policy.
    2. Find the longest matching mount prefix using an exact prefix structure.
    3. Apply the declared parent/mount collision policy.
    4. Open or reuse the child image.
    5. Rewrite the remaining path relative to the child root.
    6. Repeat until no deeper mount matches.
    7. Perform exact entry lookup in the owning image.
    8. Return a bounded entry/stream descriptor.

A generic regex scan is not the mount router.

14.3 Collision policies

ERROR
    Any conflicting parent entry, child entry, or mount namespace fails
    validation.

PARENT_WINS
    Parent entry is visible; child remains reachable only where no conflict
    exists or through an explicit alternate mount.

CHILD_WINS
    Child owns the mounted namespace.

MERGE_DIRECTORIES
    Directory listings merge while file-file and file-directory conflicts use a
    separately declared rule.

EXPLICIT_TABLE
    Project contains exact conflict decisions for named paths.

Default is ERROR.

14.4 Directory listings

list() returns the virtual namespace, not merely the parent image's physical
directory records. It merges:

    local child names
    virtual mount segments
    delegated child names
    overlay additions/tombstones
    declared collision behavior

Ordering is deterministic and documented.

14.5 Cycles

Design-time federation must be a DAG. Detect cycles by stable project identity
before build. Runtime also keeps an ancestry set of image identity plus digest
to reject hostile external or malformed recursive references.

14.6 Depth and resource budgets

Defaults are explicit and configurable within hard ceilings:

    maximum mount depth
    maximum simultaneously open child images
    maximum total section count
    maximum total decoded strings
    maximum listing result size
    maximum rule evaluations
    maximum decompressed bytes
    maximum trace steps

Budget exhaustion returns a typed error; it never falls back to unsafe parsing.

14.7 Lazy child loading

Mount metadata loads with the parent. Child headers/indexes open on first access
unless an eager policy is selected. Caches are bounded and keyed by immutable
image identity/fingerprint.

14.8 Compatibility

Parent requirements are compared with child format version, capability bitmap,
normalization policy, case policy, and runtime profile. An incompatible child is
reported before export whenever the child is available at design time.

14.9 Unified public API

The root object provides one interface across local, bundled, embedded, and
external children. Callers do not manually open each nested package for normal
resolution.

===============================================================================
15. STRONG EMBEDDED VFS-WITHIN-VFS ARCHITECTURE
===============================================================================

15.1 Core rule

An embedded child remains a complete VFS image. It is not flattened into parent
tables and is not treated as an opaque payload that must be extracted before use.

This allows:

    root.vfsbin
      contains child-a.vfsbin
        contains grandchild-a1.vfsbin
      contains child-b.vfsbin
        contains grandchild-b1.vfsbin
          contains great-grandchild-b1x.vfsbin

Every level has its own header, sections, indexes, mounts, payloads, and integrity
records.

15.2 Bounded ImageView

Opening a child creates:

    ImageView(
        backing = same parent file/mmap/scalar,
        base_offset = parent_view.base_offset + descriptor.offset,
        length = descriptor.length,
        expected_digest = descriptor.digest,
        ancestry = parent ancestry + child identity
    )

Every child-relative seek is checked:

    relative_offset <= view.length
    requested_length <= view.length - relative_offset

Only then is the absolute backing offset calculated. Checked arithmetic rejects
overflow.

15.3 No-extraction operation

Normal read, stat, list, seek, verify, and nested mount resolution operate
directly against bounded child views. No temporary child file is required.

Optional explicit extraction is a user command that writes a new artifact,
verifies it, and never changes the parent image.

15.4 Independent child truth

The embedded bytes can be verified as a child image independently of the parent.
The parent descriptor proves which exact child bytes were embedded. The child
header proves its own internal structure.

15.5 Integrity chain

For a path in a grandchild:

    root package manifest
        -> root image digest
        -> root child descriptor digest
        -> child image digest
        -> child mount descriptor
        -> grandchild descriptor digest
        -> grandchild image section/entry digest
        -> payload digest

resolve_trace() exposes this chain without requiring callers to trust a textual
claim.

15.6 Build order

Embedded federation is built bottom-up:

    build deepest children
    verify deepest children
    build their parents with exact child byte ranges
    verify parents
    continue to root
    emit final package
    independently reopen from root

Siblings build in parallel; ancestry order remains deterministic.

15.7 Mutation semantics

Editing an embedded child does not patch bytes inside a committed parent.

    1. Create a new child generation.
    2. Build and verify the new child image.
    3. Create a new parent generation embedding that child.
    4. Continue upward to root as required.
    5. Commit the new root package atomically.

This is the central preservation-first rule for VFS within VFS.

15.8 Deduplication

A future image profile may store identical child images or payload blocks once in
a content-addressed region and reference them from multiple mounts. The baseline
uses straightforward contiguous child ranges. Deduplication must never create
ambiguous ownership, mutable aliasing, or cyclic offset graphs.

15.9 Recursive caching

Cache key:

    backing fingerprint
    absolute base offset
    view length
    child digest
    format version

A cached child object is immutable. Eviction closes only its view/cache state,
not the shared backing artifact.

15.10 Deep federation tests

Required fixtures include:

    depth 1, 2, 8, 32
    sibling embedded children
    mixed bundled and embedded ancestry
    duplicate child image at different mounts
    corrupt child length
    child offset before section
    child end beyond parent
    integer-overflow descriptor
    wrong child digest
    wrong child magic
    incompatible child version
    external-reference cycle
    deep listing across virtual directories
    range reads spanning payload blocks
    cancellation during parent packing
    worker crash after child verification but before parent commit

15.11 Runtime pseudocode

    resolve(path):
        view = root_view
        relative = normalize(path)
        ancestry = empty

        while true:
            verify_view_header_if_needed(view)
            mount = view.mount_index.longest_prefix(relative)

            if mount exists:
                apply_collision_policy(view, mount, relative)
                child_view = open_child_view(view, mount, ancestry)
                ancestry.add(child_view.identity_and_digest)
                relative = strip_mount_prefix(relative, mount.prefix)
                view = child_view
                continue

            entry = view.exact_index.lookup(relative)
            return bounded_entry(view, entry)

15.12 Completion gate

Embedded support is not complete until a deeply nested file is read directly
from a bounded grandchild range inside one root .vfsbin, without extraction,
without whole-image loading, and with the same result in the Python reference
reader and generated Perl runtime.

===============================================================================
16. GENERATED PERL PACKAGE CONTRACT
===============================================================================

16.1 Baseline output

Default compatibility profile:

    Pure Perl
    Perl 5.10+ syntax profile
    No XS requirement
    No Python requirement
    No PySide6 requirement
    No Studio requirement
    No network requirement
    Core-module dependencies only where practical
    Optional acceleration profiles declared separately

A modern Perl profile may use newer syntax or optional modules, but it is an
explicit generator choice and cannot silently replace the compatibility profile.

16.2 Recommended generated package layout

    VFS-Demo-1.0.0/
      lib/
        VFS/
          Demo.pm
          Demo/
            Runtime.pm
            Image.pm
            Image/
              View.pm
              Section.pm
            Index.pm
            Index/
              Hash.pm
              Sorted.pm
              Hybrid.pm
            Federation.pm
            Resolver.pm
            Mount.pm
            Entry.pm
            Directory.pm
            Stream.pm
            Integrity.pm
            Manifest.pm
            Rules.pm
            Error.pm
      share/
        vfs-demo/
          root.vfsbin
          children/
            bundled-assets.vfsbin
            bundled-tools.vfsbin
      examples/
        basic.pl
        list_tree.pl
        range_read.pl
        nested_mount.pl
        embedded_child.pl
        trace_path.pl
        verify_package.pl
      t/
        00-load.t
        01-open.t
        02-read-text.t
        03-read-binary.t
        04-exists-stat.t
        05-list.t
        06-stream-seek.t
        07-integrity.t
        08-bundled-mount.t
        09-embedded-mount.t
        10-deep-federation.t
        11-collisions.t
        12-invalid-paths.t
        13-corrupt-bounds.t
        14-compatibility.t
        15-trace.t
        16-deterministic-fixtures.t
      Makefile.PL
      MANIFEST
      META.json
      README.md
      LICENSE
      Changes

A compact single-module profile may be offered for small packages only after the
modular profile is complete and tested.

16.3 Public object API

    my $vfs = VFS::Demo->open();

    my $bytes = $vfs->read('/assets/logo.bin');

    my $slice = $vfs->read_range(
        '/media/large.dat',
        offset => 4096,
        length => 8192,
    );

    my $ok    = $vfs->exists('/plugins/editor/config.json');
    my $stat  = $vfs->stat('/plugins/editor/config.json');
    my @names = $vfs->list('/plugins/editor');

    my $stream = $vfs->open_file('/media/large.dat');
    my $n = $stream->read($buffer, 65536);
    $stream->seek(1024, 0);
    my $pos = $stream->tell();
    my $eof = $stream->eof();
    $stream->close();

    my $trace = $vfs->resolve_trace(
        '/embedded/grandchild/data.bin'
    );

    my $mounts = $vfs->mounts();
    my $check  = $vfs->verify();
    my $report = $vfs->verify(path => '/embedded');

16.4 Return behavior

read()
    Returns exact payload bytes. Text decoding is a caller concern unless an
    explicitly generated text helper with a declared encoding is used.

read_range()
    Returns exact bytes within logical entry bounds. Out-of-range requests fail
    with a typed error.

exists()
    Returns a boolean for not-found. Corruption and compatibility failures are
    not converted into false.

stat()
    Returns documented stable keys including type, logical size, fingerprint,
    owner image, mount ancestry, and selected metadata.

list()
    Returns deterministic child names or documented entry objects.

resolve_trace()
    Returns structured steps, not only formatted text.

verify()
    Returns a structured report with checked scopes, pass/fail state,
    diagnostics, and fingerprints.

16.5 Binary behavior

All backing files are opened in binary mode. Offset arithmetic is integer-only
and bounds-checked. sysread/read/seek behavior is tested with:

    every byte value 0x00 through 0xFF
    NUL-containing payloads
    CR/LF/CRLF mixes
    executable and archive fixtures
    random payloads
    multi-block range reads
    large offsets where platform support permits

16.6 Image loading modes

FILE
    Read from a .vfsbin path using seek/read and bounded views.

MEMORY
    Read from a scalar containing the exact image bytes.

MMAP-OPTIONAL
    Optional adapter profile when a declared dependency is available.

EMBEDDED VIEW
    Read a child directly from a bounded range of the parent backing object.

The public behavior remains equivalent across modes.

16.7 Package discovery

The generated root module locates its share data through a deterministic,
documented strategy. Build tests copy the package outside the Studio repository
to prove it does not depend on source-tree relative paths.

16.8 Typed errors

Generated errors expose stable codes such as:

    VFS_E_NOT_FOUND
    VFS_E_INVALID_PATH
    VFS_E_CORRUPT_HEADER
    VFS_E_CORRUPT_SECTION
    VFS_E_BOUNDS
    VFS_E_DIGEST
    VFS_E_UNSUPPORTED_VERSION
    VFS_E_REQUIRED_CAPABILITY
    VFS_E_MOUNT_CYCLE
    VFS_E_DEPTH
    VFS_E_COLLISION
    VFS_E_EXTERNAL_CHILD
    VFS_E_CODEC
    VFS_E_CLOSED_STREAM

Error text is useful to humans, but callers may rely on documented codes and
structured fields.

16.9 Generated code rules

    - use strict and warnings;
    - stable formatting;
    - deterministic symbol ordering;
    - no eval-generated source;
    - no runtime network fetch;
    - no arbitrary module loading from image content;
    - no temporary extraction for normal embedded access;
    - no unchecked unpack length/count;
    - no O(N) exact lookup;
    - documented private/public boundary;
    - source comments identify generator and format versions;
    - user extension hooks are explicit and regeneration-safe.

16.10 Export verification

A generated package is operational only when:

    perl -c passes for every generated module;
    prove passes the generated suite;
    the package is copied to an independent temporary location;
    root and nested embedded paths reopen there;
    binary fixtures compare byte-for-byte;
    stream seek/tell behavior passes;
    collision/cycle/corruption fixtures fail correctly;
    the package manifest matches emitted files;
    repeated generation produces the same canonical fingerprint.

===============================================================================
17. GENERATED PERL INTERNAL RESPONSIBILITIES
===============================================================================

VFS::Demo
    Public constructor and documented facade.

VFS::Demo::Runtime
    Runtime configuration, limits, cache ownership, and shared services.

VFS::Demo::Image
    Parses and validates one image header/section directory.

VFS::Demo::Image::View
    Bounded backing-range abstraction. Converts checked child-relative offsets
    to backing offsets. This is the foundation of embedded VFS operation.

VFS::Demo::Image::Section
    Validated section descriptor and bounded record access.

VFS::Demo::Index
    Profile-independent exact lookup interface.

VFS::Demo::Index::Hash
    Fast in-memory map profile.

VFS::Demo::Index::Sorted
    Compact binary-search profile.

VFS::Demo::Index::Hybrid
    Prefix/directory index plus bounded cache.

VFS::Demo::Federation
    Mount catalog, child provider registry, compatibility, and cache.

VFS::Demo::Resolver
    Longest-prefix routing, path rewriting, collision policy, depth/ancestry
    budgets, and structured trace production.

VFS::Demo::Mount
    Immutable mount descriptor.

VFS::Demo::Entry
    Immutable file/directory/metadata descriptor.

VFS::Demo::Directory
    Virtual listing merge across local entries, mounts, and children.

VFS::Demo::Stream
    Binary range reader with read, seek, tell, eof, and close.

VFS::Demo::Integrity
    Header, section, payload, child, and whole-image verification.

VFS::Demo::Manifest
    Package-level artifact identities, versions, fingerprints, and capabilities.

VFS::Demo::Rules
    Compiled safe routing/alias policy tables after exact and mount lookups.

VFS::Demo::Error
    Typed exceptions/errors with stable codes and context.

17.1 Provider contract

Bundled, embedded, and external children implement one internal provider
interface:

    describe_child(mount)
    open_child(mount, parent_view, ancestry, limits)
    verify_child(mount, child_view)
    close_child(child_handle)

Embedded provider returns an Image::View over the parent backing. Bundled
provider returns a file-backed root view. External provider calls an explicitly
registered resolver and verifies returned identity/fingerprint before use.

17.2 No hidden global mutable state

Runtime caches belong to a root runtime instance. Tests can create independent
roots in one process without cross-contamination. Global constants are
immutable format definitions only.

17.3 Trace structure

Each trace step records:

    sequence
    image identity
    image-view base/length
    input path
    normalized/relative path
    operation
    index or mount record ID
    policy decision
    child identity
    integrity check
    result or error

This lets the IDE render the same semantics as the Perl runtime.

===============================================================================
18. RULES, REGEX, AND POLICY
===============================================================================

18.1 Correct role

Regex is appropriate for:

    aliases
    rewrites
    controlled policy matching
    procedural virtual entries
    search
    validation
    exceptional fallback

Regex is not the primary exact entry index.

18.2 Resolution order

Default order:

    path validation/normalization
    exact mount-prefix lookup
    collision policy
    child delegation
    exact entry lookup
    exact alias table
    scoped regex rewrite rules
    approved procedural provider
    not found

Projects may select a documented alternate profile only when Python simulation
and Perl runtime parity tests exist.

18.3 Safety

Rules declare scope, priority, action, maximum applications, and whether they may
cross a mount boundary. Detect:

    rewrite loops
    explosive pattern behavior
    repeated zero-length progress
    output root escape
    invalid replacement path
    mount-boundary violation
    excessive trace length

18.4 Procedural entries

Not part of the baseline. Future providers run behind capability and resource
budgets. Opening a project never executes arbitrary Perl or Python.

===============================================================================
19. SECURITY AND WORKSPACE TRUST
===============================================================================

19.1 Trust states

UNTRUSTED
    Project is parsed and inspected. External commands, plugins, symlink escape,
    and executable hooks are disabled.

TRUSTED FOR LOCAL SOURCES
    Declared local roots may be scanned under path policy.

TRUSTED FOR TOOLS
    Known Perl validation commands may run.

TRUSTED FOR PLUGINS
    Approved plugin manifests may load in isolated hosts.

Trust is per workspace and visible.

19.2 Path safety

All source paths are resolved and checked against declared roots. Virtual paths
are independently normalized. Source-path and virtual-path semantics are never
confused.

19.3 Export safety

Export refuses:

    destination inside a protected source root unless explicitly designed;
    traversal through symlinked destination components under unsafe policy;
    overwrite of unrelated non-package content without explicit confirmation;
    commit with incomplete evidence;
    final paths derived from unsanitized package metadata.

19.4 Tool invocation

Use executable plus argument list. Do not construct shell command strings.
Capture stdout/stderr separately and bound retained output. Timeouts and
environment allow-lists are explicit.

19.5 Image parsing

Before allocation or seek:

    validate magic/version
    validate header length
    validate section count
    check offset + length overflow
    check range containment
    check record count * record size overflow
    enforce decompression budgets
    verify required capabilities
    reject overlapping required sections unless format permits them

19.6 Integrity versus authenticity

Checksums and digests detect corruption and identify bytes. They do not prove who
created a package. Signing is a separate future capability with key management,
trust policy, revocation, and reproducible unsigned payload rules.

19.7 Plugin isolation

Plugins receive capability-scoped APIs and immutable snapshots. They do not
receive unrestricted access to GUI internals, supervisor state, source roots, or
final destinations.

===============================================================================
20. PERFORMANCE ARCHITECTURE
===============================================================================

20.1 UI responsiveness

The GUI thread performs only bounded presentation work. Target:

    pointer/keyboard response remains immediate during builds;
    no synchronous filesystem recursion;
    no large JSON parse on the GUI thread;
    no whole-project model reset for a small change;
    no per-cell widgets in large views;
    no blocking waitForFinished in interactive code.

20.2 Model/view scaling

Use QAbstractItemModel, QSortFilterProxyModel, delegates, stable IDs, and paged
snapshots. Updates are row/range-specific when practical. Large trees load
children lazily.

20.3 Parallel build lanes

Separate CPU-heavy and I/O-heavy tasks. A single spinning disk may benefit from
lower discovery/read concurrency than an SSD. Scheduler profiles are measured,
not assumed.

20.4 Zero/low-copy strategy

    - mmap or bounded file views for large immutable artifacts;
    - shared memory for sealed dense tables;
    - small control messages;
    - chunked hashing and writing;
    - no duplicate byte arrays in GUI models;
    - no whole embedded-child extraction;
    - no whole image load merely to read one entry.

20.5 Exact lookup gates

Representative gates after warm open:

    exact path lookup scales logarithmically or amortized constant according to
    selected profile;
    mount selection scales with path segments/prefix index, not total mounts;
    child opening reads only header/index sections required by profile;
    a deep lookup opens only ancestry images needed for that path.

Absolute numbers are established by benchmark fixtures on declared hardware.
The roadmap does not invent unsupported speed claims.

20.6 Incremental invalidation

Changes invalidate the smallest proven dependency set:

    payload edit
        payload block, entry digest, affected indexes/sections, ancestor image
        generations that embed the changed child.

    metadata edit
        relevant metadata/entry sections and ancestor embedded generations.

    mount edit
        parent mount/index sections and affected ancestors.

    UI layout edit
        no build artifacts.

20.7 Benchmark fixtures

    1K, 100K, and 1M entries where practical;
    many tiny files;
    few huge files;
    deep directories;
    32-level federation;
    thousands of mounts;
    binary mix;
    embedded-child heavy package;
    cold and warm cache;
    single-worker and scaled worker counts;
    cancellation under load;
    corrupt hostile headers.

20.8 Memory gates

Track peak resident memory by process role. The GUI has a separate budget from
workers. A worker exceeding its declared budget fails the task with evidence;
the scheduler may retry with a lower-concurrency or streaming profile.

20.9 Benchmark honesty

Every performance claim records:

    commit/generator version
    platform
    CPU
    storage type
    memory
    Python/PySide6 version
    Perl version
    worker count
    dataset fingerprint
    cold/warm state
    repetitions
    central tendency and spread
    validation result

===============================================================================
21. DIAGNOSTICS AND OBSERVABILITY
===============================================================================

21.1 Structured diagnostic

Each diagnostic contains:

    code
    severity
    category
    message
    workspace/project/generation
    semantic target ID
    virtual path and source path where applicable
    build/task/worker ID
    source location or binary offset
    evidence
    remediation
    caused-by chain
    timestamp for observation only
    deduplication key

Canonical build output does not contain diagnostic timestamps.

21.2 Required categories

    PROJECT_SCHEMA
    SOURCE_IO
    PATH
    OVERLAY
    FEDERATION
    MOUNT
    COLLISION
    CYCLE
    COMPATIBILITY
    FORMAT
    BOUNDS
    INTEGRITY
    BUILD
    CACHE
    IPC
    WORKER
    PERL
    PLUGIN
    SECURITY
    PERFORMANCE
    COMMIT
    RECOVERY

21.3 Build event stream

Events include:

    build planned
    task queued/started/progress/completed
    cache hit/miss/rejected
    artifact staged
    image section written
    child embedded
    structural verification passed/failed
    independent reopen passed/failed
    Perl syntax/test result
    cancellation requested/acknowledged/escalated
    commit started/completed/failed
    recovery action

21.4 Bounded observation

Progress is coalesced. Telemetry may drop under pressure. Errors and gate changes
are durable in the build evidence ledger.

21.5 Explainability parity

The Python reference resolver and generated Perl resolver produce comparable
structured traces for golden paths. The UI's Path Resolution Lens renders those
records rather than inventing a separate visual interpretation.

===============================================================================
22. TESTING STRATEGY
===============================================================================

22.1 Unit tests

    path normalization
    typed IDs
    immutable commands
    overlay resolution
    cycle detection
    longest-prefix routing
    collision policies
    section/record encoding
    bounded ImageView arithmetic
    index profiles
    generation/stale-result logic
    IPC framing/schema limits
    commit/recovery states
    Perl name/package generation

22.2 Contract tests

    Python writer <-> Python reader
    Python writer <-> generated Perl reader
    Python resolver <-> generated Perl resolver
    project schema migrations
    IPC major/minor negotiation
    plugin capability negotiation
    CLI <-> GUI semantic service parity

22.3 Golden packages

Store small canonical projects with expected:

    project snapshot
    runtime graph
    image bytes
    section map
    package tree
    generated Perl source
    manifests
    traces
    test output classifications
    fingerprints

Golden updates require reviewed diffs.

22.4 Property tests

    normalize(normalize(path)) == normalize(path)
    no valid entry range escapes its ImageView
    encode/decode round-trip
    read_range equals source slice
    listing order deterministic
    repeated build fingerprint stable
    any child descriptor accepted by reader is fully contained
    collision policies satisfy declared invariants
    cancellation never changes last committed fingerprint
    stale worker results never alter current generation

22.5 Fuzzing

Fuzz:

    project schemas
    path strings
    headers
    section directories
    counts/lengths
    mount tables
    embedded child descriptors
    nested image depth
    compressed sizes
    Perl trace fixtures

Assertions:

    no uncontrolled allocation
    no out-of-bounds read
    no infinite loop
    no source mutation
    no false successful verification
    stable typed failure

22.6 Multiprocessing tests

    spawn on Windows, macOS, and Linux;
    frozen and source modes;
    worker crash at every build stage;
    supervisor restart;
    stale result arrival;
    queue backpressure;
    shared-memory consumer crash;
    cancellation before/during/after output creation;
    concurrent independent builds;
    same-project serialized commit;
    process count and resource ceilings.

22.7 UI tests

Use Qt test tooling and headless/offscreen execution where supported:

    action enablement
    command palette
    dock persistence
    model paging
    selection/cross-navigation
    cancellation UI
    recovery presentation
    trust transitions
    diagnostic navigation
    high-DPI layouts
    accessibility names
    no blocked event loop during build fixture

22.8 Generated Perl tests

Each output package contains its own Test::More suite. Repository tests also run
generated packages under the supported Perl matrix.

22.9 Corruption corpus

Maintain named fixtures for:

    bad magic
    truncated header
    oversized section count
    overlapping sections
    bad record size
    offset overflow
    child outside parent
    invalid child digest
    recursive external cycle
    unsupported codec
    invalid UTF/path policy
    wrong package manifest
    interrupted staged export

22.10 Definition of an operational package

Operational means the exported package, after being copied to a clean location:

    loads;
    locates its data;
    opens the root image;
    resolves local and nested paths;
    reads exact binary bytes;
    seeks correctly;
    lists virtual directories;
    verifies integrity;
    reports typed failures;
    passes generated tests;
    requires no Studio process.

===============================================================================
23. PLUGIN ARCHITECTURE
===============================================================================

23.1 Plugin categories

    source provider
    transform
    validator
    codec
    visual panel
    report exporter
    external child resolver
    future emitter

23.2 Versioned manifest

    plugin ID/version
    API version range
    entry point
    capabilities
    permissions
    deterministic declaration
    process-isolation requirement
    dependency/license information
    configuration schema
    output artifact types

23.3 Isolation

Untrusted or high-risk plugins run in a plugin host process. Plugin messages use
the same bounded schema discipline as worker IPC.

23.4 Determinism

A plugin affecting canonical output must either be deterministic under declared
inputs or mark the build nondeterministic. Nondeterministic output cannot be
presented with the ordinary reproducibility guarantee.

23.5 Perl emitter protection

The first-party Perl emitter is a product-critical component, not a casual
plugin. Third-party emitters cannot change the semantics of first-party Perl
output or its tests.

===============================================================================
24. IMPLEMENTATION ROADMAP PHASES
===============================================================================

Every phase ends with executable evidence. Version labels are provisional until
repository history and release policy assign exact numbers.

24.0 Milestone vocabulary and execution groove

Numbered phases retain their original meaning. In particular, RM-P4 means the
multi-process supervisor/build scheduler; it never means neural training.

Implementation follows five dependency rails that may have evidence at different
depths without being confused for completed phases:

    FOUNDATION
        IDE shell, Chronicle workspace, commands, history, editors, trust.

    RUNTIME
        deterministic images, federation, bounded embedded children, Perl.

    SCHEDULER
        authenticated processes, lanes, ledgers, restart, recovery, budgets.

    INSTRUMENTS
        Lens, Map, X-Ray, Stack, Diff, Release View, cross-navigation.

    MONK
        policy, Loom evidence, Spindle extraction, direct training, review.

The development groove is vertical and preservation-first:

    persist truth -> edit truth -> schedule work -> verify artifacts
    -> inspect evidence -> review proposals -> commit separately

No rail can borrow a completion claim from another. Current conformance is
recorded in docs/architecture/ROADMAP_CONFORMANCE_v1.0.0a4.md.


-------------------------------------------------------------------------------
PHASE 0 - PRODUCT CONSTITUTION AND ARCHITECTURE PROOFS
-------------------------------------------------------------------------------

Goals:
    Freeze the product truth and prove the riskiest boundaries before broad UI
    work.

Deliverables:
    architecture decision records
    project/federation terminology
    preservation-first transaction contract
    PySide6 shell spike
    QProcess-launched supervisor spike
    QLocalSocket framed IPC spike
    spawn-safe worker spike on all target platforms
    frozen helper-process packaging spike
    bounded ImageView reference implementation
    Python writer/reader mini image
    minimal generated Perl reader
    embedded child no-extraction proof
    reproducibility proof
    threat model and resource budgets

Exit gate:
    A PySide6 window launches a separate supervisor, submits a spawn-safe task,
    builds a tiny root image containing a child image, and reads one child file
    through both Python and Perl with identical bytes. Cancelling the build
    leaves a pre-existing destination unchanged.

-------------------------------------------------------------------------------
PHASE 1 - DESIGN SYSTEM AND NATIVE IDE SHELL
-------------------------------------------------------------------------------

Goals:
    Establish the professional PySide6 workspace without pretending the product
    engine is complete.

Deliverables:
    QMainWindow shell
    menus/toolbars/status bar
    activity rail
    custom SVG icon system
    theme tokens and density modes
    dock framework
    tab manager
    command registry/palette
    settings and named layouts
    accessibility baseline
    empty-state and trust-state UX
    crash-safe UI settings writes

Exit gate:
    Layouts restore across sessions, commands are keyboard accessible, high-DPI
    checks pass, and no large build operation exists in the GUI thread.

-------------------------------------------------------------------------------
PHASE 2 - DOMAIN MODEL, COMMANDS, PROJECT STORAGE, AND HISTORY
-------------------------------------------------------------------------------

Goals:
    Make the workspace model authoritative and fully headless-testable.

Deliverables:
    typed IDs
    immutable project snapshots
    source/mount/rule/build-profile models
    command bus
    undo/redo adapter
    dirty dependency sets
    project schema
    migrations
    safe writes
    autosave/recovery journal
    generation history
    trust metadata
    Chronicle document and audit chain
    review-only external/neural proposal registry

Exit gate:
    A workspace with root/children/mounts saves, reopens, migrates, undoes,
    redoes, recovers from an interrupted save, and produces the same canonical
    project fingerprint through GUI and CLI services.

-------------------------------------------------------------------------------
PHASE 3 - FEDERATION EDITORS AND REFERENCE RESOLVER
-------------------------------------------------------------------------------

Goals:
    Make explicit namespace composition correct before package generation grows.

Deliverables:
    Federation Explorer model
    virtual namespace model
    mount table editor
    federation graph
    canonical path engine
    longest-prefix router
    collision policies
    cycle/depth validation
    structured resolution trace
    bundled/embedded/external domain modes
    Python reference resolver
    trace parity fixtures

Exit gate:
    Root, child, and grandchild projects resolve all golden paths with exact
    ownership, collisions, directory listings, and typed failures.

-------------------------------------------------------------------------------
PHASE 4 - MULTI-PROCESS SUPERVISOR AND BUILD SCHEDULER
-------------------------------------------------------------------------------

Goals:
    Move all substantial work behind a robust process boundary.

Naming rule:
    This is RM-P4. Monk Loom milestones use MONK-M identifiers.

Deliverables:
    QProcess supervisor lifecycle
    authenticated local IPC
    protocol negotiation
    task/result schemas
    CPU and I/O lanes
    worker pool
    generation/stale-result rejection
    bounded progress/diagnostics
    shared-buffer ledger
    cancellation ladder
    worker restart
    supervisor recovery
    resource budgets
    process observatory

Exit gate:
    Large discovery/hash fixtures run without UI stalls. Worker crashes and
    cancellations are contained. No stale result changes the active generation.

-------------------------------------------------------------------------------
PHASE 5 - DETERMINISTIC SINGLE-VFS IMAGE ENGINE
-------------------------------------------------------------------------------

Goals:
    Generate one complete, independently verifiable VFS image.

Deliverables:
    source scanner
    overlay compiler
    deterministic ordering
    version 2 header/sections
    string/directory/entry tables
    fast/compact indexes
    block writer
    integrity records
    reader and Package X-Ray decoder
    incremental cache
    staged export
    independent verifier
    reproducibility fingerprints

Exit gate:
    Mixed text/binary projects build byte-identically, round-trip every fixture,
    and never alter an existing destination on failure.

-------------------------------------------------------------------------------
PHASE 6 - OPERATIONAL PERL RUNTIME AND PACKAGE EMITTER
-------------------------------------------------------------------------------

Goals:
    Make generated Perl a supported independent product.

Deliverables:
    root facade
    Image and Image::View
    section/index readers
    Entry/Directory/Stream
    Integrity and Error
    read/read_range/exists/stat/list/open_file
    package discovery
    Makefile.PL/MANIFEST/META.json
    README/examples
    generated Test::More suite
    Perl source preview/source maps
    perl -c/prove integration
    independent-copy test

Exit gate:
    A generated single-VFS package passes the supported Perl matrix outside the
    repository and reads all binary fixtures exactly.

-------------------------------------------------------------------------------
PHASE 7 - BUNDLED AND EXTERNAL FEDERATION
-------------------------------------------------------------------------------

Goals:
    Prove multi-package routing before embedding every child into one image.

Deliverables:
    mount table runtime
    Federation/Resolver modules
    bundled provider
    external provider contract
    lazy child opening
    collision/directory semantics
    compatibility checks
    cycle/depth defenses
    Python/Perl trace parity
    nested generated tests

Exit gate:
    Root mounts at least three children, one of which mounts a grandchild.
    Reads, lists, stats, range reads, and seeks cross boundaries correctly.

-------------------------------------------------------------------------------
PHASE 8 - STRONG EMBEDDED VFS-WITHIN-VFS
-------------------------------------------------------------------------------

Goals:
    Deliver true recursive image-inside-image operation without extraction.

Deliverables:
    child descriptor table
    embedded child region
    bounded ImageView in Python and Perl
    parent/child integrity chain
    bottom-up parallel builder
    recursive lazy caches
    ancestor rebuild invalidation
    embedded image stack UI
    hostile-bounds tests
    depth/resource budgets
    explicit extraction command
    deeply nested fixtures

Exit gate:
    A root image contains a child, grandchild, and great-grandchild. A file in
    the deepest image is read through one root file by Python and Perl without a
    temporary child file or unrelated payload loading. Corrupt bounds are
    rejected before read.

-------------------------------------------------------------------------------
PHASE 9 - SIGNATURE IDE INSTRUMENTS
-------------------------------------------------------------------------------

Goals:
    Make invisible runtime truth directly inspectable.

Deliverables:
    Path Resolution Lens
    Federation Map
    Package X-Ray
    Embedded Image Stack
    Manifest Diff
    generated Perl cross-navigation
    binary byte-range highlighting
    pinned traces
    path comparison
    Release View

Exit gate:
    Selecting any resolved entry navigates coherently among source asset, virtual
    path, graph node, mount chain, image views, index record, payload range,
    integrity chain, and generated Perl resolver.

-------------------------------------------------------------------------------
PHASE 10 - RULE LAB AND CONTROLLED POLICY ENGINE
-------------------------------------------------------------------------------

Goals:
    Add aliases/rewrites/policies without damaging exact lookup or safety.

Deliverables:
    rule schema
    scoped evaluation
    alias table
    regex safety checks
    loop/application limits
    Rule Lab
    generated Perl rule table
    parity tests
    performance warnings
    trace integration

Exit gate:
    Exact paths bypass irrelevant rules and every approved policy fixture produces
    the same structured result in Python and Perl.

-------------------------------------------------------------------------------
TRACK MONK - DETERMINISTIC ADVISORY INTELLIGENCE
-------------------------------------------------------------------------------

This is a cross-cutting product track, not a replacement for RM-P0..RM-P12.

Purpose:
    Give a VFS an optional, configurable, deterministic advisory model whose
    evidence can be reproduced in Python and Pure Perl, while Monk policy,
    integrity verification, reviewed commands, and supervisor commit authority
    remain authoritative.

Evidence-backed milestones:
    MONK-M1
        Canonical fixed-point Loom attachment, deterministic inference,
        verified-head proposal-only adaptation, Python/Perl parity.

    MONK-M2
        Monk Spindle recipes, explicit verified VFS corpus, direct bounded
        training, canonical report, worker progress/cancellation.

Next milestones:
    MONK-M3
        Chronicle-backed proposal registration, evidence review, explicit
        accept/reject/supersede decisions, no implicit application.

    MONK-M4
        Graphical model/corpus/report workbench built over Chronicle and RM-P4.

    MONK-M5
        Cryptographic verifier identities, rollout/rollback policy, adversarial
        and scale qualification.

Track gate:
    A candidate may be trained, fingerprinted, registered, reviewed, rejected or
    accepted, and later applied through an ordinary verified workspace/build
    command. No model output can bypass policy or promote itself.

-------------------------------------------------------------------------------
PHASE 11 - SCALE, FUZZING, SECURITY, AND RECOVERY
-------------------------------------------------------------------------------

Goals:
    Qualify large projects and hostile inputs.

Deliverables:
    incremental invalidation
    large model paging
    cache compaction
    memory budgets
    multiprocessing stress matrix
    binary/project fuzzing
    corruption corpus
    cancellation/crash matrix
    untrusted workspace mode
    plugin-host isolation
    packaging/install tests
    security review
    performance methodology

Exit gate:
    Large fixtures remain responsive and bounded. Malformed inputs fail safely.
    Interrupted operations preserve the last committed generation.

-------------------------------------------------------------------------------
PHASE 12 - PLUGIN SDK, DOCUMENTATION, AND 1.0 RELEASE
-------------------------------------------------------------------------------

Goals:
    Stabilize public contracts and ship a complete product.

Deliverables:
    versioned plugin API
    first-party source/validator plugins
    example federations
    project templates
    VFS format specification
    Perl API reference
    multiprocessing guide
    security model
    recovery guide
    migration guide
    performance report
    installers
    signing/notarization as applicable
    dependency/license report
    reproducible release artifacts

Exit gate:
    A new user can install the Studio, open an example, inspect a nested embedded
    path, edit a mount, export the Perl package, and pass its tests using only
    shipped documentation.

===============================================================================
25. PRIORITY BACKLOG
===============================================================================

P0 - PRODUCT TRUTH

    Preservation-first staging/commit
    Safe project writes and recovery
    Deterministic single-VFS image
    Exact index lookup
    Binary-safe range reads
    Independent verifier
    Operational Perl runtime
    Spawn-safe supervisor/workers
    Generation/stale-result control
    Bundled child mounts
    Strong bounded embedded child views
    Cycle/depth/collision failures
    Generated tests
    No arbitrary project-open execution

P1 - DEFINING IDE EXPERIENCE

    Native dockable workspace
    Federation Explorer
    Federation Graph
    Mount Table
    Path Resolution Lens
    Federation Map
    Package X-Ray
    Embedded Image Stack
    Generated Perl preview
    Manifest Diff
    Release View
    Cross-navigation

P2 - PROFESSIONAL SCALE

    Incremental invalidation
    Persistent content cache
    CPU/I/O scheduler
    Shared-buffer transport
    Large model paging
    Fast/compact/hybrid runtime profiles
    Lazy child opening
    Benchmark harness
    Fuzzing
    recovery stress
    plugin-host isolation
    packaged multiprocessing qualification

P3 - PLATFORM EXPANSION

    External child ecosystem
    optional compression profiles
    authenticated signing design
    content-addressed deduplication
    procedural entries
    public plugin SDK
    read-only HTML reports
    additional emitters only after Perl maturity

===============================================================================
26. FIRST END-TO-END VERTICAL SLICE
===============================================================================

Build this before broad visual expansion:

    1. Launch the PySide6 Studio shell.
    2. Start the supervisor with QProcess.
    3. Connect over authenticated QLocalSocket.
    4. Create RootVFS, ChildVFS, and GrandchildVFS.
    5. Add one text and one binary source to each.
    6. Mount ChildVFS at /child.
    7. Mount GrandchildVFS at /deep inside ChildVFS.
    8. Select EMBEDDED delivery for both mounts.
    9. Validate paths, cycles, collisions, and compatibility.
    10. Submit a build using a task generation.
    11. Build GrandchildVFS and verify it.
    12. Embed it into ChildVFS and verify the bounded range.
    13. Embed ChildVFS into RootVFS and verify the bounded range.
    14. Generate:

        VFS-Demo-1.0.0/
          lib/VFS/Demo.pm
          lib/VFS/Demo/Runtime.pm
          lib/VFS/Demo/Image.pm
          lib/VFS/Demo/Image/View.pm
          lib/VFS/Demo/Index.pm
          lib/VFS/Demo/Federation.pm
          lib/VFS/Demo/Resolver.pm
          lib/VFS/Demo/Stream.pm
          lib/VFS/Demo/Integrity.pm
          lib/VFS/Demo/Error.pm
          share/vfs-demo/root.vfsbin
          examples/embedded_child.pl
          examples/trace_path.pl
          t/00-load.t
          t/01-read.t
          t/02-binary.t
          t/03-embedded-child.t
          t/04-deep-federation.t
          t/05-corrupt-bounds.t
          Makefile.PL
          MANIFEST
          META.json
          README.md

    15. Independently reopen root.vfsbin in Python.
    16. Resolve /child/deep/hello.bin and compare every byte.
    17. Run perl -c and prove.
    18. Copy the package to a separate directory and rerun.
    19. Display the path in Path Resolution Lens and Embedded Image Stack.
    20. Repeat the build and compare canonical fingerprints.
    21. Cancel a third build during parent packing and prove the committed
        destination is unchanged.

This slice proves the complete architecture vertically:

    PySide6 shell
    supervisor IPC
    spawn-safe workers
    immutable project generation
    bottom-up nested build
    bounded embedded views
    binary format
    independent Perl runtime
    structured trace parity
    verification
    cancellation safety
    atomic commit

===============================================================================
27. RELEASE QUALITY GATES
===============================================================================

27.1 Product truth gate

UI state distinguishes:

    designed
    validated
    planned
    queued
    building
    staged
    structurally verified
    independently reopened
    Perl syntax passed
    Perl tests passed
    reproducibility checked
    committed
    post-commit verified

27.2 Preservation gate

    Source bytes unchanged.
    Previous committed package survives every injected failure.
    Delete is reversible until explicit purge.
    Migration preserves the original.
    Cancellation and worker termination cannot corrupt final output.

27.3 Determinism gate

Repeated builds of golden projects are byte-identical across worker completion
orders. Platform-specific variation is absent or explicitly profiled.

27.4 Federation gate

Bundled, embedded, external, mixed, deep, collision, directory merge, cycle,
compatibility, and depth fixtures pass in Python and Perl.

27.5 Embedded-bounds gate

No accepted child descriptor can read outside its declared range. Hostile offset,
length, count, and overflow fixtures fail before access or allocation.

27.6 Binary gate

Every byte value, random binary, NUL content, archives, images, large offsets,
range reads, and stream seeks round-trip exactly.

27.7 Multiprocessing gate

Target platform/source/frozen matrices pass. UI remains responsive. Worker crash,
supervisor restart, stale result, shared-buffer leak, and cancellation tests pass.

27.8 Security gate

Untrusted project open executes no arbitrary code. Tool arguments are not shell
concatenated. Parsing budgets, source-root boundaries, plugin permissions, and
export-path policies pass review.

27.9 Perl gate

Generated package loads and passes tests independently under the supported Perl
profiles. No undeclared dependency or source-tree assumption remains.

27.10 Usability gate

Core workflow is operable by keyboard and mouse. Diagnostics navigate to useful
targets. Recovery and overwrite consequences are explicit.

27.11 Documentation gate

Project format, VFS format, federation semantics, embedded views, Perl API,
multiprocessing model, security model, recovery, and release procedure are
documented before 1.0.

27.12 Performance gate

Published benchmark fixtures and thresholds exist. Regressions beyond approved
limits block release. Results include environment and validation evidence.

===============================================================================
28. EXPLICITLY OUT OF SCOPE FOR THE FIRST COMPLETE RELEASE
===============================================================================

- Kernel-mode filesystem mounting.
- Editing host files in place through the VFS namespace.
- Distributed network federation.
- Transparent cloud synchronization.
- Arbitrary project-open Python or Perl execution.
- Unreviewed custom encryption.
- General-purpose code IDE replacement.
- Live collaborative multi-user editing.
- Automatic trust of external child providers.
- Mutable embedded child bytes inside a committed parent.
- Runtime self-modifying generated Perl.
- Additional language emitters before Perl is mature.
- Claims of zero-copy when measurements show copying.
- Claims of thread/process safety without platform tests.

===============================================================================
29. PRIMARY RISKS AND MITIGATIONS
===============================================================================

RISK: Frozen applications and multiprocessing behave differently by platform.
MITIGATION:
    Separate helper/supervisor executables, explicit spawn entry points,
    freeze_support where required, installer-level tests on Windows/macOS/Linux,
    and no reliance on interactive __main__ functions.

RISK: Qt objects leak into workers.
MITIGATION:
    Architectural import tests, plain immutable task schemas, headless worker
    packages, and code review gates.

RISK: Shared memory leaks after crashes.
MITIGATION:
    Ownership ledger, generation-tagged names, acknowledgements, startup cleanup,
    expiry policy, and preference for mmap artifacts when persistence is useful.

RISK: More processes increase disk contention.
MITIGATION:
    Separate CPU/I/O lanes, adaptive concurrency, workload-specific benchmarks,
    and explicit low-concurrency profiles.

RISK: Embedded children create parser complexity.
MITIGATION:
    Complete independent child images, one bounded ImageView abstraction, checked
    arithmetic, depth budgets, bottom-up build, and hostile-range corpus.

RISK: Generated Perl diverges from Python semantics.
MITIGATION:
    Shared language-neutral format contract, golden images, trace parity, and
    cross-language property/contract tests.

RISK: Incremental builds reuse invalid cache entries.
MITIGATION:
    Content/config/generator keyed cache, immutable artifacts, verification on
    retrieval, and full rebuild fallback.

RISK: "Delete" expectations cause accidental loss.
MITIGATION:
    Tombstones, visible generations, separate purge workflow, retention, and
    last-known-good protection.

RISK: A plugin compromises source or output.
MITIGATION:
    capability manifests, process isolation, untrusted default, immutable
    snapshots, and final commit authority retained by supervisor.

RISK: The IDE becomes visually impressive before the runtime works.
MITIGATION:
    vertical slice first, executable phase gates, generated Perl before advanced
    effects, and Release View based only on evidence.

RISK: Pure-Perl performance is oversold.
MITIGATION:
    fast/compact profiles, exact indexes, lazy child views, honest benchmarks,
    optional accelerators separated from baseline, and no O(N) lookup.

RISK: Deep federation becomes unbounded.
MITIGATION:
    explicit configurable limits within hard ceilings, ancestry checks, cache
    budgets, and typed limit errors.

===============================================================================
30. ENGINEERING GOVERNANCE
===============================================================================

30.1 Required architecture decisions

Record ADRs for:

    PySide6/Qt Widgets selection
    separate supervisor process
    explicit spawn baseline
    local IPC protocol
    shared-buffer ownership
    preservation-first commit
    binary format version 2
    bounded ImageView
    bottom-up embedded federation
    exact lookup profiles
    Perl 5.10+ compatibility profile
    collision default error
    plugin process boundary
    frozen packaging strategy

30.2 Specialist review areas

Changes require focused review when they affect:

    binary layout
    path normalization
    mount routing
    ImageView bounds
    integrity
    commit/recovery
    IPC framing/authentication
    shared-memory lifecycle
    process cancellation
    generated Perl runtime
    plugin permissions
    compression/encryption
    package signing

30.3 Generated artifact review

Pull requests changing output include:

    generated Perl source diff
    binary section/layout diff
    manifest diff
    golden fingerprint changes
    trace parity changes
    compatibility assessment
    benchmark impact where relevant

30.4 Quality metrics

Track:

    deterministic build rate
    Python/Perl resolution parity
    generated test pass rate
    source-preservation failures
    crash-free sessions
    worker restart success
    cancellation cleanup success
    recovery success
    stale-result rejection
    shared-buffer leak count
    UI event-loop stall duration
    benchmark regressions
    unresolved accessibility issues
    dependency vulnerabilities

Metrics support engineering judgment; they do not replace it.

30.5 Claim language

Use precise states. Never call a feature complete because source files exist.
Never call a package verified because only its generator succeeded. Never call
an optimization faster without repeatable measurements.

===============================================================================
31. DEFINITION OF DONE
===============================================================================

VFS Federation Studio 1.0 is complete when it can reliably:

    1. Create and reopen a versioned workspace.
    2. Model root, child, grandchild, and deeper VFS projects.
    3. Keep source inputs immutable.
    4. Express changes through overlays and reversible tombstones.
    5. Resolve virtual paths with exact indexes and longest-prefix mounts.
    6. Detect collisions, cycles, depth violations, and incompatibility.
    7. Build deterministic binary images through a separate supervisor/workers.
    8. Remain responsive during large builds.
    9. Cancel or survive worker failure without damaging last good output.
    10. Generate complete readable Perl distributions.
    11. Read text and arbitrary binary bytes exactly.
    12. Support read, read_range, exists, stat, list, and stream seek.
    13. Mount bundled and external children.
    14. Open embedded children as bounded views without extraction.
    15. Resolve through multiple embedded VFS levels.
    16. Verify the full parent-child integrity chain.
    17. Explain any lookup through a structured trace.
    18. Cross-navigate source, graph, mount, index, byte range, and Perl code.
    19. Independently reopen and test exports outside the repository.
    20. Reproduce canonical output.
    21. Recover interrupted project/build state honestly.
    22. Reject malformed and hostile inputs within resource budgets.
    23. Ship installers and documentation for supported platforms.
    24. Preserve a disciplined, professional, memorable IDE identity.

The essential product promise is:

    DESIGN THE NAMESPACE.
    FEDERATE THE PACKAGES.
    PRESERVE EVERY VALID GENERATION.
    TRACE EVERY PATH.
    OPEN VFS WITHIN VFS WITHOUT EXTRACTION.
    EXPORT OPERATIONAL PERL.
    PROVE THE RESULT.

===============================================================================
32. IMMEDIATE IMPLEMENTATION ORDER
===============================================================================

32.0 Current position at RELEASE 1.0.0a4

The original P0-A..P0-E proof sequence remains preserved below. The current
codebase has evidence beyond those proofs in some runtime rails, but has not
closed every earlier product gate. Work resumes in this order:

    C1A - Chronicle workspace foundation — DELIVERED HEADLESS IN 0.0.12
        canonical document, command chain, undo/redo compensation, safe saves,
        immutable history, recovery candidates, migrations, trust and proposal
        review records. Strict JSON, process-serialized compare-and-swap saves,
        no-clobber archives and deterministic executable proof are included.

    C1B - Native Chronicle integration — ADVANCED THROUGH 1.0.0a4
        Native History/Recovery/Proposal views, controller-backed Explorer,
        project/source/mount/profile editor, immediate atomic command saves,
        recovery checkpoints and compensating Undo/Redo are delivered. Chronicle
        v4 also embeds signed-agent evidence, bounded signer trust, permanent
        revocation, admission thresholds, action artifacts, and separate named
        review/application records. Crash, migration and platform qualification
        remain before RM-P2 can pass.

    C2 - Native shell completion
        command registry/palette, real tab workspace, named layouts, density,
        keyboard/accessibility/high-DPI qualification.

    C3 - Federation authoring — USABLE VERTICAL SLICE THROUGH 1.0.0a4
        real Explorer plus project/source/mount/profile tables and a deterministic
        embedded workspace-to-image/package build are delivered. Governed agents
        may propose the same bounded configuration commands, but cannot build or
        commit directly. Federation Map, compatibility editing, bundled/external
        providers and the complete design-to-runtime trace matrix remain.

    C4 - RM-P4 scheduler completion
        CPU/I/O lanes, artifact/shared-buffer ledger, cancellation escalation,
        worker restart, supervisor recovery, resource budgets and observatory.

    C5A - Governed Perl-agent workspace actions — DELIVERED SLICE IN 1.0.0a1
        Exact bundle verification, proposal-only static action recipes,
        workspace/configuration binding, deterministic dry run, separate named
        acceptance/application, atomic ordinary-command save, audit, and an
        explicit post-application build boundary are delivered. Direct in-VFS
        bundle review, dynamic planning and broader proposal types remain gated.

    C5B - Signed agent identity and regression admission — ADVANCED THROUGH 1.0.0a4
        Workspace-scoped Ed25519 trust, bounded expiry, permanent revocation,
        signed immutable manifests, independent benchmark evidence, hard policy
        rails, same-agent regression baselines, renewal review, repeated
        authorization checks, actual corpus/model-label validation, normalized
        train/benchmark separation, a 20-case adversarial proof, GUI/CLI
        controls, and exact-result task-focused Help are delivered. Exported
        Perl bundles include layered READMEs and explicit metric replay.
        Automatic bounded replay inside admission, hardware custody,
        multi-party trust, direct signed in-VFS review, and supported-host,
        fuzz, and scale qualification remain gated.

    C5C - Signature instruments and MONK-M4
        Package X-Ray, Embedded Stack, Manifest Diff, Release View, and the
        graphical Chronicle-backed Monk workbench.

Each slice updates the conformance ledger. Visual or neural novelty may continue
only when it attaches to these durable contracts.

P0-A - Freeze contracts

    project schema outline
    binary format constants/records
    ImageView bounds contract
    task/result protocol
    commit ledger
    Perl public API
    trace schema

P0-B - Prove the process boundary

    PySide6 shell
    QProcess supervisor
    QLocalSocket handshake
    spawn worker
    generation-aware task
    cancellation acknowledgement
    frozen packaging smoke tests

P0-C - Prove one image

    source discovery
    path normalization
    deterministic index
    image writer
    independent reader
    binary round-trip
    reproducibility

P0-D - Prove generated Perl

    Image::View
    exact index
    Entry/Stream
    package discovery
    tests outside repository

P0-E - Prove embedded federation

    child descriptor table
    bottom-up build
    bounded child views
    deep resolver
    integrity chain
    Python/Perl parity
    corrupt-bound tests

Only after P0-E should the full visual graph, animation, plugin SDK, and advanced
profiles expand.

===============================================================================
33. REFERENCE BASIS
===============================================================================

This roadmap is grounded in the official behavior and contracts of:

    Qt for Python / PySide6
        QMainWindow and QDockWidget for a dockable IDE shell.
        QAbstractItemModel for scalable model/view data.
        QProcess for external process lifecycle and captured channels.
        QLocalServer/QLocalSocket for local event-loop-integrated IPC.
        QSharedMemory for explicit shared segments where appropriate.
        QSaveFile for safe replacement writes.
        QUndoStack and Qt accessibility/test facilities.

    Python standard library
        multiprocessing process-based parallelism.
        explicit process contexts and spawn-safe importable targets.
        queues/pipes for bounded control messaging.
        shared_memory for explicitly owned shared buffers.
        avoidance of casual shared mutable state.

    Perl documentation
        binary mode, read/sysread, seek/tell, pack/unpack, module packaging,
        diagnostics, and Test::More-based verification.

These APIs provide mechanisms, not architecture by themselves. The Studio's
safety comes from the stronger rules in this roadmap: immutable sources,
supervisor-owned commit, bounded child views, generation-tagged results,
independent verification, and evidence-backed release gates.

===============================================================================
END OF ROADMAP
===============================================================================
