feat(backend): add foundation services and sql idempotency

backend/command-api/test/app.test.js

@@ -0,0 +1,54 @@
+import test, { beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import request from 'supertest';
+import { createApp } from '../src/app.js';
+import { __resetIdempotencyStoreForTests } from '../src/services/idempotency-store.js';
+
+process.env.AUTH_BYPASS = 'true';
+
+beforeEach(() => {
+  process.env.IDEMPOTENCY_STORE = 'memory';
+  delete process.env.IDEMPOTENCY_DATABASE_URL;
+  __resetIdempotencyStoreForTests();
+});
+
+test('GET /healthz returns healthy response', async () => {
+  const app = createApp();
+  const res = await request(app).get('/healthz');
+
+  assert.equal(res.status, 200);
+  assert.equal(res.body.ok, true);
+  assert.equal(typeof res.body.requestId, 'string');
+});
+
+test('command route requires idempotency key', async () => {
+  const app = createApp();
+  const res = await request(app)
+    .post('/commands/orders/create')
+    .set('Authorization', 'Bearer test-token')
+    .send({ payload: {} });
+
+  assert.equal(res.status, 400);
+  assert.equal(res.body.code, 'MISSING_IDEMPOTENCY_KEY');
+});
+
+test('command route is idempotent by key', async () => {
+  const app = createApp();
+
+  const first = await request(app)
+    .post('/commands/orders/create')
+    .set('Authorization', 'Bearer test-token')
+    .set('Idempotency-Key', 'abc-123')
+    .send({ payload: { order: 'x' } });
+
+  const second = await request(app)
+    .post('/commands/orders/create')
+    .set('Authorization', 'Bearer test-token')
+    .set('Idempotency-Key', 'abc-123')
+    .send({ payload: { order: 'x' } });
+
+  assert.equal(first.status, 200);
+  assert.equal(second.status, 200);
+  assert.equal(first.body.commandId, second.body.commandId);
+  assert.equal(first.body.idempotencyKey, 'abc-123');
+});

backend/command-api/test/idempotency-store.test.js

@@ -0,0 +1,56 @@
+import test, { beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  __resetIdempotencyStoreForTests,
+  buildIdempotencyKey,
+  readIdempotentResult,
+  writeIdempotentResult,
+} from '../src/services/idempotency-store.js';
+
+beforeEach(() => {
+  process.env.IDEMPOTENCY_STORE = 'memory';
+  delete process.env.IDEMPOTENCY_DATABASE_URL;
+  __resetIdempotencyStoreForTests();
+});
+
+test('buildIdempotencyKey composes user route and client key', () => {
+  const key = buildIdempotencyKey({
+    userId: 'user-1',
+    route: '/commands/orders/create',
+    idempotencyKey: 'req-abc',
+  });
+
+  assert.equal(key, 'user-1:/commands/orders/create:req-abc');
+});
+
+test('memory idempotency store returns existing payload for duplicate key', async () => {
+  const compositeKey = buildIdempotencyKey({
+    userId: 'user-1',
+    route: '/commands/orders/create',
+    idempotencyKey: 'req-abc',
+  });
+
+  const first = await writeIdempotentResult({
+    compositeKey,
+    userId: 'user-1',
+    route: '/commands/orders/create',
+    idempotencyKey: 'req-abc',
+    payload: { accepted: true, commandId: 'c-1' },
+    statusCode: 200,
+  });
+
+  const second = await writeIdempotentResult({
+    compositeKey,
+    userId: 'user-1',
+    route: '/commands/orders/create',
+    idempotencyKey: 'req-abc',
+    payload: { accepted: true, commandId: 'c-2' },
+    statusCode: 200,
+  });
+
+  const read = await readIdempotentResult(compositeKey);
+
+  assert.equal(first.payload.commandId, 'c-1');
+  assert.equal(second.payload.commandId, 'c-1');
+  assert.equal(read.payload.commandId, 'c-1');
+});