@specverse/engines 4.1.0

package/assets/examples/manifests/README.md

@@ -0,0 +1,245 @@
+# SpecVerse v3.3 Manifest Examples
+
+This directory contains example manifests demonstrating the v3.3 hybrid mapping system.
+
+## What is a Manifest?
+
+A **manifest** defines **HOW** a deployment is physically implemented by mapping deployment instances to instance factories (technology implementations).
+
+## Architecture Flow
+
+```
+Components (WHAT)
+    ↓
+Deployments (WHERE)
+    ↓ deployment reference
+Manifests (HOW)
+    ↓ hybrid mapping (3-tier priority)
+Instance Factories
+    ↓ code templates
+Generated Code
+```
+
+## Hybrid Mapping System
+
+v3.3 introduces a powerful 3-tier resolution system with clear priorities:
+
+### Resolution Priority
+
+1. **instanceMappings** (highest priority)
+   - Explicit instance name → instance factory
+   - Override everything else for specific instances
+   - Example: `analyticsDb` → `MongoDB6`
+
+2. **capabilityMappings** (medium priority)
+   - Capability pattern → instance factory
+   - Supports wildcards (`api.rest.*`)
+   - Example: `api.rest.reports` → `ReportingAPI`
+
+3. **defaultMappings** (lowest priority)
+   - Category → instance factory
+   - Fallback when no specific mapping found
+   - Example: all `controller` instances → `FastifyPrismaAPI`
+
+## Examples
+
+### 01-simple-default-mappings.yaml
+
+**Simplest approach**: Use default mappings for all instances by category.
+
+```yaml
+defaultMappings:
+  controller: "FastifyPrismaAPI"
+  storage: "PostgreSQL15"
+```
+
+**When to use:**
+- Small projects with consistent technology choices
+- All instances of same category use same factory
+- Minimal configuration needed
+
+**Resolution example:**
+```
+Instance: userApi (category: controller)
+  → Check instanceMappings: ❌ not found
+  → Check capabilityMappings: ❌ not found
+  → Check defaultMappings.controller: ✅ FastifyPrismaAPI
+```
+
+### 02-capability-mappings.yaml
+
+**Medium complexity**: Different capabilities use different factories.
+
+```yaml
+capabilityMappings:
+  - capability: "api.rest"
+    instanceFactory: "FastifyPrismaAPI"
+
+  - capability: "api.rest.reports"
+    instanceFactory: "ReportingAPI"
+    configuration:
+      caching: true
+```
+
+**When to use:**
+- Need different implementations for different capabilities
+- Pattern-based routing (e.g., all `api.rest.*` → Fastify)
+- Capability-specific configuration
+
+**Resolution example:**
+```
+Instance: reportApi with capability "api.rest.reports"
+  → Check instanceMappings: ❌ not found
+  → Check capabilityMappings: ✅ matches "api.rest.reports" → ReportingAPI
+  → (defaultMappings not checked)
+```
+
+### 03-hybrid-mappings.yaml
+
+**Full power**: All three strategies working together.
+
+```yaml
+defaultMappings:
+  controller: "FastifyPrismaAPI"
+  storage: "PostgreSQL15"
+
+capabilityMappings:
+  - capability: "api.rest.reports"
+    instanceFactory: "ReportingAPI"
+
+instanceMappings:
+  - instanceName: "analyticsDb"
+    instanceFactory: "MongoDB6"
+```
+
+**When to use:**
+- Complex applications with mixed technologies
+- Need fine-grained control over specific instances
+- Different teams/services with different tech preferences
+
+**Resolution examples:**
+
+```
+Instance: analyticsDb (category: storage)
+  → Check instanceMappings: ✅ "analyticsDb" → MongoDB6
+  → (capabilityMappings not checked - instance match takes priority)
+  → (defaultMappings not checked)
+
+Instance: reportApi (capability: "api.rest.reports")
+  → Check instanceMappings: ❌ not found
+  → Check capabilityMappings: ✅ "api.rest.reports" → ReportingAPI
+  → (defaultMappings not checked)
+
+Instance: userApi (category: controller, no specific mappings)
+  → Check instanceMappings: ❌ not found
+  → Check capabilityMappings: ❌ not found
+  → Check defaultMappings.controller: ✅ FastifyPrismaAPI
+```
+
+## Deployment Specification
+
+All examples reference `blog-api.specly`, which defines:
+
+- **Components**: User, Post, Comment models
+- **Deployment**: production environment with multiple instances
+  - `userApi` - main REST API (controller)
+  - `adminApi` - admin/reporting API (controller)
+  - `userDb` - PostgreSQL database (storage)
+  - `analyticsDb` - analytics database (storage, can override to MongoDB)
+  - `sessionCache` - Redis cache (storage)
+  - `validator` - Zod validation (service)
+
+## Using These Examples
+
+### Generate Code with Default Mappings
+
+```bash
+specverse realize all blog-api.specly \
+  -m examples/manifests/01-simple-default-mappings.yaml
+```
+
+### Generate with Capability-Based Routing
+
+```bash
+specverse realize all blog-api.specly \
+  -m examples/manifests/02-capability-mappings.yaml
+```
+
+### Generate with Full Hybrid Mapping
+
+```bash
+specverse realize all blog-api.specly \
+  -m examples/manifests/03-hybrid-mappings.yaml
+```
+
+## Best Practices
+
+### Start Simple, Add Complexity As Needed
+
+1. **Phase 1**: Use `defaultMappings` for all instances
+2. **Phase 2**: Add `capabilityMappings` for specialized capabilities
+3. **Phase 3**: Use `instanceMappings` for exceptional cases
+
+### When to Use Each Strategy
+
+**defaultMappings:**
+- ✅ Consistent technology across all instances of same category
+- ✅ Simple projects with unified tech stack
+- ✅ Getting started quickly
+
+**capabilityMappings:**
+- ✅ Different technologies for different capabilities
+- ✅ Pattern-based routing (reports, analytics, admin vs. user APIs)
+- ✅ Capability-specific configuration
+
+**instanceMappings:**
+- ✅ Exceptional instances that need different technology
+- ✅ Migration scenarios (moving one instance to new tech)
+- ✅ Per-instance fine-tuning
+
+### Configuration Precedence
+
+Configuration merges in this order (later overrides earlier):
+
+1. Instance factory defaults
+2. Global manifest configuration
+3. Mapping-specific configuration
+4. (Future: instance-level configuration in deployment)
+
+## Migration from v3.2
+
+v3.2 manifests used `implementationTypes` array:
+
+```yaml
+# v3.2 (old)
+implementationTypes:
+  - ref: "backend/fastify-prisma"
+    alias: "api"
+
+capabilityMappings:
+  - capability: "api.rest"
+    implementationType: "api"  # ← used alias
+```
+
+v3.3 hybrid mapping is cleaner:
+
+```yaml
+# v3.3 (new)
+defaultMappings:
+  controller: "FastifyPrismaAPI"
+
+# OR for more control
+capabilityMappings:
+  - capability: "api.rest"
+    instanceFactory: "FastifyPrismaAPI"  # ← direct reference
+```
+
+## See Also
+
+- [SCHEMA-CONSOLIDATION-PROPOSAL.md](../../docs/implementation-plans/v3.3-implementation/SCHEMA-CONSOLIDATION-PROPOSAL.md) - Architecture details
+- [SCHEMA-CONSOLIDATION-ADDENDUM.md](../../docs/implementation-plans/v3.3-implementation/SCHEMA-CONSOLIDATION-ADDENDUM.md) - Hybrid mapping deep dive
+- [INSTANCE-FACTORY-EXTENSIBILITY.md](../../docs/implementation-plans/v3.3-implementation/INSTANCE-FACTORY-EXTENSIBILITY.md) - Extensibility patterns
+
+---
+
+**SpecVerse v3.3** - Define once, implement anywhere with hybrid mapping flexibility.

