DarDev keeps platform contracts in packages/contracts—JSON Schemas and route catalogs that both DarDev Ops and the Go integration bus validate before boot. ops-validate runs the same gates locally and in CI so manifest drift, bus parity gaps, and malformed startup status never reach production silently. This is the contract spine behind crm-orchestrates-bus-executes: CRM and Ops declare intent; the bus executes against frozen HTTP contracts.
Domain A (Ops console at ops.dardev.net) and Domain B (platform bus on dardev-vps) must not import each other's code. They share only language-neutral files under packages/contracts plus HTTPS. That boundary is intentional—it lets Ops deploy independently from the mail stack described in inside-unified-mailer-stack while both sides agree on what a valid manifest or bus route looks like.
What lives in packages/contracts
- bus-route-catalog.json — canonical HTTP routes (method, path, handler, auth group)
- bus-auth-modes.json — fail-closed auth middleware rules for M17 security gates
- schemas/manifest-v1.schema.json — solution manifest shape (connectors, pipelines, visibility)
- schemas/connectors-registry.schema.json — registered provider types and capability IDs
- schemas/bus-route-catalog.schema.json — catalog file self-validation
- schemas/ops-startup-status.schema.json — boot-time drift warnings for SetupPanel
The route catalog currently tracks on the order of fifty bus endpoints—the same surface sync-worker exposed before the Go migration. When handlers change, engineers regenerate the catalog with ops-validate bus-sync-catalog and run bus-parity to ensure every manifest-declared route still exists in the published contract.
ops-validate commands
The ops-validate shell wrapper dispatches Go gates (bus-parity, platform-go, tracker) and Node/Python checks (json-schema, script languages, startup-awareness). For schema work the important subcommands are:
- bash scripts/ops/validate/ops-validate.sh json-schema validate — ajv-check manifests and registries against schemas/
- bash scripts/ops/validate/ops-validate.sh json-schema format — normalize JSON contract files
- bash scripts/ops/validate/ops-validate.sh json-schema format --check — CI gate; fails on unformatted drift
- bash scripts/ops/validate/ops-validate.sh json-schema-sync — copy schemas into platform/bus embed path before Docker build
- cd ops && npm run validate:json-schema — Ops runtime ajv parity with CLI
Three consumers, one truth
First consumer: CI and local pre-commit via ops-validate. Pull requests touching ops/solutions/manifests or platform/bus handlers should pass json-schema validate and bus-parity before merge. Second consumer: platform bus at startup embeds the same schemas and rejects malformed config rather than serving half-registered routes. Third consumer: Ops console uses ajv in ops/lib/json-schema.ts to validate startup status JSON written by scripts/ops/validate/startup-check.sh—warnings surface in SetupPanel without blocking dev entirely.
Manifest validation in practice
Each solution workspace—Hesabi, 20.tn, DarDev Services, company mail—stores its connector graph in solutions/{id}/manifest.json. The manifest-v1 schema enforces required fields: id, status, connectors array with typed instances, pipelines with runsOn operator-pc or vps, and visibility gates for the switcher. Validators warn when two DNS connectors claim the same zone or when showInSwitcher is true but pipelines array is empty.
Legacy registries (tracks.json, integrations/index.json, overlay files) are retired in favor of this single spine. Migration scripts map old Hesabi integration JSON into crm-twenty and list-listmonk connector instances. Until every solution migrates, ops-validate may run both legacy validate-solution-registry.mjs and new json-schema gates—the goal is one path.
Bus parity and frozen HTTP
Frozen HTTP contracts enabled the strangler migration from Node sync-worker to Go platform/bus without breaking Twenty webhooks or Listmonk subscribe flows. bus-route-catalog.json is the published API surface; validate-bus-parity.mjs asserts manifest bus.routes entries are subsets of the catalog. Ops never calls undocumented bus paths—capability actions map to catalog entries with explicit auth modes from bus-auth-modes.json.
This discipline matches deployed-realities-explained honesty: we document what is validated and shipped, not aspirational endpoints. When a route is experimental, it stays out of the catalog until the handler and schema land together.
Startup awareness schema
ops-startup-status.schema.json types the file at data/ops-startup-status.json produced on npm predev and setup-local boot. Fields include manifest drift hints, bus parity warnings, and scripts-policy violations. Platform bus logs WARN startup: lines when the file reports issues; Ops SetupPanel renders the same JSON for humans. Strict mode in CI can elevate warnings to errors via startup-awareness-status --validate --gate SA-1.
DarDevOps category alignment
JSON Schema gates are infrastructure-as-contract—the same mindset DarDevOps brings to Kubernetes manifests and GitOps repos. Contracts live in git, validators run in CI, and runtime services embed identical schemas. Product teams do not hand-edit bus routes in production; they extend packages/contracts, regenerate catalogs, and redeploy through the normal Fabric VPS pipeline.
Workflow for engineers
- Edit manifest or schema under packages/contracts/
- Run json-schema validate and format locally
- If schemas changed, run json-schema-sync
- Run bus-parity and platform-go gates before PR
- Deploy bus image; Ops picks up manifest changes on next console deploy
Future work includes OpenAPI generation from platform/bus/cmd/openapi and tighter Go-native ops-validate ports (cmd/ops-validate already handles tracker and bus-parity). The contract spine itself is production-ready—the three-domain architecture depends on it.
Why JSON Schema instead of TypeScript types shared across repos?
Ops is TypeScript and the bus is Go. JSON Schema is language-neutral, embeddable in both runtimes, and diff-friendly in PRs. TS types remain inside each domain; contracts cross the boundary only as schemas plus HTTP.
What happens if manifest validation fails in CI?
The PR fails on json-schema validate. Fix the manifest or update the schema with a version bump—never skip validators to unblock a deploy.
Do I need to run json-schema-sync on every edit?
Only when files under packages/contracts/schemas/ change. Catalog-only edits still need bus-sync-catalog if handlers moved.
How does this relate to CRM orchestration?
Twenty workflows and Ops capabilities call bus routes defined in the catalog. Schema validation ensures manifests reference real handlers before any outreach automation runs—see crm-orchestrates-bus-executes.
Where is the authoritative README?
packages/contracts/README.md in the dardev-platform monorepo lists files, commands, and consumers. Platform Go roadmap docs describe cutover status.
