# nexuscrm-contract — agent guide
> Neutral semantic contract & extension IR — the dependency root of L0.

**You are in `nexuscrm-contract`** (L0 · neutral contract / dependency root). This repo's own concern definition, public
surface, and dependency rules live in [`README.md`](README.md). The
platform-wide map below tells you where every *other* concern lives, so you land
in the right repo before writing code.

## NexusCRM platform — repository & module map

The platform is split **by release boundary** into seven repositories across
three layers. Rule of thumb: a *repository* is a release boundary, a *Go module*
is an architecture boundary, a *package* is an import boundary. Dependencies
always point **down** — `L2 → L1 → L0` — and inside L0 everything depends on the
neutral contract while nothing depends back up.

- **L0 — platform mechanism** (app-blind: knows metadata / records / policy, not
  Salesforce and not any tenant). Five repos.
- **L1 — product / dialect** (the Salesforce-compatible CRM shape). One repo.
- **L2 — tenant delivery** (one customer's overlays + final pack + deploy). One repo.

### The seven repositories

| Repo | Layer | Module path / pin | Owns |
|---|---|---|---|
| **NexusCRM** (core) | L0 | `github.com/nexuscrm/*` (workspace) | The engine + host + frontend: `metadata`, `records`, `automation`, `analytics`, `permissions`, `persistence`, `storage`, `db`, `auth`, `audit`, `events`, `files`, `outbound`, `kernel`, the `backend` HTTP host, the React `frontend`, and `tools/boundarygate`. The mutually-recursive engine SCC stays here as a modular monolith. |
| **nexuscrm-contract** | L0 | `github.com/pingcap-inc/nexuscrm-contract` `v0.1.0` | Neutral typed contract / extension IR. The root module is the stdlib-only dependency root. A separately versioned nested `wire-go` module may contain generated protobuf/gRPC bindings and pure semantic mappings, but no transport-host runtime. Everything imports the appropriate published module; neither imports back up. |
| **nexuscrm-controlplane** | L0 | `…/nexuscrm-controlplane` `v0.1.4` | Pack install / upgrade / migrate / verify / drift lifecycle + schema bootstrap (`bootstrapimpl`). Backend-free. |
| **nexuscrm-api-host** | L0 | `…/nexuscrm-api-host` `v0.1.0` | Transport host primitives: dialect transport binding, auth / session / permission middleware, websocket, security headers, version routes. |
| **nexuscrm-connectors** | L0 | `…/nexuscrm-connectors` `v0.1.0` | Integration runtime: inbound events / routing, webhooks, outbound callouts, named credentials, connector registry (capabilities / health / throttle / sync state). |
| **nexuscrm-app-packs** | L1 | pack repo + `…/dialects/dialect-*` modules | Official Salesforce-compatible CRM packs, the SF CRM dialect Go modules (`dialect-sf-crm`, `dialect-sf-crm-soql`), app frontend source, and one sealed CI-only non-CRM issue-tracker conformance fixture. No issue-tracker pack, dialect, frontend, distribution, or release surface exists. Consumed via `official_repo:<pack>` + `NEXUSCRM_OFFICIAL_APP_PACKS_ROOT`. |
| **nexuscrm-pingcap-pack** | L2 | tenant pack repo | PingCAP tenant overlays, final merged pack assembly, bootstrap / deploy orchestration. Nothing depends on it. |

### Where each concern lives (routing table)

| If you need to work on… | Go to |
|---|---|
| Metadata engine / schema interpreter | NexusCRM → `nexuscrm-metadata` |
| Records CRUD / query execution | NexusCRM → `nexuscrm-records` |
| Flow / validation / automation | NexusCRM → `nexuscrm-automation` |
| Reports / dashboards / analytics | NexusCRM → `nexuscrm-analytics` |
| Permissions / FLS / RLS / sharing | NexusCRM → `nexuscrm-permissions` |
| Persistence / storage / DB driver | NexusCRM → `nexuscrm-persistence`, `nexuscrm-storage`, `nexuscrm-db` |
| Auth / session / JWT | NexusCRM → `nexuscrm-auth` (+ `nexuscrm-api-host` middleware) |
| Audit / events / outbox | NexusCRM → `nexuscrm-audit`, `nexuscrm-events`, `nexuscrm-outbound` |
| Files / attachments | NexusCRM → `nexuscrm-files` |
| Backend HTTP host, REST handlers, engine wiring | NexusCRM → `backend` |
| React runtime + host SDK | NexusCRM → `frontend` (`src/host-sdk`, `src/host`) |
| Module-boundary gate / policy | NexusCRM → `tools/boundarygate` |
| Neutral types / contract / IR | **nexuscrm-contract** |
| Pack install / upgrade / verify / drift / bootstrap | **nexuscrm-controlplane** |
| Transport host, dialect binding, middleware, websocket | **nexuscrm-api-host** |
| Connectors / webhooks / callouts / named credentials | **nexuscrm-connectors** |
| Salesforce CRM dialect / SObject·SOQL skin / official packs / app frontend | **nexuscrm-app-packs** (L1) |
| PingCAP tenant config / final pack / deploy | **nexuscrm-pingcap-pack** (L2) |

### Dependency direction (hard rules)

- The `nexuscrm-contract` **root Go module** depends on the Go stdlib only; every
  other L0 module imports it. The separately versioned nested `wire-go` module
  may depend only on the root contract module and the code-generation/runtime
  libraries required by its generated protobuf/gRPC bindings. It must not own
  server assembly, interceptors, stats handlers, connection policy, routing, or
  authority resolution; those transport-host concerns belong in
  `nexuscrm-api-host`. The first approved use of this split is tracked by
  [NexusCRM#3555](https://github.com/pingcap-inc/NexusCRM/issues/3555).
- `nexuscrm-controlplane`, `nexuscrm-api-host`, `nexuscrm-connectors` depend on the
  contract (+ pinned `github.com/nexuscrm/*` core modules) but **must not import `backend`**.
- `NexusCRM/backend` consumes the published L0 modules as **version pins** (no local
  `replace` on `main`).
- `nexuscrm-app-packs` (L1) builds on the platform's public contract; **L0 must not import L1**.
- `nexuscrm-pingcap-pack` (L2) consumes NexusCRM + app-packs **by ref**; nothing depends on it.
- Inside NexusCRM the engine modules form a mutually-recursive SCC and are kept as
  **one modular monolith** — deliberately *not* split into separate versioned repos.

### Phase status — don't mistake interim state

- **Phase 1 — physical / release split: ✅ merged to `main`.** Seven-repo topology,
  published L0 modules consumed via real version pins, `boundarygate` Forbidden-edge = 0.
- **Phase 2 — L0 / L1 / L2 semantic purity: ⏳ not started.** Rule: *mechanism stays in
  L0; Salesforce / product / tenant shape moves to L1 / L2.* The binding execution
  contract (sequence **L0-A … L0-F**, 12-point DoD) lives in NexusCRM
  `docs/architecture/repo-split.md`. **Do not start Phase 2 behavior migration outside
  that contract.**

## Working in this repo

- **Keep the root module runtime-pure.** No `database/sql`, no `net/http`, no
  transport dependency, and no dependency on any other `nexuscrm` / `pingcap`
  module — Go stdlib only. A nested `wire-go` module is permitted solely for
  generated protobuf/gRPC bindings, pure semantic/status mappings, and inert
  wire-envelope constants approved by the serviceification contract. It is not
  a transport host: server assembly, interceptors, stats handlers, connection
  policy, routing, and authority resolution remain in `nexuscrm-api-host`. CI
  and boundary checks must enforce both sides of this split.
- Add a neutral type here only when **two or more** L0 modules (or an L1 dialect)
  must share it. Never add a Salesforce / CRM / tenant DTO or a SOQL/SOSL parser —
  those belong in `nexuscrm-app-packs` (L1).
- Build / test both modules through the repository gate: `scripts/check.sh`.
  Root-only work may use `GOWORK=off go build ./... && GOWORK=off go test
  ./...`; wire work must also run the nested module tests.
- The root module is published as `github.com/pingcap-inc/nexuscrm-contract`;
  the nested generated module is published independently as
  `github.com/pingcap-inc/nexuscrm-contract/wire-go`. Breaking changes ripple
  to every consumer of the affected module, so publish a semver tag for that
  module and let consumers re-pin.
- `CLAUDE.md` and `AGENTS.md` are kept identical — edit both together.