package/assets/examples/manifests/backend-only.yaml

@@ -0,0 +1,43 @@
+manifests:
+  backendOnlyImplementation:
+    specVersion: "3.5.0"
+    deployment:
+      deploymentSource: "../specs/main.specly"
+      deploymentName: "production"
+    configuration:
+      outputStructure: "standalone"
+      backendDir: "."
+      apiPort: 3000
+      apiHost: "0.0.0.0"
+      corsOrigins: "${CORS_ORIGINS}"
+    capabilityMappings:
+      - capability: "orm.schema"
+        instanceFactory: "PrismaORM"
+        configuration:
+          outputStructure: "standalone"
+          backendDir: "."
+      - capability: "service.controller"
+        instanceFactory: "PrismaServices"
+        configuration:
+          outputStructure: "standalone"
+          backendDir: "."
+      - capability: "api.rest"
+        instanceFactory: "FastifyAPI"
+        configuration:
+          outputStructure: "standalone"
+          backendDir: "."
+          server:
+            cors:
+              enabled: true
+              origins:
+                - "${CORS_ORIGINS}"
+      - capability: "app.entrypoint"
+        instanceFactory: "GenericApp"
+        configuration:
+          outputStructure: "standalone"
+          backendDir: "."
+      - capability: "project.scaffold"
+        instanceFactory: "GenericScaffold"
+        configuration:
+          outputStructure: "standalone"
+          includeReadme: true

