kiokuko-dsh 0.1.0

package/dist/serialization/validate.js

@@ -0,0 +1,233 @@
+import { createHash } from 'node:crypto';
+import { KiokukoError } from '../errors.js';
+import { cloneBoundaryJson, stringifyBoundaryJson } from './boundary-json.js';
+export const ENTRY_KINDS = ['fact', 'decision', 'lesson', 'preference', 'reference'];
+export const ENTRY_STATUSES = ['candidate', 'verified', 'superseded'];
+export const TRUST_LEVELS = ['untrusted', 'user_asserted', 'source_verified', 'system_verified'];
+const RECORD_FIELDS = new Set([
+    'workspace',
+    'kind',
+    'status',
+    'title',
+    'body',
+    'summary',
+    'scope',
+    'provenance',
+    'trustLevel',
+    'confidence',
+    'tags',
+    'createdBy',
+    'actor',
+]);
+const PROVENANCE_FIELDS = new Set([
+    'type',
+    'reference',
+    'sourceRepositoryId',
+    'sourceWorkspace',
+    'sourceCommit',
+    'sourcePath',
+    'sourceChunkIndex',
+    'externalSkillId',
+    'requirementScopeHash',
+    'runId',
+    'deliveryId',
+    'evidenceIds',
+    'sourcePaths',
+    'clientKind',
+    'timestamp',
+]);
+function validation(message, details = {}) {
+    throw new KiokukoError('VALIDATION_ERROR', message, details);
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function assertObject(value, field) {
+    if (!isPlainObject(value))
+        validation(`${field} must be a JSON object`);
+}
+function assertKnownFields(value, allowed, label) {
+    for (const field of Object.keys(value)) {
+        if (!allowed.has(field))
+            validation(`Unknown ${label} field: ${field}`, { field });
+    }
+}
+function assertJsonValue(value, path) {
+    if (value === null || typeof value === 'boolean' || typeof value === 'string')
+        return;
+    if (typeof value === 'number') {
+        if (Number.isFinite(value))
+            return;
+        validation(`${path} must contain only finite JSON numbers`);
+    }
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index += 1)
+            assertJsonValue(value[index], `${path}[${index}]`);
+        return;
+    }
+    if (isPlainObject(value)) {
+        for (const [key, child] of Object.entries(value))
+            assertJsonValue(child, `${path}.${key}`);
+        return;
+    }
+    validation(`${path} must be JSON-compatible`);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function enumValue(value, allowed, field) {
+    if (typeof value !== 'string' || !allowed.includes(value)) {
+        validation(`${field} must be one of: ${allowed.join(', ')}`);
+    }
+    return value;
+}
+/** Compare strings by ECMAScript UTF-16 code units, independent of the host locale. */
+export function compareCanonicalStrings(left, right) {
+    if (left === right)
+        return 0;
+    return left < right ? -1 : 1;
+}
+/** Return the de-duplicated persisted tag order used by all new revision hashes. */
+export function canonicalTagOrder(tags) {
+    return [...new Set(tags)].sort(compareCanonicalStrings);
+}
+/** Serialize JSON values with recursively sorted object keys and no insignificant whitespace. */
+export function canonicalJson(value) {
+    return stringifyBoundaryJson(cloneBoundaryJson(value, {
+        failure: () => new KiokukoError('VALIDATION_ERROR', 'value must be JSON-compatible'),
+    }));
+}
+export function canonicalContentHash(value) {
+    return createHash('sha256').update(canonicalJson(value), 'utf8').digest('hex');
+}
+function entryRevisionHashPayload(input, tags) {
+    return {
+        kind: input.kind,
+        title: input.title,
+        body: input.body,
+        summary: input.summary,
+        scope: input.scope,
+        provenance: input.provenance,
+        tags: [...tags],
+    };
+}
+/** Hash revision content with the current locale-independent persisted tag order. */
+export function canonicalEntryRevisionContentHash(input) {
+    return canonicalContentHash(entryRevisionHashPayload(input, canonicalTagOrder(input.tags)));
+}
+export function requireWorkspace(value) {
+    if (!isNonEmptyString(value))
+        validation('workspace must be a non-empty string');
+    return value;
+}
+function validateObjectField(value, field) {
+    assertObject(value, field);
+    assertJsonValue(value, field);
+    return value;
+}
+function validateProvenance(value) {
+    const provenance = validateObjectField(value, 'provenance');
+    assertKnownFields(provenance, PROVENANCE_FIELDS, 'provenance');
+    if (Object.keys(provenance).length > 0) {
+        if (!isNonEmptyString(provenance.type))
+            validation('provenance.type must be a non-empty string');
+        if (!isNonEmptyString(provenance.reference))
+            validation('provenance.reference must be a non-empty string');
+        for (const field of [
+            'sourceRepositoryId',
+            'sourceWorkspace',
+            'sourceCommit',
+            'sourcePath',
+            'externalSkillId',
+            'requirementScopeHash',
+            'runId',
+            'deliveryId',
+            'clientKind',
+            'timestamp',
+        ]) {
+            if (provenance[field] !== undefined && !isNonEmptyString(provenance[field])) {
+                validation(`provenance.${field} must be a non-empty string`);
+            }
+        }
+        for (const field of ['requirementScopeHash']) {
+            if (provenance[field] !== undefined && !/^[0-9a-f]{64}$/u.test(provenance[field])) {
+                validation(`provenance.${field} must be a lowercase SHA-256 hash`);
+            }
+        }
+        if (provenance.sourceChunkIndex !== undefined && (typeof provenance.sourceChunkIndex !== 'number' || !Number.isSafeInteger(provenance.sourceChunkIndex) || provenance.sourceChunkIndex < 0)) {
+            validation('provenance.sourceChunkIndex must be a non-negative integer');
+        }
+        for (const field of ['evidenceIds', 'sourcePaths']) {
+            const values = provenance[field];
+            if (values !== undefined) {
+                if (!Array.isArray(values) || values.length > 200 || values.some((item) => !isNonEmptyString(item))) {
+                    validation(`provenance.${field} must be a bounded string array`);
+                }
+            }
+        }
+    }
+    return provenance;
+}
+function validateTags(value) {
+    if (!Array.isArray(value))
+        validation('tags must be an array of strings');
+    if (value.length > 100)
+        validation('tags must contain at most 100 values');
+    const tags = value.map((tag, index) => {
+        if (!isNonEmptyString(tag) || tag.length > 200)
+            validation(`tags[${index}] must be a non-empty string of at most 200 characters`);
+        return tag;
+    });
+    return canonicalTagOrder(tags);
+}
+export function validateRecordInput(value) {
+    assertObject(value, 'record input');
+    assertKnownFields(value, RECORD_FIELDS, 'record input');
+    const workspace = requireWorkspace(value.workspace);
+    const kind = enumValue(value.kind, ENTRY_KINDS, 'kind');
+    const status = value.status === undefined ? 'candidate' : enumValue(value.status, ENTRY_STATUSES, 'status');
+    const title = value.title;
+    if (!isNonEmptyString(title))
+        validation('title must be a non-empty string');
+    if (typeof value.body !== 'string')
+        validation('body must be a string');
+    let summary = null;
+    if (value.summary !== undefined && value.summary !== null) {
+        if (typeof value.summary !== 'string')
+            validation('summary must be a string or null');
+        summary = value.summary;
+    }
+    const scope = value.scope === undefined ? {} : validateObjectField(value.scope, 'scope');
+    const provenance = value.provenance === undefined ? {} : validateProvenance(value.provenance);
+    const trustLevel = value.trustLevel === undefined ? 'user_asserted' : enumValue(value.trustLevel, TRUST_LEVELS, 'trustLevel');
+    const confidence = value.confidence === undefined ? 1.0 : value.confidence;
+    if (typeof confidence !== 'number' || !Number.isFinite(confidence) || confidence < 0 || confidence > 1) {
+        validation('confidence must be between 0 and 1');
+    }
+    const tags = value.tags === undefined ? [] : validateTags(value.tags);
+    const createdBy = value.createdBy === undefined ? 'kiokuko-cli' : value.createdBy;
+    if (!isNonEmptyString(createdBy))
+        validation('createdBy must be a non-empty string');
+    const actor = value.actor === undefined ? createdBy : value.actor;
+    if (!isNonEmptyString(actor))
+        validation('actor must be a non-empty string');
+    return {
+        workspace,
+        kind,
+        status,
+        title,
+        body: value.body,
+        summary,
+        scope,
+        provenance,
+        trustLevel,
+        confidence,
+        tags,
+        createdBy,
+        actor,
+    };
+}
+//# sourceMappingURL=validate.js.map

