# Explicit import grouping

Explicit grouping is opt-in. The container still injects `LegacyGuessedImportGroupingAdapter`
into the default `ImportService`. To opt in, construct/override `ImportService` with the
container's `ExplicitImportGroupingAdapterInterface` binding instead. All repositories must
share the same PDO connection.

Call `import($source, $extensions, $contexts)`. Context keys are scan-relative paths;
`'*'` supplies a fallback. Every successfully scanned file must resolve to a context with
literal boolean `confirmed => true` and either:

- a positive integer `model_id` (optional folder/title assertions must match), or
- nonempty `folder_path` and `model_name` strings.

No source-path guessing occurs in the explicit adapter. Missing confirmation/context is
rejected. `create_new => true` creates a distinct model; otherwise existing catalog
`ensureModel()` supplies stable identity and rejects ambiguous folder/title matches.
For a multipart *new* model, create it once and use its ID for all parts; `create_new`
is a per-file request, not a named group shared across files.

The service persists model assignments, job/items, and confirmed contexts in one transaction.
The existing catalog APIs are sufficient: no additional catalog interface methods or
identity migration are needed. Existing root-lock and nested-savepoint behavior is reused.

`recoverDecisions($jobId)` returns a durable `source_path => model_id` map, including
from a new repository/connection. `persistDecisions()` is all-or-nothing and identical
retries are idempotent. Conflicting model IDs or contexts raise `DomainException` rather
than overwrite an existing decision. Job deletion cascades to decisions. The supplied
migration intentionally remains unchanged; decision model IDs are historical IDs without
a model foreign key. Recovery does not recreate deleted models or guess replacement IDs.

Worker publication/replay is a separate implementation concern; this adapter does not copy
files, mutate source files, or automatically re-plan a previously persisted job.

## Verification

Integration tests in `ExplicitGroupingTest` exercise strict confirmation, missing contexts,
stable/recreated/ambiguous identities, ID assertions, per-file/wildcard service contexts,
durable recovery, immutable retry decisions, and caller-owned rollback. Linux PostgreSQL
runs use `sh bin/test-postgres.sh` in an isolated `/tmp` directory and disposable Docker
resources. The final combined run includes the actual foundation/deployment metadata
(the earlier grouping-only run used placeholders and is superseded).

## Publication and recovery

The worker chooses a collision-free destination before committing the immutable item
plan. It then publishes to that exact name using a no-overwrite hard link. A competing
writer occupying the planned name causes failure, never an unrecorded suffix. Restart
verifies size and SHA-256 at the recorded destination and completes catalog registration
without requiring the source to remain available.

Filesystem changes cannot roll back with SQL. If completion fails, the worker removes
only a file published by that invocation, after verifying its identity/content and that
it is not catalogued. Adopted files are never removed. Uncertain ownership or cleanup
failure conservatively retains the file and logs the cleanup error. Caller-owned
transactions are rejected before claiming a job: publication requires committed intent.

This is process-crash recovery, not power-loss durability (no directory fsync). Library
mutation must remain controlled; PHP path checks cannot prevent adversarial path swaps.
Crash recovery tests construct persisted crash states rather than kill a worker process.
See `.superpowers/shared-contracts/explicit-grouping-report.md` for RED/GREEN evidence.