@rangka/core 0.0.1

package/.claude/skills/extend-core/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: extend-core
+description: Extending or modifying @rangka/core internals (registries, handlers, boot, context). Use when contributing to the framework itself.
+---
+
+## Before you write any code
+
+You are modifying framework internals. App developers depend on the public API staying stable. Every change must preserve existing behavior unless intentionally breaking (with migration path).
+
+1. Identify what you are changing:
+   - A registry (SchemaRegistry, HookRegistry, PermissionRegistry, etc.)
+   - The boot sequence (`src/boot/index.ts`)
+   - The route generator (`src/api/route-generator.ts`)
+   - The hook pipeline (`src/hooks/executor.ts`, `src/hooks/middleware.ts`)
+   - FrameworkContext (`@rangka/shared` types/context.ts + `src/hooks/context.ts`)
+   - Model access layer (`src/model-api/`)
+
+2. Read the public API surface that consumers use:
+   - `FrameworkContext` in `@rangka/shared/src/types/context.ts` — hooks, services, and jobs receive this
+   - `ModelAccessInterface` / `ModelQueryInterface` in the same file — the query API app devs call
+   - `defineHooks`, `defineService`, `defineJob` in `@rangka/shared/src/define.ts` — app definition API
+   - `BootPayload` in `@rangka/shared/src/types/boot.ts` — what the client receives at startup
+
+3. Search for all consumers before modifying:
+   ```bash
+   grep -r "ctx.models" packages/core/src/
+   grep -r "FrameworkContext" packages/
+   grep -r "SchemaRegistry" packages/core/src/
+   ```
+
+## Extending a registry
+
+Registries are singleton objects created during boot. They hold runtime state.
+
+Pattern for adding a method:
+
+1. Add the method to the registry class (e.g., `src/schema/registry.ts`)
+2. If the method is exposed to app devs via FrameworkContext, update the interface in `@rangka/shared`
+3. Verify all existing tests still pass
+4. Add a test for the new method
+
+Pattern for adding a new registry:
+
+1. Create in its own file under the relevant domain (e.g., `src/notifications/registry.ts`)
+2. Instantiate in `src/boot/index.ts` during the boot sequence
+3. Wire into `FrameworkContext` if app devs need access
+4. Update `@rangka/shared` types if the interface is public
+
+## Modifying FrameworkContext
+
+This is the most sensitive change. Every hook, service, and job receives this object.
+
+Adding a new field:
+
+1. Add the field to `FrameworkContext` in `@rangka/shared/src/types/context.ts`
+2. Make it optional if not all consumers need it (backward compatible)
+3. Build it in `src/hooks/context.ts` (`createHookContext`) AND `src/context.ts` (`createFrameworkContext`)
+4. Rebuild shared first, then core: `pnpm --filter @rangka/shared build && pnpm --filter @rangka/core build`
+5. Verify no type errors across the monorepo: `pnpm build`
+
+Modifying an existing field's type:
+
+- Breaking change. Grep all usages across the monorepo. Update every consumer in the same PR.
+
+## Modifying the hook pipeline
+
+The hook pipeline is in `src/hooks/executor.ts` and `src/hooks/middleware.ts`.
+
+- `executor.ts` — runs hook chains (validate → before → after) in sequence
+- `middleware.ts` — Fastify request handlers that orchestrate the full CRUD + hooks flow
+
+Rules:
+
+- Hook phases are fixed: validate, beforeCreate, beforeUpdate, beforeSave, afterCreate, afterUpdate, afterSave, beforeDelete, afterDelete
+- Do NOT add new phases without updating `HookLifecycle` type in `src/hooks/types.ts` AND the executor
+- The middleware functions (`withHooksCreate`, `withHooksUpdate`, `withHooksDelete`) are the authoritative CRUD handlers. Never create a parallel CRUD path.
+
+## Modifying the route generator
+
+`src/api/route-generator.ts` auto-generates REST routes for all models.
+
+- It uses `withHooksCreate/Update/Delete` from `src/hooks/middleware.ts` for mutations
+- It uses `listHandler/getHandler` from `src/api/handlers.ts` for reads
+- Auth/scope/permission guards are applied as Fastify preHandler hooks
+
+To add a new capability to all model routes (e.g., new query parameter, new response field):
+
+1. Modify the relevant handler in `src/api/handlers.ts`
+2. Update OpenAPI schema generation if applicable (`src/api/openapi-schema.ts`)
+3. Test with integration tests
+
+To add a non-model route (e.g., `/api/meta/...`):
+
+- Add it inside `generateRoutes()` alongside the existing meta/session routes
+
+## Modifying model-api
+
+The model access layer (`src/model-api/`) is the query engine.
+
+- `query-builder.ts` — ModelQueryBuilder (fluent API for filtering/sorting/pagination)
+- `filter-translator.ts` — converts API filter syntax to Kysely where clauses
+- `filter-applier.ts` — applies filter conditions to a query
+- `scope-enforcer.ts` — enforces tenant/scope/field-level permissions
+- `include-resolver.ts` — resolves relationship includes
+- `field-access.ts` — strips hidden fields, enforces readOnly
+
+Rules:
+
+- New filter operators go in `filter-translator.ts`
+- New query capabilities go as methods on `ModelQueryBuilder`
+- Never bypass scope enforcement — if you need unscoped access, use `.unscoped()` explicitly
+- The `ModelAccessInterface` in `@rangka/shared` is the public contract. Adding a method there is fine (additive). Changing signatures is breaking.
+
+## Anti-patterns
+
+| Anti-pattern                                                       | Correct approach                                   |
+| ------------------------------------------------------------------ | -------------------------------------------------- |
+| New CRUD handler that skips hooks                                  | Use `withHooksCreate/Update/Delete`                |
+| Custom filter logic in a route handler                             | Add to `filter-translator.ts`                      |
+| Direct Kysely queries for model CRUD in handlers                   | Use model-api through the existing handler pattern |
+| New singleton that duplicates a registry's purpose                 | Extend the existing registry                       |
+| Modifying `FrameworkContext` in core without updating shared types | Always update `@rangka/shared` first               |
+| Adding a field to `BootPayload` without updating client consumer   | Check `packages/client/src/boot/`                  |
+
+## Checklist
+
+- [ ] Identified all consumers of the changed API (grep across monorepo)
+- [ ] Public interfaces in `@rangka/shared` updated if needed
+- [ ] `createHookContext()` and `createFrameworkContext()` both updated if FrameworkContext changed
+- [ ] No parallel code paths introduced (no duplicate CRUD, no duplicate registries)
+- [ ] Existing tests pass: `pnpm test`
+- [ ] Integration tests pass: `pnpm test:integration`
+- [ ] Full monorepo builds: `pnpm build`

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> @rangka/core@0.0.1 build /home/runner/work/rangka-framework/rangka-framework/packages/core
+> tsc --build
+