package/dist/serialization/validate.js.map

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

package/dist/server/agent-application.d.ts

@@ -0,0 +1,6 @@
+import { type HttpApplicationContext, type HttpServerHandle, type HttpServerOptions } from './http.js';
+import type { V1RouteHandler } from './router.js';
+export type AgentHttpServerOptions = Omit<HttpServerOptions, 'app' | 'v1' | 'applicationFactory'>;
+export declare function createAgentV1Handler(context: HttpApplicationContext): V1RouteHandler;
+export declare function startAgentHttpServer(options?: AgentHttpServerOptions): Promise<HttpServerHandle>;
+//# sourceMappingURL=agent-application.d.ts.map

package/dist/server/agent-application.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-application.d.ts","sourceRoot":"","sources":["../../src/server/agent-application.ts"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACxH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAQlD,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,iBAAiB,EAAE,KAAK,GAAG,IAAI,GAAG,oBAAoB,CAAC,CAAC;AAUlG,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,sBAAsB,GAAG,cAAc,CAoCpF;AAWD,wBAAsB,oBAAoB,CAAC,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAM1G"}

package/dist/server/agent-application.js

@@ -0,0 +1,74 @@
+import { KiokukoError } from '../errors.js';
+import { AgentGatewayService } from '../gateway/agent-service.js';
+import { FeedbackService } from '../gateway/checkpoint-service.js';
+import { CheckpointMutationService } from '../gateway/checkpoint-mutation-service.js';
+import { NudgeDeliveryService } from '../gateway/nudge-delivery-service.js';
+import { ContextBroker } from '../context/broker.js';
+import { startHttpServer } from './http.js';
+import { createAgentEventsRoute, agentEventsOperation } from './routes/agent-events.js';
+import { createAgentIntakeRoute, agentIntakeOperation } from './routes/agent-intake.js';
+import { createAgentRunsRoute, agentRunsOperation } from './routes/agent-runs.js';
+import { createAgentPromotionsRoute, agentPromotionsOperation } from './routes/agent-promotions.js';
+import { createTask5Route, task5Operation } from './routes/task5.js';
+import { AgentCheckpointUseCase } from './agent-checkpoint-use-case.js';
+function operationFor(method, pathname) {
+    return agentRunsOperation(method, pathname)
+        ?? agentPromotionsOperation(method, pathname)
+        ?? agentIntakeOperation(method, pathname)
+        ?? agentEventsOperation(method, pathname)
+        ?? task5Operation(method, pathname);
+}
+export function createAgentV1Handler(context) {
+    const service = new AgentGatewayService(context.database);
+    const checkpointMutation = new CheckpointMutationService(context.database);
+    const nudgeDelivery = new NudgeDeliveryService(context.database);
+    const broker = new ContextBroker(context.database, context.embeddingRuntime);
+    const routeContext = {
+        database: context.database,
+        service,
+        feedbackService: new FeedbackService(context.database),
+        broker,
+        enqueueWrite: context.enqueueWrite,
+        agentCheckpoint: new AgentCheckpointUseCase({
+            database: context.database,
+            service,
+            checkpointMutation,
+            nudgeDelivery,
+            broker,
+            enqueueWrite: context.enqueueWrite,
+        }),
+    };
+    const routes = [
+        createAgentRunsRoute(routeContext),
+        createAgentPromotionsRoute(routeContext),
+        createAgentIntakeRoute(routeContext),
+        createAgentEventsRoute(routeContext),
+        createTask5Route(routeContext),
+    ];
+    const handler = (async (request) => {
+        for (const route of routes) {
+            const result = await route(request);
+            if (result !== undefined)
+                return result;
+        }
+        return undefined;
+    });
+    handler.operationFor = ({ method, url }) => operationFor(method, url.pathname);
+    return handler;
+}
+function rejectConflictingOptions(options) {
+    const unsafe = options;
+    for (const key of ['app', 'v1', 'applicationFactory']) {
+        if (Object.prototype.hasOwnProperty.call(unsafe, key)) {
+            throw new KiokukoError('VALIDATION_ERROR', 'Agent server options cannot override the production application');
+        }
+    }
+}
+export async function startAgentHttpServer(options = {}) {
+    rejectConflictingOptions(options);
+    return startHttpServer({
+        ...options,
+        applicationFactory: (context) => context.createAuthenticatedApp(createAgentV1Handler(context)),
+    });
+}
+//# sourceMappingURL=agent-application.js.map

