SDS-045: VibesPro™ Foundation Integration Service

sds_id: SDS-045 title: VibesPro™ Foundation Integration Service status: Proposed version: 1.2.0 date_created: 2025-12-27 last_updated: 2026-01-04 implements:

ADR-030
PRD-020 supersedes:
SDS-045 cross_references:
SDS-050 # Semantic Identity & Provenance Infrastructure
REF-CE-002 # Identity Token Specification
SDS-015 # Temporal Database Service
SDS-030 # Semantic Observability bounded_context: shared —

Document Type

Software Design Specification (SDS)

Status

Proposed

Supersedes

SDS-045: VibesPro™ Adapter Specification

Implements

Cross-References (Identity & Provenance)

SDS-050: Semantic Identity & Provenance Infrastructure — Canonical identity specification
REF-CE-002: Identity Token Specification — Identity token semantics

1. System Overview

The VibesPro™ Foundation Integration Service orchestrates the incorporation of VibesPro™’s core systems into SEA-Forge™. It is NOT a new service but rather a specification of how SEA™ extends and adapts VibesPro™ components.

2. Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                          SEA-FORGE RUNTIME STACK                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────────┐  │
│  │   SEA™ DSL       │  │  GovernedSpeed™  │  │      Knowledge Graph        │  │
│  │   (Semantic)    │  │  (Governance)   │  │      (Oxigraph)             │  │
│  └────────┬────────┘  └────────┬────────┘  └────────────┬────────────────┘  │
│           │                    │                        │                    │
│           ▼                    ▼                        ▼                    │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │                    VIBESPRO FOUNDATION LAYER                          │  │
│  ├───────────────────────────────────────────────────────────────────────┤  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │  │
│  │  │ Temporal AI │  │  Type Sync  │  │ Meta-Gen    │  │ Context-Kit │   │  │
│  │  │ (Rust+redb) │  │ (TS↔Python) │  │ (Nx)        │  │ (Manifest)  │   │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘   │  │
│  │                                                                        │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │  │
│  │  │ Copier      │  │ Nx Orches.  │  │ Observ.     │  │ Just Runner │   │  │
│  │  │ (Templates) │  │ (Monorepo)  │  │ (OTel)      │  │ (Tasks)     │   │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘   │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

3. Component Specifications

3.1 Temporal AI Integration (SDS-015 Implementation)

Status: ✅ Finalized (Plan P029 C1A)
Satisfies: PRD-020 US-001, US-002

@namespace "system.sea.temporal"
@version "1.0.0"
@implements "SDS-015"

// ENTITIES: Map to VibesPro™ implementations
Entity "VectorStore" in system.sea.temporal
@rationale "Implemented by temporal_db/repository.rs using redb"
@implementation "temporal_db::TemporalRepository"

Entity "PatternOracle" in system.sea.temporal
@rationale "Implemented by crates/temporal-ai CLI"
@implementation "temporal-ai query"

Entity "MetricIndexer" in system.sea.temporal
@rationale "Implemented by ops/vector ingestion"
@implementation "vector::OTLPSource"

// FLOWS: CLI Surface
Flow "QueryPatterns" from "SEA-Agent" to "PatternOracle"
@rationale "Invoked via 'just temporal-ai-query'"
@cqrs { "kind": "query" }

Flow "EmbedPattern" from "Generator" to "VectorStore"
@rationale "Post-generation hook stores pattern embeddings"
@cqrs { "kind": "command" }

Flow "RefreshMetrics" from "CI" to "MetricIndexer"
@rationale "Invoked via 'just temporal-ai-refresh-metrics'"
@cqrs { "kind": "command" }

// POLICIES
Policy "PatternIntegrity" per Constraint Obligation priority 10
@rationale "All patterns must trace to spec IDs"
as: forall p in patterns: exists s in specs: (p.source_spec = s.id)

Implementation Mapping

SEA™ Spec	VibesPro™ File	Command
VectorStore	`temporal_db/repository.rs`	`just temporal-ai-init`
PatternOracle	`crates/temporal-ai/`	`just temporal-ai-query`
MetricIndexer	`ops/vector/vector.toml`	`just temporal-ai-refresh-metrics`

3.2 End-to-End Type Safety Pipeline

Status: ✅ Finalized (Plan P029 C1A)
Satisfies: PRD-020 US-003, US-004

@namespace "system.sea.types"
@version "1.0.0"

// ENTITIES
Entity "TypeGenerator" in system.sea.types
@rationale "Generates TypeScript types from Supabase schema"
@implementation "tools/scripts/gen_ts_from_pg.py"

