Nexus System Descriptor

1. Purpose and Design Rationale

An NSD contains everything needed to stand up a complete Nexus instance: component configurations and deployment targets, the complete data model (entity classes, BDTs, field definitions), RBAC structure, pipeline flow definitions, rulesets, style tokens, node type registry, and contract versions with conformance requirements.

---

2. File Format

Naming convention:

nexus-descriptor-{org_slug}-{version}.nsd.json

Example: nexus-descriptor-nesto-corp-2.1.0.nsd.json

The file is standard JSON (UTF-8, no BOM). Maximum size: 50 MB (including embedded rulesets and flow graphs).

---

3. Root Schema

{
  "$schema": "https://api.nexus-dev.codezerogroup.com/schemas/nsd/1.0.json",
  "nsd_version": "1.0",
  "descriptor_id": "nsd-nesto-corp-2026-05-02T14:30:00Z",
  "created_at": "2026-05-02T14:30:00Z",
  "created_by": "m.lubkowski@ou-uv.com",
  "org_slug": "nesto-corp",

  "contract_versions": { ... },
  "deployment_targets": { ... },
  "data_model": { ... },
  "rbac": { ... },
  "rulesets": { ... },
  "flows": { ... },
  "node_registry": { ... },
  "style": { ... },
  "components": { ... },

  "checksums": {
    "contract_versions": "sha256:a1b2c3...",
    "deployment_targets": "sha256:d4e5f6...",
    "data_model":         "sha256:g7h8i9...",
    "rbac":               "sha256:j0k1l2...",
    "rulesets":            "sha256:m3n4o5...",
    "flows":              "sha256:p6q7r8...",
    "node_registry":      "sha256:s9t0u1...",
    "style":              "sha256:v2w3x4...",
    "components":         "sha256:y5z6a7...",
    "root":               "sha256:b8c9d0..."
  }
}

3.1 Checksum Architecture

Each section checksum is computed as:

SHA-256( JSON.stringify(section, keys_sorted=true, indent=none) )

The root checksum is computed as:

SHA-256( sorted_concat( all_section_checksums ) )

---

4. Section: contract_versions

Declares which layer contract versions this NSD requires. Any runtime that does not implement the required contract version MUST reject the deployment.

{
  "contract_versions": {
    "controller":    "C-1.0",
    "model":         "M-1.0",
    "view":          "V-1.0",
    "orchestration": "O-1.0",
    "nsd_schema":    "1.0"
  }
}

---

5. Section: deployment_targets

Specifies which implementation of each MVC layer this NSD deploys to. Each target includes its full connection and provisioning configuration.

{
  "deployment_targets": {
    "controller": {
      "implementation": "wormwood-python-fastapi",
      "version": "0.2.0",
      "contract": "C-1.0",
      "target_stack": "aws-lambda",
      "config": { ... }
    },
    "model": {
      "implementation": "delta-prism-python-fastapi",
      "version": "0.1.0",
      "contract": "M-1.0",
      "target_stack": "aws-neptune",
      "config": { ... }
    },
    "view": {
      "implementation": "chameleonv2-react",
      "version": "1.2.2",
      "contract": "V-1.0",
      "target_stack": "static-cdn",
      "config": { ... }
    },
    "orchestration": {
      "implementation": "nexus-runtime-python",
      "version": "0.1.0",
      "contract": "O-1.0",
      "target_stack": "aws-step-functions",
      "config": { ... }
    }
  }
}

5.1 Supported Target Stacks

---

6. Section: data_model

Complete entity class definitions, Business Data Type (BDT) registry, and field-level metadata. This is the single source of truth for what data shapes exist in this deployment.

6.1 BDT Registry

Each BDT entry defines a semantic type with constraints, lifecycle class, and unit. BDTs ensure that the same field type is validated identically across every target stack.

{
  "bdt_registry": [
    {
      "code": "PLN_Amount",
      "python_type": "float",
      "description": "Polish Zloty monetary amount. Never negative.",
      "lifecycle": "MUTABLE_STATE",
      "constraints": { "min_value": 0.0, "max_value": 10000000.0 },
      "unit": "PLN",
      "nullable": false
    }
  ]
}

6.2 Entity Classes

Each entity class declares its fields with BDT references, group assignments, and per-role RBAC visibility.

6.3 Field RBAC

Every field in every entity class carries an rbac map defining visibility and editability per role. This is the schema that the View layer uses to filter fields at render time, and the Model layer uses to enforce write permissions.