package/dist/server/agent-application.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-application.js","sourceRoot":"","sources":["../../src/server/agent-application.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,yBAAyB,EAAE,MAAM,2CAA2C,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAA8E,MAAM,WAAW,CAAC;AAExH,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACxF,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACxF,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAA0B,MAAM,wBAAwB,CAAC;AAC1G,OAAO,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACpG,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAIxE,SAAS,YAAY,CAAC,MAAc,EAAE,QAAgB;IACpD,OAAO,kBAAkB,CAAC,MAAM,EAAE,QAAQ,CAAC;WACtC,wBAAwB,CAAC,MAAM,EAAE,QAAQ,CAAC;WAC1C,oBAAoB,CAAC,MAAM,EAAE,QAAQ,CAAC;WACtC,oBAAoB,CAAC,MAAM,EAAE,QAAQ,CAAC;WACtC,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,OAA+B;IAClE,MAAM,OAAO,GAAG,IAAI,mBAAmB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC1D,MAAM,kBAAkB,GAAG,IAAI,yBAAyB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3E,MAAM,aAAa,GAAG,IAAI,oBAAoB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjE,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC7E,MAAM,YAAY,GAAsB;QACtC,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,OAAO;QACP,eAAe,EAAE,IAAI,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC;QACtD,MAAM;QACN,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,eAAe,EAAE,IAAI,sBAAsB,CAAC;YAC1C,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,OAAO;YACP,kBAAkB;YAClB,aAAa;YACb,MAAM;YACN,YAAY,EAAE,OAAO,CAAC,YAAY;SACnC,CAAC;KACH,CAAC;IACF,MAAM,MAAM,GAA8B;QACxC,oBAAoB,CAAC,YAAY,CAAC;QAClC,0BAA0B,CAAC,YAAY,CAAC;QACxC,sBAAsB,CAAC,YAAY,CAAC;QACpC,sBAAsB,CAAC,YAAY,CAAC;QACpC,gBAAgB,CAAC,YAAY,CAAC;KAC/B,CAAC;IACF,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACjC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC;YACpC,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,MAAM,CAAC;QAC1C,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC,CAAmB,CAAC;IACrB,OAAO,CAAC,YAAY,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC/E,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,wBAAwB,CAAC,OAA+B;IAC/D,MAAM,MAAM,GAAG,OAA6C,CAAC;IAC7D,KAAK,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,oBAAoB,CAAC,EAAE,CAAC;QACtD,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,iEAAiE,CAAC,CAAC;QAChH,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,UAAkC,EAAE;IAC7E,wBAAwB,CAAC,OAAO,CAAC,CAAC;IAClC,OAAO,eAAe,CAAC;QACrB,GAAG,OAAO;QACV,kBAAkB,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,sBAAsB,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;KAC/F,CAAC,CAAC;AACL,CAAC"}

