feat: entity specs

.github/workflows/v0.10.0_entity-manifest.yaml

@@ -0,0 +1,30 @@
+name: v0.10.0-Entity-Manifest
+
+on:
+  pull_request:
+    paths:
+      - "pkgs/**"
+      - "entity_specs/**"
+      - "scripts/generate_entity_manifest.py"
+      - "scripts/generate_entities.py"
+      - ".github/workflows/v0.10.0_entity-manifest.yaml"
+  workflow_dispatch:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Compile entity manifest generator
+        run: |
+          python -m py_compile scripts/generate_entity_manifest.py
+          python -m py_compile scripts/generate_entities.py
+      - name: Check entity manifest drift
+        run: python scripts/generate_entity_manifest.py check
+      - name: Validate entity manifest and source specs
+        run: python scripts/generate_entity_manifest.py validate
+      - name: Check source-spec Python generation
+        run: python scripts/generate_entities.py check

entity_specs/README.md

@@ -0,0 +1,43 @@
+# Swarmauri Entity Specs
+
+This directory holds the bootstrap inventory and source specs for generated
+Swarmauri entities. The manifest is generated from the current Python source so
+the first cut can inventory the existing surface without importing package code.
+The files under `sources/` are the editable pilot source specs that future
+generators should treat as the durable authority.
+
+Run these commands from the repository root:
+
+```bash
+python scripts/generate_entity_manifest.py generate
+python scripts/generate_entity_manifest.py check
+python scripts/generate_entity_manifest.py validate
+python scripts/generate_entities.py check
+```
+
+The manifest scope includes:
+
+- `swarmauri_core`
+- `swarmauri_base`
+- `swarmauri_standard`
+- workspace packages named `swarmauri_*`
+- legacy typo packages named `swamauri_*` when they expose Swarmauri entities
+
+The manifest scope excludes `peagen`, all `tigr*` packages, `tigrcorn`, example
+packages, tests, caches, build outputs, and virtual environments.
+
+Future language generators should consume `swarmauri_entities.v1.json` and emit
+Python, Rust, npm TypeScript, TSX, React TSX, Vue TSX, and Svelte TSX outputs
+from that manifest while source specs are bootstrapped. Once a family has a
+source spec, generators should prefer the source spec over rediscovering Python
+classes independently.
+
+## Source Specs
+
+`sources/documents.v1.json` is the first pilot source spec. It describes
+`DocumentBase` and `Document` with stable entity ids, generator targets,
+registration metadata, and fields. The `validate` command checks source specs
+against the bootstrap manifest so stale ids, roles, or missing required fields
+fail before generators consume them. `scripts/generate_entities.py check`
+renders the documents Python files in memory and compares them against the
+current package sources without rewriting package files.

entity_specs/schema.v1.json

@@ -0,0 +1,308 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://swarmauri.com/schemas/swarmauri-entities.v1.json",
+  "title": "Swarmauri Entity Manifest",
+  "type": "object",
+  "required": [
+    "manifest_version",
+    "schema",
+    "generated_by",
+    "targets",
+    "scope",
+    "summary",
+    "packages",
+    "entities"
+  ],
+  "properties": {
+    "manifest_version": {
+      "const": "1"
+    },
+    "schema": {
+      "type": "string"
+    },
+    "generated_by": {
+      "type": "string"
+    },
+    "targets": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "scope": {
+      "type": "object"
+    },
+    "summary": {
+      "type": "object",
+      "required": [
+        "package_count",
+        "entity_count",
+        "by_layer",
+        "by_role"
+      ],
+      "properties": {
+        "package_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "entity_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "by_layer": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "by_role": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0
+          }
+        }
+      }
+    },
+    "packages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "name",
+          "member",
+          "scope_reason",
+          "entity_count"
+        ],
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "member": {
+            "type": "string"
+          },
+          "scope_reason": {
+            "type": "string"
+          },
+          "entity_count": {
+            "type": "integer",
+            "minimum": 1
+          }
+        }
+      }
+    },
+    "entities": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "name",
+          "layer",
+          "role",
+          "package",
+          "module",
+          "source_path",
+          "line",
+          "bases",
+          "decorators",
+          "registration",
+          "fields",
+          "enum_members",
+          "methods"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "layer": {
+            "enum": [
+              "core",
+              "base",
+              "concrete"
+            ]
+          },
+          "role": {
+            "type": "string"
+          },
+          "package": {
+            "type": "string"
+          },
+          "module": {
+            "type": "string"
+          },
+          "source_path": {
+            "type": "string"
+          },
+          "line": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "bases": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "decorators": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "registration": {
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "type_discriminator": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "resource_default": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "doc": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "fields": {
+            "type": "array"
+          },
+          "enum_members": {
+            "type": "array"
+          },
+          "methods": {
+            "type": "array"
+          }
+        }
+      }
+    },
+    "source_specs": {
+      "type": "array",
+      "description": "Optional list of editable source-spec files governed by $defs.source_spec.",
+      "items": {
+        "$ref": "#/$defs/source_spec"
+      }
+    }
+  },
+  "$defs": {
+    "source_spec": {
+      "type": "object",
+      "required": [
+        "manifest_version",
+        "family",
+        "targets",
+        "entities"
+      ],
+      "properties": {
+        "manifest_version": {
+          "const": "1"
+        },
+        "family": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string"
+        },
+        "targets": {
+          "type": "array",
+          "items": {
+            "enum": [
+              "python",
+              "rust",
+              "npm",
+              "tsx",
+              "react+tsx",
+              "vue+tsx",
+              "svelte+tsx"
+            ]
+          }
+        },
+        "entities": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/source_entity"
+          }
+        }
+      }
+    },
+    "source_entity": {
+      "type": "object",
+      "required": [
+        "id",
+        "name",
+        "layer",
+        "role",
+        "fields"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "layer": {
+          "enum": [
+            "core",
+            "base",
+            "concrete"
+          ]
+        },
+        "role": {
+          "type": "string",
+          "minLength": 1
+        },
+        "base_ids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "registration": {
+          "type": [
+            "object",
+            "null"
+          ]
+        },
+        "fields": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "annotation"
+            ],
+            "properties": {
+              "name": {
+                "type": "string",
+                "minLength": 1
+              },
+              "annotation": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}