bazis 0.96.1

package/index.ts

@@ -0,0 +1,281 @@
+/**
+ * Bazis framework — public API (barrel).
+ *
+ * The common path is intentionally flat:
+ *
+ * ```ts
+ * import { Module, Controller, Get, runApp } from "bazis";
+ * ```
+ *
+ * Namespaced re-exports stay available when grouping reads better:
+ *
+ * ```ts
+ * import { di, http } from "bazis";
+ * ```
+ *
+ * Subpath imports remain available for granular usage:
+ *
+ * ```ts
+ * import { createContainer } from "bazis/core/di";
+ * ```
+ */
+export * as app from "./core/app";
+export * as agent from "./core/agent";
+export * as background from "./core/background";
+export * as cache from "./core/cache";
+export * as di from "./core/di";
+export * as http from "./core/http";
+export * as grpc from "./core/grpc";
+export * as httpClient from "./core/http-client";
+export * as infra from "./core/infra";
+export * as kernel from "./core/kernel";
+export * as orm from "./core/orm";
+export * as websocket from "./core/websocket";
+export * as jsonapi from "./library/jsonapi";
+export * as jwt from "./library/jwt";
+export * as openapi from "./library/openapi";
+export * as redaction from "./library/redaction";
+export * as ui from "./library/ui";
+export * as validation from "./library/validation";
+
+// Golden-path application API.
+export {
+  GrpcController, GrpcMethod, GrpcError, GrpcStatus, grpcModule, grpcService, loadGrpcPackage,
+  GrpcClient, grpcClientProvider,
+  type GrpcClientOptions, type GrpcClientTlsOptions, type GrpcCallOptions, type GrpcResponse, type GrpcResponseStream,
+  type GrpcContext, type GrpcModuleOptions,
+} from "./core/grpc";
+export {
+  runApp,
+  type RunAppOptions,
+  type RunAppUiAppInfo,
+  type RunAppUiOptions,
+  type RunAppUiSurfaceOptions,
+  type UiSurfacePolicyDecision,
+  type UiSurfacePolicyInput,
+  type UiSurfacePolicyPageInput,
+  type UiSurfacePageDecision,
+  type UiSurfaceResourceDecision,
+  type UiSurfaceSessionUser,
+  type UiSurfaceSessionV1,
+} from "./core/app";
+export {
+  Global,
+  Module,
+  collectModuleUiProfiles,
+  createContainer,
+  createToken,
+  scoped,
+  singleton,
+  singletonFactory,
+  singletonFactoryWithResolver,
+  singletonValue,
+  transient,
+  type ModuleConfig,
+  type BazisModule,
+  type BazisModuleMetadata,
+  type BazisModuleRef,
+} from "./core/di";
+export {
+  AGENT_MODEL_PROVIDER,
+  Agent,
+  AgentRegistry,
+  AgentRuntime,
+  AgentRuntimeError,
+  AgentSemanticError,
+  AgentToolExecutionError,
+  AgentToolExecutor,
+  ApproximateAgentContextTokenEstimator,
+  DefaultAgentContextBuilder,
+  Prompt,
+  Task,
+  Tool,
+  agentClassSchema,
+  agentData,
+  agentTaskMetadataOf,
+  agentInvocation,
+  agentJsonSchema,
+  agentMessage,
+  agentModelCapabilities,
+  agentModelRequest,
+  agentModelResponse,
+  agentOutput,
+  agentOutputContract,
+  agentText,
+  agentToolCall,
+  agentToolContract,
+  agentToolResult,
+  collectAgentCatalog,
+  type AgentCatalog,
+  type AgentCatalogExtras,
+  type AgentContext,
+  type AgentContextBuildInput,
+  type AgentContextBuilder,
+  type AgentContextLimits,
+  type AgentContextTokenEstimator,
+  type AgentContextTraceEntry,
+  type AgentDefinition,
+  type AgentInvocation,
+  type AgentMessage,
+  type AgentMetadataIndex,
+  type AgentTaskDefinition,
+  type AgentTaskMetadata,
+  type AgentTaskOptions,
+  type TaskDecoratorOptions,
+  type AgentModelCapabilities,
+  type AgentModelRequest,
+  type AgentModelResponse,
+  type AgentOptions,
+  type AgentOutputContract,
+  type AgentRuntimeInvokeOptions,
+  type AgentRuntimeOptions,
+  type AgentRuntimeResult,
+  type AgentRuntimeStatus,
+  type AgentRuntimeTaskInvokeOptions,
+  type AgentRuntimeToolExecutionOptions,
+  type AgentToolCall,
+  type AgentExecutableTool,
+  type AgentToolAuditEntry,
+  type AgentToolAuditFailureMode,
+  type AgentToolAuditFunction,
+  type AgentToolAuditPhase,
+  type AgentToolAuditSink,
+  type AgentToolAuditSinkObject,
+  type AgentToolAuditToolInfo,
+  type AgentToolApprovalPolicy,
+  type AgentToolApprovalRequest,
+  type AgentToolExecutionContext,
+  type AgentToolExecutionOptions,
+  type AgentToolExecutorOptions,
+  type AgentToolRetryBackoff,
+  type AgentToolRetryPolicy,
+  type AgentToolSchemaValidator,
+  type AgentToolValidationIssue,
+  type AgentToolValidationResult,
+  type AgentToolHookKindV1,
+  type AgentToolHookRefV1,
+  type AgentToolRequiredHookRefV1,
+  type AgentToolHookRegistrationBaseV1,
+  type AgentToolHookRegistrationV1,
+  type AgentToolHookContextV1,
+  type AgentToolCallProjectionV1,
+  type AgentToolDescriptorProjectionV1,
+  type AgentToolBeforeEffectEventV1,
+  type AgentToolEnforcementDecisionV1,
+  type AgentToolEnforcementHookV1,
+  type AgentToolTerminalProjectionV1,
+  type AgentToolSettlementEventV1,
+  type AgentToolSettlementResultV1,
+  type AgentToolSettlementHookV1,
+  type AgentToolObserverEventV1,
+  type AgentToolObserverHookV1,
+  type AgentToolAuditHookProjectionV1,
+  type AgentToolContract,
+  type AgentToolResult,
+  type AgentModelProvider,
+  type AgentModelProviderContext,
+  type JsonValue,
+  type PromptOptions,
+  type PromptSectionKind,
+  type PromptSectionMetadata,
+  type PromptSectionOptions,
+  type ToolOptions,
+} from "./core/agent";
+export {
+  AllowAnonymous,
+  Authorize,
+  BadRequest,
+  Conflict,
+  Controller,
+  Created,
+  Delete,
+  Forbidden,
+  Get,
+  HttpContext,
+  InternalServerError,
+  NoContent,
+  NotFound,
+  Ok,
+  Post,
+  Put,
+  RequestModel,
+  Unauthorized,
+} from "./core/http";
+export {
+  Cacheable,
+  OutputCache,
+  cachedScoped,
+  cachedSingleton,
+  memory,
+} from "./core/cache";
+export {
+  Column,
+  Check,
+  DbContext,
+  Entity,
+  Index,
+  Key,
+  Schema,
+  UUID,
+  ormBazisConnect,
+  ormModule,
+  postgres,
+  repositoryFor,
+  type IRepository,
+} from "./core/orm";
+export { defineConfig, secret, type Secret } from "./core/kernel";
+export {
+  Infra,
+  infraModule,
+  llmConnect,
+  llmProfile,
+  llmRouter,
+  LlmModelRouter,
+  LlmModelRouterError,
+  openAiCompatibleAdapter,
+  OpenAiCompatibleModelProvider,
+  OpenAiCompatibleProviderError,
+  redisConnect,
+  openSearchConnect,
+  type LlmConfigShape,
+  type LlmConnectionOptions,
+  type LlmConnectorOptions,
+  type LlmModelProfile,
+  type LlmModelProfileOptions,
+  type LlmProviderAdapter,
+  type LlmRouterOptions,
+  type OpenAiCompatibleAdapterOptions,
+  type OpenAiCompatibleFetch,
+} from "./core/infra";
+export { Validator } from "./library/validation";
+export {
+  COMPILED_UI_SURFACE_V1_API_VERSION,
+  COMPILED_UI_SURFACE_V1_KIND,
+  UI_PROFILE_V1_API_VERSION,
+  UI_PROFILE_V1_KIND,
+  UiProfile,
+  canonicalUiJson,
+  compileUiSurfaceV1,
+  defineUiProfile,
+  normalizeUiJsonObject,
+  normalizeUiJsonValue,
+  uiOperation,
+  uiEndpoint,
+  uiProfileAuthoringMetadataOf,
+  uiDocumentRevision,
+  type CompiledUiSurfaceV1,
+  type CompiledUiCustomPageV1,
+  type CompiledUiFeaturePageV1,
+  type CompileUiSurfaceV1Options,
+  type CompileUiSurfaceV1Result,
+  type UiDiagnosticV1,
+  type UiJsonObject,
+  type UiJsonValue,
+  type UiProfileV1,
+  type UiProfileAuthoringMetadata,
+  type UiProfileAuthoringOptions,
+  type UiCustomPagesProfileAuthoringOptions,
+  type UiFeaturePageAuthoring,
+  type UiFeaturePageProfileV1,
+  type UiEndpointReference,
+} from "./library/ui";

