dbis_core/SOLACENET_QUICK_REFERENCE.md

# SolaceNet Quick Reference

Quick reference guide for the SolaceNet Capability Platform.

## Core Concepts

### Capability States
- `disabled` - No execution, gateway blocks
- `pilot` - Allowlist only
- `enabled` - Active for entitled scopes
- `suspended` - Execution blocked, reads allowed
- `drain` - No new requests, allow in-flight settlement

### Scoping Levels
- Tenant
- Program (product line)
- Region (jurisdiction)
- Channel (API/UI/mobile)
- Customer segment (optional)

### Rail and external protocol governance
Financial rails (SWIFT, DTC/DTCC, TT, KTT legacy evidence, etc.) and **integration contracts** for telecom-adjacent stacks (for example SS7 terminated at a carrier boundary) are **maintained under SolaceNet**: capabilities, policy, audit, Go gateway, and TypeScript adapters in `src/core/gateway/adapters/`. Full policy, code map, and change process: [docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md](docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md). **Tracked protocol gaps (complete list):** [docs/solacenet/PROTOCOL_GAPS_CHECKLIST.md](docs/solacenet/PROTOCOL_GAPS_CHECKLIST.md).

### Gateway REST (dbis_core API)
Authenticated routes under **`/api/v1/gateway`**: **`GET /rails`** (list adapter IDs), **`GET /rails/:adapterId/health`**, **`POST .../validate`**, **`POST .../receive`**, plus existing instructions and event replay. Optional SolaceNet enforcement: **`SOLACENET_GATEWAY_RAILS_ENFORCE=1`** and **`SOLACENET_DEFAULT_TENANT_ID`** — see `src/core/gateway/rails/README.md` and `.env.example`. OpenAPI: **`/api-docs`** (tag **SolaceNet Gateway Rails**).

## API Quick Reference

### Capability Registry
```bash
# List capabilities
GET /api/v1/solacenet/capabilities

# Get capability
GET /api/v1/solacenet/capabilities/{id}

# Create capability
POST /api/v1/solacenet/capabilities
{
  "capabilityId": "payment-gateway",
  "name": "Payment Gateway",
  "version": "1.0.0",
  "defaultState": "disabled"
}
```

### Entitlements
```bash
# Get entitlements
GET /api/v1/solacenet/tenants/{tenantId}/programs/{programId}/entitlements

# Create entitlement
POST /api/v1/solacenet/entitlements
{
  "tenantId": "tenant-123",
  "capabilityId": "payment-gateway",
  "stateOverride": "enabled"
}
```

### Policy Decisions
```bash
# Make decision
POST /api/v1/solacenet/policy/decide
{
  "tenantId": "tenant-123",
  "capabilityId": "payment-gateway",
  "region": "US",
  "channel": "API"
}

# Activate kill switch
POST /api/v1/solacenet/policy/kill-switch/{capabilityId}
{
  "reason": "Emergency shutdown"
}
```

### Risk Assessment
```bash
# Assess risk
POST /api/v1/risk/assess
{
  "userId": "user-123",
  "amount": "1000.00",
  "currencyCode": "USD",
  "deviceFingerprint": "abc123",
  "velocityData": {
    "count24h": 5
  }
}
```

## Service SDK Usage

```typescript
import { requireCapability } from '@/shared/solacenet/sdk';

async function processPayment(...) {
  // Check capability before proceeding
  await requireCapability('payment-gateway', {
    tenantId: 'tenant-123',
    programId: 'program-456',
    region: 'US',
    channel: 'API'
  });
  
  // Proceed with payment processing
  // ...
}
```

## Common Patterns

### Registering a New Capability

1. **Create capability:**
```typescript
await capabilityRegistryService.createCapability({
  capabilityId: 'my-capability',
  name: 'My Capability',
  version: '1.0.0',
  defaultState: 'disabled',
  dependencies: ['payment-gateway']
});
```

2. **Create entitlement:**
```typescript
await entitlementsService.createEntitlement({
  tenantId: 'tenant-123',
  capabilityId: 'my-capability',
  stateOverride: 'enabled'
});
```

3. **Use in service:**
```typescript
await requireCapability('my-capability', { tenantId: 'tenant-123' });
```

### Creating Policy Rules

```typescript
await policyEngineService.createPolicyRule({
  ruleId: 'high-risk-block',
  capabilityId: 'payment-gateway',
  scope: 'global',
  condition: {
    and: [
      { gt: { risk_score: 80 } },
      { gt: { amount: 10000 } }
    ]
  },
  decision: 'deny',
  priority: 10
});
```

### Risk Rules

```typescript
await riskRulesEngine.createRule({
  ruleId: 'velocity-check',
  name: 'High Velocity Detection',
  ruleType: 'velocity',
  condition: {
    gt: { count24h: 20 }
  },
  action: 'block',
  riskScore: 80,
  priority: 50,
  status: 'active'
});
```

## Deployment

### Docker Compose
```bash
docker-compose -f docker-compose.solacenet.yml up -d
```

### Environment Variables
```env
DATABASE_URL=postgresql://...
REDIS_URL=redis://localhost:6379
SOLACENET_GATEWAY_PORT=8080
JWT_SECRET=your-secret
```

## Troubleshooting

### Capability Not Available
1. Check entitlement exists
2. Verify capability state
3. Check policy rules
4. Review audit logs

### Policy Decision Caching
- Cache TTL: 120 seconds (configurable)
- Kill switch invalidates cache immediately
- Redis required for caching

### Gateway Issues
- Verify Redis connection
- Check backend URL configuration
- Review gateway logs

## File Locations

- **Services**: `src/core/solacenet/`
- **Shared SDK**: `src/shared/solacenet/`
- **Gateway**: `gateway/go/`
- **Rail adapters**: `src/core/gateway/adapters/` (governed per [docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md](docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md))
- **Rail enforcement env**: `src/core/gateway/rails/README.md`
- **Console**: `frontend/solacenet-console/`
- **Schema**: `prisma/schema.prisma`