feat: Install supporting backend payload folders (#30)

This PR extends backend installation so a matched backend package layout can specify a primary payload folder plus additional “supporting” payload folders, and have all of them copied into the installed backend directory (while preserving CompoundPathChecker first-match semantics).

Changes:

Added BackendInfo.supporting_paths and threaded it through BackendInstallation into repository copy logic.
Extended PackagePathChecker with supporting_subfolders resolution and added focused tests for supporting folder selection/rejection and CompoundPathChecker behavior.
Added OpenSpec documentation/spec artifacts describing the expected package-installation behavior.

Author: Mousius

openspec/changes/archive/2026-05-07-support-multiple-backend-subfolders/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-07

openspec/changes/archive/2026-05-07-support-multiple-backend-subfolders/.openspec.yaml.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: Copyright 2026, Arm Limited and/or its affiliates.
+SPDX-License-Identifier: Apache-2.0

openspec/changes/archive/2026-05-07-support-multiple-backend-subfolders/design.md

@@ -0,0 +1,43 @@
+## Context
+
+`PackagePathChecker` currently resolves one `BackendInfo.backend_path`. That
+keeps existing installs simple, but cannot express a package layout where one
+matched root contains a primary backend payload plus large, nested supporting
+folders that also need to be installed.
+
+`CompoundPathChecker` should remain first-match wins. Its checkers describe
+alternative layouts; the selected checker should return all payload folders for
+that one layout.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Preserve existing no-subfolder and single-subfolder behavior.
+- Let one matched package checker describe a primary install source plus
+  supporting folders.
+- Copy supporting folders recursively while preserving their relative names.
+- Keep the behavior local to path resolution and repository copy logic.
+
+**Non-Goals:**
+
+- Change `PyPackageBackendInstallation`, download, archive extraction, or EULA
+  behavior.
+- Add glob, wildcard, or per-file selection rules.
+- Merge results from multiple successful `CompoundPathChecker` entries.
+
+## Decisions
+
+1. Keep `BackendInfo.backend_path` as the primary install source for
+   compatibility, and add metadata for supporting folders.
+2. Copy each supporting folder as a recursive directory tree into the installed
+   backend directory under its relative folder name.
+3. Keep `CompoundPathChecker` as a first-match selector; multi-folder copying
+   comes only from the selected checker result.
+
+## Risks / Trade-offs
+
+- Sequence-like subfolder input can be confused with a string. Normalize strings
+  separately and test both forms.
+- Multi-folder copy adds a repository code path. Keep it narrow and test nested
+  supporting folder contents.

openspec/changes/archive/2026-05-07-support-multiple-backend-subfolders/design.md.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: Copyright 2026, Arm Limited and/or its affiliates.
+SPDX-License-Identifier: Apache-2.0

openspec/changes/archive/2026-05-07-support-multiple-backend-subfolders/proposal.md

@@ -0,0 +1,35 @@
+## Why
+
+Some backend packages have one primary payload plus additional supporting
+folders under the same validated root. Today the path checker can validate that
+layout but returns only one install source, so supporting folders are not copied.
+
+## What Changes
+
+- Allow a matched path checker to return a primary install source plus
+  additional supporting folders from the same package layout.
+- Extend `PackagePathChecker` for this metadata while preserving existing
+  no-subfolder and single-subfolder behavior.
+- Keep `CompoundPathChecker` first-match semantics; it selects one complete
+  layout rather than merging separate checker results.
+- Copy supporting folders recursively without requiring per-file configuration.
+
+## Capabilities
+
+### New Capabilities
+
+- `backend-package-installation`: Defines how backend package layouts are
+  validated and how primary and supporting payload folders are selected for
+  repository installation.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+- Core code: `src/mlia/backend/install.py`, backend repository copy logic, and
+  backend installation tests.
+- Plugin configuration: callers that compose `PackagePathChecker` and
+  `CompoundPathChecker`.
+- No new runtime dependencies are expected.

openspec/changes/archive/2026-05-07-support-multiple-backend-subfolders/proposal.md.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: Copyright 2026, Arm Limited and/or its affiliates.
+SPDX-License-Identifier: Apache-2.0

openspec/changes/archive/2026-05-07-support-multiple-backend-subfolders/specs/backend-package-installation/spec.md

@@ -0,0 +1,79 @@
+## ADDED Requirements
+
+### Requirement: Backend layout validation precedes payload selection
+
+The system SHALL validate configured backend layout expected files before
+selecting any backend payload folder for installation.
+
+#### Scenario: Valid package root with selected payload folders
+
+- **WHEN** a backend package contains all configured package-root expected files
+  and each configured payload folder exists
+- **THEN** the backend package is accepted as installable
+
+#### Scenario: Missing expected file
+
+- **WHEN** a backend layout is missing a configured expected file
+- **THEN** the backend layout is rejected before any payload folder is
+  selected
+
+### Requirement: Multiple backend payload folders can be installed from one matched layout
+
+The system SHALL allow backend installation configuration to select multiple
+backend payload folders from the same matched package layout.
+
+#### Scenario: Installing primary and supporting payload folders
+
+- **WHEN** a backend package is configured to install a primary payload folder
+  and an additional supporting payload folder from the same package root
+- **THEN** the installed backend repository entry contains both configured
+  payload folders from that package
+
+#### Scenario: Installing deeply nested supporting payload folder
+
+- **WHEN** a configured supporting payload folder contains nested directories
+  and many files
+- **THEN** the installed backend repository entry contains the complete
+  supporting payload folder tree
+
+#### Scenario: Missing configured payload folder
+
+- **WHEN** a backend layout is configured with multiple payload folders and any
+  configured payload folder is missing or is not a directory
+- **THEN** the backend layout is rejected as not installable
+
+### Requirement: Compound path checking selects one complete layout
+
+The system SHALL keep compound path checking as first-match selection between
+alternative backend layouts.
+
+#### Scenario: Earlier package layout matches before later layout
+
+- **WHEN** a compound path checker contains a matching package checker before a
+  later matching checker
+- **THEN** the first package checker result is used as the complete backend
+  install source set
+
+#### Scenario: First matched checker includes multiple payload folders
+
+- **WHEN** the first matched checker selects multiple payload folders
+- **THEN** all payload folders from that matched checker are installed and later
+  checker results are ignored
+
+### Requirement: Existing single-source behavior is preserved
+
+The system SHALL preserve existing `PackagePathChecker` behavior for backend
+layouts configured with no payload folder override or one payload folder
+override.
+
+#### Scenario: No backend payload folder configured
+
+- **WHEN** a backend layout is configured without a payload folder override and
+  the layout root contains all expected files
+- **THEN** the layout root is used as the backend install source
+
+#### Scenario: One package payload folder configured
+
+- **WHEN** a backend package is configured with one payload folder and that
+  folder exists
+- **THEN** the single folder remains the backend install source

openspec/changes/archive/2026-05-07-support-multiple-backend-subfolders/specs/backend-package-installation/spec.md.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: Copyright 2026, Arm Limited and/or its affiliates.
+SPDX-License-Identifier: Apache-2.0

openspec/changes/archive/2026-05-07-support-multiple-backend-subfolders/tasks.md

@@ -0,0 +1,39 @@
+## 1. Tests
+
+- [x] 1.1 Add a failing backend installation test that installs a primary
+  payload folder and an additional supporting payload folder from one vendored
+  backend package and verifies both directories are present in the repository.
+- [x] 1.2 Add a failing backend installation test where the supporting payload
+  folder contains a nested directory tree and verifies nested files are copied
+  recursively.
+- [x] 1.3 Add focused tests for `PackagePathChecker` compatibility with no
+  `backend_subfolder`, one string `backend_subfolder`, and multiple configured
+  payload folders.
+- [x] 1.5 Add a failing test for rejection when one configured backend payload
+  folder is missing or is not a directory.
+- [x] 1.6 Add a `CompoundPathChecker` regression test showing first-match
+  behavior is preserved and the first matched checker can still return multiple
+  payload folders.
+
+## 2. Core Implementation
+
+- [x] 2.1 Extend backend path resolution metadata so one matched checker can
+  describe multiple selected payload folders without breaking existing
+  `BackendInfo.backend_path` callers.
+- [x] 2.2 Extend `PackagePathChecker` to accept and normalize multiple backend
+  payload folders while preserving string `backend_subfolder` behavior.
+- [x] 2.4 Update `BackendInstallation._install_from()` and repository copy logic
+  to copy multiple selected payload folders into the installed backend directory
+  while preserving their relative names and nested contents.
+- [x] 2.5 Ensure missing configured payload folders cause path checking to fail
+  before installation.
+- [x] 2.6 Leave downstream backend plugin configuration to the owning package;
+  this core change only exposes the supporting payload folder API.
+
+## 3. Validation
+
+- [x] 3.1 Run the focused MLIA backend installation tests.
+- [x] 3.2 Skip backend plugin installation tests because downstream plugin
+  changes are outside this package.
+- [x] 3.3 Run lint/type checks required for the touched files.
+- [x] 3.4 Run the quick non-slow pytest suite if the focused checks pass.

openspec/changes/archive/2026-05-07-support-multiple-backend-subfolders/tasks.md.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: Copyright 2026, Arm Limited and/or its affiliates.
+SPDX-License-Identifier: Apache-2.0