package/library/boundary/diagnostics-v1.ts

@@ -0,0 +1,136 @@
+import type { BoundaryJsonValue } from "./json/types-v1";
+
+export type BazisDiagnosticSeverityV1 = "error" | "warning" | "info";
+export type BazisDiagnosticStageV1 = "decode" | "schema" | "semantic" | "compile" | "bind";
+
+export interface BazisDiagnosticSourceV1 {
+  readonly byteOffset: number;
+  readonly line: number;
+  readonly column: number;
+}
+
+export interface BazisDiagnosticRepairV1 {
+  readonly action: "add" | "remove" | "replace";
+  readonly pointer: string;
+  readonly value?: BoundaryJsonValue;
+}
+
+export interface BazisDiagnosticV1 {
+  readonly severity: BazisDiagnosticSeverityV1;
+  readonly stage: BazisDiagnosticStageV1;
+  readonly code: string;
+  readonly message: string;
+  readonly pointer: string;
+  readonly nodeId?: string;
+  readonly flowId?: string;
+  readonly source?: BazisDiagnosticSourceV1;
+  readonly repair?: BazisDiagnosticRepairV1;
+}
+
+export interface BazisDiagnosticsV1 {
+  readonly diagnostics: readonly BazisDiagnosticV1[];
+  readonly truncated: boolean;
+}
+
+export const BAZIS_DIAGNOSTIC_LIMIT_V1 = 100;
+const DIAGNOSTIC_MESSAGE_BYTES_V1 = 512;
+const DIAGNOSTIC_POINTER_BYTES_V1 = 2_048;
+const UTF8 = new TextEncoder();
+
+const SEVERITY_ORDER: Readonly<Record<BazisDiagnosticSeverityV1, number>> = {
+  error: 0,
+  warning: 1,
+  info: 2,
+};
+
+export function bazisDiagnosticV1(
+  diagnostic: BazisDiagnosticV1,
+): BazisDiagnosticV1 {
+  if (!/^[A-Z][A-Z0-9_]{0,127}$/.test(diagnostic.code)) {
+    throw new TypeError("Diagnostic code must be a stable uppercase ASCII identifier.");
+  }
+  return Object.freeze({
+    ...diagnostic,
+    message: truncateUtf8(diagnostic.message, DIAGNOSTIC_MESSAGE_BYTES_V1),
+    pointer: boundedPointer(diagnostic.pointer),
+    source: diagnostic.source === undefined ? undefined : Object.freeze({ ...diagnostic.source }),
+    repair: diagnostic.repair === undefined ? undefined : Object.freeze({
+      ...diagnostic.repair,
+      pointer: boundedPointer(diagnostic.repair.pointer),
+    }),
+  });
+}
+
+export function finalizeBazisDiagnosticsV1(
+  diagnostics: readonly BazisDiagnosticV1[],
+  limit = BAZIS_DIAGNOSTIC_LIMIT_V1,
+): BazisDiagnosticsV1 {
+  if (!Number.isSafeInteger(limit) || limit < 1) {
+    throw new RangeError("Diagnostic limit must be a positive safe integer.");
+  }
+  const safeLimit = Math.min(BAZIS_DIAGNOSTIC_LIMIT_V1, limit);
+  const sorted = [...diagnostics].sort(compareDiagnosticsV1);
+  if (sorted.length <= safeLimit) {
+    return Object.freeze({
+      diagnostics: Object.freeze(sorted.map(bazisDiagnosticV1)),
+      truncated: false,
+    });
+  }
+
+  const visible = sorted.slice(0, Math.max(0, safeLimit - 1)).map(bazisDiagnosticV1);
+  visible.push(bazisDiagnosticV1({
+    severity: "error",
+    stage: "schema",
+    code: "WF_DIAGNOSTICS_TRUNCATED",
+    message: "Diagnostics were truncated at the configured framework ceiling.",
+    pointer: "",
+  }));
+  return Object.freeze({ diagnostics: Object.freeze(visible), truncated: true });
+}
+
+export function escapeJsonPointerSegmentV1(value: string): string {
+  return value.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
+export function appendJsonPointerV1(pointer: string, segment: string | number): string {
+  return pointer + "/" + escapeJsonPointerSegmentV1(String(segment));
+}
+
+function compareDiagnosticsV1(left: BazisDiagnosticV1, right: BazisDiagnosticV1): number {
+  return compareText(left.pointer, right.pointer)
+    || compareText(left.code, right.code)
+    || compareText(left.nodeId ?? "", right.nodeId ?? "")
+    || compareText(left.flowId ?? "", right.flowId ?? "")
+    || SEVERITY_ORDER[left.severity] - SEVERITY_ORDER[right.severity];
+}
+
+function compareText(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function boundedPointer(pointer: string): string {
+  if (UTF8.encode(pointer).byteLength <= DIAGNOSTIC_POINTER_BYTES_V1) {
+    return pointer;
+  }
+  const segments = pointer.split("/");
+  let output = "";
+  for (let index = 1; index < segments.length; index += 1) {
+    const candidate = output + "/" + segments[index];
+    if (UTF8.encode(candidate).byteLength > DIAGNOSTIC_POINTER_BYTES_V1) {
+      break;
+    }
+    output = candidate;
+  }
+  return output;
+}
+
+function truncateUtf8(value: string, maxBytes: number): string {
+  if (UTF8.encode(value).byteLength <= maxBytes) return value;
+  let output = "";
+  for (const character of value) {
+    const candidate = output + character;
+    if (UTF8.encode(candidate).byteLength > maxBytes) break;
+    output = candidate;
+  }
+  return output;
+}

package/library/boundary/index.ts

@@ -0,0 +1,73 @@
+export {
+  BAZIS_DIAGNOSTIC_LIMIT_V1,
+  appendJsonPointerV1,
+  escapeJsonPointerSegmentV1,
+  finalizeBazisDiagnosticsV1,
+  bazisDiagnosticV1,
+  type BazisDiagnosticRepairV1,
+  type BazisDiagnosticSeverityV1,
+  type BazisDiagnosticSourceV1,
+  type BazisDiagnosticStageV1,
+  type BazisDiagnosticsV1,
+  type BazisDiagnosticV1,
+} from "./diagnostics-v1";
+export {
+  decodeBoundedJsonV1,
+  type DecodeBoundedJsonV1Options,
+  type DecodeBoundedJsonV1Result,
+} from "./json/decodeBoundedJsonV1";
+export {
+  BOUNDARY_JSON_LIMITS_V1,
+  boundaryJsonLimitsV1,
+  type BoundaryJsonLimitOverridesV1,
+  type BoundaryJsonLimitsV1,
+} from "./json/limits-v1";
+export {
+  normalizeBoundedJsonV1,
+  type NormalizeBoundedJsonV1Options,
+  type NormalizeBoundedJsonV1Result,
+} from "./json/normalizeBoundedJsonV1";
+export {
+  isBoundaryJsonObject,
+  type BoundaryJsonArray,
+  type BoundaryJsonObject,
+  type BoundaryJsonPrimitive,
+  type BoundaryJsonValue,
+} from "./json/types-v1";
+export {
+  BoundaryCanonicalizationErrorV1,
+  canonicalBoundaryJsonBytesV1,
+  canonicalBoundaryJsonV1,
+  canonicalJsonHashV1,
+} from "./serialization/canonicalJsonV1";
+export {
+  BOUNDARY_SCHEMA_V1_DOMAIN,
+  BOUNDARY_SCHEMA_MAX_DEPTH_V1,
+  BOUNDARY_SCHEMA_MAX_ENUM_VALUES_V1,
+  BOUNDARY_SCHEMA_MAX_NODES_V1,
+  type BoundaryArraySchemaV1,
+  type BoundaryBooleanSchemaV1,
+  type BoundaryIntegerSchemaV1,
+  type BoundaryNullSchemaV1,
+  type BoundaryNumberSchemaV1,
+  type BoundaryObjectSchemaV1,
+  type BoundaryScalarSchemaV1,
+  type BoundarySchemaCommonV1,
+  type BoundarySchemaTypeV1,
+  type BoundarySchemaV1,
+  type BoundaryStringFormatV1,
+  type BoundaryStringSchemaV1,
+} from "./schema/types-v1";
+export {
+  boundarySchemaHashV1,
+} from "./schema/boundarySchemaHashV1";
+export {
+  decodeBoundarySchemaV1,
+  type DecodeBoundarySchemaV1Options,
+  type DecodeBoundarySchemaV1Result,
+} from "./schema/decodeBoundarySchemaV1";
+export {
+  validateBoundaryValueV1,
+  type ValidateBoundaryValueV1Options,
+  type ValidateBoundaryValueV1Result,
+} from "./schema/validateBoundaryValueV1";