package/dist/server/agent-checkpoint-use-case.d.ts

@@ -0,0 +1,41 @@
+import type { AgentGatewayService } from '../gateway/agent-service.js';
+import type { CheckpointMutationPort, CheckpointMutationResult } from '../gateway/checkpoint-mutation-service.js';
+import type { NudgeDeliveryPort } from '../gateway/nudge-delivery-service.js';
+import type { ContextBroker, ContextBrokerResult } from '../context/broker.js';
+import type { DeliveredNudge } from '../context/nudges.js';
+import type { Recommendation } from '../context/recommendations.js';
+import { successEnvelope } from '../serialization/envelope.js';
+import type { CapabilityGatedIntakeResponse } from './routes/agent-capability-gate.js';
+export interface AgentCheckpointUseCaseDependencies {
+    readonly database: import('../db/adapter.js').SqliteDatabase;
+    readonly service: AgentGatewayService;
+    readonly checkpointMutation: CheckpointMutationPort;
+    readonly validateMutationAcknowledgement?: boolean;
+    readonly nudgeDelivery: NudgeDeliveryPort;
+    readonly broker: ContextBroker;
+    readonly enqueueWrite: <T>(operation: () => T | PromiseLike<T>) => Promise<T>;
+}
+export interface AgentCheckpointInput {
+    readonly runId: string;
+    readonly idempotencyKey: string;
+    readonly body: unknown;
+    readonly requestBindingHash: string;
+}
+export type AgentCheckpointResponse = Omit<CheckpointMutationResult, 'preliminaryRecommendations'> & {
+    readonly recommendations: readonly Recommendation[];
+    readonly capabilities: CapabilityGatedIntakeResponse['capabilities'];
+    readonly memoryPolicy: CapabilityGatedIntakeResponse['memoryPolicy'];
+    readonly warnings: CapabilityGatedIntakeResponse['warnings'];
+    readonly nextAction: CapabilityGatedIntakeResponse['nextAction'];
+    readonly context: ContextBrokerResult['context'];
+    readonly nudge: DeliveredNudge | null;
+    readonly untrusted: true;
+    readonly requestBindingHash: string;
+};
+export declare class AgentCheckpointUseCase {
+    private readonly dependencies;
+    constructor(dependencies: AgentCheckpointUseCaseDependencies);
+    execute(input: AgentCheckpointInput): Promise<AgentCheckpointResponse>;
+}
+export declare function checkpointSuccessResponse(value: AgentCheckpointResponse): ReturnType<typeof successEnvelope>;
+//# sourceMappingURL=agent-checkpoint-use-case.d.ts.map