Entity "TypeTranspiler" in system.sea.types
@rationale "Transpiles TypeScript interfaces to Python Pydantic"
@implementation "tools/scripts/gen_py_types.py"

Entity "TypeValidator" in system.sea.types
@rationale "Validates bidirectional type consistency"
@implementation "just check-types"

// FLOWS
Flow "ExtractSchema" from "Supabase" to "TypeGenerator"
@rationale "Reads PostgreSQL schema via introspection or CLI"
@cqrs { "kind": "query" }

Flow "GenerateTS" from "TypeGenerator" to "TypeScriptTypes"
@rationale "Outputs libs/shared/types/src/database.types.ts"
@cqrs { "kind": "command" }

Flow "TranspilePy" from "TypeTranspiler" to "PythonModels"
@rationale "Outputs libs/shared/types-py/src/models.py"
@cqrs { "kind": "command" }

Flow "ValidateConsistency" from "TypeValidator" to "CI"
@rationale "Fails build if types are out of sync"
@cqrs { "kind": "query" }

// POLICIES
Policy "BidirectionalConsistency" per Constraint Obligation priority 10
@rationale "TS and Python types must be byte-equivalent after generation"
as: hash(generate_ts(schema)) = hash(reverse_transpile(generate_py(ts)))

CLI Commands

# Full type generation pipeline
just gen-types          # Runs gen-types-ts then gen-types-py

# Individual steps
just gen-types-ts       # Supabase → TypeScript
just gen-types-py       # TypeScript → Python Pydantic

# Validation
just check-types        # Verify consistency, fail if drift detected

3.3 Meta-Generator System

Status: ✅ Finalized (Plan P029 C2A)
Satisfies: PRD-020 US-007, US-008

@namespace "system.sea.generators"
@version "1.0.0"

// ENTITIES
Entity "MetaGenerator" in system.sea.generators
@rationale "Generator that creates new generators"
@implementation "generators/generator/generator.ts"

Entity "GeneratorRegistry" in system.sea.generators
@rationale "Nx project registry for all generators"
@implementation "generators/**/generators.json"

// RESOURCES
Resource "GeneratorSchema" in system.sea.generators
@rationale "JSON Schema defining generator options"

Resource "GeneratorTemplate" in system.sea.generators
@rationale "EJS templates for generated output"

// FLOWS
Flow "CreateGenerator" from "Developer" to "MetaGenerator"
@rationale "Scaffolds new generator via 'just generator-new'"
@cqrs { "kind": "command" }

Flow "ExecuteGenerator" from "Pipeline" to "GeneratorRegistry"
@rationale "Runs generator via 'pnpm exec nx g'"
@cqrs { "kind": "command" }

// POLICIES
Policy "GeneratorTraceability" per Constraint Obligation priority 10
@rationale "Every generator must document its SEA™ spec source"
as: forall g in generators: exists spec in g.metadata: (spec.id matches /SDS-\d+/)

Generator Type Catalog

Type	Purpose	Target Path	Example
`domain`	DDD entities, value objects	`libs/<scope>/<name>`	`just generator-new order --type=domain`
`service`	Backend services	`apps/<name>`	`just generator-new billing --type=service`
`component`	UI components	`libs/<scope>/ui/<name>`	`just generator-new button --type=component`
`adapter`	Infrastructure adapters	`libs/<scope>/infrastructure/<name>`	`just generator-new postgres --type=adapter`
`utility`	Shared utilities	`libs/shared/<name>`	`just generator-new logger --type=utility`
`custom`	Blank template	Configurable	`just generator-new custom-thing --type=custom`

3.4 Context-Kit Integration

Status: ✅ Finalized (Plan P029 C2A)
Satisfies: PRD-020 US-006

@namespace "system.sea.context"
@version "1.0.0"

// ENTITIES
Entity "ContextManifest" in system.sea.context
@rationale "Source of truth for AI context routing"
@implementation "ce.manifest.jsonc"

Entity "SkillRegistry" in system.sea.context
@rationale "Collection of agent skills"
@implementation ".github/skills/**"

Entity "AgentOrchestrator" in system.sea.context
@rationale "Routes requests to appropriate skills/agents"
@implementation ".github/agents/orchestrator.agent.md"

// RESOURCES
Resource "Skill" in system.sea.context
@rationale "Reusable capability for AI agents"

Resource "Agent" in system.sea.context
@rationale "Role-based AI persona"

