Skip to content

refactor(cli): route portable v2 orchestration through the graphforge-api facade #1015

Description

@DecisionNerd

Found during the architecture audit (sub-agent review). AGENTS.md designates graphforge-api the public API.

Finding (MEDIUM)

The CLI bypasses the facade into storage internals, creating a second parallel path for the same operations the bindings use:

  • cli/Cargo.toml:18 — production dep cli → storage
  • cli/src/hub_clone.rs:2061-2075 — calls graphforge_storage::{resolve_project_generation, plan_complete_portable_v2, export_complete_portable_v2, verify_portable_v2} directly
  • cli/src/hub_fixture_artifacts.rs:11repack_verified_expanded_portable_v2
  • cli/src/portable_cli.rs:472StorageAllocationLifecycle
  • The facade already exposes the same ops (api/src/portable.rs:254 verify_portable_v2, re-exported api/src/lib.rs:170)

The duplicate path can diverge behaviorally from the facade used by Python/Node.

Acceptance criteria

  • CLI portable-v2 flows call graphforge-api (facade re-exports or new facade methods)
  • cli → storage production dependency removed
  • Behavior parity test: facade path and CLI path produce identical receipts for the same fixture

Architecture review decision

Co-design this with #1021. The API facade should own portable-v2 orchestration while a dedicated portable/OCI protocol crate may own network transport. Moving the registry client into graphforge-discovery is not assumed.

Additional acceptance criteria:

  • graphforge-api exposes the complete supported portable workflow without leaking storage-internal types
  • CLI, Python, and Node use the same facade behavior and receipt contract
  • Network transport remains outside storage durability code
  • Land in compatibility-preserving slices

Metadata

Metadata

Assignees

No one assigned

    Labels

    coreCore source code changesrelease:noneNo release note or version impacttoolingDeveloper tooling and automation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions