kiokuko-dsh 0.1.0

package/dist/server/idempotency.js

@@ -0,0 +1,210 @@
+import { createHash } from 'node:crypto';
+import { withImmediateTransaction } from '../db/transaction.js';
+import { KiokukoError } from '../errors.js';
+import { canonicalJson } from '../serialization/validate.js';
+const MAX_SCOPE_OR_KEY_LENGTH = 256;
+const INPUT_FIELDS = new Set(['scope', 'key', 'request', 'createdAt']);
+const CONTROL_CHARACTERS = /\p{Cc}/u;
+const CANONICAL_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u;
+const VALIDATION_MESSAGE = 'Invalid idempotency input';
+const RESPONSE_VALIDATION_MESSAGE = 'Invalid idempotency response';
+const INTEGRITY_MESSAGE = 'Stored idempotency record is invalid';
+const CONFLICT_MESSAGE = 'Idempotency key was reused with a different request';
+function invalidInput() {
+    throw new KiokukoError('VALIDATION_ERROR', VALIDATION_MESSAGE);
+}
+function invalidResponse() {
+    throw new KiokukoError('VALIDATION_ERROR', RESPONSE_VALIDATION_MESSAGE);
+}
+function sha256(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    try {
+        const prototype = Object.getPrototypeOf(value);
+        return prototype === Object.prototype || prototype === null;
+    }
+    catch {
+        return false;
+    }
+}
+function isCanonicalArrayIndex(value) {
+    if (value === '0')
+        return true;
+    if (!/^[1-9]\d*$/u.test(value))
+        return false;
+    const index = Number(value);
+    return Number.isSafeInteger(index) && index < 4_294_967_295 && String(index) === value;
+}
+function validateJsonValue(value, ancestors, failure) {
+    if (value === null || typeof value === 'boolean' || typeof value === 'string')
+        return;
+    if (typeof value === 'number') {
+        if (Number.isFinite(value))
+            return;
+        failure();
+    }
+    if (typeof value !== 'object')
+        failure();
+    if (ancestors.has(value))
+        failure();
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            for (const key of Reflect.ownKeys(value)) {
+                if (typeof key !== 'string' || (key !== 'length' && !isCanonicalArrayIndex(key)))
+                    failure();
+            }
+            for (const item of value)
+                validateJsonValue(item, ancestors, failure);
+        }
+        else {
+            if (!isPlainObject(value))
+                failure();
+            for (const key of Reflect.ownKeys(value)) {
+                if (typeof key !== 'string')
+                    failure();
+            }
+            for (const child of Object.values(value))
+                validateJsonValue(child, ancestors, failure);
+        }
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function boundedString(value) {
+    if (typeof value !== 'string'
+        || value.trim().length === 0
+        || value.length > MAX_SCOPE_OR_KEY_LENGTH
+        || CONTROL_CHARACTERS.test(value)) {
+        invalidInput();
+    }
+    return value;
+}
+function isCanonicalTimestamp(value) {
+    if (typeof value !== 'string' || !CANONICAL_TIMESTAMP.test(value))
+        return false;
+    const parsed = new Date(value);
+    return !Number.isNaN(parsed.getTime()) && parsed.toISOString() === value;
+}
+function canonicalTimestamp(value) {
+    if (!isCanonicalTimestamp(value))
+        invalidInput();
+    return value;
+}
+function validateInput(input) {
+    if (!isPlainObject(input))
+        invalidInput();
+    try {
+        for (const field of Reflect.ownKeys(input)) {
+            if (typeof field !== 'string' || !INPUT_FIELDS.has(field))
+                invalidInput();
+        }
+    }
+    catch {
+        invalidInput();
+    }
+    const scope = boundedString(input.scope);
+    const key = boundedString(input.key);
+    let requestJson;
+    try {
+        validateJsonValue(input.request, new WeakSet(), invalidInput);
+        requestJson = canonicalJson(input.request);
+    }
+    catch {
+        invalidInput();
+    }
+    const createdAt = input.createdAt === undefined
+        ? new Date().toISOString()
+        : canonicalTimestamp(input.createdAt);
+    return {
+        scope,
+        keyHash: sha256(key),
+        requestHash: sha256(requestJson),
+        createdAt,
+    };
+}
+function invalidStoredRecord() {
+    throw new KiokukoError('INTEGRITY_ERROR', INTEGRITY_MESSAGE);
+}
+function isSha256(value) {
+    return typeof value === 'string' && /^[0-9a-f]{64}$/u.test(value);
+}
+function storedResponse(row, expectedScope) {
+    if (row.scope !== expectedScope
+        || !isSha256(row.key_hash)
+        || !isSha256(row.request_hash)
+        || typeof row.response_json !== 'string'
+        || !isCanonicalTimestamp(row.created_at)) {
+        invalidStoredRecord();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(row.response_json);
+        if (canonicalJson(parsed) !== row.response_json)
+            invalidStoredRecord();
+    }
+    catch {
+        invalidStoredRecord();
+    }
+    return parsed;
+}
+function findStoredRecord(database, validated) {
+    const select = `
+    SELECT scope, key_hash, request_hash, response_json, created_at
+    FROM gateway_idempotency
+  `;
+    const direct = database.prepare(`${select} WHERE scope = ? AND key_hash = ?`).get(validated.scope, validated.keyHash);
+    if (direct) {
+        const response = storedResponse(direct, validated.scope);
+        return { requestHash: direct.request_hash, response };
+    }
+    for (const row of database.prepare(`${select} WHERE scope = ?`).all(validated.scope)) {
+        const response = storedResponse(row, validated.scope);
+        if (row.key_hash === validated.keyHash) {
+            return { requestHash: row.request_hash, response };
+        }
+    }
+    return undefined;
+}
+function validateOperation(operation) {
+    if (typeof operation !== 'function')
+        invalidInput();
+}
+function executeValidated(database, validated, operation) {
+    const existing = findStoredRecord(database, validated);
+    if (existing) {
+        if (existing.requestHash !== validated.requestHash) {
+            throw new KiokukoError('CONFLICT', CONFLICT_MESSAGE, { reason: 'request_mismatch' });
+        }
+        return existing.response;
+    }
+    const responseValue = operation();
+    let responseJson;
+    try {
+        validateJsonValue(responseValue, new WeakSet(), invalidResponse);
+        responseJson = canonicalJson(responseValue);
+    }
+    catch {
+        throw new KiokukoError('VALIDATION_ERROR', RESPONSE_VALIDATION_MESSAGE);
+    }
+    database.prepare(`
+    INSERT INTO gateway_idempotency (scope, key_hash, request_hash, response_json, created_at)
+    VALUES (?, ?, ?, ?, ?)
+  `).run(validated.scope, validated.keyHash, validated.requestHash, responseJson, validated.createdAt);
+    return JSON.parse(responseJson);
+}
+export function executeIdempotent(database, input, operation) {
+    validateOperation(operation);
+    const validated = validateInput(input);
+    return withImmediateTransaction(database, () => executeValidated(database, validated, operation));
+}
+export function executeIdempotentInTransaction(database, input, operation) {
+    validateOperation(operation);
+    const validated = validateInput(input);
+    return executeValidated(database, validated, operation);
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/server/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../../src/server/idempotency.ts"],"names":[],"mappings":"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"}

package/dist/server/instance-lock.d.ts

@@ -0,0 +1,17 @@
+import { type PathEnvironment } from '../config/paths.js';
+export type PidLiveness = (pid: number) => boolean | Promise<boolean>;
+export interface InstanceLockOptions extends PathEnvironment {
+    runtimeDirectory?: string;
+    pid?: number;
+    instanceId?: string;
+    isPidAlive?: PidLiveness;
+}
+export interface InstanceLock {
+    path: string;
+    instanceId: string;
+    release(): Promise<boolean>;
+}
+export declare function isPidAlive(pid: number): Promise<boolean>;
+export declare function acquireInstanceLock(databasePath: string, options?: InstanceLockOptions): Promise<InstanceLock>;
+export declare function releaseInstanceLock(lockFilePath: string, expectedInstanceId: string): Promise<boolean>;
+//# sourceMappingURL=instance-lock.d.ts.map

package/dist/server/instance-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-lock.d.ts","sourceRoot":"","sources":["../../src/server/instance-lock.ts"],"names":[],"mappings":"AAGA,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG/E,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtE,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,WAAW,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7B;AAgDD,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAW9D;AAED,wBAAsB,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,CAAC,CA6BxH;AAED,wBAAsB,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAgB5G"}

package/dist/server/instance-lock.js

@@ -0,0 +1,118 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { chmod, lstat, mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { getDatabaseLockPath } from '../config/paths.js';
+import { KiokukoError } from '../errors.js';
+function lockPath(databasePath, options) {
+    if (options.runtimeDirectory) {
+        const platform = options.platform ?? process.platform;
+        const platformPath = platform === 'win32' ? path.win32 : path.posix;
+        const resolvedPath = platformPath.resolve(databasePath);
+        const fingerprint = createHash('sha256').update(resolvedPath, 'utf8').digest('hex');
+        const join = platform === 'win32' ? path.win32.join : path.posix.join;
+        return join(options.runtimeDirectory, `${fingerprint}.lock`);
+    }
+    return getDatabaseLockPath(databasePath, options);
+}
+function lockRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new KiokukoError('CONFLICT', 'Database instance lock is unavailable');
+    }
+    const record = value;
+    if (typeof record.instanceId !== 'string' || typeof record.pid !== 'number' || !Number.isInteger(record.pid) || record.pid <= 0) {
+        throw new KiokukoError('CONFLICT', 'Database instance lock is unavailable');
+    }
+    return { instanceId: record.instanceId, pid: record.pid };
+}
+function assertSecureLockFile(info) {
+    if (info.isSymbolicLink())
+        throw new KiokukoError('SECURITY_REJECTION', 'Database instance lock must not be a symbolic link');
+    if (!info.isFile())
+        throw new KiokukoError('VALIDATION_ERROR', 'Database instance lock must be a regular file');
+    if (process.platform !== 'win32' && (Number(info.mode) & 0o077) !== 0) {
+        throw new KiokukoError('SECURITY_REJECTION', 'Database instance lock permissions are too broad');
+    }
+}
+async function readLockRecord(lockFilePath) {
+    assertSecureLockFile(await lstat(lockFilePath));
+    try {
+        return lockRecord(JSON.parse(await readFile(lockFilePath, 'utf8')));
+    }
+    catch (error) {
+        if (error instanceof KiokukoError)
+            throw error;
+        throw new KiokukoError('CONFLICT', 'Database instance lock is unavailable');
+    }
+}
+export async function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error) {
+            if (error.code === 'EPERM')
+                return true;
+            if (error.code === 'ESRCH')
+                return false;
+        }
+        throw error;
+    }
+}
+export async function acquireInstanceLock(databasePath, options = {}) {
+    const instanceId = options.instanceId ?? randomUUID();
+    const pid = options.pid ?? process.pid;
+    const pidLiveness = options.isPidAlive ?? isPidAlive;
+    const lockFilePath = lockPath(databasePath, options);
+    await mkdir(path.dirname(lockFilePath), { recursive: true, mode: 0o700 });
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            await writeFile(lockFilePath, `${JSON.stringify({ instanceId, pid })}\n`, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+            await chmod(lockFilePath, 0o600);
+            return {
+                path: lockFilePath,
+                instanceId,
+                release: () => releaseInstanceLock(lockFilePath, instanceId),
+            };
+        }
+        catch (error) {
+            if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST'))
+                throw error;
+            const existing = await readLockRecord(lockFilePath);
+            if (await pidLiveness(existing.pid)) {
+                throw new KiokukoError('CONFLICT', 'Another live Kiokuko instance owns this database');
+            }
+            try {
+                await unlink(lockFilePath);
+            }
+            catch (unlinkError) {
+                if (!(unlinkError instanceof Error && 'code' in unlinkError && unlinkError.code === 'ENOENT'))
+                    throw unlinkError;
+            }
+        }
+    }
+    throw new KiokukoError('CONFLICT', 'Database instance lock is busy');
+}
+export async function releaseInstanceLock(lockFilePath, expectedInstanceId) {
+    let record;
+    try {
+        record = await readLockRecord(lockFilePath);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    if (record.instanceId !== expectedInstanceId)
+        return false;
+    try {
+        await unlink(lockFilePath);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+//# sourceMappingURL=instance-lock.js.map

package/dist/server/instance-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-lock.js","sourceRoot":"","sources":["../../src/server/instance-lock.ts"],"names":[],"mappings":"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"}

package/dist/server/router.d.ts

@@ -0,0 +1,29 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export interface ReadinessState {
+    readonly ready: boolean;
+}
+export type Readiness = ReadinessState | (() => boolean | Promise<boolean>);
+export interface RouterDependencies {
+    readonly expectedToken: string;
+    readonly readiness: Readiness;
+    readonly v1?: V1RouteHandler;
+}
+export type HttpHandler = (request: IncomingMessage, response: ServerResponse) => void | Promise<void>;
+export type JsonObject = Record<string, unknown>;
+export interface V1RouteRequest {
+    readonly method: string;
+    readonly url: URL;
+    readonly headers: IncomingMessage['headers'];
+    readonly rawHeaders?: readonly string[];
+    readonly body?: JsonObject;
+}
+export interface V1RouteOperationRequest {
+    readonly method: string;
+    readonly url: URL;
+}
+export type V1RouteOperationResolver = (request: V1RouteOperationRequest) => string | undefined;
+export type V1RouteHandler = ((request: V1RouteRequest) => unknown | Promise<unknown>) & {
+    operationFor?: V1RouteOperationResolver;
+};
+export declare function createRouter(dependencies: RouterDependencies): HttpHandler;
+//# sourceMappingURL=router.d.ts.map

package/dist/server/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/server/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAKjE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,MAAM,SAAS,GAAG,cAAc,GAAG,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;AAE5E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,EAAE,CAAC,EAAE,cAAc,CAAC;CAC9B;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEvG,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAC7C,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;CAC5B;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;CACnB;AAED,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,EAAE,uBAAuB,KAAK,MAAM,GAAG,SAAS,CAAC;AAChG,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG;IACvF,YAAY,CAAC,EAAE,wBAAwB,CAAC;CACzC,CAAC;AAwFF,wBAAgB,YAAY,CAAC,YAAY,EAAE,kBAAkB,GAAG,WAAW,CAuC1E"}

package/dist/server/router.js

@@ -0,0 +1,129 @@
+import { KiokukoError } from '../errors.js';
+import { parseStrictJson } from '../setup/strict-json.js';
+import { requireBearerAuthorization } from './auth.js';
+const MAX_BODY_BYTES = 2 * 1024 * 1024;
+const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+function isJsonContentType(value) {
+    if (value === undefined)
+        return false;
+    const parts = value.split(';');
+    if (parts.length > 2 || parts[0]?.trim().toLowerCase() !== 'application/json')
+        return false;
+    return parts.length === 1 || /^charset\s*=\s*utf-8$/iu.test(parts[1]?.trim() ?? '');
+}
+function writeJson(response, status, value) {
+    const body = JSON.stringify(value);
+    if (body === undefined || Buffer.byteLength(body) > MAX_RESPONSE_BYTES) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Response exceeds the safe size bound');
+    }
+    response.writeHead(status, {
+        'cache-control': 'no-store',
+        'content-length': Buffer.byteLength(body),
+        'content-type': 'application/json; charset=utf-8',
+    });
+    response.end(body);
+}
+async function readJsonObject(request) {
+    const chunks = [];
+    let size = 0;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        request.on('data', (chunk) => {
+            if (settled)
+                return;
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            size += buffer.byteLength;
+            if (size > MAX_BODY_BYTES) {
+                settled = true;
+                request.resume();
+                reject(new KiokukoError('VALIDATION_ERROR', 'Request body is too large'));
+                return;
+            }
+            chunks.push(buffer);
+        });
+        request.on('end', () => {
+            if (settled)
+                return;
+            let text;
+            try {
+                text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(Buffer.concat(chunks));
+            }
+            catch {
+                settled = true;
+                reject(new KiokukoError('VALIDATION_ERROR', 'Request body is not valid UTF-8'));
+                return;
+            }
+            if (text.trim().length === 0) {
+                settled = true;
+                reject(new KiokukoError('VALIDATION_ERROR', 'Request body must contain JSON'));
+                return;
+            }
+            try {
+                const value = parseStrictJson(text, { allowTrailingComma: false, disallowComments: true, allowEmptyContent: false }, 'Request body is not valid JSON with unique keys');
+                if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+                    throw new KiokukoError('VALIDATION_ERROR', 'Request body must be a JSON object');
+                }
+                settled = true;
+                resolve(value);
+            }
+            catch (error) {
+                if (settled)
+                    return;
+                settled = true;
+                reject(error);
+            }
+        });
+        request.on('error', (error) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(error);
+        });
+    });
+}
+async function readReadiness(readiness) {
+    return typeof readiness === 'function' ? readiness() : readiness.ready;
+}
+export function createRouter(dependencies) {
+    return async (request, response) => {
+        const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+        if (request.method === 'GET' && url.pathname === '/health/live') {
+            writeJson(response, 200, { ok: true });
+            return;
+        }
+        if (request.method === 'GET' && url.pathname === '/health/ready') {
+            requireBearerAuthorization(request.headers.authorization, dependencies.expectedToken);
+            const ready = await readReadiness(dependencies.readiness);
+            writeJson(response, ready ? 200 : 503, { ok: ready });
+            return;
+        }
+        if (url.pathname === '/api/v1' || url.pathname.startsWith('/api/v1/')) {
+            requireBearerAuthorization(request.headers.authorization, dependencies.expectedToken);
+            if (dependencies.v1 === undefined)
+                throw new KiokukoError('NOT_FOUND', 'Endpoint not found');
+            const routeRequest = {
+                headers: request.headers,
+                method: request.method ?? 'GET',
+                rawHeaders: request.rawHeaders,
+                url,
+            };
+            const hasRequestBody = request.method === 'POST' || request.method === 'PUT' || request.method === 'PATCH';
+            if (hasRequestBody) {
+                const contentType = request.headers['content-type'];
+                if (typeof contentType !== 'string' || !isJsonContentType(contentType)) {
+                    throw new KiokukoError('VALIDATION_ERROR', 'Request content type is invalid');
+                }
+            }
+            const requestWithBody = hasRequestBody
+                ? { ...routeRequest, body: await readJsonObject(request) }
+                : routeRequest;
+            const result = await dependencies.v1(requestWithBody);
+            if (result === undefined)
+                throw new KiokukoError('NOT_FOUND', 'Endpoint not found');
+            writeJson(response, 200, result);
+            return;
+        }
+        writeJson(response, 404, { ok: false });
+    };
+}
+//# sourceMappingURL=router.js.map

