chore: sync submodule state (parent ref update)

Made-with: Cursor
2026-03-02 12:14:07 -08:00
parent 6c4555cebd
commit 89b82cdadb
883 changed files with 78752 additions and 18180 deletions
--- a/SOLACENET_QUICK_REFERENCE.md
+++ b/SOLACENET_QUICK_REFERENCE.md
@@ -0,0 +1,210 @@
+# 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)
+
+## 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/`
+- **Console**: `frontend/solacenet-console/`
+- **Schema**: `prisma/schema.prisma`