package/CLAUDE.md

@@ -0,0 +1,180 @@
+# CLAUDE.md — @rangka/core
+
+## Package overview
+
+The Rangka server runtime. Handles boot, schema resolution, database sync, API routing, authentication, hooks, services, jobs, events, and plugins. This is the single source of truth for all server-side behavior.
+
+## Tech stack
+
+- Node.js >= 20, TypeScript 5
+- Fastify (HTTP server, routing, plugins)
+- Kysely (query builder, migrations, transactions)
+- PostgreSQL (only supported database)
+
+## Project structure
+
+```
+src/
+├── api/            — Fastify server creation, route generation, request handling
+├── audit/          — Audit trail recording
+├── auth/           — JWT sessions, permissions, scopes, field-level access, seed
+├── boot/           — Boot sequence: discovery, schema loading, merging, registry init
+├── db/             — DatabaseClient, auto-sync (DiffEngine), model-ops (Kysely CRUD)
+├── events/         — EventBus (in-process pub/sub with transaction support)
+├── external-model/ — Adapter-based external data sources
+├── fixtures/       — Seed data loading
+├── helpers/        — Shared utilities
+├── hooks/          — Hook registry, executor, middleware pipeline, context builder
+├── jobs/           — Job registry, worker, scheduler, enqueue
+├── model-api/      — Model access layer (query builder, filters, scopes, includes)
+├── plugins/        — Plugin lifecycle, adapter registry, loader
+├── schema/         — SchemaRegistry, relationship resolution, types
+├── services/       — ServiceRegistry, service definitions
+├── validation/     — Model-level validation rules
+├── widgets/        — Server-side widget registry (for studio)
+├── context.ts      — FrameworkContext builder
+├── errors.ts       — AppError base class
+└── index.ts        — Public exports
+```
+
+## Key registries (MUST reuse, never recreate)
+
+| Registry             | Location                      | Purpose                                                                             |
+| -------------------- | ----------------------------- | ----------------------------------------------------------------------------------- |
+| `SchemaRegistry`     | `schema/registry.ts`          | Holds all resolved models, relationships, field metadata. Single instance per boot. |
+| `PermissionRegistry` | `auth/permission-registry.ts` | Maps roles to model/field permissions.                                              |
+| `ScopeRegistry`      | `auth/scope-registry.ts`      | Defines scope filters per role (tenant isolation, ownership).                       |
+| `HookRegistry`       | `hooks/registry.ts`           | Stores validate/beforeSave/afterSave/beforeDelete/afterDelete hooks per model.      |
+| `ServiceRegistry`    | `services/registry.ts`        | Named service definitions, instantiated with context on call.                       |
+| `JobRegistry`        | `jobs/registry.ts`            | Background job handlers.                                                            |
+| `EventBus`           | `events/bus.ts`               | In-process event pub/sub with transaction-scoped emit.                              |
+| `AdapterRegistry`    | `plugins/adapter-registry.ts` | External data source adapters (REST, GraphQL, etc).                                 |
+| `WidgetRegistry`     | `widgets/widget-registry.ts`  | Server-side widget definitions for studio.                                          |
+
+## Model access layer
+
+All CRUD operations go through `createModelAccess()` in `model-api/index.ts`. This provides:
+
+- `models.get(model, id)` — fetch single record
+- `models.query(model)` — returns a `ModelQueryBuilder` with filter/sort/paginate/include
+- `models.create(model, data)` — insert with auth context
+- `models.update(model, id, data)` — update with auth context
+- `models.delete(model, id)` — delete with auth context
+
+The query builder handles:
+
+- Scope enforcement (`scope-enforcer.ts`) — auto-applies tenant/ownership filters
+- Field-level access (`field-access.ts`) — strips hidden fields, enforces readOnly
+- Filter translation (`filter-translator.ts`) — converts API filter syntax to Kysely where clauses
+- Include resolution (`include-resolver.ts`) — resolves relationships and external model joins
+
+Never write raw Kysely queries for model CRUD. Use `createModelAccess` or the existing `KyselyModelOps`.
+
+## Hook pipeline
+
+Hooks run inside a transaction via `hooks/executor.ts`:
+
+1. `validate` — can throw to reject the operation
+2. `beforeCreate` / `beforeUpdate` / `beforeSave` — can mutate the data before write
+3. (database write happens here)
+4. `afterCreate` / `afterUpdate` / `afterSave` — side effects after successful write
+5. `beforeDelete` / `afterDelete` — same pattern for deletes
+
+Hooks receive a `FrameworkContext` built by `hooks/context.ts`. This context provides: `db` (transaction), `schema`, `auth`, `models`, `events`, `config`, `service`, `enqueue`.
+
+Never create a parallel context builder. Use `createHookContext()`.
+
+## FrameworkContext (quick reference)
+
+This is the single object passed to all hooks, services, and jobs. Defined in `@rangka/shared/src/types/context.ts`, built by `src/hooks/context.ts`.
+
+```typescript
+interface FrameworkContext {
+  db: Kysely<unknown>; // transaction-scoped connection
+  schema: SchemaRegistryInterface; // model/field/relationship lookups
+  scope: unknown; // current tenant/scope value
+  models: ModelAccessInterface; // CRUD with scopes + permissions
+  events: { emit; on }; // transaction-scoped pub/sub
+  auth: { user; roles }; // current user identity
+  config: Record<string, unknown>; // app configuration
+  service: (name) => ServiceInstance; // call other services
+  enqueue: (job, data, opts?) => Promise<void>; // background jobs
+  notify: (channel, message) => void;
+  email: { send: (template, options) => Promise<void> };
+}
+```
+
+Rules:
+
+- All data access goes through `ctx.models` (not raw Kysely for CRUD)
+- All events go through `ctx.events.emit` (not custom pub/sub)
+- All background work goes through `ctx.enqueue` (not custom dispatchers)
+- All cross-service calls go through `ctx.service(name)` (not direct imports)
+- Use `ctx.db` directly ONLY for queries ModelQueryInterface cannot express (aggregations, complex joins)
+
+## Helper utilities (MUST reuse)
+
+| Utility                             | Location                        | Purpose                                       |
+| ----------------------------------- | ------------------------------- | --------------------------------------------- |
+| `stampCreate`                       | `helpers/stamping.ts`           | Adds `created_at`, `created_by` fields        |
+| `stampUpdate`                       | `helpers/stamping.ts`           | Adds `updated_at`, `updated_by` fields        |
+| `assertOwnership`                   | `helpers/assert-ownership.ts`   | Verifies record belongs to current user/scope |
+| `findMissingRequiredFields`         | `helpers/validation.ts`         | Checks required fields before write           |
+| `validateFields`                    | `validation/field-validator.ts` | Validates field values against schema         |
+| `BadRequestError` / `NotFoundError` | `errors.ts`                     | Standard error classes for API responses      |
+| `AppError`                          | `errors.ts`                     | Base error class with code + status           |
+
+Never recreate validation, stamping, or ownership logic. These helpers are used by the middleware layer and must be consistent.
+
+## Boot sequence
+
+`boot/index.ts` orchestrates startup:
+
+1. Discover apps (file system or programmatic)
+2. Load and merge schemas (YAML model definitions)
+3. Build SchemaRegistry with resolved relationships
+4. Create DatabaseClient, run autoSync (DDL diff)
+5. Create Fastify server
+6. Register all registries (hooks, services, jobs, permissions, scopes, events)
+7. Generate API routes from resolved models
+8. Load and initialize plugins
+
+## API route generation
+
+`api/route-generator.ts` auto-generates REST endpoints for every model:
+
+- `GET /api/{module}/{model}` — list with filters, sort, pagination
+- `GET /api/{module}/{model}/:id` — get by ID
+- `POST /api/{module}/{model}` — create
+- `PATCH /api/{module}/{model}/:id` — update
+- `DELETE /api/{module}/{model}/:id` — delete
+
+Custom routes are added via services or plugins. Never duplicate the auto-generated CRUD pattern.
+
+## Commands
+
+```bash
+pnpm --filter @rangka/core build    # Build → dist/
+pnpm --filter @rangka/core test     # Unit tests
+pnpm test:integration               # Integration tests (from repo root, needs PostgreSQL)
+pnpm test:integration -- tests/integration/path/to/file.test.ts  # Single integration test
+```
+
+## Skills available
+
+- **`extend-core`** — step-by-step for modifying core internals (registries, hook pipeline, route generator, FrameworkContext)
+
+Read this skill before modifying any core internal.
+
+## Don'ts
+
+- Don't write raw SQL — use Kysely query builder via `DatabaseClient` or `KyselyModelOps`
+- Don't bypass `createModelAccess` for CRUD — it enforces scopes and permissions
+- Don't create new registries — extend existing ones or add methods to them
+- Don't build a new context object — use `createHookContext()` or `createFrameworkContext()`
+- Don't add Fastify routes manually — use the route generator or service system
+- Don't duplicate filter/sort/pagination logic — use `ModelQueryBuilder`
+- Don't access `SchemaRegistry` fields directly — use its methods (`getModel`, `getRelationships`, etc.)
+- Don't add new hook phases — use the existing validate/beforeSave/afterSave/beforeDelete/afterDelete
+- Don't create new transaction boundaries inside hooks — hooks already run in a transaction
+- Don't import from `@rangka/client` — this is a server package, client is browser-only

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rangka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @rangka/core
+
+Server-side runtime engine for the Rangka framework.
+
+## How it works
+
+This package boots a complete Fastify server from declarative model/page definitions. It handles module discovery, schema resolution, database sync, REST API generation, authentication, lifecycle hooks, background jobs, and events. All server-side behavior lives here.
+
+## Architecture
+
+```
+src/
+├── api/            — Fastify server, route generation, handlers, OpenAPI schema
+├── audit/          — Audit trail recording
+├── auth/           — JWT sessions, permissions, scopes, field-level access
+├── boot/           — Boot sequence: discovery, schema loading, merging, registry init
+├── db/             — DatabaseClient, auto-sync (DiffEngine), model-ops (Kysely CRUD)
+├── events/         — EventBus (transaction-scoped pub/sub)
+├── external-model/ — Adapter-based external data sources
+├── fixtures/       — Seed data loading
+├── helpers/        — Stamping, ownership checks, validation utilities
+├── hooks/          — Hook registry, executor, middleware, context builder
+├── jobs/           — Job registry, worker, scheduler, enqueue
+├── model-api/      — Query builder, filter translation, scope enforcement, includes
+├── plugins/        — Plugin lifecycle, adapter registry, loader
+├── schema/         — SchemaRegistry, relationship resolution
+├── services/       — ServiceRegistry, service factory
+├── validation/     — Field-level validation engine
+├── widgets/        — Server-side widget registry (for studio)
+├── context.ts      — FrameworkContext builder
+├── errors.ts       — AppError, BadRequestError, NotFoundError
+└── index.ts        — Public exports
+```
+
+## Key internal systems
+
+| System      | Entry point                   | Purpose                                        |
+| ----------- | ----------------------------- | ---------------------------------------------- |
+| Boot        | `boot/index.ts`               | Orchestrates full server startup               |
+| Schema      | `schema/registry.ts`          | Holds resolved models and relationships        |
+| Model API   | `model-api/index.ts`          | CRUD with scopes, permissions, filters         |
+| Hooks       | `hooks/executor.ts`           | Lifecycle pipeline (validate → before → after) |
+| Middleware  | `hooks/middleware.ts`         | Wraps hooks into Fastify request handlers      |
+| Routes      | `api/route-generator.ts`      | Auto-generates REST endpoints per model        |
+| Auth        | `auth/session.ts`             | JWT session management                         |
+| Permissions | `auth/permission-registry.ts` | Role-based model/field access                  |
+| Scopes      | `auth/scope-registry.ts`      | Row-level tenant isolation                     |
+| Services    | `services/registry.ts`        | Named business logic with DI                   |
+| Jobs        | `jobs/registry.ts`            | Background job processing                      |
+| Events      | `events/bus.ts`               | Transaction-scoped pub/sub                     |
+
+## Commands
+
+```bash
+pnpm --filter @rangka/core build   # Compile TypeScript
+pnpm --filter @rangka/core test    # Unit tests
+pnpm test:integration              # Integration tests (from repo root)
+```
+
+## Contributing
+
+- All data access in hooks/services goes through `ctx.models` (the ModelAccess interface). Never write raw Kysely for basic CRUD.
+- All hooks/services/jobs receive `FrameworkContext`. Use it. Don't build parallel context objects.
+- The hook pipeline is fixed: validate → beforeSave → (write) → afterSave. Don't add new phases.
+- Route handlers are auto-generated by `route-generator.ts`. Don't duplicate CRUD routes manually.
+- Registries are singletons created at boot. Extend existing ones, don't create new ones for the same purpose.
+- Helper utilities (`helpers/stamping.ts`, `helpers/validation.ts`, `helpers/assert-ownership.ts`) must be reused. Don't recreate stamping or ownership logic.
+- This package imports from `@rangka/shared` only. Never import from `@rangka/client`.

