# Private Control-Plane ↔ AGPL Core — Architecture Boundary Contract

> **Engineering handoff.** The private commercial repository was not provided to
> this preparation; nothing in it has been inspected or validated here. This
> document specifies the boundary the private control plane MUST honor so it
> remains a separate work that *uses* the unmodified AGPL Community Edition
> rather than incorporating it. These rules enforce project policy; they do not
> by themselves determine legal separateness — see counsel and
> `.legal-private/cla-review-checklist.md`.

## Mandatory rules

- **Separate execution.** Run the core as a separate binary/container or a
  separately deployed service. The control plane starts/stops it as a subprocess
  or calls it over a network/IPC boundary.
- **Pin the public release.** Pin the exact public **source release** and the
  **executable/container digest** of the core. No floating `latest`.
- **No incorporation.** No core Go imports, no static/dynamic linking, no Go
  plugins, no vendoring, no `go:linkname`, no copied implementation, and no
  AGPL-generated client code inside the control plane.
- **Independent client.** Talk to the core only through its **existing documented
  CLI / API / file interfaces**. Implement the client independently. Verify
  rights before reusing schemas, SDKs, or generated code.
- **Minimal data exchange.** Exchange only ordinary job configuration, scan
  inputs, status, and final reports (JSON/SARIF/Markdown).
- **Do not** exchange private agent-memory structures, share an internal
  blackboard, load private code into the core, or coordinate internal execution
  hooks.
- **Distinct builds.** Keep core and control-plane builds and artifacts separate.
- **Prove standalone operation.** Demonstrate the core running standalone, and the
  control plane running against a **mock** implementation of the documented
  interface.
- **No private patching.** Do not patch the core in the private repo. If an
  interface is missing, **record the gap** — any required core enhancement must
  go through a separately reviewed **public** release and source-compliance
  process before it can be used in commercial deployment.
- **Maintain source access.** Keep core license/source access available even where
  the core is supplied voluntarily by us.
- **Review before tighter integration.** Any move toward linking/embedding
  requires a new architecture review first.

## Interface inventory (the boundary surface)

The core already emits machine-readable outputs that form the boundary; the
control plane consumes these, nothing deeper:

```
  ┌─────────────────────────┐        documented, stable surface        ┌──────────────────────────┐
  │  PRIVATE control plane   │                                          │  AGPL core (unmodified,    │
  │  (separate repo/build)   │                                          │  pinned release + digest)  │
  │                          │  ── invoke: `pentestswarm scan …` ─────► │                            │
  │  scheduler, state/diff,  │     (CLI args: target, scope, flags,     │  swarm engine, agents,     │
  │  RBAC, dashboards, feed  │      --verify, output path)              │  --verify oracles, report  │
  │  service, billing        │  ◄── consume: JSON report / SARIF ────── │  + SARIF emitters          │
  │                          │     + exit code + event stream           │                            │
  └─────────────────────────┘        (process / network boundary)      └──────────────────────────┘
       artifacts kept distinct; source-download link shown in any commercial deployment
```

- **Inbound to core:** CLI invocation / documented API — target, scope,
  provider/config, `--verify`, output location. No private code injected.
- **Outbound from core:** JSON findings report, SARIF, Markdown report, campaign
  event stream, exit code. No private agent-memory / blackboard internals crossed.
- **Not part of the boundary:** `internal/…` Go packages, the blackboard, agent
  memory, execution hooks — these stay inside the core and are never imported.

## Mechanical checks for the private-repo CI (policy enforcement)

Implement these as gates in the **private** repo (specification only; not run
here):

1. **Dependency inventory** — assert the core module is **absent** from the
   control plane's direct/transitive Go dependencies
   (`go list -deps ./...` / `go mod graph` must not contain
   `github.com/Armur-Ai/Pentest-Swarm-AI`).
2. **No replace/vendored/copied core** — scan for `replace` directives pointing at
   the core, vendored core paths, or copied core source (hash/file-name match).
3. **Binary build metadata** — where available, verify the control-plane binary's
   build info does not embed the core module.
4. **Pinned artifact/source correspondence** — the pinned core digest matches the
   pinned public source release.
5. **Working source-download link** — the exact-version Corresponding Source link
   resolves.
6. **Standalone interface tests** — the control plane passes its test suite
   against a **mock** of the documented interface (proves no hidden coupling).

These checks enforce the policy above. They are necessary but not sufficient for
a legal conclusion; separateness is confirmed by counsel, not CI.