bazis 0.96.1

package/core/agent/session/codec.ts

@@ -0,0 +1,33 @@
+import { canonicalBoundaryJsonV1 as libraryCanonicalBoundaryJsonV1, canonicalJsonHashV1, decodeBoundedJsonV1, normalizeBoundedJsonV1 } from "../../../library/boundary";
+import { AgentSessionError } from "./contracts";
+
+const MARKER = "bazis.agent-session/plaintext/v1";
+const VERSION = "bazis.agent-session/checkpoint/v1";
+export const MAX_CHECKPOINT_BYTES_V1 = 2 * 1024 * 1024;
+
+function fail(code: "AGENT_SESSION_INVALID_REQUEST" | "AGENT_SESSION_CHECKPOINT_CORRUPT" | "AGENT_SESSION_LIMIT_EXCEEDED"): never { throw new AgentSessionError(code); }
+function closed(value: unknown, keys: readonly string[]): Record<string, unknown> {
+  const normalized = normalizeBoundedJsonV1(value);
+  if (!normalized.ok || value === null || typeof value !== "object" || Array.isArray(value) || Object.keys(value as object).sort().join(",") !== [...keys].sort().join(",")) fail("AGENT_SESSION_CHECKPOINT_CORRUPT");
+  return normalized.value as Record<string, unknown>;
+}
+function decode(text: string): unknown { const decoded = decodeBoundedJsonV1(text); if (!decoded.ok) fail("AGENT_SESSION_CHECKPOINT_CORRUPT"); return decoded.value; }
+export function canonicalBoundaryJsonV1(value: unknown): string { try { return libraryCanonicalBoundaryJsonV1(value); } catch { return fail("AGENT_SESSION_INVALID_REQUEST"); } }
+export function sessionDigestV1(domain: string, value: unknown): string { try { return canonicalJsonHashV1(domain, value); } catch { return fail("AGENT_SESSION_INVALID_REQUEST"); } }
+export function sealedCheckpointEnvelopeV1(request: { readonly sessionId: string; readonly checkpointRevision: number; readonly bindingHash: string; readonly canonicalCheckpointJson: string }): string {
+  if (!/^[0-9a-f-]{36}$/i.test(request.sessionId) || !Number.isSafeInteger(request.checkpointRevision) || request.checkpointRevision < 0 || !/^(sha256:)?[0-9a-f]{64}$/.test(request.bindingHash)) fail("AGENT_SESSION_INVALID_REQUEST");
+  const checkpoint = decode(request.canonicalCheckpointJson);
+  // Raw JSON admission preserves duplicate-key evidence; only the exact output
+  // of the shared canonical serializer is accepted as a checkpoint boundary.
+  if (canonicalBoundaryJsonV1(checkpoint) !== request.canonicalCheckpointJson) fail("AGENT_SESSION_INVALID_REQUEST");
+  const envelope = { marker: MARKER, version: VERSION, sessionId: request.sessionId, checkpointRevision: request.checkpointRevision, bindingHash: request.bindingHash, checkpointDigest: sessionDigestV1(VERSION, checkpoint), checkpoint };
+  const result = canonicalBoundaryJsonV1(envelope);
+  if (Buffer.byteLength(result) > MAX_CHECKPOINT_BYTES_V1) fail("AGENT_SESSION_LIMIT_EXCEEDED");
+  return result;
+}
+export function openSealedCheckpointEnvelopeV1(text: string, expected: { readonly sessionId: string; readonly checkpointRevision: number; readonly bindingHash: string }): string {
+  if (Buffer.byteLength(text) > MAX_CHECKPOINT_BYTES_V1) fail("AGENT_SESSION_CHECKPOINT_CORRUPT");
+  const envelope = closed(decode(text), ["marker", "version", "sessionId", "checkpointRevision", "bindingHash", "checkpointDigest", "checkpoint"]);
+  if (envelope.marker !== MARKER || envelope.version !== VERSION || envelope.sessionId !== expected.sessionId || envelope.checkpointRevision !== expected.checkpointRevision || envelope.bindingHash !== expected.bindingHash || typeof envelope.checkpointDigest !== "string" || envelope.checkpointDigest !== sessionDigestV1(VERSION, envelope.checkpoint) || canonicalBoundaryJsonV1(envelope) !== text) fail("AGENT_SESSION_CHECKPOINT_CORRUPT");
+  return canonicalBoundaryJsonV1(envelope.checkpoint);
+}

package/core/agent/session/contracts.ts

