npm package: @mdp-framework/gateway
Description: MDP Gateway - Policy resolver, action engine, and adapter orchestration
Author: MDP Framework Contributors
Latest version: 1.1.99

# @mdp-framework/gateway

MDP Gateway - Policy resolver, action engine, and adapter orchestration.

## Features

- **Policy Resolver**: Deterministic policy resolution from registry
- **Action Engine**: Execute policy violations with handlers
- **Capsule Store**: Dual-backend persistence (file & Postgres)
  - File backend for local development
  - Postgres backend for team/org shared state
  - JSON Merge Patch semantics with append-only arrays
  - Optimistic concurrency control
  - Retention policies and pruning

## Installation

```bash
npm install @mdp-framework/gateway
```

## Capsule Store Usage

### File Backend (Local Development)

```typescript
import { createCapsuleStore } from '@mdp-framework/gateway/store';

const store = await createCapsuleStore({
  backend: 'file',
  baseDir: '.mlang/state/capsules',
  retention: {
    localDays: 14,
    protectOpen: true,
    pins: ['capsule://proj/TEAM/pr/important-pr'],
  },
});

// CRUD operations
await store.put(capsule);
const result = await store.get('capsule://proj/TEAM/pr/pr-123');
await store.merge(id, { evidence: ['new-evidence'] });
await store.delete(id);

// Bulk operations
const list = await store.list({ kind: 'pr', limit: 10 });
const many = await store.getMany([id1, id2, id3]);

// Maintenance
await store.prune(true); // dry-run
await store.prune(false); // actually delete

// Export/import (NDJSON)
for await (const entry of store.export({ kind: 'pr' })) {
  console.log(entry);
}
```

### Postgres Backend (Team/Org)

```typescript
const store = await createCapsuleStore({
  backend: 'postgres',
  dsn: process.env.MLANG_STATE_DSN || 'postgresql://localhost/mdp',
  retention: {
    sharedDays: 60,
    protectOpen: true,
    checkLinks: true,
    protectSla: true,
  },
});

// Same API as file backend
await store.put(capsule);
const result = await store.get(id);
```

## Testing

### Unit Tests (File Backend)

```bash
npm test
```

### Integration Tests (Postgres Backend)

Requires Postgres database:

```bash
# Start test database
docker compose -f ../../docker-compose.test.yml up -d postgres

# Run integration tests
TEST_DSN=postgresql://postgres:postgres@localhost:5432/mdp_test npm test

# Stop database
docker compose -f ../../docker-compose.test.yml down
```

## Database Schema

The Postgres backend uses a single table:

```sql
CREATE TABLE mdp_capsules (
  id TEXT PRIMARY KEY,
  doc JSONB NOT NULL,
  version INT NOT NULL DEFAULT 1,
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_capsules_updated_at ON mdp_capsules(updated_at);
CREATE INDEX idx_capsules_kind ON mdp_capsules((doc->>'kind'));
CREATE INDEX idx_capsules_status ON mdp_capsules((doc->'metadata'->>'status'));
```

Schema is automatically created on first connection.

## CI Integration

Add to `.github/workflows/test.yml`:

```yaml
services:
  postgres:
    image: postgres:16-alpine
    env:
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: mdp_test
    options: >-
      --health-cmd pg_isready
      --health-interval 10s
      --health-timeout 5s
      --health-retries 5

- name: Run tests
  env:
    TEST_DSN: postgresql://postgres:postgres@localhost:5432/mdp_test
  run: npm test
```

## License

MIT