package/dist/server/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../../src/server/router.ts"],"names":[],"mappings":"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"}

package/dist/server/routes/agent-capability-gate.d.ts

@@ -0,0 +1,43 @@
+import type { GatewayIntakeResponse } from '../../gateway/agent-service.js';
+import type { ContextBrokerResult } from '../../context/broker.js';
+import type { TaskProfile } from '../../akinator/types.js';
+import { type CapabilityResolution, type CapabilityWarning, type MemoryPolicy } from '../../akinator/capabilities.js';
+import type { AgentRouteContext } from './agent-runs.js';
+export type AgentCapabilityNextAction = 'proceed' | 'answer_from_evidence_or_ask_user' | 'required_capability_unavailable';
+export type CapabilityGatedIntakeResponse = Omit<GatewayIntakeResponse, 'context'> & {
+    context: ContextBrokerResult['context'];
+    recommendations: ContextBrokerResult['recommendations'];
+    capabilities: CapabilityResolution;
+    memoryPolicy: MemoryPolicy;
+    warnings: CapabilityWarning[];
+    nextAction: AgentCapabilityNextAction;
+};
+export interface AgentCapabilityGateInput {
+    task: string;
+    intakeStatus: 'needs_answer' | 'ready' | 'exhausted';
+    taskProfile: TaskProfile;
+    recommendedTags: string[];
+    catalog: unknown;
+    broker: Pick<ContextBrokerResult, 'context' | 'recommendations'>;
+    memoryUseOverride?: 'none' | 'actionable';
+    storedEntryCount?: number;
+}
+export interface AgentCapabilityGateResult {
+    context: ContextBrokerResult['context'];
+    recommendations: ContextBrokerResult['recommendations'];
+    capabilities: CapabilityResolution;
+    memoryPolicy: MemoryPolicy;
+    warnings: CapabilityWarning[];
+    nextAction: AgentCapabilityNextAction;
+}
+export declare function deriveBrokerMemoryUseSignal(context: Pick<AgentRouteContext, 'database'>, broker: Pick<ContextBrokerResult, 'context'>): 'none' | 'actionable';
+export declare function brokerIntakeStatus(status: ContextBrokerResult['status']): AgentCapabilityGateInput['intakeStatus'];
+export declare function assertBrokerContextRun(candidate: Pick<ContextBrokerResult, 'context'>, runId: string): void;
+export declare function requestCapabilityCatalog(value: unknown): unknown;
+export declare function applyAgentCapabilityGate(input: AgentCapabilityGateInput): AgentCapabilityGateResult;
+/** Count stored entries only when the final model-facing context is empty. */
+export declare function applyAgentCapabilityGateWithDeliveryObservation(input: Omit<AgentCapabilityGateInput, 'storedEntryCount'>, countStoredEntries: () => number): AgentCapabilityGateResult;
+/** Rank once, decide against that immutable snapshot, and persist only the
+ * exact approved delivery. A rejected or throwing gate never writes context. */
+export declare function attachCapabilityGatedContext(context: AgentRouteContext, value: GatewayIntakeResponse, catalog: unknown): Promise<CapabilityGatedIntakeResponse>;
+//# sourceMappingURL=agent-capability-gate.d.ts.map