@@ -0,0 +1,96 @@
+import type { Secret } from "../../kernel";
+import type { BazisModuleRef } from "../../di";
+import type { AgentToolExecutorOptions, AgentToolSchemaValidator } from "../AgentToolExecutor";
+import { normalizeJsonValue, type JsonObject, type JsonValue } from "../semantic";
+import { Validator } from "../../../library/validation";
+
+const UUID_V1_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export interface AgentSessionPrincipalV1 { readonly subject: string; readonly tenant?: string; }
+export interface AgentSessionCallContextV1 { readonly principal: AgentSessionPrincipalV1; readonly signal?: AbortSignal; }
+
+export class CreateAgentSessionRequestV1 {
+  @Validator({ required: true, pattern: UUID_V1_PATTERN })
+  sessionId!: string;
+  @Validator({ required: true, pattern: UUID_V1_PATTERN })
+  requestId!: string;
+  @Validator({ required: true, minLength: 1, maxLength: 128 })
+  agentName!: string;
+  @Validator({ minLength: 1, maxLength: 128 })
+  taskName?: string;
+  @Validator({
+    required: true,
+    // JsonValue deliberately includes null. Keep absence invalid while
+    // allowing that exact JSON literal through the existing Validator flow.
+    validateIf: (instance) => (instance as CreateAgentSessionRequestV1).input !== null,
+    custom: (value) => {
+      try {
+        normalizeJsonValue(value, "agentSession.input");
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  })
+  input!: JsonValue;
+  @Validator({ minLength: 1, maxLength: 128 })
+  modelProfile?: string;
+  @Validator({ min: 1, max: 64, integer: true })
+  maxSteps?: number;
+  @Validator({ min: 1, max: 64, integer: true })
+  maxToolCallsPerStep?: number;
+  @Validator({ min: 1, max: 900000, integer: true })
+  runTimeoutMs?: number;
+}
+export class RunAgentSessionRequestV1 {
+  @Validator({ required: true, pattern: UUID_V1_PATTERN }) sessionId!: string;
+  @Validator({ required: true, pattern: UUID_V1_PATTERN }) commandId!: string;
+}
+export class ReadAgentSessionRequestV1 { @Validator({ required: true, pattern: UUID_V1_PATTERN }) sessionId!: string; }
+export class StopAgentSessionRequestV1 { @Validator({ required: true, pattern: UUID_V1_PATTERN }) sessionId!: string; @Validator({ required: true, pattern: UUID_V1_PATTERN }) commandId!: string; }
+export class ResumeAgentSessionRequestV1 { @Validator({ required: true, pattern: UUID_V1_PATTERN }) sessionId!: string; @Validator({ required: true, pattern: UUID_V1_PATTERN }) commandId!: string; }
+export class ReadAgentSessionEventsRequestV1 { @Validator({ required: true, pattern: UUID_V1_PATTERN }) sessionId!: string; after?: AgentSessionCursorV1; @Validator({ min: 1, max: 500, integer: true }) limit?: number; }
+
+export type AgentSessionStateV1 = "created" | "running" | "stop-requested" | "stopped" | "completed" | "failed" | "outcome-unknown";
+export type AgentSessionCursorV1 = string;
+export interface AgentSessionOutcomeV1 { readonly status: "completed" | "failed" | "outcome-unknown"; readonly finalText?: string; readonly output?: JsonValue; readonly error?: { readonly code: string; readonly message: string }; }
+export interface AgentSessionViewV1 {
+  readonly version: 1; readonly sessionId: string; readonly invocationId: string; readonly agentName: string; readonly taskName?: string;
+  readonly tenant?: string; readonly state: AgentSessionStateV1; readonly revision: number; readonly steps: number; readonly stopRequested: boolean;
+  readonly resumeAllowed: boolean; readonly createdAt: string; readonly updatedAt: string; readonly outcome?: AgentSessionOutcomeV1;
+}
+export interface AgentSessionRunResultV1 { readonly session: AgentSessionViewV1; }
+export interface AgentSessionStopResultV1 { readonly disposition: "requested" | "already-stopped" | "already-terminal"; readonly session: AgentSessionViewV1; }
+export type AgentSessionEventKindV1 = "session-created" | "run-started" | "owner-reclaimed" | "model-dispatch-intent" | "model-result" | "tool-dispatch-intent" | "tool-result" | "stop-requested" | "stopped" | "completed" | "failed" | "outcome-unknown";
+export interface AgentSessionEventV1 { readonly version: 1; readonly eventId: string; readonly sessionId: string; readonly sequence: number; readonly kind: AgentSessionEventKindV1; readonly occurredAt: string; readonly projection: JsonObject; }
+export interface AgentSessionEventPageV1 { readonly items: readonly AgentSessionEventV1[]; readonly nextCursor: AgentSessionCursorV1; readonly hasMore: boolean; }
+
+export abstract class AgentSessions {
+  abstract create(request: CreateAgentSessionRequestV1, context: AgentSessionCallContextV1): Promise<AgentSessionViewV1>;
+  abstract run(request: RunAgentSessionRequestV1, context: AgentSessionCallContextV1): Promise<AgentSessionRunResultV1>;
+  abstract read(request: ReadAgentSessionRequestV1, context: AgentSessionCallContextV1): Promise<AgentSessionViewV1>;
+  abstract stop(request: StopAgentSessionRequestV1, context: AgentSessionCallContextV1): Promise<AgentSessionStopResultV1>;
+  abstract resume(request: ResumeAgentSessionRequestV1, context: AgentSessionCallContextV1): Promise<AgentSessionRunResultV1>;
+  abstract readEvents(request: ReadAgentSessionEventsRequestV1, context: AgentSessionCallContextV1): Promise<AgentSessionEventPageV1>;
+}
+
+export interface AgentSessionAuthorizationTargetV1 { readonly sessionId: string; readonly ownerSubject: string; readonly tenant?: string; readonly agentName: string; readonly taskName?: string; }
+export type AgentSessionAuthorizationRequestV1 =
+  | { readonly action: "create"; readonly principal: AgentSessionPrincipalV1; readonly candidate: AgentSessionAuthorizationTargetV1 }
+  | { readonly action: "run" | "read" | "read-events" | "stop" | "resume"; readonly principal: AgentSessionPrincipalV1; readonly session: AgentSessionAuthorizationTargetV1 & { readonly state: AgentSessionStateV1 } };
+export abstract class AgentSessionAuthorizationPolicyV1 { abstract authorize(request: AgentSessionAuthorizationRequestV1): Promise<boolean>; }
+
+export interface AgentSessionCheckpointProtectionConfigV1 { readonly activeKeyId: string; readonly readableKeyIds: readonly string[]; readonly keys: Readonly<Record<string, Secret>>; }
+export interface AgentSessionSealRequestV1 { readonly sessionId: string; readonly checkpointRevision: number; readonly bindingHash: string; readonly canonicalCheckpointJson: string; }
+export interface AgentSessionSealedCheckpointV1 { readonly envelopeVersion: "bazis.agent-session/sealed/v1"; readonly keyId: string; readonly ciphertext: string; }
+export interface AgentSessionOpenRequestV1 { readonly expectedSessionId: string; readonly expectedCheckpointRevision: number; readonly expectedBindingHash: string; readonly sealed: AgentSessionSealedCheckpointV1; }
+export abstract class AgentSessionCheckpointProtectorV1 { abstract seal(request: AgentSessionSealRequestV1): Promise<AgentSessionSealedCheckpointV1>; abstract open(request: AgentSessionOpenRequestV1): Promise<string>; }
+
+export interface AgentSessionModuleOptionsV1 {
+  readonly imports?: readonly BazisModuleRef[]; readonly agentModules: readonly BazisModuleRef[]; readonly implementationVersion: string;
+  readonly admission: { readonly bucket: string; readonly maxActiveRuns?: number };
+  readonly execution?: { readonly providerCallTimeoutMs?: number; readonly taskSchemaValidator?: AgentToolSchemaValidator; readonly toolExecutorOptions?: Pick<AgentToolExecutorOptions, "approvalPolicy" | "schemaValidator" | "auditSink" | "defaultTimeoutMs" | "scopeDisposeTimeoutMs" | "requiredPlatformHooks" | "hookRedaction">; };
+  readonly limits?: { readonly runTimeoutMs?: number; readonly maxSessionSteps?: number; readonly maxToolCallsPerStep?: number; readonly ownerLeaseMs?: number; readonly ownerHeartbeatMs?: number; readonly ownerStopGraceMs?: number; readonly authorizationTimeoutMs?: number; readonly checkpointProtectionTimeoutMs?: number; readonly databaseLockTimeoutMs?: number; readonly databaseStatementTimeoutMs?: number; readonly databaseWaitTimeoutMs?: number; readonly stopCheckIntervalMs?: number; readonly maxInputBytes?: number; readonly maxCheckpointBytes?: number; readonly maxJournalPayloadBytes?: number; readonly maxJournalEntries?: number; readonly reservedControlJournalEntries?: number; readonly defaultJournalPageSize?: number; readonly maxJournalPageSize?: number; };
+}
+export type AgentSessionErrorCodeV1 = `AGENT_SESSION_${"INVALID_REQUEST" | "FORBIDDEN" | "NOT_FOUND" | "CONFLICT" | "OWNER_ACTIVE" | "ADMISSION_UNAVAILABLE" | "NOT_RESUMABLE" | "DEADLINE_EXCEEDED" | "LIMIT_EXCEEDED" | "AMBIENT_TRANSACTION_FORBIDDEN" | "BINDING_MISMATCH" | "CHECKPOINT_UNAVAILABLE" | "CHECKPOINT_CORRUPT" | "OUTCOME_UNKNOWN" | "STORE_CORRUPT" | "STORE_UNAVAILABLE" | "AUTHORIZATION_UNAVAILABLE" | "HOST_STOPPING" | "UNSUPPORTED_VERSION" | "IDEMPOTENCY_CONFLICT" | "COMMIT_OUTCOME_UNKNOWN" | "CONFIG_MISMATCH"}`;
+export class AgentSessionError extends Error { constructor(readonly code: AgentSessionErrorCodeV1, readonly retryable = false) { super(code); this.name = "AgentSessionError"; } }

package/core/agent/session/entities.ts

@@ -0,0 +1,84 @@
+import { Column, DbContext, Entity, Index, Key } from "../../../library/orm";
+
+/** Immutable v1 schema. These tables are owned exclusively by AgentSessionDbContext. */
+@Entity({ table: "bazis_agent_sessions_v1" })
+@Index(["createKey"], { unique: true })
+@Index(["sessionId"], { unique: true })
+export class AgentSessionRowV1 {
+  @Key({ generated: false }) @Column({ type: "uuid" }) id = "";
+  @Column({ type: "uuid" }) sessionId = "";
+  @Column({ type: "uuid" }) invocationId = "";
+  @Column({ type: "text" }) createKey = "";
+  @Column({ type: "text" }) requestBinding = "";
+  @Column({ type: "text" }) ownerSubject = "";
+  @Column({ type: "text", nullable: true }) tenant?: string;
+  @Column({ type: "text" }) agentName = "";
+  @Column({ type: "text", nullable: true }) taskName?: string;
+  @Column({ type: "text" }) implementationVersion = "";
+  @Column({ type: "text" }) bindingHash = "";
+  @Column({ type: "text" }) state = "created";
+  @Column({ type: "integer" }) revision = 0;
+  @Column({ type: "integer" }) steps = 0;
+  @Column({ type: "boolean" }) stopRequested = false;
+  @Column({ type: "integer" }) checkpointRevision = 0;
+  @Column({ type: "text", nullable: true }) ownerId?: string;
+  @Column({ type: "integer" }) ownerEpoch = 0;
+  @Column({ type: "datetime", nullable: true }) ownerLeaseUntil?: Date;
+  @Column({ type: "text", nullable: true }) runCommandId?: string;
+  @Column({ type: "datetime", nullable: true }) runDeadline?: Date;
+  @Column({ type: "integer" }) nextSequence = 1;
+  @Column({ type: "integer", nullable: true }) pendingIntentSequence?: number;
+  @Column({ type: "boolean" }) admissionReserved = false;
+  @Column({ type: "datetime" }) createdAt = new Date();
+  @Column({ type: "datetime" }) updatedAt = new Date();
+}
+
+@Entity({ table: "bazis_agent_session_checkpoints_v1" })
+@Index(["sessionId", "checkpointRevision"], { unique: true })
+export class AgentSessionCheckpointRowV1 {
+  @Key({ generated: false }) @Column({ type: "uuid" }) id = "";
+  @Column({ type: "uuid" }) sessionId = "";
+  @Column({ type: "integer" }) checkpointRevision = 0;
+  @Column({ type: "text" }) bindingHash = "";
+  @Column({ type: "text" }) keyId = "";
+  @Column({ type: "text" }) ciphertext = "";
+  @Column({ type: "datetime" }) createdAt = new Date();
+}
+
+@Entity({ table: "bazis_agent_session_journal_v1" })
+@Index(["sessionId", "sequence"], { unique: true })
+@Index(["sessionId", "commandId"], { unique: false })
+export class AgentSessionJournalRowV1 {
+  @Key({ generated: false }) @Column({ type: "uuid" }) id = "";
+  @Column({ type: "uuid" }) eventId = "";
+  @Column({ type: "uuid" }) sessionId = "";
+  @Column({ type: "integer" }) sequence = 0;
+  @Column({ type: "integer" }) aggregateRevision = 0;
+  @Column({ type: "text" }) kind = "";
+  @Column({ type: "text", nullable: true }) commandId?: string;
+  @Column({ type: "text" }) projectionJson = "{}";
+  @Column({ type: "text", nullable: true }) binding?: string;
+  @Column({ type: "datetime" }) occurredAt = new Date();
+}
+
+@Entity({ table: "bazis_agent_session_admission_v1" })
+@Index(["bucket"], { unique: true })
+export class AgentSessionAdmissionRowV1 {
+  @Key({ generated: false }) @Column({ type: "uuid" }) id = "";
+  @Column({ type: "text" }) bucket = "";
+  @Column({ type: "text" }) configHash = "";
+  @Column({ type: "integer" }) maxActiveRuns = 8;
+  @Column({ type: "integer" }) activeReservations = 0;
+  @Column({ type: "datetime" }) updatedAt = new Date();
+}
+
+export class AgentSessionDbContext extends DbContext {
+  readonly sessions = this.set(AgentSessionRowV1);
+  readonly checkpoints = this.set(AgentSessionCheckpointRowV1);
+  readonly journal = this.set(AgentSessionJournalRowV1);
+  readonly admission = this.set(AgentSessionAdmissionRowV1);
+}
+
+export const AGENT_SESSION_ENTITIES_V1 = Object.freeze([
+  AgentSessionRowV1, AgentSessionCheckpointRowV1, AgentSessionJournalRowV1, AgentSessionAdmissionRowV1,
+] as const);

package/core/agent/session/protector.ts

@@ -0,0 +1,92 @@
+import { createToken } from "../../di";
+import { reader, type InfraConnector } from "../../infra";
+import { type AppConfig, type ConfigRegistry, Secret } from "../../kernel";
+import { ValueConverters, type ValueConverter } from "../../../library/orm";
+import { types as nodeUtilTypes } from "node:util";
+import { AgentSessionError, type AgentSessionCheckpointProtectionConfigV1, type AgentSessionCheckpointProtectorV1, type AgentSessionOpenRequestV1, type AgentSessionSealRequestV1, type AgentSessionSealedCheckpointV1 } from "./contracts";
+import { openSealedCheckpointEnvelopeV1, sealedCheckpointEnvelopeV1 } from "./codec";
+import { identifyConnector } from "../../infra/connectorIdentity";
+
+export const AGENT_SESSION_CHECKPOINT_PROTECTOR = createToken<AgentSessionCheckpointProtectorV1>("AgentSessionCheckpointProtectorV1");
+
+function closedDataRecord(value: unknown, keys: readonly string[]): Record<string, unknown> | undefined {
+  if (typeof value !== "object" || value === null || nodeUtilTypes.isProxy(value)) return undefined;
+  if (Object.getPrototypeOf(value) !== Object.prototype) return undefined;
+  const ownKeys = Reflect.ownKeys(value);
+  if (ownKeys.length !== keys.length || ownKeys.some((key) => typeof key !== "string" || !keys.includes(key))) return undefined;
+  const result: Record<string, unknown> = Object.create(null);
+  for (const key of keys) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || !descriptor.enumerable || !("value" in descriptor)) return undefined;
+    result[key] = descriptor.value;
+  }
+  return result;
+}
+
+function closedStringArray(value: unknown): readonly string[] | undefined {
+  if (!Array.isArray(value) || nodeUtilTypes.isProxy(value)) return undefined;
+  if (Reflect.ownKeys(value).some((key) => key !== "length" && (typeof key !== "string" || !/^(0|[1-9][0-9]*)$/.test(key)))) return undefined;
+  const result: string[] = [];
+  for (let index = 0; index < value.length; index += 1) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+    if (!descriptor || !descriptor.enumerable || !("value" in descriptor) || typeof descriptor.value !== "string") return undefined;
+    result.push(descriptor.value);
+  }
+  return result;
+}
+
+function snapshot(config: AppConfig<AgentSessionCheckpointProtectionConfigV1>) {
+  const values = reader(config); const activeKeyId = values.get("activeKeyId"); const readableKeyIds = values.get("readableKeyIds"); const keys = values.get("keys");
+  const readable = closedStringArray(readableKeyIds);
+  if (typeof activeKeyId !== "string" || !activeKeyId || !readable || !keys || typeof keys !== "object" || nodeUtilTypes.isProxy(keys)) throw new AgentSessionError("AGENT_SESSION_CHECKPOINT_UNAVAILABLE");
+  const keyRecord = keys as object;
+  if (Object.getPrototypeOf(keyRecord) !== Object.prototype || Reflect.ownKeys(keyRecord).some((key) => typeof key !== "string" || key === "__proto__" || key === "prototype" || key === "constructor")) throw new AgentSessionError("AGENT_SESSION_CHECKPOINT_UNAVAILABLE");
+  for (const key of Reflect.ownKeys(keyRecord)) {
+    const descriptor = Object.getOwnPropertyDescriptor(keyRecord, key as string);
+    if (!descriptor || !descriptor.enumerable || descriptor.get || descriptor.set || !(descriptor.value instanceof Secret)) throw new AgentSessionError("AGENT_SESSION_CHECKPOINT_UNAVAILABLE");
+  }
+  const converters = new Map<string, ValueConverter<string, string>>();
+  for (const id of readable) {
+    if (typeof id !== "string" || !id || converters.has(id)) throw new AgentSessionError("AGENT_SESSION_CHECKPOINT_UNAVAILABLE");
+    const descriptor = Object.getOwnPropertyDescriptor(keyRecord, id);
+    if (!descriptor || descriptor.get || descriptor.set || !(descriptor.value instanceof Secret)) throw new AgentSessionError("AGENT_SESSION_CHECKPOINT_UNAVAILABLE");
+    const secret = descriptor.value.reveal();
+    if (!secret) throw new AgentSessionError("AGENT_SESSION_CHECKPOINT_UNAVAILABLE");
+    converters.set(id, ValueConverters.encrypted(secret));
+  }
+  if (!converters.has(activeKeyId)) throw new AgentSessionError("AGENT_SESSION_CHECKPOINT_UNAVAILABLE");
+  return Object.freeze({ activeKeyId, readable: new Set(converters.keys()), converters });
+}
+class CheckpointProtector implements AgentSessionCheckpointProtectorV1 {
+  constructor(private readonly keys: ReturnType<typeof snapshot>) {}
+  async seal(request: AgentSessionSealRequestV1): Promise<AgentSessionSealedCheckpointV1> {
+    const input = closedDataRecord(request, ["sessionId", "checkpointRevision", "bindingHash", "canonicalCheckpointJson"]);
+    if (!input || typeof input.sessionId !== "string" || typeof input.checkpointRevision !== "number" || typeof input.bindingHash !== "string" || typeof input.canonicalCheckpointJson !== "string") throw new AgentSessionError("AGENT_SESSION_INVALID_REQUEST");
+    const converter = this.keys.converters.get(this.keys.activeKeyId);
+    if (!converter) throw new AgentSessionError("AGENT_SESSION_CHECKPOINT_UNAVAILABLE");
+    const sealRequest: AgentSessionSealRequestV1 = {
+      sessionId: input.sessionId,
+      checkpointRevision: input.checkpointRevision,
+      bindingHash: input.bindingHash,
+      canonicalCheckpointJson: input.canonicalCheckpointJson,
+    };
+    return Object.freeze({ envelopeVersion: "bazis.agent-session/sealed/v1", keyId: this.keys.activeKeyId, ciphertext: converter.toProvider(sealedCheckpointEnvelopeV1(sealRequest)) });
+  }
+  async open(request: AgentSessionOpenRequestV1): Promise<string> {
+    const input = closedDataRecord(request, ["expectedSessionId", "expectedCheckpointRevision", "expectedBindingHash", "sealed"]);
+    const sealed = input === undefined ? undefined : closedDataRecord(input.sealed, ["envelopeVersion", "keyId", "ciphertext"]);
+    if (!input || !sealed || typeof input.expectedSessionId !== "string" || typeof input.expectedCheckpointRevision !== "number" || typeof input.expectedBindingHash !== "string" || sealed.envelopeVersion !== "bazis.agent-session/sealed/v1" || typeof sealed.keyId !== "string" || typeof sealed.ciphertext !== "string" || !this.keys.readable.has(sealed.keyId)) throw new AgentSessionError("AGENT_SESSION_CHECKPOINT_UNAVAILABLE");
+    const converter = this.keys.converters.get(sealed.keyId);
+    if (!converter) throw new AgentSessionError("AGENT_SESSION_CHECKPOINT_UNAVAILABLE");
+    try { return openSealedCheckpointEnvelopeV1(converter.fromProvider(sealed.ciphertext), { sessionId: input.expectedSessionId, checkpointRevision: input.expectedCheckpointRevision, bindingHash: input.expectedBindingHash }); } catch (error) { if (error instanceof AgentSessionError) throw error; throw new AgentSessionError("AGENT_SESSION_CHECKPOINT_CORRUPT"); }
+  }
+}
+export function agentSessionCheckpointProtection(config: AppConfig<AgentSessionCheckpointProtectionConfigV1>): InfraConnector<AgentSessionCheckpointProtectorV1> {
+  return identifyConnector(Object.freeze({
+    token: AGENT_SESSION_CHECKPOINT_PROTECTOR,
+    config,
+    create: (configs?: ConfigRegistry) => new CheckpointProtector(snapshot(configs?.get(config) ?? config)),
+    connect: () => undefined,
+    dispose: () => undefined,
+  }), "agent-session-checkpoint-protection");
+}

