@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

npm install @mdp-framework/gateway

Capsule Store Usage

File Backend (Local Development)

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)

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)

npm test

Integration Tests (Postgres Backend)

Requires Postgres database:

# 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:

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:

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