6.4 Lifecycle Policy

---

7. Section: rbac

Complete RBAC structure for the deployment: roles with permission matrices, organisations, teams, and members. The NSD declares the full permission model; the runtime enforces it.

---

8. Section: rulesets

All calculation, validation, and scoring rulesets. Each ruleset is a named, versioned collection of rules with formulas, priorities, and technology scoping.

8.1 Formula Portability

Formulas use the Wormwood formula language. The formula language is the portable contract — every Controller implementation must parse and evaluate the same formula syntax identically.

---

9. Section: flows

All pipeline definitions with their complete graph structures, node configurations, edge wiring, and trigger configurations. Each flow is a directed acyclic graph (DAG) of typed nodes connected by edges.

9.1 Graph Determinism

The same graph with the same trigger input and the same Human Gate decisions MUST produce the same run result on every target stack. Node positions are visual metadata for the Canvas editor and have no effect on execution. Execution order is determined by topological sort of the edge graph.

---

10. Section: node_registry

Declares all node types available in this deployment. Each node type defines its inputs, outputs, config fields, and implementation status. This is the type system for the pipeline graph — a flow can only use node types declared in this registry.

---

11. Section: style

ChameleonV2 theme tokens and CSS customisation. Applied globally and overridable per-pipeline via flows[].style_tokens.

{
  "style": {
    "global_tokens": {
      "theme": "light",
      "accent_color": "#6366f1",
      "font_family": "Inter, system-ui, sans-serif",
      "border_radius": "8px",
      "input_height": "40px",
      "label_weight": "500",
      "error_color": "#ef4444",
      "success_color": "#22c55e",
      "warning_color": "#f59e0b"
    },
    "brand": {
      "logo_url": null,
      "favicon_url": null,
      "product_name": "Nexus"
    }
  }
}

---

12. Section: components

Infrastructure-level component definitions. Each component maps to a deployable service, binary, or function with resource requirements, health check endpoints, and inter-component dependencies.

---

13. Checksum Verification

13.1 Generating Checksums

import hashlib, json

def section_checksum(section_data: dict) -> str:
    canonical = json.dumps(section_data, sort_keys=True, separators=(',', ':'))
    return "sha256:" + hashlib.sha256(canonical.encode('utf-8')).hexdigest()

def root_checksum(section_checksums: dict) -> str:
    parts = [f"{k}={v}" for k, v in sorted(section_checksums.items())]
    combined = "|".join(parts)
    return "sha256:" + hashlib.sha256(combined.encode('utf-8')).hexdigest()

13.2 Verification at Deploy Time

The Nexus DevOps Service MUST:

1. Recompute all section checksums from the NSD content
2. Compare against the declared checksums
3. Recompute root checksum from section checksums
4. Compare against declared checksums.root
5. Reject deployment if any checksum mismatches

13.3 Section-Level Diff

Comparing two NSD versions is a comparison of their checksums objects. If a section checksum is identical, the section content has not changed and does not need redeployment. This enables:

• Ruleset-only deploys (Controller hot-reload, no Model/View restart)
• Style-only deploys (View asset rebuild, no backend restart)
• RBAC-only deploys (permission refresh, no data migration)

---

14. NSD Lifecycle

14.1 Deployment Sequence

1. Validate NSD — verify checksums, contract versions, schema
2. Plan — diff against current deployed NSD, identify changed sections
3. Preview — show which components will be redeployed and to which targets
4. Execute — deploy changed sections in dependency order: Model → Controller → Orchestration → View → Admin
5. Verify — run health checks on all deployed components
6. Seal — mark NSD as deployed, record deployment timestamp

14.2 Rollback

If deployment fails at any step: stop, revert all changed components to previous NSD version, mark new NSD as revoked with failure reason. The previous NSD remains deployed.

---

15. Security

15.1 Secrets Handling

Secret references use ${secrets.key_name}. Resolved at deploy time from the configured backend. The NSD file never contains plaintext credentials.

15.2 NSD Signing (Future)

When implemented, NSDs will carry an Ed25519 signature with public key fingerprint. The DevOps Service will reject unsigned NSDs in production environments.

15.3 Sensitive Field Protection

Entity class fields with rbac value "masked" for any role MUST be encrypted at rest in the Model layer. The NSD declares which fields require encryption; the target implementation enforces it.

---

16. DevOps Service Interface

---

Technique Summary

17. Versioned Document References