Resource "Prompt" in system.sea.context
@rationale "Reusable prompt template"

// FLOWS
Flow "RouteRequest" from "User" to "AgentOrchestrator"
@rationale "Determines which skill/agent should handle request"
@cqrs { "kind": "query" }

Flow "InvokeSkill" from "AgentOrchestrator" to "SkillRegistry"
@rationale "Executes skill with appropriate context"
@cqrs { "kind": "command" }

SEA-Specific Skills to Add

// ce.manifest.jsonc additions
{
  "artifacts": [
    {
      "id": "ce.skill.sea-dsl-authoring",
      "kind": "skill",
      "path": ".github/skills/sea-dsl-authoring/SKILL.md",
      "tags": ["semantic-core", "authoring"],
      "inputs": {
        "files": ["docs/specs/semantic-core/reference/001-sbvr-ubm-dsl-specification.md"],
        "concepts": ["sea-dsl", "policies", "flows"],
        "tools": ["toolset:write"],
      },
    },
    {
      "id": "ce.skill.governance-validation",
      "kind": "skill",
      "path": ".github/skills/governance-validation/SKILL.md",
      "tags": ["governance", "calm", "validation"],
      "inputs": {
        "files": [
          "docs/specs/architectural-governance/reference/001-calm-dsl-language-specification.md",
        ],
        "concepts": ["calm", "architecture-as-code"],
        "tools": ["toolset:exec"],
      },
    },
    {
      "id": "ce.skill.spec-authoring",
      "kind": "skill",
      "path": ".github/skills/spec-authoring/SKILL.md",
      "tags": ["specs", "adr", "prd", "sds"],
      "inputs": {
        "files": ["docs/specs/shared/reference/001-adr-template-structure.md"],
        "concepts": ["spec-driven", "traceability"],
        "tools": ["toolset:write"],
      },
    },
  ],
}

3.5 Copier Template Extensions

@namespace "system.sea.templates"
@version "1.0.0"

// ENTITIES
Entity "CopierEngine" in system.sea.templates
@rationale "Template generation engine"
@implementation "copier.yml"

Entity "SEAHookInjector" in system.sea.templates
@rationale "Injects SEA™ governance hooks post-generation"
@implementation "hooks/post_gen.py"

// FLOWS
Flow "GenerateProject" from "Developer" to "CopierEngine"
@rationale "Creates new SEA-governed project"
@cqrs { "kind": "command" }

Flow "InjectGovernance" from "CopierEngine" to "SEAHookInjector"
@rationale "Adds SEA™ validation, IFL minting, CALM checks"
@cqrs { "kind": "command" }

// POLICIES
Policy "GovernanceInjection" per Constraint Obligation priority 10
@rationale "All generated projects must have SEA™ governance"
as: forall p in projects: (p.has_sea_validation = true AND p.has_ifl_minting = true)

Extended Copier Questions

# copier.yml SEA™ extensions
include_sea_governance:
  type: bool
  help: |
    Enable SEA™ DSL validation in the generated project?

    This adds:
    - SEA™ DSL linting in pre-commit
    - CALM architecture validation
    - Spec traceability checks
  default: true

include_ifl_identity:
  type: bool
  help: |
    Enable IFL (Internal Federated Ledger) identity minting?

    This adds:
    - Deterministic identity tokens (ifl:hash)
    - Merkle proof generation
    - Provenance auditing
  default: true
  when: '{{ include_sea_governance }}'

sea_bounded_context:
  type: str
  help: |
    Which SEA™ bounded context does this project belong to?

    Examples:
    - semantic-core
    - cognitive-extension
    - architectural-governance
    - developer-tooling
  default: 'developer-tooling'
  when: '{{ include_sea_governance }}'

3.6 Generation Adapter Interfaces (from SDS-045)

This section consolidates the adapter interfaces originally specified in SDS-045.

@namespace "system.vibespro.api"
@version "1.0.0"

// ENTITIES
Entity "ManifestProjector" in system.vibespro.api
@rationale "The structural compiler that maps semantic intent into architectural reality."

Entity "CodeGenerator" in system.vibespro.api
@rationale "The deterministic synthesis engine that emits end-language artifacts."

Entity "IdempotentWriter" in system.vibespro.api
@rationale "The safety module responsible for non-destructive file system mutations."

// RESOURCES
Resource "ManifestIR" in system.vibespro.api
@rationale "The architectural intermediate representation (IR) of domain intent."

Resource "GenerationStep" in system.vibespro.api
@rationale "A typed instruction for a specific generator backend (Nx, Copier, etc.)."

