@justscale/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JustScale
+
+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,261 @@
+# @justscale/core
+
+The foundation every JustScale app sits on. `@justscale/core` is the DI container, the service/controller/feature primitives, the composition builder (`JustScale()`), the durable-process runtime, the model layer, and the distributed primitives (locks + channels). It also ships the `just` binary.
+
+The distinguishing idea: **composition is validated at compile time.** A missing dependency is a type error, not a runtime crash. You get that by describing services, controllers, and features as values with typed dependency tokens and letting `build()` check the graph.
+
+Full docs: [justscale.sh](https://justscale.sh) — start at [overview/philosophy](https://justscale.sh/overview/philosophy).
+
+## Install
+
+```bash
+pnpm add @justscale/core
+```
+
+Peer deps: `zod` (required for schemas), `@justscale/typescript` (optional; installs `ptsc` for the durable-process compiler), `esbuild` (optional; used by parts of the CLI).
+
+## Hello world
+
+```ts
+import JustScale, { defineService, createController } from '@justscale/core';
+import { Get } from '@justscale/http';
+
+class Greeter extends defineService({
+  factory: () => ({ hello: (name: string) => `Hello, ${name}!` }),
+}) {}
+
+const GreetController = createController({
+  inject: { greeter: Greeter },
+  routes: ({ greeter }) => ({
+    greet: Get('/greet/:name').handle(({ params, res }) =>
+      res.json({ message: greeter.hello(params.name) }),
+    ),
+  }),
+});
+
+const app = JustScale()
+  .add(Greeter)
+  .add(GreetController)
+  .build();
+
+await app.serve();
+```
+
+`.add(...)` composes services, controllers, and features into a scope. `build()` type-checks the DI graph — forget `.add(Greeter)` and `GreetController` won't compile. `serve()` pulls `HttpConfig` from the scope (default port `6142`) and opens the sockets.
+
+Real apps usually declare per-environment config through `createEnvironment` + an env contract and boot via `just dev` / `just test`; see [examples/simple-app](https://github.com/justscale/justscale/tree/main/examples/simple-app) for the canonical shape.
+
+## Primitives
+
+### Services — [justscale.sh/fundamentals/services](https://justscale.sh/fundamentals/services)
+
+```ts
+class UserService extends defineService({
+  inject: { users: UserRepository },
+  factory: ({ users }) => ({
+    findByEmail: (email: string) =>
+      users.findOne(User.fields.email.eq(email)),
+  }),
+}) {}
+```
+
+`defineService({ inject, factory })` returns a class you extend. `inject` lists the DI tokens you need; `factory` receives the resolved instances and returns your service. The returned class is itself the DI token — pass `UserService` to `.add(UserService)` or inject it elsewhere.
+
+Abstract tokens (`defineAbstract`) let services declare "I need _something_ that implements this interface" without naming a concrete class. Bind a concrete implementation at compose time with `bindService(AbstractToken, ConcreteService)`. Same pattern for repositories via `bindRepository(ModelRepository.of(User), UserRepository)`.
+
+### Controllers — [justscale.sh/fundamentals/controllers](https://justscale.sh/fundamentals/controllers)
+
+```ts
+createController({
+  inject: { svc: MyService },
+  routes: ({ svc }) => ({
+    foo: Get('/foo').use(middleware).guard(check).handle(ctx => svc.foo(ctx)),
+    bar: Cli('bar').input(z.object({...})).handle(ctx => svc.bar(ctx)),
+  }),
+});
+```
+
+Controllers are DI units that hold routes. Route factories come from transport packages — `Get`/`Post`/... from `@justscale/http`, `Ws` from `@justscale/websocket`, `SSE` from `@justscale/sse`, `Cli` from `@justscale/core/cli`, `Procedure` from contracts — and all flow through the same `.use(middleware).guard(...).handle(...)` pipeline with per-route typing.
+
+### Features — [justscale.sh/fundamentals/features](https://justscale.sh/fundamentals/features)
+
+```ts
+export const AuthFeature = createFeatureBuilder()
+  .name('auth')
+  .requires(Config.of(AuthConfig))
+  .provides(b => b.add(AuthService).add(AuthEndpointsController));
+```
+
+Features are shippable capability bundles: a named package of services + controllers + config requirements that other apps consume via `.add(AuthFeature)`. `.requires(...)` bubbles DI requirements up to whoever adds the feature — the requirement is checked at their `build()`, not yours.
+
+### Contracts — [justscale.sh/rpc](https://justscale.sh/rpc/overview)
+
+```ts
+import { defineContract, rpc } from '@justscale/core/contract';
+
+class UserContract extends defineContract({
+  protocol: 'grpc',
+  serviceName: 'user.UserService',
+  methods: {
+    getUser: rpc(GetUserRequestSchema, UserSchema),
+  },
+}) {}
+```
+
+Contracts describe a typed set of methods independent of transport. A controller implements a contract via `createController.implements(UserContract, ...)`; the same implementation can be served over gRPC (`@justscale/rpc`), in-process, or routed across cluster nodes. Contracts also act as DI tokens — injecting `UserContract` gets you a client that resolves locally when bound, remotely otherwise.
+
+## Composition
+
+### `JustScale()`
+
+```ts
+JustScale()
+  .add(ServiceA)
+  .add(ControllerB)
+  .add(FeatureC)
+  .build();
+```
+
+The builder is the unit of composition. Every `.add()` contributes services, controllers, features, or bindings into a scope. `.build()` returns a validated `BuiltApp` with `.serve()`, `.match()`, `.run()`, and friends.
+
+### Sub-apps — [justscale.sh/advanced/plugins](https://justscale.sh/advanced/plugins)
+
+```ts
+const AdminSubApp = JustScale()
+  .requires(CatalogService)
+  .requires(InventoryService)
+  .add(AdminController)
+  .add(OpenApiFeature)
+  .build();
+
+const Shop = JustScale()
+  .add(CatalogService)
+  .add(InventoryService)
+  .add(ShopController)
+  .add(AdminSubApp)
+  .build();
+```
+
+A `JustScale()` compilation unit with `.requires(...)` is a sub-app. Mounting it into a parent (`parent.add(SubApp)`) bridges the required services in via scope-switched proxies — calls from inside the sub-app still execute under the parent's container, locks, and observability context. Admin-only services live in their own scope without polluting the host.
+
+### `AbstractContainer`
+
+Reflection on a scope. Inject `AbstractContainer` into a service or controller and you get a typed view of the controllers/services/features bound to that scope. `@justscale/feature-openapi` uses it to emit a per-scope OpenAPI spec — add the feature to a sub-app and the spec covers just that sub-app.
+
+## Durable processes — [justscale.sh/processes/signals](https://justscale.sh/processes/signals)
+
+```ts
+import { createProcess, signal, race, delay } from '@justscale/core/process';
+import { defineSignals } from '@justscale/core/process';
+
+class OrderSignals extends defineSignals(signal => ({
+  paid: signal('/order/:order/paid').data<{ txId: string }>().types({ Order }),
+})) {}
+
+const orderFulfillment = createProcess({
+  path: '/order/:order/fulfillment',
+  inject: { signals: OrderSignals },
+  async handler({ signals }, { order }) {
+    const r = race();
+    switch (true) {
+      case signal(r, signals.paid):
+        return { status: 'paid', txId: r.txId };
+      case delay.days(r, 3):
+        return { status: 'timeout' };
+    }
+  },
+});
+```
+
+Durable processes survive restarts. Their state is serialized through the `Processable` protocol, timers and signals resume transparently, and the compiler (via `@justscale/typescript`'s `ptsc`) rewrites the handler into a safely resumable shape. The runtime is transport-agnostic — signals can fire from HTTP, CLI, WS, cluster, anywhere.
+
+## Models — [justscale.sh/models/overview](https://justscale.sh/models/overview)
+
+```ts
+import { defineModel, field } from '@justscale/core/models';
+
+class User extends defineModel({
+  name: 'User',
+  fields: {
+    email: field.string().max(255).unique(),
+    balance: field.decimal(10, 2).default('0.00'),
+  },
+}) {}
+
+repo.find({ where: User.fields.email.eq('test@example.com') });
+```
+
+Field builders, not Zod — `field.*` gives you typed queryable field expressions (`.eq`, `.gt`, `.ilike`, composed with `and`/`or`). Services inject the abstract `ModelRepository.of(User)` token and stay storage-agnostic; the concrete implementation (e.g. `createPgRepository` from `@justscale/postgres`) is bound at compose time.
+
+References (`field.ref(OtherModel)`) are first-class values, not string IDs. Controllers receive `Reference<T>` in their params and services take `Locked<T>` for mutations; the framework keeps the domain ID-free.
+
+## Distributed primitives
+
+### Locks — [justscale.sh/fundamentals/locks](https://justscale.sh/fundamentals/locks)
+
+Abstract lock API with an `acquire(key, opts)` signature that returns a disposable guard — integrates with the `using` statement for auto-release. The default provider is in-memory (good for tests). `@justscale/postgres` provides a Postgres advisory-lock backend that coordinates across instances, so locks survive being held from different processes hitting the same database.
+
+### Channels — [justscale.sh/fundamentals/channels](https://justscale.sh/fundamentals/channels)
+
+Typed pub/sub with async iterables. `createChannels({ ... })` declares a set of named channels with per-message schemas; subscribers consume via `for await` on a subscription. The default `MemoryChannelBackend` works for a single process; `@justscale/postgres`'s `createPostgresChannelBackend` fans messages out over `LISTEN/NOTIFY` so multiple app instances pointed at the same database all see each publish. Message encoding goes through the `Processable` protocol so domain values (model refs, dates, decimals) survive the round-trip.
+
+## Configuration — [justscale.sh/configuration/overview](https://justscale.sh/configuration/overview)
+
+```ts
+import { defineConfigPartial, createConfig, Config } from '@justscale/core';
+
+export const AppConfig = defineConfigPartial('app', z.object({
+  siteUrl: z.string(),
+  logLevel: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+}));
+
+.add(createConfig({
+  provides: [AppConfig],
+  factory: () => ({ [AppConfig.key]: { siteUrl: 'https://example.com' } }),
+}));
+```
+
+Config is a first-class primitive, not an env-var dip. Features declare the `Config.of(...)` partials they need; the app satisfies them with `createConfig(...)`. Zod schemas validate at startup and defaults feed through (e.g. `HttpConfig.port` defaults to `6142`).
+
+## Subpath exports
+
+Everything beyond the bare `@justscale/core` import lives behind a subpath so you pay only for what you load:
+
+- `@justscale/core/models` — `defineModel`, `field`, `ModelRepository`, references
+- `@justscale/core/process` — durable `createProcess`, `defineSignals`, `race`, `signal`, `delay`
+- `@justscale/core/cluster` — multi-node transport, routing, scheduled tasks
+- `@justscale/core/cli` — `Cli` route factory for `just`-discovered commands
+- `@justscale/core/channel` — typed pub/sub async iterables
+- `@justscale/core/lock` — abstract lock API with an in-memory default
+- `@justscale/core/config` — config service, `defineConfigPartial`, `createConfig`
+- `@justscale/core/contract` — `defineContract` for cross-transport controllers
+- `@justscale/core/feature` — `createFeatureBuilder`
+- `@justscale/core/memory` — in-memory adapter implementations (tests / prototyping)
+- `@justscale/core/middleware`, `/logger`, `/lifecycle`, `/plugin` — narrower slices of the bare surface
+
+## `just` CLI — [justscale.sh/cli/usage](https://justscale.sh/cli/usage)
+
+Installing this package installs the `just` binary:
+
+```bash
+just dev               # boot the app in dev mode with HMR
+just build             # build the workspace
+just test              # run tests (filterable via flags)
+just init              # initialize project / IDE / AI config
+just install <plugin>  # install a JustScale plugin package
+```
+
+`just` also discovers commands exported by any installed `@justscale/*` plugin — adding `@justscale/postgres` gives you `just migrate`, for example. Tab-completion installs itself on first invocation; `just __complete` is the internal back-channel, not a user-facing command.
+
+## Observability
+
+Services and controllers run under an async context with request tracing, scope management, and pluggable instrumentation. `registerInstrumentation` lets OpenTelemetry / Datadog / custom collectors subscribe without the app code having to know; `@justscale/feature-otel` is a ready-made wiring.
+
+## More
+
+- [Quick start](https://justscale.sh/overview/quick-start)
+- [Core philosophy](https://justscale.sh/overview/philosophy)
+- [Repository pattern](https://justscale.sh/repositories/overview)
+- [Cluster overview](https://justscale.sh/cluster/overview)
+- [Permissions](https://justscale.sh/features/permissions)
+- [OpenAPI](https://justscale.sh/techniques/openapi)

package/bin/just.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+
+// Register tsx (if available in the user's project) so `just` can directly
+// import TypeScript source — including .ts files referenced as .js, which
+// Node's native type-stripping does not resolve. Without this, simple
+// cases like `justscale.config.ts` → `./src/cli.mode.js` → `./app.js`
+// chains fail with ERR_MODULE_NOT_FOUND.
+try {
+  const require = createRequire(`${process.cwd()}/`);
+  const { register } = require('tsx/esm/api');
+  register();
+} catch {
+  // tsx isn't installed in the user's project — Node still handles plain .ts
+  // files via type stripping; .js→.ts rewriting just won't work. Users hit
+  // that edge case get a clear ERR_MODULE_NOT_FOUND pointing at the missing
+  // file, which is a decent nudge to install tsx or compile first.
+}
+
+// Await `main()` and drive an explicit exit code. Without this, if `main()`
+// rejects under load, the process exits non-zero with no error message and
+// any pending stdio may be lost — which manifested as flaky e2e tests that
+// saw exitCode 1 despite correct help output reaching stdout. The explicit
+// exit also closes lingering handles (readline, etc.) deterministically.
+try {
+  const { main } = await import('../dist/cli/bin/main.js');
+  await main();
+  process.exit(0);
+} catch (err) {
+  // Dump full diagnostic — the test harness captures stderr and this
+  // makes intermittent failures debuggable in CI logs.
+  console.error('[just] fatal:', err && err.stack ? err.stack : err);
+  process.exit(1);
+}

package/dist/app.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Application Bootstrap
+ *
+ * Creates and configures the application. Transport-agnostic - plugins provide protocol handling.
+ */
+import { Container, type ServiceToken } from './core/service.js';
+import { type RequestType } from './core/context.js';
+import { type ControllerDef, type ControllerInstance, type CompiledRoute } from './core/controller.js';
+import { type BuildContext } from './builder/build-context.js';
+import type { Adapter } from './kernel/adapter.js';
+/** Matched route with extracted params */
+export interface MatchedRoute {
+    route: CompiledRoute<any>;
+    deps: Record<string, unknown>;
+    params: Record<string, string>;
+    /**
+     * The container the matched route belongs to. Set when the match
+     * came from a sub-app - `execute()` uses this to run the request
+     * scope in the owning container, so sub-app handlers see their own
+     * `getContainer()` / `getRequestContext()`.
+     *
+     * Undefined for routes matched in the parent's own controllers list;
+     * `execute()` falls back to the parent container in that case.
+     */
+    owningContainer?: Container;
+}
+/** Options for route execution */
+export interface ExecuteOptions {
+    /** Defaults to 'http'. */
+    requestType?: RequestType;
+}
+export interface App<TControllers extends ControllerDef<any>[] = ControllerDef<any>[]> {
+    readonly container: Container;
+    readonly controllers: ControllerInstance<any>[];
+    readonly adapters: readonly Adapter[];
+    /** @internal */
+    readonly __buildContext?: BuildContext;
+    /** Resolves when all controllers are resolved and the app is ready to handle requests. */
+    readonly ready: Promise<void>;
+    readonly subApps: readonly App<any>[];
+    match(method: string, pathname: string): MatchedRoute | null;
+    execute(matched: MatchedRoute, contextAdditions: Record<string, unknown>, options?: ExecuteOptions): Promise<unknown>;
+}
+/** @internal */
+interface AppCoreConfig {
+    services?: ServiceToken[];
+    controllers?: ControllerDef<any>[];
+    _beforeControllerResolution?: (container: Container, controllers: ControllerDef<any>[]) => void;
+    _asyncBeforeControllerResolution?: (container: Container, controllers: ControllerDef<any>[]) => Promise<void>;
+    _getMatchDelegates?: () => ReadonlyArray<App<any>>;
+    _parentBuildContext?: BuildContext;
+}
+/** @internal */
+export declare function createAppInternal(config: AppCoreConfig): App;
+export {};
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,SAAS,EACT,KAAK,YAAY,EAKlB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAyB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC5E,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAGnB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAQnD,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,SAAS,CAAC;CAC7B;AAED,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B,0BAA0B;IAC1B,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,MAAM,WAAW,GAAG,CAAC,YAAY,SAAS,aAAa,CAAC,GAAG,CAAC,EAAE,GAAG,aAAa,CAAC,GAAG,CAAC,EAAE;IACnF,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;IAEhD,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAEtC,gBAAgB;IAChB,QAAQ,CAAC,cAAc,CAAC,EAAE,YAAY,CAAC;IAEvC,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9B,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;IAEtC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAAC;IAE7D,OAAO,CACL,OAAO,EAAE,YAAY,EACrB,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED,gBAAgB;AAChB,UAAU,aAAa;IACrB,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAA;IACzB,WAAW,CAAC,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,CAAA;IAClC,2BAA2B,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,KAAK,IAAI,CAAA;IAC/F,gCAAgC,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7G,kBAAkB,CAAC,EAAE,MAAM,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAA;IAClD,mBAAmB,CAAC,EAAE,YAAY,CAAA;CACnC;AAkMD,gBAAgB;AAChB,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,GAAG,CAE5D"}

package/dist/app.js

@@ -0,0 +1,182 @@
+/**
+ * Application Bootstrap
+ *
+ * Creates and configures the application. Transport-agnostic - plugins provide protocol handling.
+ */
+import { Container, SERVICE_ID, getServiceProvides, } from './core/service.js';
+import { runInFullRequestScope } from './core/context.js';
+import { collectBuiltins, registerBuiltinProvider, } from './core/controller.js';
+import { AbstractContainer, createContainerReflection, } from './core/container-reflection.js';
+import { _buildContext } from './builder/build-context.js';
+import { getRegisteredTransports } from './cluster/cluster.js';
+import { executeSteps } from './builder/execute.js';
+registerBuiltinProvider(({ route, createLogger }) => ({
+    logger: createLogger(route.name || 'handler'),
+}));
+function createAppCore(config) {
+    const container = new Container();
+    const controllers = [];
+    const installedAdapters = new Set();
+    const buildCtx = config._parentBuildContext ?? {
+        installAdapter: (a) => installedAdapters.add(a),
+    };
+    for (const service of config.services ?? []) {
+        const isDefinedService = typeof service === 'function' && SERVICE_ID in service;
+        if (typeof service === 'function' && !isDefinedService) {
+            container.registerClass(service);
+        }
+        else {
+            const serviceDef = service;
+            container.register(serviceDef);
+            const provides = getServiceProvides(serviceDef);
+            if (provides) {
+                for (const providedToken of provides) {
+                    container.registerFor(providedToken, serviceDef);
+                }
+            }
+        }
+    }
+    const allControllers = config.controllers ?? [];
+    if (config._beforeControllerResolution) {
+        config._beforeControllerResolution(container, allControllers);
+    }
+    for (const transport of getRegisteredTransports()) {
+        if (transport.beforeControllerResolution) {
+            transport.beforeControllerResolution(container, allControllers);
+        }
+    }
+    container.registerInstance(AbstractContainer, createContainerReflection({
+        controllers,
+        resolve: (token) => container.resolve(token),
+    }));
+    const ready = _buildContext.run(buildCtx, () => (async () => {
+        if (config._asyncBeforeControllerResolution) {
+            await config._asyncBeforeControllerResolution(container, allControllers);
+        }
+        const controllerPromises = (config.controllers ?? []).map(async (controllerDef) => {
+            container.register(controllerDef);
+            const instance = await container.resolve(controllerDef);
+            instance.__def = controllerDef;
+            return instance;
+        });
+        const resolved = await Promise.all(controllerPromises);
+        controllers.push(...resolved);
+        await container.resolveAll();
+        await container.wireModelPrototypes();
+    })());
+    function match(method, pathname) {
+        for (const controller of controllers) {
+            for (const route of controller.routes) {
+                if (route.method !== method)
+                    continue;
+                const routeMatch = pathname.match(route.pattern);
+                if (!routeMatch)
+                    continue;
+                const params = {};
+                route.paramNames.forEach((name, i) => {
+                    params[name] = routeMatch[i + 1] ?? '';
+                });
+                return { route, deps: controller.deps, params };
+            }
+        }
+        if (config._getMatchDelegates) {
+            for (const delegate of config._getMatchDelegates()) {
+                const sub = delegate.match(method, pathname);
+                if (sub) {
+                    return {
+                        ...sub,
+                        owningContainer: sub.owningContainer ?? delegate.container,
+                    };
+                }
+            }
+        }
+        return null;
+    }
+    async function execute(matched, contextAdditions, options) {
+        const { route, deps } = matched;
+        const requestType = options?.requestType ?? 'http';
+        const scopeContainer = matched.owningContainer ?? container;
+        return runInFullRequestScope({
+            container: scopeContainer,
+            type: requestType,
+            name: `${route.method} ${route.path}`,
+            metadata: {
+                [`${requestType}.method`]: route.method,
+                [`${requestType}.route`]: route.path,
+                'route.name': route.name,
+            },
+            observability: {
+                route: route.name,
+                method: route.method,
+                path: route.path,
+            },
+        }, async () => {
+            const cleanupFns = [];
+            const onCleanup = (fn) => {
+                cleanupFns.push(fn);
+            };
+            const builtins = collectBuiltins({
+                route,
+                deps,
+                createLogger: (context) => scopeContainer.createLogger(context),
+            });
+            // Build handler context - transport context + builtins only
+            // Dependencies are accessed via closure capture from the routes function
+            // Transport provides: params, body, query, res (for HTTP) via contextAdditions
+            // Builtins (like logger) are always available via registered providers
+            const ctx = {
+                ...contextAdditions, // Transport-specific: params, res, body, query, etc.
+                ...builtins, // Builtin providers (logger, etc.)
+                onCleanup, // Cleanup registration
+            };
+            try {
+                // Run steps (middleware + guards) via the canonical path that reads
+                // route.steps, identical to how HTTP and CLI dispatch works.
+                // route.middlewares / route.guards are always [] after compilation.
+                const passed = await executeSteps(route, ctx);
+                if (!passed) {
+                    return undefined; // Guard denied
+                }
+                // Call handler with full context
+                return route.handler(ctx);
+            }
+            finally {
+                for (let i = cleanupFns.length - 1; i >= 0; i--) {
+                    try {
+                        await cleanupFns[i]();
+                    }
+                    catch (cleanupError) {
+                        const logger = builtins.logger;
+                        logger?.error?.('Cleanup function threw', { error: cleanupError });
+                    }
+                }
+            }
+        });
+    }
+    const app = {
+        container,
+        controllers,
+        get adapters() {
+            return Array.from(installedAdapters);
+        },
+        __buildContext: buildCtx,
+        get subApps() {
+            return config._getMatchDelegates?.() ?? [];
+        },
+        ready: ready.then(() => {
+            for (const transport of getRegisteredTransports()) {
+                if (transport.onAppCreated) {
+                    transport.onAppCreated(app);
+                }
+            }
+        }),
+        match,
+        execute,
+    };
+    return app;
+}
+/** @internal */
+export function createAppInternal(config) {
+    return createAppCore(config);
+}
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

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

package/dist/builder/build-context.d.ts

@@ -0,0 +1,8 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { Adapter } from '../kernel/adapter.js';
+export interface BuildContext {
+    installAdapter(a: Adapter): void;
+}
+export declare const _buildContext: AsyncLocalStorage<BuildContext>;
+export declare const currentBuilder: () => BuildContext | undefined;
+//# sourceMappingURL=build-context.d.ts.map

package/dist/builder/build-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-context.d.ts","sourceRoot":"","sources":["../../src/builder/build-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,MAAM,WAAW,YAAY;IAC3B,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAClC;AAED,eAAO,MAAM,aAAa,iCAAwC,CAAC;AAEnE,eAAO,MAAM,cAAc,QAAO,YAAY,GAAG,SAAqC,CAAC"}

package/dist/builder/build-context.js

@@ -0,0 +1,4 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+export const _buildContext = new AsyncLocalStorage();
+export const currentBuilder = () => _buildContext.getStore();
+//# sourceMappingURL=build-context.js.map

package/dist/builder/build-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-context.js","sourceRoot":"","sources":["../../src/builder/build-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAOrD,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,iBAAiB,EAAgB,CAAC;AAEnE,MAAM,CAAC,MAAM,cAAc,GAAG,GAA6B,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,CAAC"}

package/dist/builder/builder.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Builder Utilities
+ *
+ * Helper functions for creating bindings in the DI system.
+ */
+import type { RepositoryBinding, ServiceBinding, InstanceBinding } from './types.js';
+import type { RepositoryToken } from '../models/repository.js';
+import type { ServiceToken } from '../core/service.js';
+import { Logger } from '../core/logger.js';
+import { Lifecycle } from '../core/lifecycle.js';
+/**
+ * Built-in tokens that are always available.
+ * Logger and Lifecycle are auto-provided by the container/cluster builder.
+ */
+export type BuiltInTokens = [typeof Logger, typeof Lifecycle];
+/**
+ * Bind a repository token to an implementation.
+ *
+ * This creates a binding for the DI system to wire up repositories.
+ */
+export declare function bindRepository<T>(token: RepositoryToken<T>, implementation: unknown): RepositoryBinding<T>;
+/**
+ * Bind an abstract service token to a concrete implementation.
+ *
+ * This creates a binding for the DI system to wire up abstract services.
+ * Use this when you have an abstract class and want to specify which
+ * concrete implementation should be used.
+ *
+ * @example
+ * ```typescript
+ * import JustScale, { bindService } from '@justscale/core'
+ *
+ * JustScale()
+ *   .add(MemoryChannelBackend)
+ *   .add(bindService(AbstractChannelBackend, MemoryChannelBackend))
+ *   .build()
+ * ```
+ */
+export declare function bindService<TAbstract, TImpl extends TAbstract = TAbstract>(abstractToken: ServiceToken<TAbstract>, implementation: ServiceToken<TImpl>): ServiceBinding<TAbstract>;
+/**
+ * Bind an abstract service token to a pre-created instance.
+ *
+ * This creates a binding for the DI system to wire up abstract services
+ * to specific instances. Use this when you have an instance you want to
+ * share across the app.
+ *
+ * @example
+ * ```typescript
+ * import JustScale, { bindInstance } from '@justscale/core'
+ *
+ * const taskRepo = new InMemoryScheduledTaskRepository()
+ *
+ * JustScale()
+ *   .add(bindInstance(ScheduledTaskRepository, taskRepo))
+ *   .add(TaskController)
+ *   .build()
+ * ```
+ */
+export declare function bindInstance<T>(abstractToken: ServiceToken<T>, instance: T): InstanceBinding<T>;
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/builder/builder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACrF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,MAAM,EAAE,OAAO,SAAS,CAAC,CAAC;AAM9D;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,EACzB,cAAc,EAAE,OAAO,GACtB,iBAAiB,CAAC,CAAC,CAAC,CAMtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,KAAK,SAAS,SAAS,GAAG,SAAS,EACxE,aAAa,EAAE,YAAY,CAAC,SAAS,CAAC,EACtC,cAAc,EAAE,YAAY,CAAC,KAAK,CAAC,GAClC,cAAc,CAAC,SAAS,CAAC,CAM3B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,aAAa,EAAE,YAAY,CAAC,CAAC,CAAC,EAC9B,QAAQ,EAAE,CAAC,GACV,eAAe,CAAC,CAAC,CAAC,CAMpB"}