package/dist/server/routes/agent-capability-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-capability-gate.d.ts","sourceRoot":"","sources":["../../../src/server/routes/agent-capability-gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAC5E,OAAO,KAAK,EAA4B,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAU7F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAML,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAClB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGzD,MAAM,MAAM,yBAAyB,GACjC,SAAS,GACT,kCAAkC,GAClC,iCAAiC,CAAC;AAEtC,MAAM,MAAM,6BAA6B,GAAG,IAAI,CAAC,qBAAqB,EAAE,SAAS,CAAC,GAAG;IACnF,OAAO,EAAE,mBAAmB,CAAC,SAAS,CAAC,CAAC;IACxC,eAAe,EAAE,mBAAmB,CAAC,iBAAiB,CAAC,CAAC;IACxD,YAAY,EAAE,oBAAoB,CAAC;IACnC,YAAY,EAAE,YAAY,CAAC;IAC3B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,UAAU,EAAE,yBAAyB,CAAC;CACvC,CAAC;AAEF,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,cAAc,GAAG,OAAO,GAAG,WAAW,CAAC;IACrD,WAAW,EAAE,WAAW,CAAC;IACzB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,SAAS,GAAG,iBAAiB,CAAC,CAAC;IACjE,iBAAiB,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAC1C,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,mBAAmB,CAAC,SAAS,CAAC,CAAC;IACxC,eAAe,EAAE,mBAAmB,CAAC,iBAAiB,CAAC,CAAC;IACxD,YAAY,EAAE,oBAAoB,CAAC;IACnC,YAAY,EAAE,YAAY,CAAC;IAC3B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,UAAU,EAAE,yBAAyB,CAAC;CACvC;AAkED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,UAAU,CAAC,EAC5C,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,SAAS,CAAC,GAC3C,MAAM,GAAG,YAAY,CAQvB;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,mBAAmB,CAAC,QAAQ,CAAC,GACpC,wBAAwB,CAAC,cAAc,CAAC,CAG1C;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,IAAI,CAAC,mBAAmB,EAAE,SAAS,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAI3G;AAQD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEhE;AAyBD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,wBAAwB,GAAG,yBAAyB,CA0BnG;AAED,8EAA8E;AAC9E,wBAAgB,+CAA+C,CAC7D,KAAK,EAAE,IAAI,CAAC,wBAAwB,EAAE,kBAAkB,CAAC,EACzD,kBAAkB,EAAE,MAAM,MAAM,GAC/B,yBAAyB,CAU3B;AAED;gFACgF;AAChF,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,qBAAqB,EAC5B,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,6BAA6B,CAAC,CAqDxC"}