feat: explode archive materials into named contract slots with a prefix policy selector

[javirln]

Summary

Makes chainloop attestation add usable with fixed, named contracts when a single logical input is delivered as an archive of many same-kind files (for example a bundle of SARIF reports). Today an archive can be exploded into many materials, but the resulting materials get generic auto-generated names and therefore cannot satisfy a contract's required, named material slot, nor be targeted by a name-based policy selector. This change closes that gap.

Three additive, backward-compatible pieces.

1. Stable, reproducible naming for exploded materials

When --value is an explodable archive (.zip / .tar / .tar.gz) for an explodable kind, the CLI now:

• sorts the archive entries by their normalized path, deterministically and independent of the order the archive was written in;
• names the first entry with the exact --name, and the rest <name>-1, <name>-2, …

The first entry therefore fills a required, named contract slot, and the file-to-name mapping is fully reproducible for a given archive (no timestamps or randomness).

chainloop attestation add --kind SARIF --name scan-report --value scans.zip
# -> scan-report, scan-report-1, scan-report-2, ...

2. The source archive is recorded as evidence

The original archive is recorded once as an EVIDENCE material and cross-linked with every exploded material in both directions via the chainloop.material.references annotation, so the source bundle itself is attested and traceable to the materials derived from it.

3. Prefix match mode for material selectors

Adds an additive match_mode to the contract material selector — EXACT (default) and PREFIX — on both standalone policy attachments (PolicyAttachment.MaterialSelector) and policy groups (PolicyGroup.Material). A single shared predicate drives both paths.

PREFIX matches the exact name or a <name>-<suffix> derivative, so a selector can target an entire exploded set:

policies:
  materials:
    - ref: my-policy
      selector:
        name: scan-report
        match_mode: PREFIX   # matches scan-report, scan-report-1, ...

PREFIX is a literal prefix — it matches any material whose name begins with the value — so choose a discriminating prefix (typically the full slot name, e.g. scan-report, which matches scan-report, scan-report-1, …).

How policies apply to the exploded set

A policy attachment applies to a material when the policy's declared kind matches the material's type and the selector, if present, matches the name. Evaluation is per material: N matching materials times M attachments produce N×M independent evaluations, each recorded against its own material. Exploding N reports into a prefix-selected slot therefore runs every attachment against every report. This also supports multi-slot contracts where each role has its own prefix selector (for example a build-time scan slot and a stripped-release scan slot): the two prefixes never cross-match, so each role's policies apply only to that role's materials.

What this covers

• Explode into a required, named contract slot, and multi-slot contracts via per-role prefix selectors.
• .zip, .tar, and .tar.gz; deterministic ordering; --name collisions; user --annotations propagated to every exploded material; archive-as-evidence cross-linking in both directions.
• Backward compatible: existing selectors with no match_mode keep exact-match behavior, and adding a single (non-archive) material is unchanged.

What this does not cover

• Nested archives are not recursed: a .zip inside the archive is treated as a single regular file.
• Archive-native kinds (for example ZAP_DAST_ZIP) are still recorded whole, not exploded.
• If --name collides with a material already present in the attestation, the allocator never overwrites it, so the first exploded entry becomes <name>-1 and will not fill an exact required slot named <name> in that case.
• No merging of file contents: each exploded entry stays its own material with its own digest.

Compatibility

The proto change is purely additive (a new optional enum field with UNSPECIFIED = 0 decoding to exact match). Contracts are persisted as raw body plus serialized proto, so no data migration is required and existing contracts deserialize unchanged.

AI assistance: Claude Code.

[chainloop-platform]

AI Session Analysis

Missing AI Coding Sessions

We detected commits in this PR that were AI-assisted, but the matching Chainloop Trace session(s) could not be found in Chainloop.

Please make sure the AI coding session evidence has been sent by the Chainloop CLI, or add the skip-ai-session label to this PR to bypass this check.

Learn more about Chainloop Trace.

---

Powered by Chainloop and Chainloop Trace

[cubic-dev-ai]

All reported issues were addressed across 19 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 3 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 10 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[jiparis]

Looks great, @javirln . Just a nit comment.