Patchworks Under Wine
=====================

This guide documents the supported Linux-through-Wine command path for
Patchworks Matrix Builder.

The current known-good day-to-day operator workflow is still native Windows on
a workstation that already has a valid local Patchworks installation and
system-level licensing configured. Use the Wine path only when you
intentionally need the Linux/Wine runtime seam.

Prerequisites
-------------

- A local Patchworks install bundle, including ``patchworks.jar``.
- A working Wine runtime (``wine64`` or ``wine`` on ``PATH``).
- Java callable inside Wine context (``wine64 cmd /c java -version``).
- A valid ForestModel XML and fragments DBF generated by FEMIC export.
- UBC VPN connectivity if Patchworks license validation requires campus IP.
- ``SPSHOME`` must point to the Patchworks install root in a Wine-visible
  Windows path (for example ``Z:\\...``).
- If ``patchworks.use_xvfb: true``, ``xvfb-run`` must be installed on PATH.

Config File
-----------

Use ``config/patchworks.runtime.yaml``:

.. code-block:: yaml

   patchworks:
     jar_path: reference/Patchworks/patchworks.jar
     wine_prefix: null
     license_env: SPS_LICENSE_SERVER
     license_value: <sps_user>@auth.spatial.ca
     spshome: Z:\\Program Files\\Spatial Planning Systems\\Patchworks
     use_xvfb: false

   matrix_builder:
     fragments_path: output/patchworks_k3z_validated/fragments/fragments.dbf
     output_dir: output/patchworks_k3z_validated/tracks
     forestmodel_xml_path: output/patchworks_k3z_validated/forestmodel.xml
     accounts_exclude_regex: []  # optional regex filters for proto/accounts rows

CLI Workflow
------------

1. Run preflight checks:

   .. code-block:: bash

      PYTHONPATH=src python -m femic patchworks preflight --config config/patchworks.runtime.yaml

2. Launch Matrix Builder directly:

   .. code-block:: bash

      PYTHONPATH=src python -m femic patchworks matrix-build --config config/patchworks.runtime.yaml

3. Optional interactive launcher mode:

   .. code-block:: bash

      PYTHONPATH=src python -m femic patchworks matrix-build \
        --config config/patchworks.runtime.yaml \
        --interactive

Generated Runtime Artifacts
---------------------------

Each run writes:

- ``runtime/logs/patchworks_matrixbuilder_stdout-<run_id>.log``
- ``runtime/logs/patchworks_matrixbuilder_stderr-<run_id>.log``
- ``runtime/logs/patchworks_matrixbuilder_manifest-<run_id>.json``

For non-interactive matrix builds, FEMIC now also promotes
``tracks/protoaccounts.csv`` to ``tracks/accounts.csv`` when present.
If ``accounts.csv`` already exists, it is moved to a timestamped backup
(``accounts_backup_YYYYMMDD_HHMMSS.csv``) before replacement.
If ``matrix_builder.accounts_exclude_regex`` is configured, matching rows are
removed during promotion (based on ``ATTRIBUTE``/``ACCOUNT``) and the manifest
captures both the applied patterns and excluded row count.

The manifest includes command string, return code, config paths, and log paths.
Matrix runs now fail hard when fatal runtime signatures are detected in process
output (for example licensing/native-library failures) or when matrix output
artifacts are missing/empty.

Notes
-----

- Patchworks binaries are proprietary and should remain outside published docs
  artifacts and repository source control.
- ``<sps_user>`` is a template token, not a literal production value. On known
  good Windows workstations, prefer the existing system-level
  ``SPS_LICENSE_SERVER`` configuration instead of overriding it in FEMIC
  runtime config.
- FEMIC preflight validates environment/config only; Patchworks performs license
  server checks during launch.
- When running in headless Linux, set ``patchworks.use_xvfb: true`` to wrap
  Wine invocation in ``xvfb-run -a``.
- Wine path translation uses the ``Z:`` drive mapping (for example
  ``/path/to/workspace/...`` -> ``Z:\\path\\to\\workspace\\...``).