# nexuscrm-contract
> Neutral semantic contract & extension IR for the NexusCRM platform.

Part of the **NexusCRM platform**, split by release boundary into L0 platform repos + L1 product packs + L2 tenant delivery. This repository is an **L0 platform contract module**.

## What this is
This is the type and contract foundation of the platform — the common language that every L0 module and L1 pack speaks. It defines neutral identifiers, metadata/records/query/lifecycle descriptors, the pack and component manifest contracts, neutral extension-point and runtime-port interfaces, seed-row and schema-catalog types, neutral error/problem categories, and policy-binding descriptors. It is declaration-first: it carries no runtime behavior, only the shared semantic intermediate representation other modules implement and exchange. When an approved neutral contract is exposed over protobuf/gRPC, this repository may also publish a separately versioned nested `wire-go` module containing generated bindings, pure semantic/status mappings, and inert wire-envelope constants; transport hosting remains elsewhere.

## Role in the L0 / L1 / L2 architecture
This sits at the very bottom of L0 as the dependency root. It is platform **mechanism vocabulary**, not product, Salesforce, or tenant shape. Every other L0 concern module and every L1 dialect pack imports it; it imports nothing back. Because it is the shared contract, it must stay neutral so that any product family can be expressed on top without leaking product specifics downward.

## What belongs here
- Neutral IDs and constants
- Metadata, records, query, and lifecycle descriptors
- Pack and component manifest contracts
- Neutral extension-point and runtime-port interfaces
- Seed-row and schema-catalog types
- Neutral error / problem categories
- Policy-binding descriptors

## What does NOT belong here
- Any data or transport-host runtime: no `database/sql`, no `net/http`, server
  assembly, interceptors, stats handlers, connection policy, routing, or
  authority resolution
- Any dependency on backend, controlplane, api-host, or a database driver
- Salesforce / CRM wire DTOs
- A SOQL / SOSL parser or any query-language implementation
- Tenant deploy shape

The root Go module remains runtime- and transport-pure. This repository owns
the reviewed proto source. The separately released
[`wire-go`](wire-go/README.md) nested module contains only generated
protobuf/gRPC bindings, pure semantic/status mappings, and inert envelope
constants for coarse Runtime capabilities that have completed wire publication.
It contains no
transport host; its dependencies do not enter the root module's production or
test closure.

## Public surface (key packages)
- `pkg/contract` — core neutral contract surface shared across the platform
- `pkg/models` — neutral metadata/records/auth/flow descriptor models
- `pkg/constants` — neutral identifiers, context keys, permission constants
- `pkg/controlplane` — neutral control-plane port and runtime-profile interfaces
- `pkg/connector` — neutral connector field-mapping and push-contract types
- `pkg/metadatair` — neutral metadata IR identity, ownership, source, and lowering-boundary contract
- `pkg/approvalir` — lossless typed approval field-update values with closed
  kinds, a canonical neutral definition envelope for Catalog compiler input,
  and fail-closed validation; no product wire grammar or parser
- `pkg/runtime/commonv1` — shared Runtime v1 receipts, safe failures, physical
  identifier bounds, and fail-fast overload invariant; transport-free
- `pkg/runtime/applicationnavigationv1` — synchronous, revision-bound Read,
  Resolve, and Save of current application navigation; explicit empty documents,
  lossless resource/page/URL targets, and request-bound save responses. Page IDs
  are stable application references; routes and availability remain app-owned.
  Authentication, authorization, persistence, and transport remain outside this
  semantic module. See [the navigation contract](APPLICATION_NAVIGATION_V1.md).
- `pkg/runtime/permissionadminv1` — stored permission-authoring catalogs and
  grants, distinct from caller-effective permission evaluation
- `pkg/runtime/permissionauthoringv1` — one coherent Permission Set authoring
  snapshot plus one bounded atomic five-family patch, identity-and-revision
  bound compare-token concurrency, durable command reconciliation, and closed
  retry semantics; the opaque token is neither a credential nor proof-of-read,
  and transport plus trusted authority remain outside the semantic request
