feat: drop_ledger drops the whole ledger; root-branch check is struct…

[bplatz]

Sits on top of #1243

drop_ledger was misnamed: it accepted a ledger ID like "mydb:main", normalized it to a branch, and dropped only that one branch. That made dropping a multi-branch ledger a per-call iteration on the caller, and made dropping a ledger via name ("mydb") silently equivalent to dropping just mydb:main while leaving siblings + the cross-branch @shared/dicts/ namespace orphaned.

This PR makes drop_ledger do what it says: remove the entire ledger — every branch, every retracted-but-not-purged record, plus the shared dict namespace. It also replaces the "main is special" name-based guards in drop_branch and rebase_branch with a structural check on source_branch.is_none().

Changes

drop_ledger is now whole-ledger

• Snapshots every NsRecord under the ledger name via all_records() (not list_branches, which excludes retracted) so hard-drop cleans up retracted-but-not-purged branches too. Enumeration failures propagate as Err — silently coercing to NotFound would let the HTTP route fall through to drop_graph_source and potentially delete an unrelated graph source with the same name.
• Sorts branches leaf-first via source_branch pointers (cycle-safe). Partial failure leaves orphan parents, never dangling children.
• Cancels and waits for pending background indexing on each branch before any storage mutation.
• Per-branch loop: deletes per-branch artifacts (hard) and either retracts (soft) or invokes AdminPublisher::drop_branch (hard). The hard-mode path is parent-aware, so surviving parents keep accurate branches counts even if the operation aborts. Concurrent NotFound is race-as-success; any other nameservice failure bails with ApiError::Drop before touching parents or @shared/. Retry is safe — every step is idempotent under partial prior progress.
• After every branch is gone, wipes {ledger_name}/@shared/dicts/. No more orphan shared blobs on full-ledger drop.
• Cache disconnect runs unconditionally per branch so stale state never survives the operation.

Input parsing is explicit

Input	Behavior
"mydb"	Whole-ledger drop. Canonical form.
"mydb:main"	Whole-ledger drop, with a warning attached to the report nudging callers toward the bare name. Backwards-compat for existing examples.
"mydb:dev" (or any non-default branch suffix)	Rejected with 400/ApiError::Http. Caller almost certainly meant drop_branch("mydb", "dev"); the error message says so.

This is deliberately the conservative migration: "mydb" cannot accidentally drop only mydb:main, and "mydb:dev" cannot accidentally drop the whole mydb ledger.

Root-branch refusal is structural

Both drop_branch and rebase_branch previously refused the literal string "main". The new check is record-based: record.source_branch.is_none(). That means:

• A ledger created with a non-default initial branch (e.g. mydb:trunk) correctly refuses operations on its root.
• A non-root branch that happens to be named "main" (e.g. created as a child of trunk) is droppable / rebaseable like any other.

"main" is now purely a default-name convention — DEFAULT_BRANCH in fluree-db-core/src/ledger_id.rs. No code path treats the string "main" as semantically special.

DropReport and HTTP wire format

Additive shape change:

pub struct DropReport {
    pub ledger_id: String,                // ledger name (bare, no :branch)
    pub status: DropStatus,                // aggregate across branches
    pub artifacts_deleted: usize,          // sum across branches + @shared cleanup
    pub branch_reports: Vec<BranchDropReport>,  // NEW: per-branch, leaf-first
    pub warnings: Vec<String>,
}

The HTTP DropResponse exposes the per-branch detail as branches_dropped: Vec<String> (omitted via skip_serializing_if when empty).

{
  "ledger_id": "mydb",
  "status": "dropped",
  "files_deleted": 73,
  "branches_dropped": ["mydb:feature-x", "mydb:dev", "mydb:main"]
}

The CLI's fluree drop output gains a branch count on multi-branch drops:

Dropped ledger 'oldledger' (deleted 73 artifacts across 3 branches)

Docs

End-to-end refresh:

• docs/api/endpoints.md — POST /drop reflects whole-ledger semantics, the branches_dropped field, leaf-first ordering, the input-form rules, and the 400 on non-default suffixes. POST /drop-branch link fixed (was /branch/drop / #post-branchdrop).
• docs/getting-started/rust-api.md — drop_ledger section reframed around whole-ledger semantics; drop_branch callout for single-branch drops; updated idempotency to reflect new NotFound behavior.
• docs/cli/drop.md — bare-name input, leaf-first semantics, branch-suffix rejection, updated example output.
• docs/cli/server-integration.md — branch-drop and rebase contracts reframed as root-branch refusals (no more "Cannot be 'main'").
• docs/concepts/ledgers-and-nameservice.md — "main" is the default, root refusal is structural.
• docs/operations/admin-and-health.md — POST /drop summary updated to match.

Stale doc comment fixed

The Rust doc-comment above drop_ledger previously described the old branch-level flow ("Normalizes the ledger ID (ensures :main suffix)" → "Retracts from nameservice") and claimed hard mode still attempts cleanup for not-found ledgers. Rewritten end-to-end:

• 7-step Operation list reflects whole-ledger flow.
• Idempotency block notes that NotFound returns without touching storage — orphaned storage with no NsRecord pointer is not swept by drop_ledger, that's a separate admin concern.
• Documents the abort-with-ApiError::Drop behavior on real nameservice failure and that retry is safe.

New / updated tests:

• drop_ledger_accepts_bare_name_and_default_suffix — bare name is canonical; report uses the bare name; no warning.
• drop_ledger_main_suffix_warns_but_works — :main form is accepted but attaches the migration warning.
• drop_ledger_rejects_non_default_branch_suffix — mydb:dev is rejected and the error names drop_branch.
• drop_ledger_hard_clears_every_branch_and_shared — multi-branch ledger with one branch retracted-as-deferred (because it has live children); hard drop_ledger walks leaf-first, wipes @shared/dicts/, and re-creating the alias succeeds.
• drop_main_refused — refuses the default root with a "root branch" error.
• drop_branch_refuses_non_main_root — refuses a non-main-named root structurally.
• drop_branch_allows_non_root_named_main — allows a non-root branch literally named "main".
• rebase_main_refused / rebase_refuses_non_main_root — same structural refusal for rebase.

LocalStack integration test from the prior PR (s3_testcontainers_hard_drop_clears_ledger) still passes — exercises the same code paths against real S3 + DynamoDB.

Migration notes

• HTTP POST /drop: callers passing "mydb" now drop the whole ledger; previously they dropped only mydb:main. Callers passing "mydb:main" see the same outcome but a warning is attached.
• HTTP callers passing "mydb:dev" (any non-default branch suffix) will now get a 400. They should switch to POST /drop-branch.
• Rust callers mirror the same rules. drop_branch (the right tool for branch-scoped drops) is unchanged in shape.
• DropReport.ledger_id is now the bare ledger name. Anything asserting against the old mydb:main form needs updating.

[zonotope]

The only thing I'd flag here is the missing event for purging a ledger. Lgtm otherwise.

[zonotope]

This is hairsplitting, I know, so take or leave it as you wish. It's totally subjective, but perhaps we could just say "root" here. main (or whatever) is the root of the ledger, and everything else is a branch. It seems weird to me to have a notion of "root branch". I think "root" fits better or, to continue the tree metaphor, we could say "trunk" or "stem". But, like I said, very subjective, so take it or leave it.

[bplatz]

Addressed in fd8fe74.

[zonotope]

I feel like this should also be an error to eliminate any possibility of surprise, especially since we're no longer treating the main name specially.

[bplatz]

Addressed in aff03b7.

[zonotope]

This bypasses the publisher.purge call that we used to make in favor of publisher.drop_branch for every branch. This matters because .purge used to emit the LedgerRectracted event to the subscribers. Now the subscribers won't know to clear their local caches.

[bplatz]

Addressed in 573c6f7.

[zonotope]

This will do a full nameservice scan then a filter to get the branches. I think it would be better to do the initial scan scoped to the ledger name prefix for the nameservice back ends that support it, but I think that would require a larger refactor of the nameservice traits, so it probably isn't for this pr.

[bplatz]

Agreed — not for this PR. Tracking in #1248.