package/dist/server/agent-checkpoint-use-case.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-checkpoint-use-case.d.ts","sourceRoot":"","sources":["../../src/server/agent-checkpoint-use-case.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,KAAK,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,2CAA2C,CAAC;AAClH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAGpE,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAG/D,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,mCAAmC,CAAC;AASvF,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,QAAQ,EAAE,OAAO,kBAAkB,EAAE,cAAc,CAAC;IAC7D,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,kBAAkB,EAAE,sBAAsB,CAAC;IACpD,QAAQ,CAAC,+BAA+B,CAAC,EAAE,OAAO,CAAC;IACnD,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,wBAAwB,EAAE,4BAA4B,CAAC,GAAG;IACnG,QAAQ,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE,CAAC;IACpD,QAAQ,CAAC,YAAY,EAAE,6BAA6B,CAAC,cAAc,CAAC,CAAC;IACrE,QAAQ,CAAC,YAAY,EAAE,6BAA6B,CAAC,cAAc,CAAC,CAAC;IACrE,QAAQ,CAAC,QAAQ,EAAE,6BAA6B,CAAC,UAAU,CAAC,CAAC;IAC7D,QAAQ,CAAC,UAAU,EAAE,6BAA6B,CAAC,YAAY,CAAC,CAAC;IACjE,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC,SAAS,CAAC,CAAC;IACjD,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC,CAAC;AA8EF,qBAAa,sBAAsB;IACrB,OAAO,CAAC,QAAQ,CAAC,YAAY;gBAAZ,YAAY,EAAE,kCAAkC;IAEvE,OAAO,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,uBAAuB,CAAC;CA2E7E;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,uBAAuB,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAE5G"}

