@autobe/agent 0.30.0-dev.20260315 → 0.30.0

package/src/orchestrate/interface/utils/AutoBeJsonSchemaFactory.ts

@@ -1,714 +1,714 @@
-import {
-  AutoBeDatabase,
-  AutoBeInterfaceSchemaDesign,
-  AutoBeOpenApi,
-} from "@autobe/interface";
-import { AutoBeOpenApiTypeChecker, StringUtil } from "@autobe/utils";
-import { OpenApiConverter, OpenApiTypeChecker } from "@typia/utils";
-import typia, { OpenApi, tags } from "typia";
-import { v7 } from "uuid";
-
-import { AutoBeInterfaceSchemaProgrammer } from "../programmers/AutoBeInterfaceSchemaProgrammer";
-import { AutoBeJsonSchemaCollection } from "./AutoBeJsonSchemaCollection";
-import { AutoBeJsonSchemaValidator } from "./AutoBeJsonSchemaValidator";
-
-export namespace AutoBeJsonSchemaFactory {
-  /* -----------------------------------------------------------
-    ASSIGNMENTS
-  ----------------------------------------------------------- */
-  export const presets = (
-    typeNames: Set<string>,
-  ): Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> => {
-    const schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> = {};
-    for (const [key, value] of Object.entries(DEFAULT_SCHEMAS)) {
-      schemas[key] = value;
-      typeNames.delete(key);
-    }
-    for (const key of typeNames)
-      if (AutoBeJsonSchemaValidator.isPage(key)) {
-        const data: string = getPageName(key);
-        schemas[key] = writePageSchema(data);
-        typeNames.delete(key);
-        typeNames.add(data);
-      }
-    return schemas;
-  };
-
-  export const fixPaginationSchemas = (
-    schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>,
-  ): void => {
-    const pageRequest: AutoBeOpenApi.IJsonSchemaDescriptive.IObject =
-      DEFAULT_SCHEMAS[
-        "IPage.IRequest"
-      ] as AutoBeOpenApi.IJsonSchemaDescriptive.IObject;
-    for (const [key, value] of Object.entries(schemas)) {
-      if (key.endsWith(".IRequest") === false) continue;
-      else if (AutoBeOpenApiTypeChecker.isObject(value) === false) continue;
-
-      if (value.properties.page === undefined)
-        value.properties.page = pageRequest.properties.page;
-      if (value.properties.limit === undefined)
-        value.properties.limit = pageRequest.properties.limit;
-    }
-  };
-
-  export const fixAuthorizationSchemas = (
-    schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>,
-  ): void => {
-    for (const [key, value] of Object.entries(schemas)) {
-      if (key.endsWith(".IAuthorized") === false) continue;
-      else if (AutoBeOpenApiTypeChecker.isObject(value) === false) continue;
-
-      const parent: AutoBeOpenApi.IJsonSchemaDescriptive | undefined =
-        schemas[key.replace(".IAuthorized", "")];
-      if (
-        parent === undefined ||
-        AutoBeOpenApiTypeChecker.isObject(parent) === false
-      ) {
-        value.properties.token = {
-          "x-autobe-specification":
-            "Authorization token comes from the session table.",
-          description: "Authorization token.",
-          $ref: "#/components/schemas/IAuthorizationToken",
-        };
-        if (value.required.includes("token") === false)
-          value.required.push("token");
-      } else {
-        value.properties = {
-          ...parent.properties,
-          ...value.properties,
-        };
-        value.properties.token = {
-          "x-autobe-specification":
-            "Authorization token comes from the session table.",
-          description: "Authorization token.",
-          $ref: "#/components/schemas/IAuthorizationToken",
-        };
-        value.required = Array.from(
-          new Set([...parent.required, ...value.required]),
-        );
-        if (value.required.includes("id") === false) value.required.push("id");
-        if (value.required.includes("token") === false)
-          value.required.push("token");
-      }
-    }
-  };
-
-  export const finalize = (props: {
-    application: AutoBeDatabase.IApplication;
-    operations: AutoBeOpenApi.IOperation[];
-    collection: AutoBeJsonSchemaCollection;
-  }): void => {
-    removeDuplicated(props);
-    fixTimestamps({
-      application: props.application,
-      document: {
-        operations: props.operations,
-        components: {
-          schemas: props.collection.schemas,
-          authorizations: [],
-        },
-      },
-    });
-    linkRelatedModels({
-      application: props.application,
-      document: {
-        operations: props.operations,
-        components: {
-          schemas: props.collection.schemas,
-          authorizations: [],
-        },
-      },
-    });
-  };
-
-  export const removeUnused = (props: {
-    operations: AutoBeOpenApi.IOperation[];
-    schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>;
-  }): void => {
-    while (true) {
-      const used: Set<string> = new Set();
-      const visit = (schema: AutoBeOpenApi.IJsonSchema): void =>
-        OpenApiTypeChecker.visit({
-          components: { schemas: props.schemas },
-          schema,
-          closure: (next) => {
-            if (OpenApiTypeChecker.isReference(next)) {
-              const key: string = next.$ref.split("/").pop()!;
-              used.add(key);
-            }
-          },
-        });
-      for (const op of props.operations) {
-        if (op.requestBody !== null)
-          visit({
-            $ref: `#/components/schemas/${op.requestBody.typeName}`,
-          });
-        if (op.responseBody !== null)
-          visit({
-            $ref: `#/components/schemas/${op.responseBody.typeName}`,
-          });
-      }
-
-      const complete: boolean =
-        Object.keys(props.schemas).length === 0 ||
-        Object.keys(props.schemas).every((key) => used.has(key) === true);
-      if (complete === true) break;
-      for (const key of Object.keys(props.schemas))
-        if (used.has(key) === false) delete props.schemas[key];
-    }
-  };
-
-  const removeDuplicated = (props: {
-    operations: AutoBeOpenApi.IOperation[];
-    collection: AutoBeJsonSchemaCollection;
-  }): void => {
-    // gather duplicated schemas
-    const correct: Map<string, string> = new Map();
-    for (const key of Object.keys(props.collection.schemas)) {
-      if (key.includes(".") === false) continue;
-      const dotRemoved: string = key.replace(".", "");
-      if (props.collection.schemas[dotRemoved] === undefined) continue;
-      correct.set(dotRemoved, key);
-    }
-
-    // fix operations' references
-    for (const op of props.operations) {
-      if (op.requestBody && correct.has(op.requestBody.typeName))
-        op.requestBody.typeName = correct.get(op.requestBody.typeName)!;
-      if (op.responseBody && correct.has(op.responseBody.typeName))
-        op.responseBody.typeName = correct.get(op.responseBody.typeName)!;
-    }
-
-    // fix schemas' references
-    const $refChangers: Map<OpenApi.IJsonSchema, () => void> = new Map();
-    for (const value of Object.values(props.collection.schemas))
-      OpenApiTypeChecker.visit({
-        components: { schemas: props.collection.schemas },
-        schema: value,
-        closure: (next) => {
-          if (OpenApiTypeChecker.isReference(next) === false) return;
-          const x: string = next.$ref.split("/").pop()!;
-          const y: string | undefined = correct.get(x);
-          if (y === undefined) return;
-          $refChangers.set(
-            next,
-            () => (next.$ref = `#/components/schemas/${y}`),
-          );
-        },
-      });
-    for (const fn of $refChangers.values()) fn();
-
-    // remove duplicated schemas
-    for (const key of correct.keys()) props.collection.delete(key);
-  };
-
-  const fixTimestamps = (props: {
-    document: AutoBeOpenApi.IDocument;
-    application: AutoBeDatabase.IApplication;
-  }): void => {
-    const entireModels: AutoBeDatabase.IModel[] = props.application.files
-      .map((f) => f.models)
-      .flat();
-    for (const value of Object.values(props.document.components.schemas)) {
-      if (AutoBeOpenApiTypeChecker.isObject(value) === false) continue;
-
-      const model: AutoBeDatabase.IModel | undefined = value[
-        "x-autobe-database-schema"
-      ]
-        ? entireModels.find((m) => m.name === value["x-autobe-database-schema"])
-        : undefined;
-      if (model === undefined) continue;
-
-      const properties: string[] = Object.keys(value.properties);
-      for (const key of properties) {
-        if (
-          key !== "created_at" &&
-          key !== "updated_at" &&
-          key !== "deleted_at"
-        )
-          continue;
-        const column: AutoBeDatabase.IPlainField | undefined =
-          model.plainFields.find((c) => c.name === key);
-        if (column === undefined) delete value.properties[key];
-      }
-    }
-  };
-
-  const linkRelatedModels = (props: {
-    document: AutoBeOpenApi.IDocument;
-    application: AutoBeDatabase.IApplication;
-  }): void => {
-    const modelDict: Set<string> = new Set(
-      props.application.files
-        .map((f) => f.models)
-        .flat()
-        .map((m) => m.name),
-    );
-    for (const [key, value] of Object.entries(
-      props.document.components.schemas,
-    )) {
-      if (
-        AutoBeOpenApiTypeChecker.isObject(value) === false ||
-        !!value["x-autobe-database-schema"]?.length
-      )
-        continue;
-
-      const typeName: string = key.split(".")[0]!.substring(1);
-      const modelName: string =
-        AutoBeInterfaceSchemaProgrammer.getDatabaseSchemaName(typeName);
-      if (modelDict.has(modelName) === true)
-        value["x-autobe-database-schema"] = modelName;
-    }
-  };
-
-  /* -----------------------------------------------------------
-    PAGINATION
-  ----------------------------------------------------------- */
-  export const writePageSchema = (
-    key: string,
-  ): AutoBeOpenApi.IJsonSchemaDescriptive.IObject => ({
-    type: "object",
-    properties: {
-      pagination: {
-        "x-autobe-specification": "Pagination information for the page.",
-        description: "Page information.",
-        $ref: "#/components/schemas/IPage.IPagination",
-      },
-      data: {
-        "x-autobe-specification": `List of records of type ${key}.`,
-        description: "List of records.",
-        type: "array",
-        items: {
-          $ref: `#/components/schemas/${key}`,
-        },
-      },
-    },
-    required: ["pagination", "data"],
-    description: StringUtil.trim`
-      A page.
-  
-      Collection of records with pagination information.
-    `,
-    "x-autobe-specification": `A page containing records of type ${key}.`,
-    "x-autobe-database-schema": null, // filled by relation review agent
-  });
-
-  // export const fixPage = (path: string, input: unknown): void => {
-  //   if (isRecord(input) === false || isRecord(input[path]) === false) return;
-  //   if (input[path].description) delete input[path].description;
-  //   if (input[path].required) delete input[path].required;
-
-  //   for (const key of Object.keys(input[path]))
-  //     if (DEFAULT_SCHEMAS[key] !== undefined)
-  //       input[path][key] = DEFAULT_SCHEMAS[key];
-  //     else if (AutoBeJsonSchemaValidator.isPage(key) === true) {
-  //       const data: string = key.substring("IPage".length);
-  //       input[path][key] = writePageSchema(data);
-  //     }
-  // };
-
-  export const getPageName = (key: string): string =>
-    key.substring("IPage".length);
-
-  // const isRecord = (input: unknown): input is Record<string, unknown> =>
-  //   typeof input === "object" && input !== null;
-
-  export const DEFAULT_SCHEMAS = (() => {
-    const init: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> =
-      (typia.json.schemas<
-        [IPage.IPagination, IPage.IRequest, IAuthorizationToken, IEntity]
-      >().components?.schemas ?? {}) as Record<
-        string,
-        AutoBeOpenApi.IJsonSchemaDescriptive
-      >;
-    for (const value of Object.values(init))
-      AutoBeOpenApiTypeChecker.visit({
-        components: {
-          schemas: init,
-          authorizations: [],
-        },
-        schema: value,
-        closure: (next) => {
-          if (AutoBeOpenApiTypeChecker.isObject(next)) {
-            next["x-autobe-database-schema"] = null;
-          }
-        },
-      });
-    return init;
-  })();
-
-  /* -----------------------------------------------------------
-    PLUGIN
-  ----------------------------------------------------------- */
-  export const fixDesign = (
-    design: AutoBeInterfaceSchemaDesign,
-  ): AutoBeOpenApi.IJsonSchema => {
-    const emended: AutoBeOpenApi.IJsonSchema = fixSchema(design.schema);
-    const final: AutoBeOpenApi.IJsonSchema = {
-      ...emended,
-      ...({
-        description: design.description,
-        "x-autobe-specification": design.specification,
-      } satisfies Pick<
-        AutoBeOpenApi.IJsonSchemaDescriptive,
-        "description" | "x-autobe-specification"
-      >),
-    };
-    if (AutoBeOpenApiTypeChecker.isObject(final))
-      final["x-autobe-database-schema"] = design.databaseSchema;
-    return final;
-  };
-
-  export const fixSchema = <Schema extends AutoBeOpenApi.IJsonSchema>(
-    schema: Schema,
-  ): Schema => {
-    const id: string = v7();
-    const emended: AutoBeOpenApi.IJsonSchema = (
-      (OpenApiConverter.upgradeComponents({
-        schemas: {
-          [id]: schema,
-        },
-      }).schemas ?? {}) as Record<string, AutoBeOpenApi.IJsonSchema>
-    )[id];
-
-    const visited: WeakSet<object> = new WeakSet();
-    if (AutoBeOpenApiTypeChecker.isObject(emended)) {
-      visited.add(emended);
-      for (const v of Object.values(emended.properties)) visited.add(v);
-    }
-
-    AutoBeOpenApiTypeChecker.visit({
-      components: {
-        authorizations: [],
-        schemas: {},
-      },
-      schema: emended,
-      closure(next) {
-        if (visited.has(next) === false)
-          for (const k of Object.keys(next))
-            if (k.startsWith("x-")) {
-              // biome-ignore lint: intended
-              delete (next as any)[k];
-            }
-        if (AutoBeOpenApiTypeChecker.isString(next)) fixStringSchema(next);
-        else if (AutoBeOpenApiTypeChecker.isArray(next)) fixArraySchema(next);
-        else if (AutoBeOpenApiTypeChecker.isInteger(next))
-          fixIntegerSchema(next);
-        else if (AutoBeOpenApiTypeChecker.isNumber(next)) fixNumberSchema(next);
-      },
-    });
-
-    const result: Schema = emended as Schema;
-    if (AutoBeOpenApiTypeChecker.isObject(result))
-      for (const [key, value] of Object.entries(result.properties)) {
-        if (key !== "id" && key.endsWith("_id") === false) continue;
-        else if (AutoBeOpenApiTypeChecker.isString(value))
-          fixReferenceIdSchema(value);
-        else if (AutoBeOpenApiTypeChecker.isOneOf(value)) {
-          const str: AutoBeOpenApi.IJsonSchema.IString | undefined =
-            value.oneOf.find((v) => AutoBeOpenApiTypeChecker.isString(v));
-          if (str !== undefined) fixReferenceIdSchema(str);
-        }
-      }
-    return result;
-  };
-
-  const convertConst = (
-    schema:
-      | AutoBeOpenApi.IJsonSchema.INumber
-      | AutoBeOpenApi.IJsonSchema.IInteger,
-    value: number,
-  ): void => {
-    // biome-ignore lint: @todo
-    const description: string | undefined = (schema as any).description;
-
-    for (const key of Object.keys(schema)) {
-      // biome-ignore lint: @todo
-      delete (schema as any)[key];
-    }
-
-    // biome-ignore lint: @todo
-    (schema as any).const = value;
-    if (description !== undefined) {
-      // biome-ignore lint: @todo
-      (schema as any).description = description;
-    }
-  };
-
-  const fixStringSchema = (schema: AutoBeOpenApi.IJsonSchema.IString): void => {
-    if (schema.format !== undefined) {
-      delete schema.pattern;
-      if (
-        schema.format === "uuid" ||
-        schema.format === "ipv4" ||
-        schema.format === "ipv6" ||
-        schema.format === "date" ||
-        schema.format === "date-time" ||
-        schema.format === "time"
-      ) {
-        delete schema.minLength;
-        delete schema.maxLength;
-        delete schema.contentMediaType;
-      }
-    }
-    if (schema.contentMediaType === "") delete schema.contentMediaType;
-    if (schema.minLength === 0) delete schema.minLength;
-  };
-
-  const fixArraySchema = (schema: AutoBeOpenApi.IJsonSchema.IArray): void => {
-    if (schema.minItems === 0) delete schema.minItems;
-  };
-
-  /**
-   * Fix integer schema by converting single valid value ranges to const.
-   *
-   * Handles:
-   *
-   * - Minimum === maximum → const
-   * - Minimum: N, exclusiveMaximum: N+1 → const N
-   * - ExclusiveMinimum: N-1, maximum: N → const N
-   * - ExclusiveMinimum: N-1, exclusiveMaximum: N+1 → const N
-   */
-  const fixIntegerSchema = (
-    schema: AutoBeOpenApi.IJsonSchema.IInteger,
-  ): void => {
-    const value: number | undefined = (() => {
-      if (schema.minimum !== undefined && schema.maximum === schema.minimum)
-        return schema.minimum;
-      if (
-        schema.minimum !== undefined &&
-        schema.exclusiveMaximum === schema.minimum + 1
-      )
-        return schema.minimum;
-      if (
-        schema.maximum !== undefined &&
-        schema.exclusiveMinimum === schema.maximum - 1
-      )
-        return schema.maximum;
-      if (
-        schema.exclusiveMinimum !== undefined &&
-        schema.exclusiveMaximum === schema.exclusiveMinimum + 2
-      )
-        return schema.exclusiveMinimum + 1;
-      return undefined;
-    })();
-
-    if (value !== undefined) convertConst(schema, value);
-  };
-
-  /**
-   * Fix number schema by converting single valid value ranges to const.
-   *
-   * Handles:
-   *
-   * - Minimum === maximum → const
-   */
-  const fixNumberSchema = (schema: AutoBeOpenApi.IJsonSchema.INumber): void => {
-    // minimum === maximum → const
-    if (
-      schema.minimum !== undefined &&
-      schema.maximum !== undefined &&
-      schema.minimum === schema.maximum
-    )
-      return convertConst(schema, schema.minimum);
-  };
-
-  const fixReferenceIdSchema = (
-    schema: AutoBeOpenApi.IJsonSchema.IString,
-  ): void => {
-    schema.format = "uuid";
-    fixStringSchema(schema);
-  };
-}
-
-namespace IPage {
-  /**
-   * Pagination metadata containing current page position and total data
-   * statistics.
-   *
-   * This interface provides comprehensive pagination information returned
-   * alongside paginated list data. It enables clients to implement navigation
-   * controls, display progress indicators, and determine data boundaries for UI
-   * rendering.
-   *
-   * @x-autobe-specification Pagination metadata for paginated list responses. Included in all list endpoint responses.
-   */
-  export interface IPagination {
-    /**
-     * Current page number being viewed (1-indexed).
-     *
-     * Indicates which page of results is currently being returned. Page
-     * numbering starts from 1, so the first page is page 1 (not 0). This value
-     * reflects the page parameter from the request after validation and bounds
-     * checking.
-     *
-     * @x-autobe-specification 1-indexed current page number. Defaults to 1.
-     */
-    current: number & tags.Type<"uint32">;
-
-    /**
-     * Maximum number of records per page.
-     *
-     * Defines the upper bound on how many records can be returned in a single
-     * page. This corresponds to the limit parameter from the request. The
-     * actual number of records in the data array may be less than this value on
-     * the final page or when total records are fewer than the limit.
-     *
-     * @x-autobe-specification Maximum records per page. Actual count may be less on last page.
-     */
-    limit: number & tags.Type<"uint32">;
-
-    /**
-     * Total count of all records matching the query criteria.
-     *
-     * Represents the complete number of records available across all pages, not
-     * just the current page. This value is computed via a COUNT query and is
-     * essential for calculating total pages and displaying pagination UI
-     * elements like "Showing 1-10 of 150 results".
-     *
-     * @x-autobe-specification Total record count across all pages.
-     */
-    records: number & tags.Type<"uint32">;
-
-    /**
-     * Total number of pages available.
-     *
-     * Calculated as ceiling of {@link records} divided by {@link limit}. When
-     * records is 0, pages will also be 0. This value enables clients to render
-     * page navigation controls and validate page bounds.
-     *
-     * @x-autobe-specification Total pages. Calculated as Math.ceil(records / limit).
-     */
-    pages: number & tags.Type<"uint32">;
-  }
-
-  /**
-   * Pagination request parameters for list endpoints.
-   *
-   * Defines the query parameters used to control pagination when requesting
-   * list data. Both parameters are optional with sensible defaults, allowing
-   * clients to fetch data without specifying pagination if default behavior is
-   * acceptable.
-   *
-   * @x-autobe-specification Pagination query parameters for list endpoints. All fields optional.
-   */
-  export interface IRequest {
-    /**
-     * Target page number to retrieve (1-indexed).
-     *
-     * Specifies which page of results to return. Page numbering starts from 1.
-     * If omitted, null, or undefined, defaults to page 1 (first page).
-     * Requesting a page beyond the available range returns an empty data array
-     * with valid pagination metadata reflecting the actual totals.
-     *
-     * @x-autobe-specification 1-indexed page number. Defaults to 1 if not provided.
-     */
-    page?: null | (number & tags.Type<"uint32">);
-
-    /**
-     * Maximum number of records to return per page.
-     *
-     * Controls how many records are included in each page response. If omitted,
-     * null, or undefined, defaults to 100 records per page. The server may
-     * enforce upper bounds to prevent excessive resource consumption on large
-     * requests.
-     *
-     * @default 100
-     *
-     * @x-autobe-specification Maximum records per page. Defaults to 100 if not provided.
-     */
-    limit?: null | (number & tags.Type<"uint32">);
-  }
-}
-
-/**
- * JWT-based authorization token pair with expiration metadata.
- *
- * Provides a complete authentication token structure containing both access and
- * refresh tokens along with their respective expiration timestamps. This
- * dual-token pattern enables secure, stateless authentication with automatic
- * session renewal capabilities.
- *
- * The access token is short-lived for security, while the refresh token allows
- * obtaining new access tokens without requiring the user to re-enter
- * credentials. This structure is automatically included in authentication
- * responses across all generated backend applications.
- *
- * @x-autobe-specification Dual-token authentication structure with access/refresh tokens and expiration info.
- */
-interface IAuthorizationToken {
-  /**
-   * Short-lived JWT access token for authenticating API requests.
-   *
-   * This token must be included in the Authorization header using the Bearer
-   * scheme (e.g., `Authorization: Bearer {access}`) for all endpoints requiring
-   * authentication. The token contains encoded claims including user identity,
-   * roles, and permissions. Typically expires within 15-60 minutes for
-   * security; use the refresh token to obtain a new access token when expired.
-   *
-   * @x-autobe-specification JWT access token. Use in Authorization header as "Bearer {access}".
-   */
-  access: string;
-
-  /**
-   * Long-lived refresh token for obtaining new access tokens.
-   *
-   * Used to request new access tokens when the current access token expires,
-   * allowing session continuation without re-authentication. Should be stored
-   * securely and transmitted only to the token refresh endpoint. Typical
-   * lifetime ranges from 7 to 30 days depending on security requirements.
-   *
-   * @x-autobe-specification Refresh token for obtaining new access tokens without re-authentication.
-   */
-  refresh: string;
-
-  /**
-   * ISO 8601 timestamp when the access token expires.
-   *
-   * After this timestamp, the access token will be rejected by authenticated
-   * endpoints. Clients should proactively refresh before expiration to maintain
-   * seamless user experience. A common strategy is to refresh when remaining
-   * time falls below 5 minutes. This timestamp is also embedded within the JWT
-   * itself as the "exp" claim.
-   *
-   * @x-autobe-specification Access token expiration timestamp in ISO 8601 format.
-   */
-  expired_at: string & tags.Format<"date-time">;
-
-  /**
-   * ISO 8601 timestamp indicating the absolute session expiration deadline.
-   *
-   * Represents the latest possible time the refresh token can be used. Once
-   * this timestamp is reached, the user must fully re-authenticate with
-   * credentials. This defines the maximum session duration regardless of
-   * activity. If refresh token rotation is enabled, this deadline may extend
-   * with each successful refresh.
-   *
-   * @x-autobe-specification Refresh token expiration timestamp. Re-authentication required after this time.
-   */
-  refreshable_until: string & tags.Format<"date-time">;
-}
-
-/**
- * Base entity interface providing standard primary key identification.
- *
- * Serves as the foundational interface for all database entities in the
- * generated application. Every model and record type extends this interface,
- * ensuring consistent identification semantics across all database tables and
- * API responses.
- *
- * @x-autobe-specification Base interface for all database entities. Contains the primary key.
- */
-interface IEntity {
-  /**
-   * Unique identifier for this entity (UUID format).
-   *
-   * Auto-generated primary key using UUID format. This value is assigned by the
-   * system upon record creation and cannot be modified afterward. All foreign
-   * key relationships in the database reference this field.
-   *
-   * @x-autobe-specification Primary key in UUID format. Auto-generated, read-only.
-   */
-  id: string & tags.Format<"uuid">;
-}
+import {
+  AutoBeDatabase,
+  AutoBeInterfaceSchemaDesign,
+  AutoBeOpenApi,
+} from "@autobe/interface";
+import { AutoBeOpenApiTypeChecker, StringUtil } from "@autobe/utils";
+import { OpenApiConverter, OpenApiTypeChecker } from "@typia/utils";
+import typia, { OpenApi, tags } from "typia";
+import { v7 } from "uuid";
+
+import { AutoBeInterfaceSchemaProgrammer } from "../programmers/AutoBeInterfaceSchemaProgrammer";
+import { AutoBeJsonSchemaCollection } from "./AutoBeJsonSchemaCollection";
+import { AutoBeJsonSchemaValidator } from "./AutoBeJsonSchemaValidator";
+
+export namespace AutoBeJsonSchemaFactory {
+  /* -----------------------------------------------------------
+    ASSIGNMENTS
+  ----------------------------------------------------------- */
+  export const presets = (
+    typeNames: Set<string>,
+  ): Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> => {
+    const schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> = {};
+    for (const [key, value] of Object.entries(DEFAULT_SCHEMAS)) {
+      schemas[key] = value;
+      typeNames.delete(key);
+    }
+    for (const key of typeNames)
+      if (AutoBeJsonSchemaValidator.isPage(key)) {
+        const data: string = getPageName(key);
+        schemas[key] = writePageSchema(data);
+        typeNames.delete(key);
+        typeNames.add(data);
+      }
+    return schemas;
+  };
+
+  export const fixPaginationSchemas = (
+    schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>,
+  ): void => {
+    const pageRequest: AutoBeOpenApi.IJsonSchemaDescriptive.IObject =
+      DEFAULT_SCHEMAS[
+        "IPage.IRequest"
+      ] as AutoBeOpenApi.IJsonSchemaDescriptive.IObject;
+    for (const [key, value] of Object.entries(schemas)) {
+      if (key.endsWith(".IRequest") === false) continue;
+      else if (AutoBeOpenApiTypeChecker.isObject(value) === false) continue;
+
+      if (value.properties.page === undefined)
+        value.properties.page = pageRequest.properties.page;
+      if (value.properties.limit === undefined)
+        value.properties.limit = pageRequest.properties.limit;
+    }
+  };
+
+  export const fixAuthorizationSchemas = (
+    schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>,
+  ): void => {
+    for (const [key, value] of Object.entries(schemas)) {
+      if (key.endsWith(".IAuthorized") === false) continue;
+      else if (AutoBeOpenApiTypeChecker.isObject(value) === false) continue;
+
+      const parent: AutoBeOpenApi.IJsonSchemaDescriptive | undefined =
+        schemas[key.replace(".IAuthorized", "")];
+      if (
+        parent === undefined ||
+        AutoBeOpenApiTypeChecker.isObject(parent) === false
+      ) {
+        value.properties.token = {
+          "x-autobe-specification":
+            "Authorization token comes from the session table.",
+          description: "Authorization token.",
+          $ref: "#/components/schemas/IAuthorizationToken",
+        };
+        if (value.required.includes("token") === false)
+          value.required.push("token");
+      } else {
+        value.properties = {
+          ...parent.properties,
+          ...value.properties,
+        };
+        value.properties.token = {
+          "x-autobe-specification":
+            "Authorization token comes from the session table.",
+          description: "Authorization token.",
+          $ref: "#/components/schemas/IAuthorizationToken",
+        };
+        value.required = Array.from(
+          new Set([...parent.required, ...value.required]),
+        );
+        if (value.required.includes("id") === false) value.required.push("id");
+        if (value.required.includes("token") === false)
+          value.required.push("token");
+      }
+    }
+  };
+
+  export const finalize = (props: {
+    application: AutoBeDatabase.IApplication;
+    operations: AutoBeOpenApi.IOperation[];
+    collection: AutoBeJsonSchemaCollection;
+  }): void => {
+    removeDuplicated(props);
+    fixTimestamps({
+      application: props.application,
+      document: {
+        operations: props.operations,
+        components: {
+          schemas: props.collection.schemas,
+          authorizations: [],
+        },
+      },
+    });
+    linkRelatedModels({
+      application: props.application,
+      document: {
+        operations: props.operations,
+        components: {
+          schemas: props.collection.schemas,
+          authorizations: [],
+        },
+      },
+    });
+  };
+
+  export const removeUnused = (props: {
+    operations: AutoBeOpenApi.IOperation[];
+    schemas: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive>;
+  }): void => {
+    while (true) {
+      const used: Set<string> = new Set();
+      const visit = (schema: AutoBeOpenApi.IJsonSchema): void =>
+        OpenApiTypeChecker.visit({
+          components: { schemas: props.schemas },
+          schema,
+          closure: (next) => {
+            if (OpenApiTypeChecker.isReference(next)) {
+              const key: string = next.$ref.split("/").pop()!;
+              used.add(key);
+            }
+          },
+        });
+      for (const op of props.operations) {
+        if (op.requestBody !== null)
+          visit({
+            $ref: `#/components/schemas/${op.requestBody.typeName}`,
+          });
+        if (op.responseBody !== null)
+          visit({
+            $ref: `#/components/schemas/${op.responseBody.typeName}`,
+          });
+      }
+
+      const complete: boolean =
+        Object.keys(props.schemas).length === 0 ||
+        Object.keys(props.schemas).every((key) => used.has(key) === true);
+      if (complete === true) break;
+      for (const key of Object.keys(props.schemas))
+        if (used.has(key) === false) delete props.schemas[key];
+    }
+  };
+
+  const removeDuplicated = (props: {
+    operations: AutoBeOpenApi.IOperation[];
+    collection: AutoBeJsonSchemaCollection;
+  }): void => {
+    // gather duplicated schemas
+    const correct: Map<string, string> = new Map();
+    for (const key of Object.keys(props.collection.schemas)) {
+      if (key.includes(".") === false) continue;
+      const dotRemoved: string = key.replace(".", "");
+      if (props.collection.schemas[dotRemoved] === undefined) continue;
+      correct.set(dotRemoved, key);
+    }
+
+    // fix operations' references
+    for (const op of props.operations) {
+      if (op.requestBody && correct.has(op.requestBody.typeName))
+        op.requestBody.typeName = correct.get(op.requestBody.typeName)!;
+      if (op.responseBody && correct.has(op.responseBody.typeName))
+        op.responseBody.typeName = correct.get(op.responseBody.typeName)!;
+    }
+
+    // fix schemas' references
+    const $refChangers: Map<OpenApi.IJsonSchema, () => void> = new Map();
+    for (const value of Object.values(props.collection.schemas))
+      OpenApiTypeChecker.visit({
+        components: { schemas: props.collection.schemas },
+        schema: value,
+        closure: (next) => {
+          if (OpenApiTypeChecker.isReference(next) === false) return;
+          const x: string = next.$ref.split("/").pop()!;
+          const y: string | undefined = correct.get(x);
+          if (y === undefined) return;
+          $refChangers.set(
+            next,
+            () => (next.$ref = `#/components/schemas/${y}`),
+          );
+        },
+      });
+    for (const fn of $refChangers.values()) fn();
+
+    // remove duplicated schemas
+    for (const key of correct.keys()) props.collection.delete(key);
+  };
+
+  const fixTimestamps = (props: {
+    document: AutoBeOpenApi.IDocument;
+    application: AutoBeDatabase.IApplication;
+  }): void => {
+    const entireModels: AutoBeDatabase.IModel[] = props.application.files
+      .map((f) => f.models)
+      .flat();
+    for (const value of Object.values(props.document.components.schemas)) {
+      if (AutoBeOpenApiTypeChecker.isObject(value) === false) continue;
+
+      const model: AutoBeDatabase.IModel | undefined = value[
+        "x-autobe-database-schema"
+      ]
+        ? entireModels.find((m) => m.name === value["x-autobe-database-schema"])
+        : undefined;
+      if (model === undefined) continue;
+
+      const properties: string[] = Object.keys(value.properties);
+      for (const key of properties) {
+        if (
+          key !== "created_at" &&
+          key !== "updated_at" &&
+          key !== "deleted_at"
+        )
+          continue;
+        const column: AutoBeDatabase.IPlainField | undefined =
+          model.plainFields.find((c) => c.name === key);
+        if (column === undefined) delete value.properties[key];
+      }
+    }
+  };
+
+  const linkRelatedModels = (props: {
+    document: AutoBeOpenApi.IDocument;
+    application: AutoBeDatabase.IApplication;
+  }): void => {
+    const modelDict: Set<string> = new Set(
+      props.application.files
+        .map((f) => f.models)
+        .flat()
+        .map((m) => m.name),
+    );
+    for (const [key, value] of Object.entries(
+      props.document.components.schemas,
+    )) {
+      if (
+        AutoBeOpenApiTypeChecker.isObject(value) === false ||
+        !!value["x-autobe-database-schema"]?.length
+      )
+        continue;
+
+      const typeName: string = key.split(".")[0]!.substring(1);
+      const modelName: string =
+        AutoBeInterfaceSchemaProgrammer.getDatabaseSchemaName(typeName);
+      if (modelDict.has(modelName) === true)
+        value["x-autobe-database-schema"] = modelName;
+    }
+  };
+
+  /* -----------------------------------------------------------
+    PAGINATION
+  ----------------------------------------------------------- */
+  export const writePageSchema = (
+    key: string,
+  ): AutoBeOpenApi.IJsonSchemaDescriptive.IObject => ({
+    type: "object",
+    properties: {
+      pagination: {
+        "x-autobe-specification": "Pagination information for the page.",
+        description: "Page information.",
+        $ref: "#/components/schemas/IPage.IPagination",
+      },
+      data: {
+        "x-autobe-specification": `List of records of type ${key}.`,
+        description: "List of records.",
+        type: "array",
+        items: {
+          $ref: `#/components/schemas/${key}`,
+        },
+      },
+    },
+    required: ["pagination", "data"],
+    description: StringUtil.trim`
+      A page.
+  
+      Collection of records with pagination information.
+    `,
+    "x-autobe-specification": `A page containing records of type ${key}.`,
+    "x-autobe-database-schema": null, // filled by relation review agent
+  });
+
+  // export const fixPage = (path: string, input: unknown): void => {
+  //   if (isRecord(input) === false || isRecord(input[path]) === false) return;
+  //   if (input[path].description) delete input[path].description;
+  //   if (input[path].required) delete input[path].required;
+
+  //   for (const key of Object.keys(input[path]))
+  //     if (DEFAULT_SCHEMAS[key] !== undefined)
+  //       input[path][key] = DEFAULT_SCHEMAS[key];
+  //     else if (AutoBeJsonSchemaValidator.isPage(key) === true) {
+  //       const data: string = key.substring("IPage".length);
+  //       input[path][key] = writePageSchema(data);
+  //     }
+  // };
+
+  export const getPageName = (key: string): string =>
+    key.substring("IPage".length);
+
+  // const isRecord = (input: unknown): input is Record<string, unknown> =>
+  //   typeof input === "object" && input !== null;
+
+  export const DEFAULT_SCHEMAS = (() => {
+    const init: Record<string, AutoBeOpenApi.IJsonSchemaDescriptive> =
+      (typia.json.schemas<
+        [IPage.IPagination, IPage.IRequest, IAuthorizationToken, IEntity]
+      >().components?.schemas ?? {}) as Record<
+        string,
+        AutoBeOpenApi.IJsonSchemaDescriptive
+      >;
+    for (const value of Object.values(init))
+      AutoBeOpenApiTypeChecker.visit({
+        components: {
+          schemas: init,
+          authorizations: [],
+        },
+        schema: value,
+        closure: (next) => {
+          if (AutoBeOpenApiTypeChecker.isObject(next)) {
+            next["x-autobe-database-schema"] = null;
+          }
+        },
+      });
+    return init;
+  })();
+
+  /* -----------------------------------------------------------
+    PLUGIN
+  ----------------------------------------------------------- */
+  export const fixDesign = (
+    design: AutoBeInterfaceSchemaDesign,
+  ): AutoBeOpenApi.IJsonSchema => {
+    const emended: AutoBeOpenApi.IJsonSchema = fixSchema(design.schema);
+    const final: AutoBeOpenApi.IJsonSchema = {
+      ...emended,
+      ...({
+        description: design.description,
+        "x-autobe-specification": design.specification,
+      } satisfies Pick<
+        AutoBeOpenApi.IJsonSchemaDescriptive,
+        "description" | "x-autobe-specification"
+      >),
+    };
+    if (AutoBeOpenApiTypeChecker.isObject(final))
+      final["x-autobe-database-schema"] = design.databaseSchema;
+    return final;
+  };
+
+  export const fixSchema = <Schema extends AutoBeOpenApi.IJsonSchema>(
+    schema: Schema,
+  ): Schema => {
+    const id: string = v7();
+    const emended: AutoBeOpenApi.IJsonSchema = (
+      (OpenApiConverter.upgradeComponents({
+        schemas: {
+          [id]: schema,
+        },
+      }).schemas ?? {}) as Record<string, AutoBeOpenApi.IJsonSchema>
+    )[id];
+
+    const visited: WeakSet<object> = new WeakSet();
+    if (AutoBeOpenApiTypeChecker.isObject(emended)) {
+      visited.add(emended);
+      for (const v of Object.values(emended.properties)) visited.add(v);
+    }
+
+    AutoBeOpenApiTypeChecker.visit({
+      components: {
+        authorizations: [],
+        schemas: {},
+      },
+      schema: emended,
+      closure(next) {
+        if (visited.has(next) === false)
+          for (const k of Object.keys(next))
+            if (k.startsWith("x-")) {
+              // biome-ignore lint: intended
+              delete (next as any)[k];
+            }
+        if (AutoBeOpenApiTypeChecker.isString(next)) fixStringSchema(next);
+        else if (AutoBeOpenApiTypeChecker.isArray(next)) fixArraySchema(next);
+        else if (AutoBeOpenApiTypeChecker.isInteger(next))
+          fixIntegerSchema(next);
+        else if (AutoBeOpenApiTypeChecker.isNumber(next)) fixNumberSchema(next);
+      },
+    });
+
+    const result: Schema = emended as Schema;
+    if (AutoBeOpenApiTypeChecker.isObject(result))
+      for (const [key, value] of Object.entries(result.properties)) {
+        if (key !== "id" && key.endsWith("_id") === false) continue;
+        else if (AutoBeOpenApiTypeChecker.isString(value))
+          fixReferenceIdSchema(value);
+        else if (AutoBeOpenApiTypeChecker.isOneOf(value)) {
+          const str: AutoBeOpenApi.IJsonSchema.IString | undefined =
+            value.oneOf.find((v) => AutoBeOpenApiTypeChecker.isString(v));
+          if (str !== undefined) fixReferenceIdSchema(str);
+        }
+      }
+    return result;
+  };
+
+  const convertConst = (
+    schema:
+      | AutoBeOpenApi.IJsonSchema.INumber
+      | AutoBeOpenApi.IJsonSchema.IInteger,
+    value: number,
+  ): void => {
+    // biome-ignore lint: @todo
+    const description: string | undefined = (schema as any).description;
+
+    for (const key of Object.keys(schema)) {
+      // biome-ignore lint: @todo
+      delete (schema as any)[key];
+    }
+
+    // biome-ignore lint: @todo
+    (schema as any).const = value;
+    if (description !== undefined) {
+      // biome-ignore lint: @todo
+      (schema as any).description = description;
+    }
+  };
+
+  const fixStringSchema = (schema: AutoBeOpenApi.IJsonSchema.IString): void => {
+    if (schema.format !== undefined) {
+      delete schema.pattern;
+      if (
+        schema.format === "uuid" ||
+        schema.format === "ipv4" ||
+        schema.format === "ipv6" ||
+        schema.format === "date" ||
+        schema.format === "date-time" ||
+        schema.format === "time"
+      ) {
+        delete schema.minLength;
+        delete schema.maxLength;
+        delete schema.contentMediaType;
+      }
+    }
+    if (schema.contentMediaType === "") delete schema.contentMediaType;
+    if (schema.minLength === 0) delete schema.minLength;
+  };
+
+  const fixArraySchema = (schema: AutoBeOpenApi.IJsonSchema.IArray): void => {
+    if (schema.minItems === 0) delete schema.minItems;
+  };
+
+  /**
+   * Fix integer schema by converting single valid value ranges to const.
+   *
+   * Handles:
+   *
+   * - Minimum === maximum → const
+   * - Minimum: N, exclusiveMaximum: N+1 → const N
+   * - ExclusiveMinimum: N-1, maximum: N → const N
+   * - ExclusiveMinimum: N-1, exclusiveMaximum: N+1 → const N
+   */
+  const fixIntegerSchema = (
+    schema: AutoBeOpenApi.IJsonSchema.IInteger,
+  ): void => {
+    const value: number | undefined = (() => {
+      if (schema.minimum !== undefined && schema.maximum === schema.minimum)
+        return schema.minimum;
+      if (
+        schema.minimum !== undefined &&
+        schema.exclusiveMaximum === schema.minimum + 1
+      )
+        return schema.minimum;
+      if (
+        schema.maximum !== undefined &&
+        schema.exclusiveMinimum === schema.maximum - 1
+      )
+        return schema.maximum;
+      if (
+        schema.exclusiveMinimum !== undefined &&
+        schema.exclusiveMaximum === schema.exclusiveMinimum + 2
+      )
+        return schema.exclusiveMinimum + 1;
+      return undefined;
+    })();
+
+    if (value !== undefined) convertConst(schema, value);
+  };
+
+  /**
+   * Fix number schema by converting single valid value ranges to const.
+   *
+   * Handles:
+   *
+   * - Minimum === maximum → const
+   */
+  const fixNumberSchema = (schema: AutoBeOpenApi.IJsonSchema.INumber): void => {
+    // minimum === maximum → const
+    if (
+      schema.minimum !== undefined &&
+      schema.maximum !== undefined &&
+      schema.minimum === schema.maximum
+    )
+      return convertConst(schema, schema.minimum);
+  };
+
+  const fixReferenceIdSchema = (
+    schema: AutoBeOpenApi.IJsonSchema.IString,
+  ): void => {
+    schema.format = "uuid";
+    fixStringSchema(schema);
+  };
+}
+
+namespace IPage {
+  /**
+   * Pagination metadata containing current page position and total data
+   * statistics.
+   *
+   * This interface provides comprehensive pagination information returned
+   * alongside paginated list data. It enables clients to implement navigation
+   * controls, display progress indicators, and determine data boundaries for UI
+   * rendering.
+   *
+   * @x-autobe-specification Pagination metadata for paginated list responses. Included in all list endpoint responses.
+   */
+  export interface IPagination {
+    /**
+     * Current page number being viewed (1-indexed).
+     *
+     * Indicates which page of results is currently being returned. Page
+     * numbering starts from 1, so the first page is page 1 (not 0). This value
+     * reflects the page parameter from the request after validation and bounds
+     * checking.
+     *
+     * @x-autobe-specification 1-indexed current page number. Defaults to 1.
+     */
+    current: number & tags.Type<"uint32">;
+
+    /**
+     * Maximum number of records per page.
+     *
+     * Defines the upper bound on how many records can be returned in a single
+     * page. This corresponds to the limit parameter from the request. The
+     * actual number of records in the data array may be less than this value on
+     * the final page or when total records are fewer than the limit.
+     *
+     * @x-autobe-specification Maximum records per page. Actual count may be less on last page.
+     */
+    limit: number & tags.Type<"uint32">;
+
+    /**
+     * Total count of all records matching the query criteria.
+     *
+     * Represents the complete number of records available across all pages, not
+     * just the current page. This value is computed via a COUNT query and is
+     * essential for calculating total pages and displaying pagination UI
+     * elements like "Showing 1-10 of 150 results".
+     *
+     * @x-autobe-specification Total record count across all pages.
+     */
+    records: number & tags.Type<"uint32">;
+
+    /**
+     * Total number of pages available.
+     *
+     * Calculated as ceiling of {@link records} divided by {@link limit}. When
+     * records is 0, pages will also be 0. This value enables clients to render
+     * page navigation controls and validate page bounds.
+     *
+     * @x-autobe-specification Total pages. Calculated as Math.ceil(records / limit).
+     */
+    pages: number & tags.Type<"uint32">;
+  }
+
+  /**
+   * Pagination request parameters for list endpoints.
+   *
+   * Defines the query parameters used to control pagination when requesting
+   * list data. Both parameters are optional with sensible defaults, allowing
+   * clients to fetch data without specifying pagination if default behavior is
+   * acceptable.
+   *
+   * @x-autobe-specification Pagination query parameters for list endpoints. All fields optional.
+   */
+  export interface IRequest {
+    /**
+     * Target page number to retrieve (1-indexed).
+     *
+     * Specifies which page of results to return. Page numbering starts from 1.
+     * If omitted, null, or undefined, defaults to page 1 (first page).
+     * Requesting a page beyond the available range returns an empty data array
+     * with valid pagination metadata reflecting the actual totals.
+     *
+     * @x-autobe-specification 1-indexed page number. Defaults to 1 if not provided.
+     */
+    page?: null | (number & tags.Type<"uint32">);
+
+    /**
+     * Maximum number of records to return per page.
+     *
+     * Controls how many records are included in each page response. If omitted,
+     * null, or undefined, defaults to 100 records per page. The server may
+     * enforce upper bounds to prevent excessive resource consumption on large
+     * requests.
+     *
+     * @default 100
+     *
+     * @x-autobe-specification Maximum records per page. Defaults to 100 if not provided.
+     */
+    limit?: null | (number & tags.Type<"uint32">);
+  }
+}
+
+/**
+ * JWT-based authorization token pair with expiration metadata.
+ *
+ * Provides a complete authentication token structure containing both access and
+ * refresh tokens along with their respective expiration timestamps. This
+ * dual-token pattern enables secure, stateless authentication with automatic
+ * session renewal capabilities.
+ *
+ * The access token is short-lived for security, while the refresh token allows
+ * obtaining new access tokens without requiring the user to re-enter
+ * credentials. This structure is automatically included in authentication
+ * responses across all generated backend applications.
+ *
+ * @x-autobe-specification Dual-token authentication structure with access/refresh tokens and expiration info.
+ */
+interface IAuthorizationToken {
+  /**
+   * Short-lived JWT access token for authenticating API requests.
+   *
+   * This token must be included in the Authorization header using the Bearer
+   * scheme (e.g., `Authorization: Bearer {access}`) for all endpoints requiring
+   * authentication. The token contains encoded claims including user identity,
+   * roles, and permissions. Typically expires within 15-60 minutes for
+   * security; use the refresh token to obtain a new access token when expired.
+   *
+   * @x-autobe-specification JWT access token. Use in Authorization header as "Bearer {access}".
+   */
+  access: string;
+
+  /**
+   * Long-lived refresh token for obtaining new access tokens.
+   *
+   * Used to request new access tokens when the current access token expires,
+   * allowing session continuation without re-authentication. Should be stored
+   * securely and transmitted only to the token refresh endpoint. Typical
+   * lifetime ranges from 7 to 30 days depending on security requirements.
+   *
+   * @x-autobe-specification Refresh token for obtaining new access tokens without re-authentication.
+   */
+  refresh: string;
+
+  /**
+   * ISO 8601 timestamp when the access token expires.
+   *
+   * After this timestamp, the access token will be rejected by authenticated
+   * endpoints. Clients should proactively refresh before expiration to maintain
+   * seamless user experience. A common strategy is to refresh when remaining
+   * time falls below 5 minutes. This timestamp is also embedded within the JWT
+   * itself as the "exp" claim.
+   *
+   * @x-autobe-specification Access token expiration timestamp in ISO 8601 format.
+   */
+  expired_at: string & tags.Format<"date-time">;
+
+  /**
+   * ISO 8601 timestamp indicating the absolute session expiration deadline.
+   *
+   * Represents the latest possible time the refresh token can be used. Once
+   * this timestamp is reached, the user must fully re-authenticate with
+   * credentials. This defines the maximum session duration regardless of
+   * activity. If refresh token rotation is enabled, this deadline may extend
+   * with each successful refresh.
+   *
+   * @x-autobe-specification Refresh token expiration timestamp. Re-authentication required after this time.
+   */
+  refreshable_until: string & tags.Format<"date-time">;
+}
+
+/**
+ * Base entity interface providing standard primary key identification.
+ *
+ * Serves as the foundational interface for all database entities in the
+ * generated application. Every model and record type extends this interface,
+ * ensuring consistent identification semantics across all database tables and
+ * API responses.
+ *
+ * @x-autobe-specification Base interface for all database entities. Contains the primary key.
+ */
+interface IEntity {
+  /**
+   * Unique identifier for this entity (UUID format).
+   *
+   * Auto-generated primary key using UUID format. This value is assigned by the
+   * system upon record creation and cannot be modified afterward. All foreign
+   * key relationships in the database reference this field.
+   *
+   * @x-autobe-specification Primary key in UUID format. Auto-generated, read-only.
+   */
+  id: string & tags.Format<"uuid">;
+}