package/assets/examples/manifests/blog-api.md

@@ -0,0 +1,78 @@
+# Blog API - Manifest Example Specification
+
+**File**: `blog-api.specly`
+
+## Overview
+
+Simple blog platform API specification used to demonstrate v3.3 hybrid manifest mappings and deployment configurations.
+
+## Purpose
+
+This is a **manifest reference example** used by:
+- Manifest examples in `06-deploy/`
+- v3.3 implementation type demonstrations
+- Capability mapping examples
+- Deployment configuration testing
+
+## Key Features
+
+- **Simple Models**: User, Post, Comment
+- **Clean Architecture**: Minimal dependencies
+- **Manifest Testing**: Referenced by multiple manifests
+- **Deployment Target**: Used in deployment examples
+
+## Models
+
+### User
+- Username and email authentication
+- Password hash storage
+- Audit timestamps
+
+### Post
+- Blog post content
+- Title and slug (SEO-friendly URL)
+- Publishing workflow (draft, published, archived)
+- Author relationship with cascade delete
+
+### Comment
+- User-generated content
+- Timestamp tracking
+- Post and user relationships
+
+## Usage with Manifests
+
+```bash
+# Docker Compose deployment
+specverse realize all examples/manifests/blog-api.specly \
+  -m examples/06-deploy/06-04-docker-compose-manifest.specly
+
+# Kubernetes deployment
+specverse realize all examples/manifests/blog-api.specly \
+  -m examples/06-deploy/06-03-kubernetes-deployment-manifest.specly
+
+# Cloud-native deployment
+specverse realize all examples/manifests/blog-api.specly \
+  -m examples/06-deploy/06-05-cloud-native-manifest.specly
+```
+
+## Referenced By
+
+This specification is referenced by:
+- `06-04-docker-compose-manifest.specly`
+- `06-03-kubernetes-deployment-manifest.specly`
+- `06-05-cloud-native-manifest.specly`
+- Various implementation manifest examples
+
+## Deployment Scenarios
+
+1. **Development**: Docker Compose with local database
+2. **Staging**: Kubernetes cluster with managed database
+3. **Production**: Cloud-native with auto-scaling
+4. **Testing**: In-memory database for unit tests
+
+## Related Examples
+
+- `06-deploy/` - All deployment manifest examples
+- `12-v3.3-features/12-01-blog-platform-v3.3.specly` - v3.3 blog features
+- `08-service-layer/blog-api.specly` - Service layer version
+- `12-end-to-end/manifests/` - Implementation manifests

package/assets/examples/manifests/blog-api.specly

@@ -0,0 +1,79 @@
+# Simple Blog API Deployment Example
+# Referenced by manifest examples to demonstrate v3.3 hybrid mapping
+
+components:
+  BlogAPI:
+    version: "1.0.0"
+    description: "Simple blog platform API"
+
+    models:
+      User:
+        attributes:
+          username: String required unique
+          email: Email required unique
+          passwordHash: String required
+          createdAt: DateTime auto=now
+
+      Post:
+        attributes:
+          title: String required
+          slug: String required unique
+          content: Text required
+          publishedAt: DateTime
+          status: String required values=[draft,published,archived]
+        relationships:
+          author: belongsTo User cascade
+
+      Comment:
+        attributes:
+          content: Text required
+          createdAt: DateTime auto=now
+        relationships:
+          post: belongsTo Post cascade
+          author: belongsTo User
+
+deployments:
+  production:
+    version: "1.0.0"
+    environment: production
+    description: "Production deployment with multiple instances"
+
+    instances:
+      controllers:
+        # Main API controller
+        userApi:
+          component: "BlogAPI"
+          advertises: ["api.rest", "api.rest.crud"]
+          uses: ["storage.database"]
+
+        # Admin API with additional capabilities
+        adminApi:
+          component: "BlogAPI"
+          advertises: ["api.rest.admin", "api.rest.reports"]
+          uses: ["storage.database", "storage.cache"]
+
+      storage:
+        # Main PostgreSQL database
+        userDb:
+          component: "BlogAPI"
+          type: "relational"
+          advertises: ["storage.database"]
+
+        # Analytics database (can be overridden to MongoDB)
+        analyticsDb:
+          component: "BlogAPI"
+          type: "document"
+          advertises: ["storage.database.analytics"]
+
+        # Session cache
+        sessionCache:
+          component: "BlogAPI"
+          type: "keyvalue"
+          advertises: ["storage.cache"]
+
+      services:
+        # Validation service
+        validator:
+          component: "BlogAPI"
+          advertises: ["validation.runtime"]
+          uses: ["api.rest"]