package/dist/__tests__/coerce.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=coerce.test.d.ts.map

package/dist/__tests__/coerce.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coerce.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/coerce.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/coerce.test.js

@@ -0,0 +1,121 @@
+import { describe, it, expect } from 'vitest';
+import { toBool, toInt, isNil, toCount } from '../helpers/coerce.js';
+describe('toBool', () => {
+    it('returns true for boolean true', () => {
+        expect(toBool(true)).toBe(true);
+    });
+    it('returns true for string "true"', () => {
+        expect(toBool('true')).toBe(true);
+    });
+    it('returns true for number 1', () => {
+        expect(toBool(1)).toBe(true);
+    });
+    it('returns true for string "1"', () => {
+        expect(toBool('1')).toBe(true);
+    });
+    it('returns false for boolean false', () => {
+        expect(toBool(false)).toBe(false);
+    });
+    it('returns false for string "false"', () => {
+        expect(toBool('false')).toBe(false);
+    });
+    it('returns false for 0', () => {
+        expect(toBool(0)).toBe(false);
+    });
+    it('returns false for null', () => {
+        expect(toBool(null)).toBe(false);
+    });
+    it('returns false for undefined', () => {
+        expect(toBool(undefined)).toBe(false);
+    });
+    it('returns false for empty string', () => {
+        expect(toBool('')).toBe(false);
+    });
+    it('returns false for arbitrary string', () => {
+        expect(toBool('yes')).toBe(false);
+    });
+});
+describe('toInt', () => {
+    it('returns the integer for a number', () => {
+        expect(toInt(42)).toBe(42);
+    });
+    it('truncates floating point numbers', () => {
+        expect(toInt(3.9)).toBe(3);
+        expect(toInt(-2.7)).toBe(-2);
+    });
+    it('parses numeric strings', () => {
+        expect(toInt('10')).toBe(10);
+        expect(toInt('  5 ')).toBe(5);
+    });
+    it('returns fallback for NaN values', () => {
+        expect(toInt('abc')).toBe(0);
+        expect(toInt('abc', -1)).toBe(-1);
+    });
+    it('returns fallback for null', () => {
+        expect(toInt(null)).toBe(0);
+        expect(toInt(null, 99)).toBe(99);
+    });
+    it('returns fallback for undefined', () => {
+        expect(toInt(undefined)).toBe(0);
+    });
+    it('returns fallback for Infinity', () => {
+        expect(toInt(Infinity)).toBe(0);
+        expect(toInt(-Infinity, 5)).toBe(5);
+    });
+    it('returns fallback for empty string', () => {
+        expect(toInt('')).toBe(0);
+    });
+    it('handles string with leading zeros', () => {
+        expect(toInt('007')).toBe(7);
+    });
+});
+describe('isNil', () => {
+    it('returns true for null', () => {
+        expect(isNil(null)).toBe(true);
+    });
+    it('returns true for undefined', () => {
+        expect(isNil(undefined)).toBe(true);
+    });
+    it('returns false for 0', () => {
+        expect(isNil(0)).toBe(false);
+    });
+    it('returns false for empty string', () => {
+        expect(isNil('')).toBe(false);
+    });
+    it('returns false for false', () => {
+        expect(isNil(false)).toBe(false);
+    });
+    it('returns false for NaN', () => {
+        expect(isNil(NaN)).toBe(false);
+    });
+    it('returns false for objects', () => {
+        expect(isNil({})).toBe(false);
+        expect(isNil([])).toBe(false);
+    });
+});
+describe('toCount', () => {
+    it('extracts count from object', () => {
+        expect(toCount({ count: '5' })).toBe(5);
+        expect(toCount({ count: 10 })).toBe(10);
+    });
+    it('returns 0 for null', () => {
+        expect(toCount(null)).toBe(0);
+    });
+    it('returns 0 for undefined', () => {
+        expect(toCount(undefined)).toBe(0);
+    });
+    it('returns 0 when count is missing', () => {
+        expect(toCount({})).toBe(0);
+    });
+    it('returns 0 when count is not a number', () => {
+        expect(toCount({ count: 'abc' })).toBe(0);
+    });
+    it('handles bigint-style string from database', () => {
+        expect(toCount({ count: '12345' })).toBe(12345);
+    });
+    it('handles raw numeric value without object wrapper', () => {
+        expect(toCount(7)).toBe(7);
+        expect(toCount('3')).toBe(3);
+    });
+});
+//# sourceMappingURL=coerce.test.js.map