package/core/app/index.ts

@@ -0,0 +1,5 @@
+// Composition layer: the single application entry point. Depends on the kernel, HTTP, gRPC and
+// the validation library (it is the composition root, so it may use everything), hiding
+// infrastructure wiring from application code.
+export { runApp, type RunAppOptions } from "./runApp";
+export * from "./ui";

package/core/app/runApp.ts

@@ -0,0 +1,293 @@
+import {
+  collectModuleUiProfiles,
+  collectModuleControllers,
+  DI,
+  Global,
+  Module,
+  singletonValue,
+  type BazisModuleRef,
+} from "../di";
+import { loadBazisGeneratedRuntime } from "../generatedRuntime";
+import { httpModule, useModelValidator, type HttpModuleOptions, type ModelValidator } from "../http";
+import { grpcModule, type GrpcModuleOptions } from "../grpc";
+import { buildHttpOpenApiDocument } from "../http/OpenApi/openApiDocument";
+import { KernelBuilder, Bazis, type KernelOptions, type ValidatableConfig } from "../kernel";
+import {
+  isUiProfileAuthoringClass,
+  type UiProfileV1,
+} from "../../library/ui";
+import { modelValidatorAdapter } from "../../library/validation";
+import {
+  type RunAppUiOptions,
+  type RunAppUiSurfaceOptions,
+  type UiSurfaceHostingOptions,
+} from "./ui/uiSurfaceHosting";
+import { resolveUiProfileAuthoringV1, UiProfileV1Registry, type UiLabels } from "./ui/uiProfileResolver";
+import { UiSurfaceDocumentProvider, UiSurfaceHttpController } from "./ui/uiSurfaceHttp";
+
+/**
+ * Application start options. Everything is optional: without `http` and `grpc` the app
+ * starts as a worker/CLI (kernel and hosted services only).
+ */
+export interface RunAppOptions {
+  /**
+   * Start the HTTP server. Controllers are collected from the whole module tree
+   * automatically, no need to list them. Pass `{}` for the defaults
+   * (port 3000) or an object with settings (port/prefix/cors/...).
+   */
+  readonly http?: HttpModuleOptions;
+  /** gRPC server; discovers feature-module grpcControllers, independently of HTTP. */
+  readonly grpc?: GrpcModuleOptions;
+  /** Kernel options (environment, shutdown timeout, signals, ...). */
+  readonly kernel?: KernelOptions;
+  /**
+   * Request-model validator. The `@/library/validation` engine is used by
+   * default. Pass your own to replace it.
+   */
+  readonly validator?: ModelValidator;
+  /** Fine-tuning of the kernel builder (logger, config sources, ...). */
+  readonly configure?: (builder: KernelBuilder) => void;
+  /**
+   * Additional declarative configs (`defineConfig`) that do not belong to a
+   * specific module. Usually configs live next to their owner: `@Infra` brings
+   * connector configs, and a feature module brings its own `config`.
+   * Every config is checked at startup (fail-fast): missing secrets and
+   * invalid values stop the start immediately.
+   */
+  readonly config?: ValidatableConfig | readonly ValidatableConfig[];
+  /**
+   * Infrastructure manifest: a class with `@Infra` (or the result of `infraModule(...)`).
+   * It is a global module with connectors (DB/cache/search): clients are registered under
+   * their tokens, connections open before the servers and close after them.
+   *
+   * ```ts
+   * await runApp(AppModule, { infra: AppInfra, http: { port: 3000 } });
+   * ```
+   */
+  readonly infra?: BazisModuleRef;
+  /**
+   * Application cache as a self-installing value. Pass `memory({ ... })` for
+   * an in-memory cache. The distributed Redis backend is enabled separately via
+   * `infra: AppInfra` (`redisConnect(redisConfig, { cache: "distributed" })`).
+   * Registers `ICache`, enables `@OutputCache`/`@Cacheable` and a health check.
+   *
+   * ```ts
+   * import { memory } from "@/core/cache";
+   * await runApp(AppModule, { cache: memory({ maxEntries: 1000 }), http: {} });
+   * ```
+   */
+  readonly cache?: BazisModuleRef;
+  /**
+   * Declarative UI surface hosting. Feature modules contribute reference-based
+   * `@UiProfile` declarations through module `uiProfiles` metadata. Explicit
+   * surfaces expose protected `/ui/:surface`, `/openapi` and `/session`
+   * endpoints. Every published surface must provide authorization, a monotonic
+   * policy projection and a safe session mapper.
+   */
+  readonly ui?: RunAppUiOptions;
+}
+
+function withUiRuntime(
+  root: BazisModuleRef,
+  option: RunAppOptions["ui"],
+  http: HttpModuleOptions | undefined,
+): BazisModuleRef {
+  const declarations = collectModuleUiProfiles([root]);
+  const openApi = http === undefined ? undefined : buildUiOpenApiDocument(root, http);
+  const profiles = resolveUiProfiles(root, declarations, http, openApi, option?.labels);
+  const profileRegistry = new UiProfileV1Registry(profiles, openApi);
+  const httpOptions = http === undefined ? undefined : normalizeUiSurfaceHostingOptions(option, http);
+  if (httpOptions === undefined || openApi === undefined) {
+    return root;
+  }
+  const surfaceDocuments = new UiSurfaceDocumentProvider(httpOptions, profileRegistry, openApi);
+
+  @Global()
+  @Module({
+    providers: [singletonValue(UiSurfaceDocumentProvider, surfaceDocuments)],
+    exports: [UiSurfaceDocumentProvider],
+  })
+  class BazisUiModule {}
+
+  @Module({
+    imports: [BazisUiModule],
+    controllers: [
+      DI.bindDeps(UiSurfaceHttpController, UiSurfaceDocumentProvider),
+    ],
+  })
+  class BazisUiHttpModule {}
+
+  return { imports: [BazisUiModule, BazisUiHttpModule, root] };
+}
+
+/** @internal Resolves module-owned `@UiProfile` declarations before DI wiring. */
+export function resolveUiProfiles(
+  root: BazisModuleRef,
+  declarations: readonly unknown[],
+  http: HttpModuleOptions | undefined,
+  prebuiltOpenApi?: ReturnType<typeof buildHttpOpenApiDocument>,
+  labels?: UiLabels,
+): readonly UiProfileV1[] {
+  const authoring: object[] = [];
+  for (const declaration of declarations) {
+    if (isUiProfileAuthoringClass(declaration)) {
+      authoring.push(declaration);
+      continue;
+    }
+    throw new TypeError(
+      `uiProfiles declaration ${declarationName(declaration)} must use @UiProfile().`,
+    );
+  }
+  if (authoring.length === 0) {
+    return [];
+  }
+
+  const openApi = prebuiltOpenApi ?? buildUiOpenApiDocument(root, http ?? {});
+  const profiles: UiProfileV1[] = [];
+  for (const declaration of authoring) {
+    const result = resolveUiProfileAuthoringV1({ declaration, openApi, labels });
+    if (!result.ok) {
+      const details = result.diagnostics
+        .map((diagnostic) => `${diagnostic.code}: ${diagnostic.message}`)
+        .join("\n");
+      throw new TypeError(`@UiProfile resolution failed:\n${details}`);
+    }
+    profiles.push(...result.profiles);
+  }
+  return Object.freeze(profiles);
+}
+
+function buildUiOpenApiDocument(
+  root: BazisModuleRef,
+  http: HttpModuleOptions,
+): ReturnType<typeof buildHttpOpenApiDocument> {
+  const docs = typeof http.docs === "object" && http.docs !== null ? http.docs : undefined;
+  return buildHttpOpenApiDocument({
+    controllers: collectModuleControllers([root]),
+    globalPrefix: http.prefix,
+    versioning: http.versioning,
+    title: docs?.title ?? "Bazis UI profiles",
+    version: docs?.version ?? "1.0.0",
+  });
+}
+
+function declarationName(value: unknown): string {
+  if (typeof value === "function") {
+    return value.name || "<anonymous>";
+  }
+  if (value === null) {
+    return "null";
+  }
+  return typeof value;
+}
+
+/** @internal Exported for hosting contract tests. */
+export function normalizeUiSurfaceHostingOptions(
+  option: RunAppOptions["ui"],
+  http: HttpModuleOptions,
+): UiSurfaceHostingOptions | undefined {
+  if (option === undefined) {
+    return undefined;
+  }
+  requirePublishedSurfaces(option.surfaces);
+  return {
+    app: {
+      name: option.app?.name ?? "Bazis",
+      version: option.app?.version ?? "1.0.0",
+    },
+    ...uiSurfaceHostingPaths(http),
+    surfaces: option.surfaces,
+  };
+}
+
+function requirePublishedSurfaces(surfaces: readonly RunAppUiSurfaceOptions[]): void {
+  if (surfaces.length === 0) {
+    throw new TypeError("UI hosting requires at least one explicitly registered surface.");
+  }
+}
+
+function uiSurfaceHostingPaths(http: HttpModuleOptions): Pick<UiSurfaceHostingOptions, "apiBasePath"> {
+  const prefix = http.prefix?.trim() ?? "";
+  return {
+    apiBasePath: prefix.length === 0 ? "/" : normalizeAbsolutePath(prefix),
+  };
+}
+
+function normalizeAbsolutePath(path: string): string {
+  const trimmed = path.trim();
+  const prefixed = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  return `/${prefixed.split("/").filter((part) => part.length > 0).join("/")}`;
+}
+
+/**
+ * The single application entry point, simpler than `NestFactory`.
+ *
+ * ```ts
+ * // main.ts
+ * import { runApp } from "@/core/app";
+ * import { AppModule } from "./modules/App.module";
+ *
+ * await runApp(AppModule, { http: { port: 3000, prefix: "api" } });
+ * ```
+ *
+ * It does three things you would otherwise write by hand:
+ * 1. starts the HTTP server and collects controllers from the whole module tree;
+ * 2. plugs in the request body validator (DIP glue between the kernel and the library);
+ * 3. starts the kernel with graceful shutdown on SIGINT/SIGTERM.
+ *
+ * The root module stays clean: `@Module({ imports: [UsersModule] })`.
+ */
+export async function runApp(root: BazisModuleRef, options: RunAppOptions = {}): Promise<number> {
+  const configure = options.configure;
+  await loadBazisGeneratedRuntime();
+
+  // Infrastructure and cache are global modules; add them to the graph next to the feature root.
+  const globals: BazisModuleRef[] = [];
+  if (options.infra !== undefined) {
+    globals.push(options.infra);
+  }
+  if (options.cache !== undefined) {
+    globals.push(options.cache);
+  }
+  const appRoot: BazisModuleRef =
+    globals.length > 0 || options.config !== undefined
+      ? {
+          imports: [...globals, root],
+          ...(options.config !== undefined ? { config: options.config } : {}),
+        }
+      : root;
+
+  if (options.http !== undefined) {
+    // Validation is glued in the composition root (the HTTP kernel only knows
+    // the `ModelValidator` port; the validation engine is a library).
+    const validator = options.validator ?? modelValidatorAdapter;
+    // Keep the legacy bridge for direct bindModel() callers, while also
+    // passing an instance-owned validator to the HTTP server. Capturing it per
+    // server prevents another app in the same process from changing validation
+    // behavior after startup.
+    useModelValidator(validator);
+
+    const httpAppRoot = withUiRuntime(
+      { imports: [appRoot, ...(options.http.imports ?? [])] },
+      options.ui,
+      options.http,
+    );
+    const httpRoot = httpModule({
+      ...options.http,
+      validator,
+      imports: [httpAppRoot],
+    });
+    const runtimeRoot = options.grpc === undefined ? httpRoot : {
+      imports: [httpRoot, grpcModule({ ...options.grpc, validator: options.grpc.validator === undefined ? validator : options.grpc.validator, imports: [appRoot, ...(options.grpc.imports ?? [])] })],
+    };
+    return Bazis.run(runtimeRoot, options.kernel, configure);
+  }
+
+  if (options.validator) {
+    useModelValidator(options.validator);
+  }
+  const runtimeRoot = withUiRuntime(appRoot, options.ui, undefined);
+  const transportRoot = options.grpc === undefined ? runtimeRoot
+    : grpcModule({ ...options.grpc, validator: options.grpc.validator === undefined ? options.validator ?? modelValidatorAdapter : options.grpc.validator, imports: [runtimeRoot, ...(options.grpc.imports ?? [])] });
+  return Bazis.run(transportRoot, options.kernel, configure);
+}

package/core/app/ui/index.ts

@@ -0,0 +1,29 @@
+export {
+  EN_UI_LABELS,
+  resolveUiProfileAuthoringV1,
+  RU_UI_LABELS,
+  type ResolveUiProfileAuthoringV1Options,
+  type UiLabels,
+  type ResolveUiProfileAuthoringV1Result,
+} from "./uiProfileResolver";
+export type {
+  RunAppUiAppInfo,
+  RunAppUiOptions,
+  RunAppUiSurfaceOptions,
+} from "./uiSurfaceHosting";
+export {
+  UI_SURFACE_SESSION_V1_API_VERSION,
+  UI_SURFACE_SESSION_V1_KIND,
+  UiSurfaceDocumentProvider,
+} from "./uiSurfaceHttp";
+export type {
+  UiSurfaceOperationRole,
+  UiSurfacePolicyDecision,
+  UiSurfacePolicyInput,
+  UiSurfacePolicyPageInput,
+  UiSurfacePolicyResourceInput,
+  UiSurfacePageDecision,
+  UiSurfaceResourceDecision,
+  UiSurfaceSessionUser,
+  UiSurfaceSessionV1,
+} from "./uiSurfaceHttp";