package/assets/examples/manifests/frontend-only.yaml

@@ -0,0 +1,27 @@
+manifests:
+  frontendOnlyImplementation:
+    specVersion: "3.5.0"
+    deployment:
+      deploymentSource: "../specs/main.specly"
+      deploymentName: "production"
+    configuration:
+      outputStructure: "standalone"
+      frontendDir: "."
+      apiBaseUrl: "${VITE_API_BASE_URL}"
+      apiPrefix: "/api"
+    capabilityMappings:
+      - capability: "app.frontend"
+        instanceFactory: "ReactApp"
+        configuration:
+          outputStructure: "standalone"
+          frontendDir: "."
+          apiBaseUrl: "${VITE_API_BASE_URL}"
+          vite:
+            port: 5173
+            proxy:
+              /api: "${VITE_API_BASE_URL}"
+      - capability: "ui.components"
+        instanceFactory: "ReactComponents"
+        configuration:
+          outputStructure: "standalone"
+          frontendDir: "."

package/assets/examples/manifests/fullstack-app.yaml

@@ -0,0 +1,44 @@
+manifests:
+  FullStackApp:
+    specVersion: "3.5.0"
+    name: "fullstack-app-implementation"
+    description: "Full-stack application with React frontend, Fastify API, and event-driven architecture"
+    version: "1.0.0"
+    deployment:
+      deploymentSource: "./blog-api.specly"
+      deploymentName: "production"
+    defaultMappings:
+      storage: "PostgreSQL15"
+      controller: "FastifyAPI"
+      service: "PrismaORM"
+      view: "ReactComponents"
+      communication: "EventEmitter"
+    capabilityMappings:
+      - capability: "api.rest"
+        instanceFactory: "FastifyAPI"
+      - capability: "api.rest.crud"
+        instanceFactory: "FastifyAPI"
+      - capability: "storage.database"
+        instanceFactory: "PostgreSQL15"
+      - capability: "ui.components"
+        instanceFactory: "ReactComponents"
+      - capability: "ui.views"
+        instanceFactory: "ReactComponents"
+      - capability: "ui.forms"
+        instanceFactory: "ReactComponents"
+      - capability: "messaging.pubsub"
+        instanceFactory: "EventEmitter"
+      - capability: "messaging.events"
+        instanceFactory: "EventEmitter"
+      - capability: "validation.runtime"
+        instanceFactory: "ZodValidation"
+    configuration:
+      frontend:
+        buildTool: "vite"
+        outputDir: "dist/client"
+        publicPath: "/app"
+      backend:
+        outputDir: "dist/server"
+        port: 3000
+      events:
+        mode: "development"

package/assets/examples/manifests/fullstack-monorepo.yaml

@@ -0,0 +1,62 @@
+manifests:
+  fullstackMonorepoImplementation:
+    specVersion: "3.5.0"
+    deployment:
+      deploymentSource: "../specs/main.specly"
+      deploymentName: "development"
+    configuration:
+      outputStructure: "monorepo"
+      frontendDir: "frontend"
+      backendDir: "backend"
+      apiBaseUrl: "http://localhost:3000"
+      apiPrefix: "/api"
+    capabilityMappings:
+      - capability: "orm.schema"
+        instanceFactory: "PrismaORM"
+        configuration:
+          outputStructure: "monorepo"
+          backendDir: "backend"
+      - capability: "service.controller"
+        instanceFactory: "PrismaServices"
+        configuration:
+          outputStructure: "monorepo"
+          backendDir: "backend"
+      - capability: "api.rest"
+        instanceFactory: "FastifyAPI"
+        configuration:
+          outputStructure: "monorepo"
+          backendDir: "backend"
+          server:
+            port: 3000
+            cors:
+              enabled: true
+              origins:
+                - "http://localhost:5173"
+      - capability: "app.entrypoint"
+        instanceFactory: "GenericApp"
+        configuration:
+          outputStructure: "monorepo"
+          backendDir: "backend"
+      - capability: "app.frontend"
+        instanceFactory: "ReactApp"
+        configuration:
+          outputStructure: "monorepo"
+          frontendDir: "frontend"
+          apiBaseUrl: "http://localhost:3000"
+          vite:
+            port: 5173
+            proxy:
+              /api: "http://localhost:3000"
+      - capability: "ui.components"
+        instanceFactory: "ReactComponents"
+        configuration:
+          outputStructure: "monorepo"
+          frontendDir: "frontend"
+      - capability: "project.scaffold"
+        instanceFactory: "GenericScaffold"
+        configuration:
+          outputStructure: "monorepo"
+          includeReadme: true
+          workspaces:
+            - "backend"
+            - "frontend"