@gencow/core 0.1.27 → 0.1.29

package/src/index.ts

@@ -9,34 +9,134 @@ export type {
   GencowCtx,
   AuthCtx,
   UserIdentity,
-  QueryDef,
-  MutationDef,
   RealtimeCtx,
+  RealtimeNotifyEvent,
+  AIContext,
+  AIMessage,
+  AIResult,
+} from "./context.js";
+export { defineApi } from "./context.js";
+export type { QueryDef } from "./reactive-query-types.js";
+export type { MutationDef } from "./reactive-mutation-types.js";
+export type {
   HttpActionDef,
   HttpActionRequest,
   HttpActionResponse,
   HttpActionHandler,
-  AIContext,
-  AIMessage,
-  AIResult,
-} from "./reactive.js";
+} from "./http-action.js";
+export type {
+  SearchPrimitive,
+  SearchScope,
+  SearchFilter,
+  SearchOptions,
+  VectorSearchOptions,
+  HybridSearchOptions,
+  SearchHit,
+  SearchResponse,
+  SearchTierConfig,
+} from "./search-types.js";
+export type {
+  DocumentVisibility,
+  DocumentConvertMode,
+  DocumentConvertProvider,
+  DocumentResolvedProvider,
+  DocumentConvertInput,
+  DocumentPage,
+  DocumentSection,
+  DocumentProviderTrace,
+  DocumentConvertResult,
+  DocumentCacheArtifact,
+  DocumentCacheKeyInput,
+  GencowServicesCtx,
+  WorkflowDocumentServicesCtx,
+} from "./document-types.js";
+export { buildDocumentCacheKey } from "./document-types.js";
+export type {
+  WakeAppBootFailedResult,
+  WakeAppDeferredResult,
+  WakeAppDeferredStatus,
+  WakeAppResult,
+  WakeAppSuccessResult,
+  WakeAppSuccessStatus,
+} from "./wake-app-result.js";
+export {
+  DEFAULT_WAKE_RETRY_AFTER_SEC,
+  buildWakeAppBootFailedResult,
+  buildWakeAppSuccessResult,
+  isWakeAppDeferredResult,
+} from "./wake-app-result.js";
+export type { PlatformCapacityPreset, PlatformCapacityProfileName } from "./platform-capacity-profile.js";
+export {
+  PLATFORM_CAPACITY_ENV_KEYS,
+  PLATFORM_CAPACITY_PRESETS,
+  PLATFORM_CAPACITY_PROFILE_ENV,
+  detectPlatformCapacityProfile,
+  resolvePlatformCapacityPreset,
+} from "./platform-capacity-profile.js";
+export type {
+  RagIngestReindexMode,
+  RagIngestInput,
+  RagIngestWorkflowArgs,
+  RagIngestStartResult,
+  RagIngestJobStatus,
+  RagIngestJobRecord,
+} from "./rag-ingest-types.js";
+export type {
+  CitationCoverage,
+  ClaimSupportStatus,
+  GroundedAnswerMode,
+  Citation,
+  ClaimEvidenceMap,
+  GroundedAnswer,
+  GroundingBudget,
+  GroundedClaimInput,
+  GroundedCompareInput,
+  GroundedTopicInput,
+  GroundedAnswerInput,
+  GroundingRuntime,
+} from "./grounded-answer-types.js";
+export { DEFAULT_GROUNDING_BUDGET } from "./grounded-answer-types.js";
+export type {
+  RagOperationKind,
+  RagOperationMetricUnit,
+  RagIndexHealth,
+  RagOperationMetric,
+  RagOperationsSummary,
+  RagEvaluationExpectedClaim,
+  RagEvaluationFixture,
+  RagEvaluationFixtureResult,
+  RagEvaluationRunResult,
+  RagReindexMode,
+  RagReindexPlan,
+} from "./rag-operations-types.js";
+export {
+  ragCorpora,
+  ragSources,
+  ragSections,
+  ragChunks,
+  ragIngestJobs,
+  ragOperationMetrics,
+} from "./rag-schema.js";
+export { buildQuerySubscriptionKey, subscriptionKeyMatchesQueryKey } from "./reactive-realtime.js";
+export { query, getQueryHandler, getQueryDef, getRegisteredQueries } from "./reactive-query.js";
+export { mutation, getRegisteredMutations } from "./reactive-mutation.js";
+export { procQuery, procMutation } from "./procedure.js";
+export type {
+  GencowProcedureBuilder,
+  GencowProcedureDef,
+  GencowProcedureMiddleware,
+  GencowProcedureHandler,
+} from "./procedure.js";
+export { httpAction, getRegisteredHttpActions } from "./http-action.js";
 export {
-  query,
-  mutation,
-  httpAction,
-  buildRealtimeCtx,
   subscribe,
   unsubscribe,
   registerClient,
   deregisterClient,
+  buildRealtimeCtx,
   handleWsMessage,
-  getQueryHandler,
-  getQueryDef,
-  getRegisteredQueries,
-  getRegisteredMutations,
-  getRegisteredHttpActions,
-} from "./reactive.js";
-export type { Storage } from "./storage.js";
+} from "./reactive-realtime.js";
+export type { Storage, StoredFile } from "./storage.js";
 export { createScheduler, getSchedulerInfo } from "./scheduler.js";
 export type {
   Scheduler,
@@ -82,17 +182,40 @@ export { v, parseArgs, GencowValidationError } from "./v.js";
 export type { Validator, Infer, InferArgs } from "./v.js";
 export { withRetry } from "./retry.js";
 export type { RetryOptions } from "./retry.js";
+export { filterTenantRuntimeEnvVars, isReservedTenantRuntimeEnvKey } from "./runtime-env-policy.js";
 export { cronJobs } from "./crons.js";
 export type { CronJobsBuilder, CronJobDef, IntervalOptions, DailyOptions, WeeklyOptions } from "./crons.js";
 export { defineAuth } from "./auth-config.js";
-export type { GencowAuthConfig, AuthEmailVerification } from "./auth-config.js";
+export type {
+  GencowAuthConfig,
+  AuthEmailVerification,
+  AuthPasswordReset,
+  AuthEvents,
+  AuthHookContext,
+  AuthUserLike,
+  AuthOAuthConfig,
+  SocialProviderConfig,
+  SocialProvidersConfig,
+  KakaoConfig,
+  NaverConfig,
+  CustomOAuthProvider,
+  OAuthUserInfo,
+} from "./auth-config.js";
+export { defineConfig } from "./config.js";
+export type { GencowConfig, GencowDbConfig, GencowDeployConfig } from "./config.js";
 
 // ─── RLS + CRUD Factory ───────────
 export { ownerRls, getOwnerRlsMeta, registerOwnerRls } from "./rls.js";
 export type { OwnerRlsMeta } from "./rls.js";
 export { createRlsDb } from "./rls-db.js";
 export type { RlsSessionContext } from "./rls-db.js";
-export { crud, parseFilterNode, applyFilterOp, getOwnerRlsTables, getRegisteredCrudCodegenMeta } from "./crud.js";
+export {
+  crud,
+  parseFilterNode,
+  applyFilterOp,
+  getOwnerRlsTables,
+  getRegisteredCrudCodegenMeta,
+} from "./crud.js";
 export type { CrudCodegenMeta } from "./crud.js";
 
 // Deprecated alias — 하위호환용, 향후 메이저 버전에서 제거 예정

package/src/platform-capacity-profile.ts

@@ -0,0 +1,114 @@
+export type PlatformCapacityProfileName = "prod" | "dev" | "local";
+
+export interface PlatformCapacityPreset {
+  profile: PlatformCapacityProfileName;
+  maxConcurrentRunning: number | null;
+  maxConcurrentWake: number | null;
+  maxWakeQueueMs: number;
+  minAvailableRamMB: number | null;
+  evictionThresholdMB: number | null;
+  sleepTimeoutMinutes: number;
+  sleepMaxPerCycle: number;
+  warmPoolMinIdle: number;
+  warmPoolMax: number;
+  deployCandidateReserve: number;
+}
+
+export const PLATFORM_CAPACITY_PROFILE_ENV = "GENCOW_CAPACITY_PROFILE";
+
+export const PLATFORM_CAPACITY_ENV_KEYS = [
+  PLATFORM_CAPACITY_PROFILE_ENV,
+  "MAX_CONCURRENT_RUNNING",
+  "MAX_CONCURRENT_WAKE",
+  "MAX_WAKE_QUEUE_MS",
+  "MIN_AVAILABLE_RAM_MB",
+  "WAKE_RETRY_AFTER_SEC",
+  "EVICTION_THRESHOLD_MB",
+  "GENCOW_SLEEP_TIMEOUT_MINUTES",
+  "GENCOW_SLEEP_MAX_PER_CYCLE",
+  "WARM_POOL_MIN_IDLE",
+  "WARM_POOL_MAX",
+  "DEPLOY_CANDIDATE_RESERVE",
+  "GENCOW_APP_PORT_RANGE",
+  "COWBOX_WARM_POOL_PORT_RANGE",
+] as const;
+
+export const PLATFORM_CAPACITY_PRESETS: Record<PlatformCapacityProfileName, PlatformCapacityPreset> = Object.freeze({
+  prod: Object.freeze({
+    profile: "prod",
+    maxConcurrentRunning: 600,
+    maxConcurrentWake: 20,
+    maxWakeQueueMs: 5000,
+    minAvailableRamMB: 8192,
+    evictionThresholdMB: 16384,
+    sleepTimeoutMinutes: 15,
+    sleepMaxPerCycle: 50,
+    warmPoolMinIdle: 10,
+    warmPoolMax: 650,
+    deployCandidateReserve: 40,
+  }),
+  dev: Object.freeze({
+    profile: "dev",
+    maxConcurrentRunning: 60,
+    maxConcurrentWake: 5,
+    maxWakeQueueMs: 3000,
+    minAvailableRamMB: 2048,
+    evictionThresholdMB: 4096,
+    sleepTimeoutMinutes: 10,
+    sleepMaxPerCycle: 20,
+    warmPoolMinIdle: 3,
+    warmPoolMax: 70,
+    deployCandidateReserve: 5,
+  }),
+  local: Object.freeze({
+    profile: "local",
+    maxConcurrentRunning: null,
+    maxConcurrentWake: null,
+    maxWakeQueueMs: 5000,
+    minAvailableRamMB: null,
+    evictionThresholdMB: null,
+    sleepTimeoutMinutes: 30,
+    sleepMaxPerCycle: 10,
+    warmPoolMinIdle: 3,
+    warmPoolMax: 10,
+    deployCandidateReserve: 0,
+  }),
+});
+
+function normalizeDomain(value: string | undefined): string {
+  return (value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/^https?:\/\//, "")
+    .replace(/\/.*$/, "");
+}
+
+export function detectPlatformCapacityProfile(
+  env: Record<string, string | undefined> = process.env,
+): PlatformCapacityProfileName {
+  const explicit = env[PLATFORM_CAPACITY_PROFILE_ENV]?.trim().toLowerCase();
+  if (explicit) {
+    if (["prod", "production", "128gb"].includes(explicit)) return "prod";
+    if (["dev", "development", "16gb"].includes(explicit)) return "dev";
+    if (["local", "test", "disabled"].includes(explicit)) return "local";
+    throw new Error(`Invalid ${PLATFORM_CAPACITY_PROFILE_ENV}: ${explicit}. Expected prod, dev, or local.`);
+  }
+
+  const baseDomain = normalizeDomain(env.BASE_DOMAIN);
+  if (baseDomain === "gencow.dev") return "dev";
+  if (baseDomain === "gencow.app") return "prod";
+
+  const platformUrl = normalizeDomain(env.GENCOW_PLATFORM_URL);
+  if (platformUrl === "gencow.dev") return "dev";
+  if (platformUrl === "gencow.app") return "prod";
+
+  if (env.NODE_ENV === "production" && env.IS_PLATFORM === "true") return "prod";
+  return "local";
+}
+
+export function resolvePlatformCapacityPreset(
+  env: Record<string, string | undefined> = process.env,
+): PlatformCapacityPreset {
+  const profile = detectPlatformCapacityProfile(env);
+  return { ...PLATFORM_CAPACITY_PRESETS[profile] };
+}

package/src/procedure.ts

@@ -0,0 +1,283 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { GencowCtx } from "./context.js";
+
+type InferInputSchema<TSchema> = TSchema extends { "~standard": { types: { input: infer TInput } } }
+  ? TInput
+  : TSchema extends StandardSchemaV1
+    ? StandardSchemaV1.InferInput<TSchema>
+    : unknown;
+
+type InferOutputSchema<TSchema> = TSchema extends { "~standard": { types: { output: infer TOutput } } }
+  ? TOutput
+  : TSchema extends { _output: infer TOutput }
+    ? TOutput
+    : TSchema extends StandardSchemaV1
+      ? StandardSchemaV1.InferOutput<TSchema>
+      : unknown;
+
+type NextFn<TContext, TInput, TOutput> = (overrides?: {
+  context?: TContext;
+  input?: TInput;
+}) => Promise<TOutput>;
+
+export type GencowProcedureMiddleware<TContext, TInput, TOutput> = (options: {
+  context: TContext;
+  input: TInput;
+  next: NextFn<TContext, TInput, TOutput>;
+}) => Promise<TOutput> | TOutput;
+
+export type GencowProcedureHandler<TContext, TInput, TOutput> = (options: {
+  context: TContext;
+  input: TInput;
+}) => Promise<TOutput> | TOutput;
+
+export interface GencowProcedureDef<
+  TKind extends "query" | "mutation" = "query" | "mutation",
+  TContext = any,
+  TInput = unknown,
+  TOutput = unknown,
+> {
+  kind: TKind;
+  name: string;
+  /** When false (default), RPC requires an authenticated user. */
+  isPublic: boolean;
+  middlewares: readonly GencowProcedureMiddleware<TContext, TInput, TOutput>[];
+  inputSchema?: StandardSchemaV1;
+  outputSchema?: StandardSchemaV1;
+  inputValidationIndex: number;
+  outputValidationIndex: number;
+  handler: (context: TContext, input: TInput) => Promise<TOutput>;
+}
+
+export interface GencowProcedureBuilder<
+  TKind extends "query" | "mutation" = "query" | "mutation",
+  TContext = any,
+  TInput = unknown,
+  TOutput = unknown,
+> {
+  name(name: string): GencowProcedureBuilder<TKind, TContext, TInput, TOutput>;
+  /**
+   * Allow calling this procedure without authentication (like `query("x", { public: true, ... })`).
+   * Default is authenticated-only.
+   */
+  allowPublic(): GencowProcedureBuilder<TKind, TContext, TInput, TOutput>;
+  use(
+    middleware: GencowProcedureMiddleware<TContext, TInput, TOutput>,
+  ): GencowProcedureBuilder<TKind, TContext, TInput, TOutput>;
+  input<TNextSchema extends StandardSchemaV1>(
+    schema: TNextSchema,
+  ): GencowProcedureBuilder<TKind, TContext, InferInputSchema<TNextSchema>, TOutput>;
+  output<TNextSchema extends StandardSchemaV1>(
+    schema: TNextSchema,
+  ): GencowProcedureBuilder<TKind, TContext, TInput, InferOutputSchema<TNextSchema>>;
+  handler(
+    handler: GencowProcedureHandler<TContext, TInput, TOutput>,
+  ): GencowProcedureDef<TKind, TContext, TInput, TOutput>;
+}
+
+function hasStandardSchema(schema: unknown): schema is StandardSchemaV1 {
+  return (
+    !!schema &&
+    typeof schema === "object" &&
+    "~standard" in schema &&
+    !!(schema as any)["~standard"] &&
+    typeof (schema as any)["~standard"].validate === "function"
+  );
+}
+
+async function validateWithSchema<TOutput>(schema: unknown, value: unknown): Promise<TOutput> {
+  if (!schema) return value as TOutput;
+
+  if (hasStandardSchema(schema)) {
+    const result = (await schema["~standard"].validate(value)) as
+      | { value: TOutput }
+      | { issues: readonly { message: string }[] };
+    if ("issues" in result && result.issues.length > 0) {
+      throw new Error(result.issues[0]?.message ?? "Validation failed");
+    }
+    if ("value" in result) {
+      return result.value as TOutput;
+    }
+    throw new Error("Validation failed");
+  }
+
+  throw new Error("procQuery/procMutation only supports Standard Schema v1 validators");
+}
+
+function composeMiddlewares<TContext, TInput, TOutput>(
+  middlewares: Array<GencowProcedureMiddleware<TContext, TInput, TOutput>>,
+  handler: GencowProcedureHandler<TContext, TInput, TOutput>,
+  inputSchema: StandardSchemaV1 | undefined,
+  outputSchema: StandardSchemaV1 | undefined,
+  inputValidationIndex: number,
+  outputValidationIndex: number,
+): (context: TContext, input: TInput) => Promise<TOutput> {
+  return async (initialContext, initialInput) => {
+    let idx = -1;
+    const boundedInputValidationIndex = Math.min(Math.max(0, inputValidationIndex), middlewares.length);
+    const boundedOutputValidationIndex = Math.min(Math.max(0, outputValidationIndex), middlewares.length);
+
+    const run = async (currentIdx: number, context: TContext, input: TInput): Promise<TOutput> => {
+      if (currentIdx <= idx) {
+        throw new Error("next() called multiple times in the same middleware");
+      }
+      idx = currentIdx;
+      let currentInput = input;
+
+      if (currentIdx === boundedInputValidationIndex) {
+        currentInput = (await validateWithSchema(inputSchema, currentInput)) as TInput;
+      }
+
+      if (currentIdx === middlewares.length) {
+        const output = await handler({ context, input: currentInput });
+        if (currentIdx === boundedOutputValidationIndex) {
+          return await validateWithSchema<TOutput>(outputSchema, output);
+        }
+        return output;
+      }
+
+      const middleware = middlewares[currentIdx];
+      const output = await middleware({
+        context,
+        input: currentInput,
+        next: async (overrides) => {
+          return await run(
+            currentIdx + 1,
+            (overrides?.context ?? context) as TContext,
+            (overrides?.input ?? currentInput) as TInput,
+          );
+        },
+      });
+
+      if (currentIdx === boundedOutputValidationIndex) {
+        return await validateWithSchema<TOutput>(outputSchema, output);
+      }
+
+      return output;
+    };
+
+    return await run(0, initialContext, initialInput);
+  };
+}
+
+class GencowProcedureBuilderImpl<
+  TKind extends "query" | "mutation",
+  TContext = any,
+  TInput = unknown,
+  TOutput = unknown,
+> implements GencowProcedureBuilder<TKind, TContext, TInput, TOutput> {
+  constructor(
+    private readonly kind: TKind,
+    private readonly procedureName?: string,
+    private readonly middlewares: Array<GencowProcedureMiddleware<TContext, TInput, TOutput>> = [],
+    private readonly inputSchema?: StandardSchemaV1,
+    private readonly outputSchema?: StandardSchemaV1,
+    private readonly inputValidationIndex = -1,
+    private readonly outputValidationIndex = -1,
+    private readonly isPublic = false,
+  ) {}
+
+  name(name: string) {
+    return new GencowProcedureBuilderImpl<TKind, TContext, TInput, TOutput>(
+      this.kind,
+      name,
+      this.middlewares,
+      this.inputSchema,
+      this.outputSchema,
+      this.inputValidationIndex,
+      this.outputValidationIndex,
+      this.isPublic,
+    );
+  }
+
+  allowPublic() {
+    return new GencowProcedureBuilderImpl<TKind, TContext, TInput, TOutput>(
+      this.kind,
+      this.procedureName,
+      this.middlewares,
+      this.inputSchema,
+      this.outputSchema,
+      this.inputValidationIndex,
+      this.outputValidationIndex,
+      true,
+    );
+  }
+
+  use(middleware: GencowProcedureMiddleware<TContext, TInput, TOutput>) {
+    return new GencowProcedureBuilderImpl<TKind, TContext, TInput, TOutput>(
+      this.kind,
+      this.procedureName,
+      [...this.middlewares, middleware],
+      this.inputSchema,
+      this.outputSchema,
+      this.inputValidationIndex,
+      this.outputValidationIndex,
+      this.isPublic,
+    );
+  }
+
+  input<TNextSchema extends StandardSchemaV1>(schema: TNextSchema) {
+    const nextInputValidationIndex = this.middlewares.length < 0 ? 0 : this.middlewares.length;
+
+    return new GencowProcedureBuilderImpl<TKind, TContext, InferInputSchema<TNextSchema>, TOutput>(
+      this.kind,
+      this.procedureName,
+      this.middlewares as Array<GencowProcedureMiddleware<TContext, InferInputSchema<TNextSchema>, TOutput>>,
+      schema,
+      this.outputSchema,
+      nextInputValidationIndex,
+      this.outputValidationIndex,
+      this.isPublic,
+    );
+  }
+
+  output<TNextSchema extends StandardSchemaV1>(schema: TNextSchema) {
+    const nextOutputValidationIndex = this.middlewares.length < 0 ? 0 : this.middlewares.length;
+
+    return new GencowProcedureBuilderImpl<TKind, TContext, TInput, InferOutputSchema<TNextSchema>>(
+      this.kind,
+      this.procedureName,
+      this.middlewares as Array<GencowProcedureMiddleware<TContext, TInput, InferOutputSchema<TNextSchema>>>,
+      this.inputSchema,
+      schema,
+      this.inputValidationIndex,
+      nextOutputValidationIndex,
+      this.isPublic,
+    );
+  }
+
+  handler(
+    handler: GencowProcedureHandler<TContext, TInput, TOutput>,
+  ): GencowProcedureDef<TKind, TContext, TInput, TOutput> {
+    if (!this.procedureName) {
+      throw new Error("Procedure name is required. Call .name(...) before .handler(...)");
+    }
+
+    const run = composeMiddlewares(
+      this.middlewares,
+      handler,
+      this.inputSchema,
+      this.outputSchema,
+      this.inputValidationIndex,
+      this.outputValidationIndex,
+    );
+
+    return {
+      kind: this.kind,
+      name: this.procedureName,
+      isPublic: this.isPublic,
+      middlewares: [...this.middlewares],
+      inputSchema: this.inputSchema,
+      outputSchema: this.outputSchema,
+      inputValidationIndex: this.inputValidationIndex,
+      outputValidationIndex: this.outputValidationIndex,
+      handler: run,
+    };
+  }
+}
+
+export const procQuery: GencowProcedureBuilder<"query", GencowCtx> =
+  new GencowProcedureBuilderImpl<"query", GencowCtx>("query");
+
+export const procMutation: GencowProcedureBuilder<"mutation", GencowCtx> =
+  new GencowProcedureBuilderImpl<"mutation", GencowCtx>("mutation");

package/src/rag-ingest-types.ts

@@ -0,0 +1,52 @@
+import type { DocumentConvertProvider, DocumentConvertMode, DocumentProviderTrace, DocumentVisibility } from "./document-types.js";
+
+export type RagIngestReindexMode = "if_changed" | "force";
+export type RagIngestJobStatus =
+  | "queued"
+  | "converting"
+  | "chunking"
+  | "embedding"
+  | "upserting"
+  | "completed"
+  | "failed"
+  | "canceled";
+
+export type RagIngestInput = {
+  storageId: string;
+  corpus: string;
+  visibility: DocumentVisibility;
+  ownerUserId?: string;
+  sourceKey?: string;
+  metadata?: Record<string, unknown>;
+  reindexMode?: RagIngestReindexMode;
+  mode?: DocumentConvertMode;
+  provider?: DocumentConvertProvider;
+};
+
+export type RagIngestWorkflowArgs = RagIngestInput & {
+  jobId: string;
+  sourceId: string;
+};
+
+export type RagIngestStartResult = {
+  workflowId: string;
+  jobId: string;
+  sourceId: string;
+  status: "queued";
+};
+
+export type RagIngestJobRecord = {
+  id: string;
+  workflowId: string;
+  sourceId: string;
+  corpus: string;
+  visibility: DocumentVisibility;
+  ownerUserId: string | null;
+  status: RagIngestJobStatus;
+  stage: string;
+  providerTrace: Partial<DocumentProviderTrace> | Record<string, never>;
+  metrics: Record<string, unknown>;
+  error: string | null;
+  startedAt: string;
+  completedAt: string | null;
+};