package/dist/server/agent-checkpoint-use-case.js

@@ -0,0 +1,159 @@
+import { KiokukoError } from '../errors.js';
+import { checkpointEligibility } from '../ledger/checkpoint-eligibility.js';
+import { buildRecommendations } from '../context/recommendations.js';
+import { canonicalJson } from '../serialization/validate.js';
+import { successEnvelope } from '../serialization/envelope.js';
+import { assertCapabilityCatalogBinding } from '../akinator/capability-binding.js';
+import { retrievableWorkspaceEntryCount } from '../memory/hybrid-retrieval.js';
+import { applyAgentCapabilityGateWithDeliveryObservation, assertBrokerContextRun, brokerIntakeStatus, deriveBrokerMemoryUseSignal, requestCapabilityCatalog, } from './routes/agent-capability-gate.js';
+function withoutCapabilityCatalog(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return value;
+    const result = { ...value };
+    delete result.capabilities;
+    return result;
+}
+function checkpointSignalArray(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Checkpoint signals are invalid after validation');
+    }
+    return [...value];
+}
+function checkpointSignals(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Checkpoint signals are invalid after validation');
+    }
+    const request = value;
+    return {
+        changedPaths: checkpointSignalArray(request.changedPaths),
+        errorSignatures: checkpointSignalArray(request.errorSignatures),
+    };
+}
+function assertActiveCheckpointRun(run) {
+    const eligibility = checkpointEligibility(run.status);
+    if (eligibility.allowed)
+        return;
+    throw new KiokukoError('CONFLICT', 'Checkpoint is not allowed for a non-active run', {
+        checkpointEligibility: eligibility,
+        runStatus: run.status,
+    });
+}
+function brokerPersistence(dependencies) {
+    return {
+        enqueueWrite: (operation) => dependencies.enqueueWrite(operation),
+    };
+}
+function sameTaskProfile(left, right) {
+    return left.taskType === right.taskType
+        && left.target === right.target
+        && left.expected === right.expected
+        && left.constraints === right.constraints;
+}
+function checkpointIntegrity() {
+    throw new KiokukoError('INTEGRITY_ERROR', 'Checkpoint mutation acknowledgement is inconsistent');
+}
+function assertMutationAcknowledgement(mutation, runId) {
+    if (mutation.projection === null
+        || mutation.runId !== runId
+        || mutation.acceptedThrough !== mutation.projection.throughSequence
+        || mutation.profileHash !== mutation.projection.profileHash
+        || !sameTaskProfile(mutation.taskProfile, mutation.projection.taskProfile)) {
+        checkpointIntegrity();
+    }
+    try {
+        if (canonicalJson(mutation.preliminaryRecommendations)
+            !== canonicalJson(buildRecommendations({ projection: mutation.projection, broker: {} }))) {
+            checkpointIntegrity();
+        }
+    }
+    catch {
+        checkpointIntegrity();
+    }
+}
+export class AgentCheckpointUseCase {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    async execute(input) {
+        const catalog = requestCapabilityCatalog(input.body);
+        const initialRun = this.dependencies.service.readRun({ runId: input.runId });
+        assertActiveCheckpointRun(initialRun);
+        assertCapabilityCatalogBinding(initialRun.metadata, catalog);
+        const serviceRequest = withoutCapabilityCatalog(input.body);
+        // The ledger mutation is committed before any broker work starts.
+        const mutation = await this.dependencies.enqueueWrite(() => this.dependencies.checkpointMutation.checkpoint({
+            runId: input.runId,
+            idempotencyKey: input.idempotencyKey,
+            request: serviceRequest,
+        }));
+        if (this.dependencies.validateMutationAcknowledgement !== false) {
+            assertMutationAcknowledgement(mutation, input.runId);
+        }
+        const signals = checkpointSignals(serviceRequest);
+        const gated = await this.dependencies.broker.queryGated({
+            workspace: 'run-bound',
+            runId: input.runId,
+            characterBudget: mutation.characterBudget,
+            changedPaths: signals.changedPaths,
+            errorSignatures: signals.errorSignatures,
+        }, (candidate) => {
+            assertBrokerContextRun(candidate, input.runId);
+            const memoryUse = deriveBrokerMemoryUseSignal(this.dependencies, candidate);
+            const value = applyAgentCapabilityGateWithDeliveryObservation({
+                task: initialRun.title ?? '',
+                intakeStatus: brokerIntakeStatus(candidate.status),
+                taskProfile: candidate.taskProfile,
+                recommendedTags: candidate.recommendedTags,
+                catalog,
+                broker: candidate,
+                memoryUseOverride: memoryUse,
+            }, () => retrievableWorkspaceEntryCount(this.dependencies.database, initialRun.workspace));
+            return {
+                persist: value.context !== null || candidate.context === null,
+                value,
+                assertBeforePersist: () => {
+                    if (deriveBrokerMemoryUseSignal(this.dependencies, candidate) !== memoryUse) {
+                        throw new KiokukoError('CONFLICT', 'Memory capability decision changed before context persistence');
+                    }
+                },
+            };
+        }, brokerPersistence(this.dependencies));
+        const finalRun = this.dependencies.service.readRun({ runId: input.runId });
+        assertActiveCheckpointRun(finalRun);
+        if (finalRun.lastSequence !== gated.broker.acceptedThrough) {
+            throw new KiokukoError('CONFLICT', 'Agent run changed while checkpoint context was being prepared');
+        }
+        const intakeStatus = brokerIntakeStatus(gated.broker.status);
+        const projection = gated.broker.projection;
+        if (intakeStatus === 'needs_answer' || projection === null) {
+            throw new KiokukoError('INTEGRITY_ERROR', 'Checkpoint context is not bound to finalized intake');
+        }
+        const nudge = await this.dependencies.enqueueWrite(() => this.dependencies.nudgeDelivery.deliver({
+            runId: input.runId,
+            idempotencyKey: input.idempotencyKey,
+            throughSequence: gated.broker.acceptedThrough,
+            projection,
+            recommendations: gated.value.recommendations,
+        }));
+        const { preliminaryRecommendations: _preliminaryRecommendations, ...mutationResponse } = mutation;
+        return {
+            ...mutationResponse,
+            runStatus: finalRun.status,
+            intakeStatus,
+            taskProfile: { ...gated.broker.taskProfile, source: 'akinator+ledger-revisions' },
+            profileHash: gated.broker.profileHash,
+            projection,
+            ...gated.value,
+            nudge,
+            requestBindingHash: input.requestBindingHash,
+            untrusted: true,
+        };
+    }
+}
+export function checkpointSuccessResponse(value) {
+    return successEnvelope('agent.checkpoint', value);
+}
+//# sourceMappingURL=agent-checkpoint-use-case.js.map

package/dist/server/agent-checkpoint-use-case.js.map

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

package/dist/server/app.d.ts

@@ -0,0 +1,5 @@
+import type { RequestListener } from 'node:http';
+import { type RouterDependencies } from './router.js';
+export type AppDependencies = RouterDependencies;
+export declare function createApp(dependencies: AppDependencies): RequestListener;
+//# sourceMappingURL=app.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/server/app.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,eAAe,EAAE,MAAM,WAAW,CAAC;AAElE,OAAO,EAAkC,KAAK,kBAAkB,EAAuB,MAAM,aAAa,CAAC;AAE3G,MAAM,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAoFjD,wBAAgB,SAAS,CAAC,YAAY,EAAE,eAAe,GAAG,eAAe,CAQxE"}