import: provide an authorized cleanup path for failed or obsolete ImportRepo leaves

[genedna]

Summary

A failed or exploratory ImportRepo cannot currently be cleaned up through the product surface. The ordinary POST /api/v1/delete-entry route rejects paths under the ImportRepo directory, while the receive-pack path does not allow a follow-up update. A trial left an approximately 5 KB repository leaf under /third-party/workbuddy that is neither updateable nor deletable.

This creates a permanent operational residue for every mistaken import. A storage-only deployment needs a deliberate, authorized cleanup lifecycle even if ImportRepo remains import-once.

Versions and environment

• Mega2 image: genedna/mega2:latest
• Deployment: local macOS OrbStack evaluation stack
• Import directory: /third-party
• Transport: Git Smart HTTP and product write API

Reproduction

1. Import a repository into a new /third-party/<owner>/<repo> leaf.
2. Determine that the import was created at the wrong path or should be discarded.
3. Attempt a supported cleanup with the product directory-delete endpoint.

The operation is rejected for the ImportRepo namespace. A new push cannot replace the leaf either.

Actual behavior

• ImportRepo has a create path but no supported recovery or removal path for an obsolete leaf.
• Users can accumulate unusable data while testing imports.
• The only apparent remedy is direct backend intervention, which is unsuitable for normal operators.

Expected behavior

An authorized operator can deliberately clean up an obsolete ImportRepo leaf through a documented product operation, or can place it into a documented terminal archived state that removes it from normal serving and discovery.

The normal restriction against editing the contents of an imported repository may remain intact.

Scope boundaries

In scope:

• An explicit cleanup or archive lifecycle for a complete ImportRepo leaf.
• Authorization, auditability, idempotency, and object-storage retention semantics.
• Clear client and API documentation.

Out of scope:

• General file-level mutation inside ImportRepo.
• An unauthenticated destructive endpoint.
• Immediate physical deletion of blobs when retention or garbage-collection policy requires a delayed sweep.

Acceptance criteria

1. An authorized request can target one complete ImportRepo leaf and either delete it or transition it to the documented terminal state.
2. The operation cannot delete the ImportRepo root or escape the requested namespace.
3. Retrying a completed cleanup is safe and returns a stable outcome.
4. The leaf is no longer advertised or cloneable after its terminal transition, subject to the documented retention policy.
5. The implementation records an audit event or equivalent durable operational trace without exposing credentials.
6. Tests cover cleanup of a populated ImportRepo, an unauthorized attempt, a retry, and a non-ImportRepo path.
7. Documentation explains the recovery path and any asynchronous object-storage garbage collection.

Related evidence

• User trial report dated 2026-09-23, section P1-2.
• The current directory-entry contract intentionally rejects delete and move operations under ImportRepo; this issue requests the missing leaf lifecycle rather than unrestricted mutation.