- `pkg/runtime/analyticsauthoringv1` — typed, bounded platform-native atomic
  dashboard/report/folder authoring operations with request-bound receipts;
  report create requires a concrete folder authorization target, while report
  updates distinguish absent, set, and clear date-filter effects; public
  product payloads remain caller-owned
- `pkg/runtime/resourceaccessv1` — neutral resource grant mutation and
  effective-access lookup with request-bound principals and resources
- `pkg/runtime/recordsv1` — selected-root v1 semantic values, receipts, failures, limits, and validation
- `pkg/runtime/recordattachmentsv1` — bounded source-to-file resolution with
  byte-accurate source-field proof, opaque unavailable outcomes, and no product
  URL grammar, source-table, or authorization payload
- `pkg/runtime/recordaccessv1` — coarse batch record-access v1 semantics,
  immutable neutral vectors, bounds, deterministic result rules, and retry
  classification; no identity or authority payload
- `pkg/runtime/queryv1` — one bounded structured records-query page and its
  field-history branch, with typed recursive values, exact decimals, receipts,
  deterministic projection order, and no external query/cursor grammar
- `pkg/runtime/relatedcountsv1` — one bounded relationship-field count batch
  with separate parent authorization identity, opaque item-local outcomes, and
  one consistency receipt set; product route grammar and response projection
  remain caller-owned
- `pkg/runtime/pagelayoutresolutionv1` — one bounded caller-effective PageLayout
  selection batch with authenticated identity kept server-owned, opaque layout
  documents, same-call related-list targets, and deterministic receipts
- `pkg/runtime/recorddefaultsv1` — one bounded create-default preview with
  typed sibling-max and current-principal values, closed provenance, optional
  related-parent context, and no product layout or response grammar
- `pkg/runtime/bulkingestv1` — neutral durable bulk-ingest job lifecycle and
  bounded client-streaming upload, with request-bound responses and only
  disclosure-safe terminal failure codes; product HTTP/CSV wire defaults remain
  caller-owned
- `pkg/runtime/recyclebinv1` — one bounded caller-visible deleted-record list
  with delete-event authority, CRUD/RLS/FLS filtering, chronological ordering,
  opaque per-object failures, and one consistency receipt set; equal deletion
  instants are semantically tied, while product route grammar and restore/purge
  mutations remain caller-owned
- `pkg/runtime/recordmutationv1` — coarse idempotent root-record mutation
  command, exact typed values, atomic/independent batch semantics, terminal
  outcomes, reconciliation, canonical digest grammar, and immutable vectors;
  no identity, database, worker, or product projection
- `pkg/runtime/applicationresultv1` — canonical Connector V2 ExecutionRef
  identity plus Runtime-owned terminal application-result digests, commit
  receipts, and exact reconciliation; no connector state, persistence, worker,
  provider, or transport hosting
- `pkg/runtime/outboundintentv1` — provider-neutral Runtime-to-Integration
  outbound-intent lifecycle with typed mail payloads, delivery results,
  accepted resource no-effect receipts, and shared Integration V2 identity codecs;
  existing producers retain their identifier authority, while an explicitly
  opted-in producer may use trusted-scope logical-effect identity; no credential
  secret, provider implementation, or transport hosting
- `pkg/runtime/mailboxauthorizationv1` — narrow connected-mailbox lifecycle
  authorization whose app installation and subject come only from trusted
  Runtime context; no caller-selected authority or effective-permission export
- `pkg/runtime/flowcommandv3` — canonical Connector V2 Runtime Flow payload
  carrying one complete ExecutionRef, exact inputs, and an explicit
  external-effects mode; existing Flow payload versions remain unchanged
- `pkg/runtime/approvalv1` — coarse idempotent approval execution plus
  authorized approval-state reads, closed operation/result unions, immutable
  Runtime receipts, and bounded neutral lifecycle projections; no product HTTP
  grammar, metadata decoder, database tables, or transport hosting
- `pkg/runtime/delegationv1` — Runtime delegation v1 semantic claims,
  canonical Ed25519 compact-JWS codec, hard protocol ceilings, capability
  intersection, and immutable public-key verification; no key provider,
  transport, session/security store, or authority runtime
- `pkg/runtime/identityv1` — neutral `IdentityContext.Exchange` semantic
  request/response and failure contract; user credentials remain transport-only