Resource "FileBuffer" in system.vibespro.api
@rationale "In-memory generated content awaiting idempotent verification."

// FLOWS
Flow "ProjectAST" from "SEACore" to "ManifestProjector"
@rationale "Translates the semantic AST into an implementable Manifest IR."

Flow "EmitManifest" from "ManifestProjector" to "CodeGenerator" resource "ManifestIR"
@rationale "Provides the stable architectural contract to the synthesis layer."

Flow "PlanGeneration" from "CodeGenerator" to "GovernedSpeed™" resource "GenerationStep"
@rationale "Submits a plan of discrete generation tasks for risk evaluation."

Flow "SynthesizeArtifacts" from "CodeGenerator" to "IdempotentWriter" resource "FileBuffer"
@rationale "Transforms manifest nodes into file content via language-specific emitters."

Flow "VerifyDrift" from "IdempotentWriter" to "SEACore"
@rationale "Detects divergence between observed file state and intended semantic state."

Flow "SafeWrite" from "IdempotentWriter" to "FileSystem"
@rationale "Atomically updates files while preserving human-authored 'safe zones'."

// POLICIES
Policy "DeterministicProjection" per Constraint Obligation priority 10
@rationale "Identical KGS snapshots must result in byte-identical Manifest IRs."
as: forall m in resources where m.name = "ManifestIR": (m.is_deterministic = true)

Policy "ProtectedRegionIntegrity" per Constraint Obligation priority 10
@rationale "Generators are strictly forbidden from overwriting human code markers."
as: forall f in flows where f.name = "SafeWrite": (f.respects_protected_regions = true)

Policy "ManifestGating" per Constraint Obligation priority 10
@rationale "No generation may occur unless the Manifest satisfies CALM boundaries."
as: forall m in resources where m.name = "ManifestIR":
    exists g in system.governance: (g.approves(m))

Adapter Implementation Details

Component	Location	Responsibility
VibesPro™ Adapter	`tools/adapters/vibespro`	Translates user intent into deterministic Copier parameters
SEA™ Generation Orchestrator	`tools/sea-gen`	Central lifecycle manager for generation

Adapter Interfaces:

generate(template: string, params: object) — Invoke Copier template
check_idempotence(manifest: string) — Verify reproducible builds via copier.lock

Orchestrator Pipeline:

Synth: Call VibesPro™ Adapter to write files
Verify: Run sea-semantic validate on generated CADSL/SBVR
Govern: Run calm validate on architecture definitions
Sync: Trigger type-sync (Pydantic → TS)
Project: Emit metadata to Knowledge Graph

Template Parameters (MECE Set):

Identity: name, domain, owner
Risk: criticality, data_classification
Profiles: runtime (py/ts), deployment (edge/cloud)
AI config: llm_policy (local/remote)

4. Justfile Command Mapping

# ============================================================================
# SEA-VIBESPRO FOUNDATION COMMANDS
# ============================================================================

# --- Temporal AI (Pattern Oracle) ---
temporal-ai-init:
    @just -f vibes-pro/justfile temporal-ai-init

temporal-ai-query QUERY TOP="5":
    @just -f vibes-pro/justfile temporal-ai-query "{{QUERY}}" {{TOP}}

temporal-ai-stats:
    @just -f vibes-pro/justfile temporal-ai-stats

# --- Type Safety Pipeline ---
gen-types:
    @just -f vibes-pro/justfile gen-types

gen-types-ts:
    @just -f vibes-pro/justfile gen-types-ts

gen-types-py:
    @just -f vibes-pro/justfile gen-types-py

check-types:
    @just -f vibes-pro/justfile check-types

# --- Meta-Generators ---
generator-new NAME TYPE="custom":
    @just -f vibes-pro/justfile generator-new {{NAME}} type={{TYPE}}

generator-list:
    @pnpm exec nx g --list

# --- Developer Experience ---
setup:
    @just -f vibes-pro/justfile setup

ai-validate:
    @just -f vibes-pro/justfile ai-validate
    @node scripts/spec-cross-check.js --mode staging --dir docs/specs

# --- Observability ---
observe-start:
    @just -f vibes-pro/justfile observe-start

observe-test-all:
    @just -f vibes-pro/justfile observe-test-all

5. CI/CD Integration

Validation Pipeline

# .github/workflows/sea-vibespro-validate.yml
name: SEA-VibesPro™ Validation