package/dist/__tests__/coerce.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coerce.test.js","sourceRoot":"","sources":["../../src/__tests__/coerce.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/context.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.test.d.ts.map

package/dist/__tests__/context.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/context.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/context.test.js

@@ -0,0 +1,99 @@
+import { describe, it, expect } from 'vitest';
+import { createFrameworkContext, createRequestContext } from '../context.js';
+import { ServiceRegistry } from '../services/registry.js';
+import { EventBus } from '../events/bus.js';
+import { SchemaRegistry } from '../schema/registry.js';
+describe('createFrameworkContext', () => {
+    function setup() {
+        const kysely = { fake: 'db' };
+        const db = {
+            kysely,
+            selectFrom: () => { },
+            insertInto: () => { },
+            updateTable: () => { },
+            deleteFrom: () => { },
+        };
+        const schema = new SchemaRegistry([]);
+        const eventBus = new EventBus();
+        const serviceRegistry = new ServiceRegistry();
+        return { db, kysely, schema, eventBus, serviceRegistry };
+    }
+    it('returns context with all fields populated', () => {
+        const { db, kysely, schema, eventBus, serviceRegistry } = setup();
+        const ctx = createFrameworkContext({
+            db,
+            schema,
+            eventBus,
+            serviceRegistry,
+            config: { env: 'test' },
+        });
+        expect(ctx.db).toBe(kysely);
+        expect(ctx.schema).toBe(schema);
+        expect(ctx.events.emit).toBeTypeOf('function');
+        expect(ctx.events.on).toBeTypeOf('function');
+        expect(ctx.auth).toEqual({ user: null, roles: [] });
+        expect(ctx.config).toEqual({ env: 'test' });
+        expect(ctx.service).toBeTypeOf('function');
+        expect(ctx.enqueue).toBeTypeOf('function');
+        expect(ctx.notify).toBeTypeOf('function');
+        expect(ctx.email.send).toBeTypeOf('function');
+    });
+    it('service() resolves registered services', () => {
+        const { db, schema, eventBus, serviceRegistry } = setup();
+        serviceRegistry.register({
+            name: 'pricing',
+            factory: () => ({ calculate: (x) => x }),
+        });
+        const ctx = createFrameworkContext({ db, schema, eventBus, serviceRegistry });
+        const pricing = ctx.service('pricing');
+        expect(pricing.calculate(100)).toBe(100);
+    });
+    it('defaults config to empty object', () => {
+        const { db, schema, eventBus, serviceRegistry } = setup();
+        const ctx = createFrameworkContext({ db, schema, eventBus, serviceRegistry });
+        expect(ctx.config).toEqual({});
+    });
+});
+describe('createRequestContext', () => {
+    function setup() {
+        const kysely = { fake: 'db' };
+        const db = {
+            kysely,
+            selectFrom: () => { },
+            insertInto: () => { },
+            updateTable: () => { },
+            deleteFrom: () => { },
+        };
+        const schema = new SchemaRegistry([]);
+        const eventBus = new EventBus();
+        const serviceRegistry = new ServiceRegistry();
+        const base = createFrameworkContext({ db, schema, eventBus, serviceRegistry });
+        return { base, kysely };
+    }
+    it('inherits from base context', () => {
+        const { base } = setup();
+        const auth = { user: { id: '1', email: 'admin@test.com' } };
+        const reqCtx = createRequestContext({ base, auth, roles: ['Administrator'] });
+        expect(reqCtx.schema).toBe(base.schema);
+        expect(reqCtx.service).toBe(base.service);
+        expect(reqCtx.auth).toEqual({
+            user: { id: '1', email: 'admin@test.com' },
+            roles: ['Administrator'],
+        });
+    });
+    it('uses transaction db when provided', () => {
+        const { base } = setup();
+        const trx = { fake: 'trx' };
+        const auth = {};
+        const reqCtx = createRequestContext({ base, auth, trx });
+        expect(reqCtx.db).toBe(trx);
+        expect(reqCtx.db).not.toBe(base.db);
+    });
+    it('uses base db when no transaction provided', () => {
+        const { base } = setup();
+        const auth = {};
+        const reqCtx = createRequestContext({ base, auth });
+        expect(reqCtx.db).toBe(base.db);
+    });
+});
+//# sourceMappingURL=context.test.js.map