@lyku/lockstep-core 0.2.1

package/LLMs.md

@@ -0,0 +1,979 @@
+# @lyku/lockstep-core — LLM Reference
+
+This document is a complete mechanical reference for the `@lyku/lockstep-core` library. It contains exact type signatures, exhaustive enum values, mapping rules, generated output examples, and edge cases needed to correctly generate code that uses this framework.
+
+## Pipeline overview
+
+```
+pg-models (PostgresRecordModel)
+    ↓ generateJsonModels
+json-models (JSON schemas + TypeScript types + Insertable types)
+    ↓ generateDbTypes
+db-types (Kysely Database interface)
+
+mapi-models (TsonHandlerModel)
+    ↓ generateApiTypes
+mapi-types (Request/Response TypeScript types)
+    ↓ generateHandles
+handles (Handler factories with validators)
+    ↓ generateClient
+monolith-ts-api (Type-safe HTTP + WebSocket client with MessagePack)
+```
+
+---
+
+## 1. PostgreSQL column types
+
+### PostgresColumnBase (all columns inherit this)
+
+```typescript
+type PostgresColumnBase = {
+	readonly unique?: boolean;
+	readonly primaryKey?: boolean;
+	readonly generated?: {
+		readonly always?: boolean;
+		readonly as: string;
+		readonly from?: string;
+		readonly stored?: boolean;
+	};
+	readonly checks?: string[];
+	readonly description?: string;
+	readonly title?: string;
+};
+```
+
+### Complete column type list
+
+Every column model extends `PostgresColumnBase`. The `type` field is the discriminant.
+
+| Column model             | `type` values                            | Extra fields                                                                                                | → Schema                                | → Kysely            | → TypeScript |
+| ------------------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------- | ------------------- | ------------ |
+| `BigIntColumnModel`      | `'bigint'`, `'int8'`                     | `minimum?, maximum?, exclusiveMinimum?, exclusiveMaximum?, multipleOf?, default?, examples?` (all `bigint`) | `{ type: 'bigint' }`                    | `bigint`            | `bigint`     |
+| `BigSerialColumnModel`   | `'bigserial'`, `'serial8'`               | same as BigInt                                                                                              | `{ type: 'bigint', default: -1n }`      | `Generated<bigint>` | `bigint`     |
+| `IntegerColumnModel`     | `'integer'`, `'int'`, `'int2'`, `'int4'` | `minimum?, maximum?, exclusiveMinimum?, exclusiveMaximum?, multipleOf?, default?, examples?` (all `number`) | `{ type: 'number' }`                    | `number`            | `number`     |
+| `SmallIntColumnModel`    | `'smallint'`, `'int2'`                   | same as Integer                                                                                             | `{ type: 'number' }`                    | `number`            | `number`     |
+| `SerialColumnModel`      | `'serial'`, `'serial4'`                  | same as Integer                                                                                             | `{ type: 'number', default: -1 }`       | `Generated<number>` | `number`     |
+| `SmallSerialColumnModel` | `'smallserial'`, `'serial2'`             | same as Integer                                                                                             | `{ type: 'number', default: -1 }`       | `Generated<number>` | `number`     |
+| `RealColumnModel`        | `'real'`, `'float4'`                     | same as Integer                                                                                             | `{ type: 'number' }`                    | `number`            | `number`     |
+| `DoubleColumnModel`      | `'double precision'`, `'float8'`         | same as Integer                                                                                             | `{ type: 'number' }`                    | `number`            | `number`     |
+| `NumericColumnModel`     | `'numeric'`                              | same as Integer + `precision?, scale?`                                                                      | `{ type: 'number' }`                    | `number`            | `number`     |
+| `MoneyColumnModel`       | `'money'`                                | same as Integer                                                                                             | `{ type: 'number' }`                    | `number`            | `number`     |
+| `BooleanColumnModel`     | `'boolean'`, `'bool'`                    | `default?: boolean, examples?`                                                                              | `{ type: 'boolean' }`                   | `boolean`           | `boolean`    |
+| `TextColumnModel`        | `'text'`                                 | `minLength?, maxLength?, pattern?, enum?, default?`                                                         | `{ type: 'string' }`                    | `string`            | `string`     |
+| `VarcharColumnModel`     | `'varchar'`, `'character varying'`       | `minLength?, maxLength?, pattern?, enum?, default?`                                                         | `{ type: 'string' }`                    | `string`            | `string`     |
+| `CharColumnModel`        | `'char'`, `'character'`, `'bpchar'`      | `length, pattern?, enum?`                                                                                   | `{ type: 'string' }`                    | `string`            | `string`     |
+| `DateColumnModel`        | `'date'`                                 | `default?, minimum?, maximum?`                                                                              | `{ type: 'date' }`                      | `Date`              | `Date`       |
+| `Timestamp`              | `'timestamp'`                            | `timezone?, precision?, default?, minimum?, maximum?`                                                       | `{ type: 'date' }`                      | `Date`              | `Date`       |
+| `Timestamptz`            | `'timestamptz'`                          | same as Timestamp                                                                                           | `{ type: 'date' }`                      | `Date`              | `Date`       |
+| `TimeColumnModel`        | `'time'`                                 | `timezone?, precision?`                                                                                     | `{ type: 'date' }`                      | `Date`              | `Date`       |
+| `EnumColumnModel`        | `'enum'`                                 | `enum: readonly string[]`                                                                                   | preserved                               | `string`            | `string`     |
+| `ArrayColumnModel`       | `'array'`                                | `items: PostgresColumnModel, minItems?, maxItems?`                                                          | `{ type: 'array', items: <recursive> }` | recursive           | recursive    |
+| `JsonbColumnModel`       | `'jsonb'`                                | `schema?: JsonSchema`                                                                                       | schema or `{ type: 'object' }`          | `unknown` or typed  | varies       |
+| `ByteaColumnModel`       | `'bytea'`                                | none                                                                                                        | —                                       | `Buffer`            | `Buffer`     |
+| `PointColumnModel`       | `'point'`                                | none                                                                                                        | —                                       | —                   | —            |
+
+### PostgresColumnModel (union of all above)
+
+```typescript
+type PostgresColumnModel = ArrayColumnModel | BigIntColumnModel | BigSerialColumnModel | BooleanColumnModel | ByteaColumnModel | CharColumnModel | DateColumnModel | DoubleColumnModel | EnumColumnModel | IntegerColumnModel | JsonbColumnModel | MoneyColumnModel | NumericColumnModel | PointColumnModel | RealColumnModel | SmallIntColumnModel | SmallSerialColumnModel | SerialColumnModel | TextColumnModel | TimeColumnModel | Timestamp | Timestamptz | VarcharColumnModel;
+```
+
+---
+
+## 2. PostgreSQL record and table models
+
+### PostgresRecordModel
+
+```typescript
+type PostgresRecordModel = PostgresRecordModelWithoutRequired | PostgresRecordModelWithRequired;
+
+type PostgresRecordModelWithoutRequired = {
+	readonly properties: Record<string, PostgresColumnModel>;
+	readonly minProperties?: number;
+	readonly maxProperties?: number;
+	readonly default?: Record<string, unknown>;
+	readonly examples?: Record<string, unknown>[];
+	readonly additionalProperties?: false | PostgresColumnModel;
+	readonly description?: string;
+	readonly title?: string;
+};
+
+type PostgresRecordModelWithRequired = PostgresRecordModelWithoutRequired & {
+	readonly required: readonly string[];
+};
+```
+
+**Critical rule**: Properties listed in `required` become non-optional in the generated TypeScript type. Properties NOT in `required` become optional (`?`). If `required` is omitted entirely, ALL properties are optional.
+
+### PostgresTableModel
+
+```typescript
+type PostgresTableModel<S extends PostgresRecordModel> = {
+	readonly schema: S;
+	readonly indexes?: IndexesOf<S>;
+	readonly primaryKey?: keyof S['properties'] | readonly (keyof S['properties'])[];
+	readonly foreignKeys?: Partial<Record<keyof S['properties'], { readonly [key: string]: string }>>;
+	readonly triggers?: readonly PostgresTriggerModel[];
+	readonly unique?: keyof S['properties'] | readonly (keyof S['properties'])[];
+	readonly docs?: any[];
+};
+```
+
+### Example: defining a pg-model
+
+```typescript
+import type { PostgresRecordModel } from '@lyku/lockstep-core';
+
+export const friendship = {
+	properties: {
+		id: { type: 'bigserial' },
+		created: { type: 'timestamptz', default: { sql: 'CURRENT_TIMESTAMP' } },
+		users: { type: 'array', items: { type: 'bigint' }, minItems: 2, maxItems: 2 },
+		deleted: { type: 'timestamptz' },
+	},
+	required: ['created', 'id', 'users'],
+} as const satisfies PostgresRecordModel;
+```
+
+Always use `as const satisfies PostgresRecordModel` — the `as const` preserves literal types needed by the generators.
+
+---
+
+## 3. Schema types
+
+The from-schema type system is the intermediate schema language used by API models and json-models.
+
+### TsonSchema (union)
+
+```typescript
+type TsonSchema = ArrayTsonSchema | BooleanTsonSchema | EnumTsonSchema | DateTsonSchema | MapTsonSchema | NumberTsonSchema | ObjectTsonSchema | StringTsonSchema | UnionTsonSchema | ExclusiveTsonSchema | IntersectionTsonSchema | BigIntTsonSchema | RefTsonSchema;
+
+type TsonSchemaOrPrimitive = TsonSchema | string | number | boolean | bigint | string[];
+```
+
+### Individual schemas with all fields
+
+**StringTsonSchema**:
+
+```typescript
+type StringTsonSchema = {
+	readonly type: 'string';
+	readonly format?: 'date' | 'time' | 'date-time' | 'email' | 'hostname' | 'ipv4' | 'ipv6' | 'uri' | 'uri-reference' | 'uuid' | 'uri-template' | 'json-pointer' | 'relative-json-pointer' | 'regex';
+	readonly minLength?: number;
+	readonly maxLength?: number;
+	readonly pattern?: string;
+	readonly const?: string; // If present, becomes a literal type
+	readonly examples?: string[];
+	readonly description?: string;
+	readonly title?: string;
+};
+```
+
+→ TypeScript: `string` (or `"literal"` if `const` is set)
+
+**NumberTsonSchema**:
+
+```typescript
+type NumberTsonSchema = {
+	readonly type: 'number' | 'integer'; // Both map to `number` in TS
+	readonly minimum?: number;
+	readonly maximum?: number;
+	readonly default?: number;
+	readonly const?: number;
+	readonly examples?: number[];
+	readonly description?: string;
+	readonly title?: string;
+};
+```
+
+→ TypeScript: `number`
+
+**BigIntTsonSchema**:
+
+```typescript
+type BigIntTsonSchema = {
+	readonly type: 'bigint';
+	readonly minimum?: bigint;
+	readonly maximum?: bigint;
+	readonly default?: bigint;
+	readonly const?: bigint;
+	readonly examples?: bigint[];
+	readonly description?: string;
+	readonly title?: string;
+};
+```
+
+→ TypeScript: `bigint`
+
+**BooleanTsonSchema**:
+
+```typescript
+type BooleanTsonSchema = {
+	readonly type: 'boolean';
+	readonly default?: boolean;
+	readonly const?: boolean;
+	readonly examples?: boolean[];
+	readonly description?: string;
+	readonly title?: string;
+};
+```
+
+→ TypeScript: `boolean`
+
+**DateTsonSchema**:
+
+```typescript
+type DateTsonSchema = {
+	readonly type: 'date';
+	readonly minimum?: Date;
+	readonly maximum?: Date;
+	readonly const?: Date;
+	readonly description?: string;
+	readonly title?: string;
+};
+```
+
+→ TypeScript: `Date`
+
+**ArrayTsonSchema**:
+
+```typescript
+type ArrayTsonSchema = {
+	readonly type: 'array';
+	readonly items: TsonSchemaOrPrimitive;
+	readonly maxItems?: number;
+	readonly minItems?: number;
+	readonly uniqueItems?: boolean;
+	readonly default?: unknown[];
+	readonly examples?: unknown[][];
+	readonly description?: string;
+	readonly title?: string;
+};
+```
+
+→ TypeScript: `Array<T>` where T is the items schema converted
+
+**ObjectTsonSchema**:
+
+```typescript
+type ObjectTsonSchema = {
+	readonly type: 'object';
+	readonly properties?: Record<string, TsonSchemaOrPrimitive>;
+	readonly required?: readonly string[]; // ← CRITICAL: determines optional vs required
+	readonly minProperties?: number;
+	readonly maxProperties?: number;
+	readonly default?: Record<string, unknown>;
+	readonly examples?: Record<string, unknown>[];
+	readonly additionalProperties?: false | TsonSchemaOrPrimitive;
+	readonly patternProperties?: false | Record<string, TsonSchemaOrPrimitive>;
+	readonly description?: string;
+	readonly title?: string;
+};
+```
+
+→ TypeScript: `{ key: Type; optionalKey?: Type; ... }`
+
+**CRITICAL**: If `required` is omitted or empty, ALL properties become optional (`?`) in the generated type. This is the #1 source of type mismatches between handlers and generated types.
+
+**EnumTsonSchema**:
+
+```typescript
+type EnumTsonSchema = {
+	readonly enum: readonly (string | number)[];
+	readonly description?: string;
+	readonly title?: string;
+};
+```
+
+→ TypeScript: `'value1' | 'value2' | ...`
+
+**UnionTsonSchema** (`anyOf`):
+
+```typescript
+type UnionTsonSchema = {
+	readonly anyOf: readonly TsonSchemaOrPrimitive[];
+	readonly description?: string;
+	readonly default?: unknown;
+};
+```
+
+→ TypeScript: `(A | B | C)`
+
+**ExclusiveTsonSchema** (`oneOf`):
+
+```typescript
+type ExclusiveTsonSchema = {
+	readonly oneOf: readonly TsonSchemaOrPrimitive[];
+	readonly description?: string;
+	readonly default?: unknown;
+};
+```
+
+→ TypeScript: `(A | B | C)` (same as union at type level; validated differently at runtime)
+
+**IntersectionTsonSchema** (`allOf`):
+
+```typescript
+type IntersectionTsonSchema = {
+	readonly allOf: readonly TsonSchemaOrPrimitive[];
+	readonly description?: string;
+	readonly default?: unknown;
+};
+```
+
+→ TypeScript: `(A & B & C)`
+
+**MapTsonSchema**:
+
+```typescript
+type MapTsonSchema = {
+	readonly type: 'map';
+	readonly keys: StringTsonSchema | EnumTsonSchemaOf<string>;
+	readonly values: TsonSchema;
+	readonly partial?: boolean;
+	readonly default?: Record<string, unknown>;
+};
+```
+
+→ TypeScript: `Record<string, V>` or `Partial<Record<K, V>>`
+
+**RefTsonSchema**:
+
+```typescript
+type RefTsonSchema = { $ref: string };
+```
+
+→ TypeScript: `any` (work in progress)
+
+---
+
+## 4. API handler models
+
+### TsonHandlerModel (union)
+
+```typescript
+type TsonHandlerModel = TsonHttpHandlerModel | TsonStreamHandlerModel;
+```
+
+### TsonHttpHandlerModel
+
+```typescript
+type TsonHttpHandlerModel = Readonly<
+	| GetHandlerModel // { method: 'GET' }
+	| PostHandlerModel // { method: 'POST', request?: TsonSchema }
+	| PutHandlerModel // { method: 'PUT', request?: TsonSchema }
+	| DeleteHandlerModel // { method: 'DELETE', request?: TsonSchema }
+	| PatchHandlerModel // { method: 'PATCH', request?: TsonSchema }
+	| OptionsHandlerModel // { method: 'OPTIONS' }
+	| HeadHandlerModel // { method: 'HEAD' }
+	| VagueHandlerModel // no method, { request?: TsonSchema }
+>;
+```
+
+Most endpoints in the codebase use `VagueHandlerModel` (no `method` field). The default HTTP method is POST.
+
+### TsonStreamHandlerModel (WebSocket)
+
+```typescript
+type TsonStreamHandlerModel = Readonly<
+	TsonHandlerBase & {
+		readonly stream:
+			| true
+			| {
+					readonly tweakRequest?: TsonSchema;
+					readonly tweakResponse?: TsonSchema;
+			  };
+	}
+>;
+```
+
+When `stream` is present, the generated handle uses `onOpen` instead of `execute`, and the context type is `SocketContext` instead of `HttpContext`.
+
+### TsonHandlerBase (all fields)
+
+```typescript
+type TsonHandlerBase = {
+	readonly response?: TsonSchema;
+	readonly authenticated: boolean; // ← determines Secure vs MaybeSecure context
+	readonly throws?: readonly number[];
+	readonly path?: string; // override URL path (default: kebab-case of export name)
+
+	// Documentation (all optional)
+	readonly title?: string;
+	readonly description?: string;
+	readonly category?: string;
+	readonly tags?: readonly string[];
+	readonly since?: string;
+	readonly examples?: readonly {
+		readonly title: string;
+		readonly description?: string;
+		readonly request?: unknown;
+		readonly response?: unknown;
+		readonly status?: number;
+	}[];
+	readonly notes?: readonly string[];
+	readonly errors?: readonly {
+		readonly code: number;
+		readonly title: string;
+		readonly description: string;
+		readonly example?: unknown;
+		readonly resolution?: string;
+	}[];
+	readonly relatedEndpoints?: readonly string[];
+	readonly deprecated?: {
+		readonly since: string;
+		readonly useInstead?: string;
+		readonly reason?: string;
+	};
+	readonly rateLimit?: {
+		readonly requests: number;
+		readonly period: string;
+		readonly scope?: 'user' | 'ip' | 'global';
+	};
+	readonly requiredPermissions?: readonly string[];
+};
+```
+
+### Example: defining an HTTP endpoint
+
+```typescript
+import type { TsonHandlerModel } from '@lyku/lockstep-core';
+
+export const getServiceStatus = {
+	request: {
+		type: 'object',
+		properties: {
+			service: { type: 'string', maxLength: 50 },
+		},
+		required: ['service'],
+	},
+	response: {
+		type: 'object',
+		properties: {
+			name: { type: 'string' },
+			status: { type: 'string', enum: ['operational', 'degraded', 'outage'] },
+			uptime24h: { type: 'number' },
+		},
+		required: ['name', 'status', 'uptime24h'], // ← without this, all properties are optional
+	},
+	authenticated: false,
+	throws: [400, 404, 500],
+	title: 'Get Service Status',
+	category: 'Status',
+	since: '1.0.0',
+} as const satisfies TsonHandlerModel;
+```
+
+### Example: defining a WebSocket endpoint
+
+```typescript
+export const listenForAchievementGrants = {
+	request: {
+		type: 'object',
+		properties: { game: { type: 'number' } },
+		required: [],
+	},
+	response: {
+		type: 'array',
+		items: {
+			type: 'object',
+			properties: {
+				achievement: { type: 'bigint' },
+				user: { type: 'bigint' },
+				granted: { type: 'date' },
+			},
+			required: ['achievement', 'user', 'granted'],
+		},
+	},
+	stream: true,
+	authenticated: true,
+	throws: [400, 401, 404, 500],
+	title: 'Listen for Achievement Grants',
+	category: 'Games',
+	since: '1.0.0',
+} as const satisfies TsonHandlerModel;
+```
+
+---
+
+## 5. Handler contexts
+
+When implementing a route handler, the second argument is a typed context object. The context type is determined by:
+
+1. `authenticated: true` → `Secure*Context` (has `requester: bigint` and `session: string`)
+2. `authenticated: false` → `MaybeSecure*Context` (requester/session are optional)
+3. No `stream` field → `*HttpContext`
+4. `stream` field present → `*SocketContext`
+
+### Context type definitions
+
+```typescript
+type BaseContextFragment<Model extends TsonHandlerModel> = {
+	strings: Record<string, string>;
+	model: Model;
+	now: Date;
+};
+
+type SecurityContextFragment = {
+	requester: bigint;
+	session: string;
+};
+
+type HttpContextFragment = {
+	request: Request;
+	responseHeaders: Headers;
+};
+
+type SocketContextFragment<Types extends StreamTypes> = {
+	emit: (data: Types['response'] | Uint8Array) => void;
+	onClose: (closer: () => void) => void;
+	onTweak: (handler: (data: ExtractTweakRequest<Types>) => void) => void;
+};
+
+// HTTP
+type SecureHttpContext<Model> = BaseContextFragment<Model> & SecurityContextFragment & HttpContextFragment;
+type MaybeSecureHttpContext<Model> = BaseContextFragment<Model> & Partial<SecurityContextFragment> & HttpContextFragment;
+
+// Socket
+type SecureSocketContext<Model, Types> = BaseContextFragment<Model> & SecurityContextFragment & SocketContextFragment<Types>;
+type MaybeSecureSocketContext<Model, Types> = BaseContextFragment<Model> & Partial<SecurityContextFragment> & SocketContextFragment<Types>;
+```
+
+### Context fields reference
+
+| Field             | Type                     | Present in           | Description                       |
+| ----------------- | ------------------------ | -------------------- | --------------------------------- |
+| `requester`       | `bigint`                 | Secure contexts only | Authenticated user's ID           |
+| `session`         | `string`                 | Secure contexts only | Session token                     |
+| `request`         | `Request`                | HTTP contexts        | Raw HTTP Request object           |
+| `responseHeaders` | `Headers`                | HTTP contexts        | Mutable response headers          |
+| `emit`            | `(data) => void`         | Socket contexts      | Send data to the connected client |
+| `onClose`         | `(cb) => void`           | Socket contexts      | Register a disconnect callback    |
+| `onTweak`         | `(handler) => void`      | Socket contexts      | Handle mid-stream request changes |
+| `strings`         | `Record<string, string>` | All                  | Localized strings                 |
+| `model`           | `TsonHandlerModel`       | All                  | The endpoint's schema model       |
+| `now`             | `Date`                   | All                  | Timestamp of the request          |
+
+---
+
+## 6. Generated output (verbatim examples)
+
+### generateJsonModels output
+
+Input pg-model:
+
+```typescript
+export const accountDeletionRequest = {
+	properties: {
+		id: { type: 'bigserial' },
+		user: { type: 'bigint' },
+		requestedAt: { type: 'timestamptz', default: { sql: 'CURRENT_TIMESTAMP' } },
+		confirmationCode: { type: 'varchar', maxLength: 64 },
+		confirmedAt: { type: 'timestamptz' },
+	},
+	required: ['id', 'user', 'requestedAt', 'confirmationCode'],
+} as const satisfies PostgresRecordModel;
+```
+
+Generated `.d.ts`:
+
+```typescript
+export declare const accountDeletionRequest: {
+	type: 'object';
+	properties: {
+		id: { type: 'bigint' };
+		user: { type: 'bigint' };
+		requestedAt: { type: 'date'; default: { sql: 'CURRENT_TIMESTAMP' } };
+		confirmationCode: { type: 'string'; maxLength: 64 };
+		confirmedAt: { type: 'date' };
+	};
+	required: ['id', 'user', 'requestedAt', 'confirmationCode'];
+};
+export type AccountDeletionRequest = {
+	id: bigint;
+	user: bigint;
+	requestedAt: Date;
+	confirmationCode: string;
+	confirmedAt?: Date; // ← not in required, so optional
+};
+
+export type InsertableAccountDeletionRequest = {
+	id?: bigint; // ← all optional for inserts
+	user?: bigint;
+	requestedAt?: Date;
+	confirmationCode?: string;
+	confirmedAt?: Date;
+};
+```
+
+### generateDbTypes output
+
+Generated Kysely types:
+
+```typescript
+import { ColumnType, Generated, Insertable, JSONColumnType, Selectable, Updateable } from 'kysely';
+
+export type AccountDeletionRequests = {
+	id: Generated<bigint>; // ← bigserial → Generated<bigint>
+	user: bigint;
+	requestedAt: Date;
+	confirmationCode: string;
+	confirmedAt?: Date;
+	scheduledFor?: Date;
+	processedAt?: Date;
+	cancelled?: Date;
+};
+
+export type Achievements = {
+	description?: string;
+	id: bigint;
+	icon: string;
+	name: string;
+	points: number;
+	tier?: 'tin' | 'bronze' | 'silver' | 'gold' | 'tritium'; // ← enum preserved
+	game?: number;
+	created: Date;
+	updated?: Date;
+};
+
+// ... all tables ...
+
+export interface Database {
+	accountDeletionRequests: AccountDeletionRequests;
+	achievements: Achievements;
+	// ... all tables (pluralized names) ...
+}
+```
+
+**Table naming**: The generator pluralizes table names in the Database interface. `friendship` → `friendships`, `canaryMetric` → `canaryMetrics`. When using `pg.selectFrom()`, use the pluralized name.
+
+### generateApiTypes output
+
+```typescript
+export type AcceptFriendRequestRequest = bigint;
+export type AcceptFriendRequestResponse = void;
+
+export type CreateFriendRequestRequest = bigint;
+export type CreateFriendRequestResponse = { id: bigint };
+
+export type GetServiceStatusRequest = { service: string };
+export type GetServiceStatusResponse = {
+	name: string;
+	status: 'operational' | 'degraded' | 'outage';
+	uptime24h: number;
+};
+
+// Aggregate type map
+export type MonolithTypes = {
+	acceptFriendRequest: {
+		request: AcceptFriendRequestRequest;
+		response: AcceptFriendRequestResponse;
+	};
+	createFriendRequest: {
+		request: CreateFriendRequestRequest;
+		response: CreateFriendRequestResponse;
+	};
+	getServiceStatus: {
+		request: GetServiceStatusRequest;
+		response: GetServiceStatusResponse;
+	};
+	// ... all endpoints ...
+};
+```
+
+### generateHandles output
+
+For an HTTP endpoint (`authenticated: true`, no `stream`):
+
+**Generated `.d.ts`**:
+
+```typescript
+import { acceptFriendRequest } from '@lyku/mapi-models';
+import type { AcceptFriendRequestRequest } from '@lyku/mapi-types';
+import type { SecureHttpContext } from '@lyku/route-helpers';
+
+export declare const handleAcceptFriendRequest: (handler: (request: AcceptFriendRequestRequest, context: SecureHttpContext<typeof acceptFriendRequest>) => void | Promise<void>) => {
+	readonly execute: (request: AcceptFriendRequestRequest, context: SecureHttpContext<typeof acceptFriendRequest>) => void | Promise<void>;
+	readonly validator: {
+		validate: (request: unknown) => string[];
+		validateOrThrow: (request: unknown) => void;
+		isValid: (request: unknown) => string | true;
+	};
+	readonly model: typeof acceptFriendRequest;
+};
+```
+
+**Generated `.js`**:
+
+```javascript
+import { acceptFriendRequest } from '@lyku/mapi-models';
+export const handleAcceptFriendRequest = (handler) => ({
+	execute: handler,
+	validator: {
+		validate: (request) => {
+			const allErrors = [];
+			let bigintValue = request;
+			if (typeof request === 'string') {
+				try {
+					bigintValue = BigInt(request);
+				} catch {
+					allErrors.push('Value must be a bigint');
+				}
+			} else if (typeof request !== 'bigint') {
+				allErrors.push('Value must be a bigint');
+			}
+			return allErrors;
+		},
+		validateOrThrow: (request) => {
+			let bigintValue = request;
+			if (typeof request === 'string') {
+				try {
+					bigintValue = BigInt(request);
+				} catch {
+					throw new Error('Value must be a bigint');
+				}
+			} else if (typeof request !== 'bigint') {
+				throw new Error('Value must be a bigint');
+			}
+		},
+		isValid: (request) => {
+			let bigintValue = request;
+			if (typeof request === 'string') {
+				try {
+					bigintValue = BigInt(request);
+				} catch {
+					return 'Value must be a bigint';
+				}
+			} else if (typeof request !== 'bigint') {
+				return 'Value must be a bigint';
+			}
+			return true;
+		},
+	},
+	model: {
+		/* full model object embedded via BON */
+	},
+});
+```
+
+For a WebSocket endpoint (`stream: true`):
+
+**Generated `.d.ts`**:
+
+```typescript
+import { listenForAchievementGrants } from '@lyku/mapi-models';
+import type { MonolithTypes } from '@lyku/mapi-types';
+import type { ListenForAchievementGrantsRequest } from '@lyku/mapi-types';
+import type { SecureSocketContext } from '@lyku/route-helpers';
+
+export declare const handleListenForAchievementGrants: (
+  handler: (
+    request: ListenForAchievementGrantsRequest,
+    context: SecureSocketContext<
+      typeof listenForAchievementGrants,
+      MonolithTypes['listenForAchievementGrants']
+    >,
+  ) => void | Promise<void>,
+) => {
+  readonly onOpen: (                    // ← onOpen, not execute
+    request: ListenForAchievementGrantsRequest,
+    context: SecureSocketContext<
+      typeof listenForAchievementGrants,
+      MonolithTypes['listenForAchievementGrants']
+    >,
+  ) => void | Promise<void>;
+  readonly validator: { ... };
+  readonly model: typeof listenForAchievementGrants;
+};
+```
+
+**Key difference**: Stream handlers expose `onOpen` instead of `execute`.
+
+---
+
+## 7. Type conversion rules
+
+### Schema → TypeScript (used by generateApiTypes)
+
+| Schema                                                            | TypeScript output                        |
+| ----------------------------------------------------------------- | ---------------------------------------- |
+| `{ type: 'string' }`                                              | `string`                                 |
+| `{ type: 'string', const: 'hello' }`                              | `"hello"`                                |
+| `{ type: 'number' }`                                              | `number`                                 |
+| `{ type: 'integer' }`                                             | `number`                                 |
+| `{ type: 'bigint' }`                                              | `bigint`                                 |
+| `{ type: 'boolean' }`                                             | `boolean`                                |
+| `{ type: 'date' }`                                                | `Date`                                   |
+| `{ type: 'array', items: X }`                                     | `Array<X>`                               |
+| `{ type: 'object', properties: { a: X, b: Y }, required: ['a'] }` | `{ a: X; b?: Y }`                        |
+| `{ type: 'object', properties: { a: X }, required: [] }`          | `{ a?: X }`                              |
+| `{ type: 'object', properties: { a: X } }`                        | `{ a?: X }` (no required = all optional) |
+| `{ enum: ['a', 'b', 'c'] }`                                       | `'a' \| 'b' \| 'c'`                      |
+| `{ enum: [1, 2, 3] }`                                             | `1 \| 2 \| 3`                            |
+| `{ oneOf: [X, Y] }`                                               | `(X \| Y)`                               |
+| `{ anyOf: [X, Y] }`                                               | `(X \| Y)`                               |
+| `{ allOf: [X, Y] }`                                               | `(X & Y)`                                |
+| `{ type: 'map', keys: K, values: V }`                             | `Record<string, V>`                      |
+| `{ $ref: '...' }`                                                 | `any`                                    |
+| primitive `'hello'`                                               | `"hello"`                                |
+| primitive `42`                                                    | `42`                                     |
+| primitive `true`                                                  | `true`                                   |
+| primitive `123n`                                                  | `123`                                    |
+| no response defined                                               | `void`                                   |
+
+### PostgreSQL → Kysely type mapping
+
+| PostgreSQL type                            | Kysely type                             | Notes          |
+| ------------------------------------------ | --------------------------------------- | -------------- |
+| `bigint`, `int8`                           | `bigint`                                |                |
+| `bigserial`, `serial8`                     | `Generated<bigint>`                     | Auto-increment |
+| `serial`, `serial4`                        | `Generated<number>`                     | Auto-increment |
+| `smallserial`, `serial2`                   | `Generated<number>`                     | Auto-increment |
+| `integer`, `int`, `int2`, `int4`           | `number`                                |                |
+| `smallint`                                 | `number`                                |                |
+| `real`, `float4`                           | `number`                                |                |
+| `double precision`, `float8`               | `number`                                |                |
+| `numeric`                                  | `number`                                |                |
+| `money`                                    | `number`                                |                |
+| `boolean`, `bool`                          | `boolean`                               |                |
+| `text`, `varchar`, `char`                  | `string`                                |                |
+| `date`, `timestamp`, `timestamptz`, `time` | `Date`                                  |                |
+| `enum` with values                         | `'val1' \| 'val2'`                      | Literal union  |
+| `array` with items                         | `T[]`                                   | Recursive      |
+| `jsonb`                                    | `unknown` (or typed if schema provided) |                |
+| `bytea`                                    | `Buffer`                                |                |
+
+Columns with `default` or `generated` AND in `required`: still required in the full type, but optional in the Insertable type.
+
+Columns with serial/bigserial types: wrapped in `Generated<T>` which makes them optional on insert.
+
+---
+
+## 8. Validation rules
+
+Generated validators check these conditions per schema type:
+
+| Schema type        | Validations                                                                                                            |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `string`           | `typeof === 'string'`, minLength, maxLength, pattern (regex), format (email/uuid/uri/ipv4/ipv6/hostname/date-time)     |
+| `number`/`integer` | `typeof === 'number'` (or coerced from string), min, max, exclusiveMin, exclusiveMax, integer check                    |
+| `bigint`           | `typeof === 'bigint'` (or coerced from string via `BigInt()`), min, max                                                |
+| `boolean`          | `typeof === 'boolean'`                                                                                                 |
+| `date`             | `instanceof Date`, min, max                                                                                            |
+| `object`           | `typeof === 'object' && !== null && !Array.isArray()`, required property presence, per-property validation (recursive) |
+| `array`            | `Array.isArray()`, minItems, maxItems, per-item validation                                                             |
+| `enum`             | membership check against allowed values                                                                                |
+| `oneOf`            | validates against each schema, exactly one must pass                                                                   |
+
+**Coercion**: Validators accept string representations of numbers (`Number(str)`) and bigints (`BigInt(str)`) and attempt conversion before validation.
+
+---
+
+## 9. BON serialization
+
+BON (Binary Object Notation) is JSON with BigInt support, used internally for embedding models in generated code.
+
+### Format differences from JSON
+
+| Value           | JSON               | BON                          |
+| --------------- | ------------------ | ---------------------------- |
+| `123n` (bigint) | Not supported      | `123n`                       |
+| `new Date(...)` | `"2025-01-01T..."` | `new Date("2025-01-01T...")` |
+| `undefined`     | Not supported      | `undefined`                  |
+| `NaN`           | `null`             | `NaN`                        |
+| `Infinity`      | `null`             | `Infinity`                   |
+
+### Security limits in parseBON
+
+- Max nesting depth: 10,000
+- Max string length: 100 MB
+- Max input length: 100 MB
+- Max object properties: 100,000
+- Max array elements: 10,000,000
+- Blocked property names: `__proto__`, `constructor`, `prototype`
+
+---
+
+## 10. filterHandlerModels
+
+When generators process mapi-models exports, they filter to only valid handler models:
+
+```typescript
+function filterHandlerModels(models: Record<string, unknown>): Record<string, TsonHandlerModel> {
+	// Keeps entries where:
+	//   typeof value === 'object' && value !== null
+	//   && 'authenticated' in value
+	//   && typeof value.authenticated === 'boolean'
+	// Discards everything else (helper constants, type re-exports, arrays, etc.)
+}
+```
+
+This means non-handler exports (like `messageEventTypes`, `socialStreamTopics`, arrays, strings) are safely ignored.
+
+---
+
+## 11. CLI usage
+
+```bash
+# Generate JSON schemas + TS types from PostgreSQL models
+from-schema generate json-models \
+  --models ./pg-models \
+  --output ./json-models \
+  --extras ./extras              # optional: extra schemas to include
+
+# Generate Kysely Database type
+from-schema generate db-types \
+  --models ./pg-models \
+  --output ./db-types \
+  --file kysely.d.ts             # optional: output filename (default: index.d.ts)
+
+# Generate API request/response types
+from-schema generate api-types \
+  --models ./mapi-models \
+  --output ./mapi-types \
+  --types-name MonolithTypes     # optional: aggregate type name (default: ApiTypes)
+
+# Generate handler factories
+from-schema generate handles \
+  --models ./mapi-models \
+  --output ./handles \
+  --models-pkg @lyku/mapi-models \
+  --types-pkg @lyku/mapi-types \
+  --context-pkg @lyku/lockstep-core/contexts  # optional
+  --types-name MonolithTypes                 # optional
+
+# Generate API client
+from-schema generate client \
+  --models ./mapi-models \
+  --output ./client \
+  --types-pkg @lyku/mapi-types \
+  --types-name MonolithTypes     # optional
+```
+
+---
+
+## 12. Common pitfalls
+
+1. **Missing `required` in response schema**: If you define an object response without `required`, ALL properties become optional in the generated type. Your handler returning `{ name: 'foo' }` won't typecheck against `{ name?: string }` because the handler produces a required field but the type expects optional.
+
+2. **Singular vs plural table names**: pg-models use singular names (`canaryMetric`), but the generated Kysely Database interface pluralizes them (`canaryMetrics`). Use the plural form in `pg.selectFrom('canaryMetrics')`.
+
+3. **`as const satisfies`**: Always use `as const satisfies PostgresRecordModel` or `as const satisfies TsonHandlerModel`. Without `as const`, literal types are widened and generators produce wrong output.
+
+4. **BigInt in validators**: Validators accept string inputs for bigint fields and attempt `BigInt(str)` coercion. This means `"123"` is valid input for a bigint field.
+
+5. **Stream handlers use `onOpen`**: The generated handle for a `stream: true` model exposes `onOpen` (not `execute`). The context type is `SocketContext` (not `HttpContext`).
+
+6. **`void` response**: If no `response` is defined in the model, the generated response type is `void`. The handler should not return a value.
+
+7. **Enum columns vs enum schemas**: PostgreSQL `{ type: 'enum', enum: ['a', 'b'] }` columns generate Kysely types as `'a' | 'b'` (literal union), but the schema conversion loses the enum values — the generated schema just becomes `{ type: 'string' }`. Use enum schemas (`{ enum: ['a', 'b'] }` without `type`) in mapi-models to preserve literal types in API types.
+
+---
+
+## 13. Exports
+
+```
+@lyku/lockstep-core               # All schema types, BON, type converters, validators
+@lyku/lockstep-core/contexts      # Handler context types (SecureHttpContext, etc.)
+@lyku/lockstep-core/generators    # Code generators (generateJsonModels, etc.)
+```