@ontologie/mock-server

In-process mock server for local SDK development. Exposes createMockServer() returning a createFetch() function compatible with the global fetch API.

Status — V1.0 (post-Phase-5)

| Surface | Status | Notes | |---------|--------|-------| | Read paths (ObjectSet.fetchPage, manifest, types, link-types, graph traverse/neighbors/paths) | ✅ Supported | Returns deterministic fixtures matching staging shapes | | Action describe (GET /api/v1/actions/:key/describe) | ✅ Supported | Returns stub action descriptor | | Calendar / Audit / Forms / Scenarios / Decision-compares (read+write) | ✅ Supported | In-memory state, deterministic round-trips | | V1 REST instance CRUD (POST /api/v1/object-types/:apiName/instances, PUT/DELETE /api/v1/instances/:id, /instances/batch) | ✅ Supported (Phase 5) | In-memory store, version increment on update, soft delete | | ActionBuilder (POST /api/v1/actions/:key/dry-run and /invoke) | ✅ Supported (Phase 5) | Returns PlanArtifactV1 + ActionResult stubs | | Legacy CQRS writes (POST /api/commands/execute, /api/commands/batch) | ⚠️ Returns 501 MOCK_LEGACY_CQRS_DEPRECATED | Defensive guard for legacy callers — current SDK uses REST routes above |

Usage

import { createMockServer } from '@ontologie/mock-server';
import { createClient } from '@ontologie/sdk-client';

const mock = createMockServer();
globalThis.fetch = mock.createFetch();

const client = createClient({
  baseUrl: 'http://mock.dataforge.local',
  apiKey: 'mock-key',
  workspaceId: 'mock-ws',
});

// Reads — fully supported:
const types = await client.ontology.types.list();
const result = await client.ontology.Employee.where(e => e.salary.gt(50000)).fetchPage();

// Writes — fully supported (Phase 5):
const employee = await client.ontology.Employee.create({ name: 'Alice', salary: 60000 });
const updated = await client.ontology.Employee.update(employee.data.id, { salary: 70000 });
await client.ontology.Employee.delete(employee.data.id);

// Batch operations:
const batch = await client.ontology.Employee.batchCreate([
  { name: 'Bob' },
  { name: 'Charlie' },
]);

// Actions:
const plan = await client.actions.on('Contract').action('approve').target('con-1').dryRun();
const result2 = await client.actions.on('Contract').action('approve').applyPlan(plan.planId);

Phase 5 implementation details (closes #1076)

Phase 5 of epic #1077 wires real handlers for V1 REST routes that the SDK uses post-Phase-4 (PR #1099). Pre-Phase-5 these returned 501. Now :

| Route | Behavior | |-------|----------| | POST /api/v1/object-types/:apiName/instances | Stores in MockServer.objects Map, returns {success, data: {id, object_type_id, data, version: 1, status: 'active', ...}} | | POST /api/v1/object-types/:apiName/instances/batch | Iterates body.updates[], dispatches by op type, returns {succeeded, failed, results[]} | | PUT /api/v1/instances/:id | Cross-type lookup, version increment, returns updated instance. 404 if not found | | DELETE /api/v1/instances/:id | Cross-type lookup, removes from store, returns {success, data: {id, status: 'deleted'}}. 404 if not found | | POST /api/v1/actions/:key/dry-run | Returns minimal PlanArtifactV1 stub with canApply: true, signature placeholders | | POST /api/v1/actions/:key/invoke | Returns ActionResult stub with runId, actionKey, empty editedRefs + blockedSideEffects |

Legacy CQRS writes (501 mitigation)

POST /api/commands/execute and /api/commands/batch now return MOCK_LEGACY_CQRS_DEPRECATED 501 with a message explaining that the SDK uses REST routes post-Phase-4. This is a defensive guard for legacy callers. Current SDK code does not hit these paths.

Cross-references

• Epic : #1077 Track G-bis
• Audit : docs/quality/COMMAND-PRIMITIVE-AUDIT-2026-05-01.md
• Phase 4 (root cause fix) : #1099
• Issue : #1076 — closed by this PR
• Parity test : src/server.parity.test.ts — 23 tests covering reads + writes + actions + legacy 501 guard