- `pkg/runtime/sessionv1` — neutral Runtime-owned session lifecycle semantic;
  raw credentials and issued bearer/control values remain transport-only
- `pkg/runtime/federatedloginv1` — neutral Runtime-owned, expiring, single-use
  federated-login state transaction with redirect binding and operation-specific
  nondisclosing Consume failures; provider and public OAuth routes remain L1-owned
- `pkg/runtime/authorizationv1` — neutral Runtime-owned authorization and
  machine-grant lifecycle semantic; public OAuth routes and issued credentials
  remain transport- and app-owned
- `pkg/runtime/externaleffectv1` — neutral pull-based handoff for
  Runtime-owned durable external effects; it carries frozen requests and
  bounded results but no credential secret, provider implementation, or HTTP
  owner
- `pkg/runtime/permissionstatev1` — neutral Permission State lineage/revision,
  authoritative subject, immutable effective snapshot, effect receipt, and
  authority-failure values; no persistence, admission, cache, or transport
  runtime
- `pkg/runtime/securityprojectionv1` — neutral Catalog-to-Runtime security
  projection value identity shared by publication and persistence; no authority,
  repository, lifecycle, or transport behavior
- `pkg/runtime/servingbindingv1` — exact Catalog-derived Runtime serving
  binding value for workload, installation, AppRelease, canonical resource,
  opaque ToolContract digest, capability ceiling, and serving receipts; no
  selector, registry, scope mapping, resource normalizer, or product tool data
- `pkg/catalogpublicationv1` — complete org Catalog publication binding,
  validation, and canonical digest identity shared by control-plane publication
  and Runtime observation; no writer, selector, repository, or serving behavior
- `pkg/catalogpublicationv2` — receipt-backed complete org Catalog publication
  binding with sibling validation-view and owner-receipt-set evidence digests,
  stdlib-only validation, canonical bytes, and immutable vectors; no authority,
  transition, selector, repository, or serving behavior
- `pkg/runtimeports` — neutral runtime-port interfaces (e.g. field-provenance, mapping readers)
- `pkg/schemacatalog` — neutral schema-catalog and standard-permission types
- `pkg/seedrows` — neutral seed-row definitions (standard actions, permissions)

- `pkg/recordsguard` — neutral create-from-source guard descriptors
- `pkg/autonumberseed` — neutral autonumber seed descriptors
- `pkg/stagetiming` — neutral stage-timing types

The Runtime delegation v1 ownership, cryptographic grammar, hard ceilings, and
compatibility policy are specified in
[`RUNTIME_DELEGATION_V1.md`](RUNTIME_DELEGATION_V1.md).
Runtime record-mutation v1 evidence, semantics, ambiguity handling, and
publication order are specified in
[`RECORD_MUTATION_V1.md`](RECORD_MUTATION_V1.md).
Outbound resource owner fencing, terminal no-effect receipts, shared identity
semantics, and mixed-version recovery are specified in
[`OUTBOUND_INTENT_LIFECYCLE.md`](OUTBOUND_INTENT_LIFECYCLE.md).
- `pkg/assertion` — neutral assertion/invariant descriptors

## Dependency rules
- Root module may depend on: the Go standard library only
- A separately versioned nested `wire-go` module may depend on: the root
  contract module plus protobuf/gRPC code-generation and generated-code runtime
  libraries
- Neither module may depend on: any other NexusCRM implementation module, any
  data runtime (`database/sql`), any transport-host runtime (`net/http`, server
  assembly, interceptors, stats handlers, connection policy, routing, authority
  resolution), or any product/Salesforce/tenant code

## How it is consumed
```go
require github.com/pingcap-inc/nexuscrm-contract v0.1.0
```
Consumed by every other L0 module (connectors, controlplane, api-host, and the core engine modules) and by the L1 app-packs dialects as the shared contract.

## Release & versioning
The root module and any nested generated module are published as independently
pinned Go modules. Breaking changes are rare and bump minor/major; consumers
pin the module they import. This split does not move transport-host ownership
out of `nexuscrm-api-host`. The first approved use of this split is tracked by
[NexusCRM#3555](https://github.com/pingcap-inc/NexusCRM/issues/3555).