feat: drop_named_graph + fluree graph CLI (list, drop)

[bplatz]

Summary

• Adds a per-branch named-graph drop: Fluree::drop_named_graph(ledger_id, graph_iri) retracts every triple currently asserted under a named graph in a single new commit. History at older t is preserved, the graph IRI keeps its g_id, and the operation is idempotent on an empty graph (no commit produced).
• Wires up a wire endpoint POST /v1/fluree/drop-graph (admin-protected) and a matching CLI: fluree graph drop <iri> plus a companion fluree graph list. Both subcommands support --remote, tracked-remote auto-routing, and --direct.
• Fixes the ledger.named-graphs block in the /info payload so newly registered graphs show up immediately (not after the next index build).
• Fixes fluree branch drop so a second drop of an already-retracted branch prints "no-op" instead of "Dropped branch".

Details

drop_named_graph (new)

Fluree::drop_named_graph(ledger_id, graph_iri) -> Result<DropNamedGraphReport> walks the live triples under graph_iri and stages a single retract-only commit. Concrete behavior:

• History preserved. Time-travel reads at any prior t see the old graph contents. The graph IRI keeps its assigned g_id; later inserts re-populate it normally.
• Per-branch. Dropping on mydb:dev leaves mydb:main untouched.
• Idempotent. An already-empty graph short-circuits with no commit produced and a DropStatus::AlreadyRetracted outcome.
• System graphs rejected. urn:fluree:default, urn:fluree:txn-meta, urn:fluree:config (the three system graphs) return ApiError::Http(400). Unknown IRIs return 404 before staging so the graph registry isn't silently extended.
• IRI validation. graph_iri is validated as an absolute IRI: requires a <scheme>:<rest> head, no whitespace, no C0/DEL control characters, and rejects RFC 3987-excluded characters. Leading/trailing whitespace is rejected outright, not silently trimmed (7 unit tests in validate_absolute_iri).

Wire endpoint: POST /v1/fluree/drop-graph

Admin-protected — same bracket as /drop, /create, /reindex. Body and response specified in docs/api/endpoints.md; full server-side contract documented in docs/cli/server-integration.md ("Drop Named Graph Contract").

CLI

fluree graph drop <iri>

fluree graph drop <IRI> [--ledger <name>] [--remote <name>] [--direct]

Three-mode dispatch matching the rest of the --remote family: explicit --remote <name> → named remote; otherwise auto-route through a locally running fluree server start if server.meta.json is present; otherwise direct local execution. --direct skips auto-routing.

fluree graph list

fluree graph list [--ledger <name>] [--include-system] [--json] [--remote <name>] [--direct]

Parses the existing /info payload's ledger.named-graphs section. By default hides the three system graphs; --include-system shows them.

Companion fixes

ledger.named-graphs now built from the live registry

build_ledger_block used to enumerate named graphs via BinaryIndexStore::graph_entries(). Two failure modes:

• A ledger with no index ever built reported only urn:default.
• A graph registered in a commit after the last index build was silently missing from info.ledger.named-graphs until the next index ran.

Since fluree graph list parses that same payload, the bug surfaced there as well — newly registered user graphs wouldn't show up between drops or right after an insert.

Fixed by iterating ledger.snapshot.graph_registry.iter_entries() instead, which is mutated at commit-apply time and so is always current. Per-graph flakes / size totals still come from IndexStats.graphs when populated and fall back to 0 otherwise.

fluree branch drop honors DropStatus::AlreadyRetracted

Both the local and remote branch-drop paths in fluree-db-cli/src/commands/branch.rs were only inspecting the deferred field when deciding what to print, so a second drop of an already-retracted branch was reported as a successful "Dropped branch" instead of a no-op. The bug applied to the local report and to the JSON response handler (print_branch_dropped).

Both paths now branch on the authoritative status / DropStatus field:

Status	Output
AlreadyRetracted	"Branch '<name>' was already retracted (no-op)."
NotFound	"Branch '<name>' not found."
Dropped	Existing dropped / deferred-retract messages, keyed on deferred.

Docs

• New: docs/cli/graph.md — full reference for the fluree graph subcommand family.
• New: "Drop Named Graph Contract" and "Graph List Contract" sections in docs/cli/server-integration.md.
• New: POST /drop-graph spec in docs/api/endpoints.md.
• Cross-links: docs/cli/drop.md and docs/concepts/datasets-and-named-graphs.md point at the new graph reference.
• Updated: docs/SUMMARY.md, docs/cli/README.md table of contents.
• Updated: /info contract entry in server-integration.md now notes ledger.named-graphs as required for fluree graph list.

Tests

• 11 integration tests in fluree-db-api/tests/it_drop_named_graph.rs covering:
  • Happy path single-graph drop, multi-triple graph drop.
  • Idempotency on an already-empty graph (no commit produced).
  • History preservation via DatasetSpec + TimeSpec lookups at older t.
  • Per-branch isolation: drop on one branch leaves the other intact.
  • Every validation / rejection branch (system graphs, unknown IRI, whitespace, invalid scheme, control characters, RFC 3987 excluded chars).
• 7 unit tests for validate_absolute_iri.
• it_ledger_info_named_graphs.rs (179 lines) covers the /info registry fix — pre-index, post-insert, post-drop snapshots all agree with the live registry.
• Existing it_branch extended with assertions for the AlreadyRetracted CLI output fix.