on:
  push:
    branches: [main, dev]
  pull_request:

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup VibesPro™
        run: just setup

      - name: Temporal AI Check
        run: |
          just temporal-ai-build
          just temporal-ai-init || true
          just temporal-ai-stats

      - name: Type Safety Check
        run: |
          just gen-types
          just check-types

      - name: AI Validation
        run: just ai-validate

      - name: SEA™ Spec Validation
        run: node scripts/spec-cross-check.js --mode production --dir docs/specs

6. Migration Guide

From Standalone SEA™ to SEA-VibesPro™

Clone VibesPro™ as Submodule/Subtree

git subtree add --prefix=vibes-pro https://github.com/GodSpeedAI/VibesPro™ main --squash

Extend ce.manifest.jsonc
- Add SEA-specific skills
- Add SEA™ agent configurations
Extend copier.yml
- Add SEA™ governance questions
- Add IFL identity options
Update hooks/post_gen.py
- Add SEA™ DSL validation hooks
- Add CALM validation hooks
Update justfile
- Add proxy commands to VibesPro™ justfile
- Add SEA-specific validation

Core References

Identity & Provenance

SDS-050: Semantic Identity & Provenance Infrastructure — Identity primitives for pattern embeddings
REF-CE-002: Identity Token Specification — Token semantics for artifact lineage

Observability

SDS-030: Semantic Observability — Telemetry and tracing integration

[!NOTE] This specification supersedes SDS-045: VibesPro™ Adapter Specification. Adapter interfaces are now documented in Section 3.6.

8. Pattern Oracle Integration in Generation Planning (Plan P010)

Added 2025-12-30: Specifies how PatternOracle recommendations from SDS-015 are wired into the VibesPro™ generation planning phase.

8.1. Recommendation Flow Architecture

The PatternOracle (SDS-015) provides semantic similarity-based recommendations that feed into the generation planning phase:

GenerationPlanner receives SEA™ DSL intent from the Semantic Compiler
RequestPatternRecommendations queries the PatternOracle for similar historical patterns
PatternInjector augments the generation context with top-K recommendations
CodeGenerator uses injected patterns to inform template selection
RecordPatternUsage closes the learning loop by storing generation outcomes

8.2. SEA-DSL Flow Specification

@namespace "system.vibespro.planning"
@version "1.0.0"
@implements "SDS-045, SDS-015"

/**
 * @cqrs { "kind": "query" }
 * @read_model { "name": "PatternRecommendationProjection" }
 */
Flow "RequestPatternRecommendations" from "GenerationPlanner" to "PatternOracle"
@rationale "Queries historical patterns with semantic similarity to current generation context"

/**
 * @cqrs { "kind": "command" }
 * @tx { "transactional": false }
 */
Flow "InjectPatterns" from "PatternInjector" to "CodeGenerator"
@rationale "Augments generation context with top-K pattern recommendations"

/**
 * @cqrs { "kind": "event" }
 * @outbox { "mode": "required" }
 */
Flow "RecordPatternUsage" from "CodeGenerator" to "VectorStore"
@rationale "Post-generation hook stores pattern usage for learning feedback"

Policy "PatternRelevanceThreshold" per Constraint Obligation priority 10
@rationale "Only inject patterns with combined_score above threshold"
as: forall r in recommendations:
    if r.combined_score >= 0.7 then r.eligible_for_injection = true

8.3. Integration Contracts

interface PatternRecommendationRequest {
  generation_intent: string; // SEA™ DSL snippet or natural language
  bounded_context: string; // Target BC
  artifact_type: 'entity' | 'flow' | 'adapter' | 'service' | 'test';
  top_k?: number; // default: 5
  min_score?: number; // default: 0.7
}

interface PatternRecommendation {
  pattern_id: string; // ifl:hash identity
  combined_score: number; // From PatternOracle (SDS-015)
  risk_level: 'Low' | 'Medium' | 'High';
  template_path: string;
}

8.4. Invariants

INV-ID	Invariant	Enforcement
INV-VP-01	Pattern recommendations MUST respect LocalFirstPrivacy	Embedding-based queries only
INV-VP-02	Generation MUST record outcomes for learning	Post-gen hook triggers RecordPatternUsage
INV-VP-03	High-risk patterns MUST be flagged	RecommendationSafetyGate (SDS-015)

Flow	Source Spec	Purpose
RecommendPatterns	SDS-015	Triggers during generation planning
IndexTelemetry	SDS-015, SDS-030	Records governance scores for weighting
RefreshStats	SDS-015	Updates pattern success rates