ctx-router 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hyugorix
+
+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,320 @@
+# ctx-router
+
+A transport-agnostic router built around a single execution context.
+
+Write your business logic once. Run it over HTTP, events, jobs, queues, or anything else — without rewriting handlers.
+
+## Why ctx-router exists
+
+Most applications start simple:
+
+- HTTP with Express / Fastify
+- A few REST endpoints
+- Some middleware
+
+Then reality hits:
+
+- You add background jobs (SQS, Kafka, cron)
+- You need async workers
+- You want to reuse business logic
+- You deploy to Lambda or another runtime
+- You end up duplicating logic across transports
+
+The problem is not routing.
+The problem is transport leakage into business logic.
+
+## What ctx-router is
+
+ctx-router is a routing + execution layer that:
+
+- Normalizes all ingress types into a single context
+- Routes based on patterns, not frameworks
+- Executes logic as a linear pipeline
+- Keeps transport concerns outside your business code
+
+It is not:
+
+- A web framework
+- An HTTP abstraction
+- A DI container
+
+It is a context router.
+
+## Core idea (one sentence)
+
+Everything becomes a ctx. Routes select a pipeline. Pipelines mutate the ctx.
+
+## High-level flow
+
+```mermaid
+flowchart LR
+    A["Ingress<br/>HTTP / Queue / Job"] --> B["Create ctx"]
+    B --> C["Adapter enrich"]
+    C --> D["router.exec(ctx)"]
+    D --> E["Route match"]
+    E --> F["Pipeline execution"]
+    F --> G["ctx.res set"]
+    G --> H["Adapter sends response / ack"]
+```
+
+## Key concepts (read in order)
+
+### 1. Context (ctx)
+
+The single object that flows through your entire system.
+
+- Created once per request / event
+- Mutated by middleware and handlers
+- Returned at the end
+
+Business logic never touches raw framework objects.
+
+### 2. Routes are patterns
+
+Routes are identified by patterns, not concrete values.
+
+Examples:
+
+- `user.:id.detail`
+- `job.:resource.clean`
+- `GET /user/:id`
+
+Patterns:
+
+- are low-cardinality
+- are safe to log & index
+- are the identity of a route
+
+Raw values are kept separately.
+
+### 3. Pipelines are linear
+
+Every route resolves to a prebuilt pipeline:
+
+```
+[ middleware1 → middleware2 → handler ]
+```
+
+- Always sequential
+- Always awaited
+- No fan-out
+- No magic
+
+### 4. Build-time vs runtime
+
+| Phase      | What happens                               |
+| ---------- | ------------------------------------------ |
+| Build time | `route()`, `via()`, `to()` build pipelines |
+| Runtime    | `exec(ctx)` selects & runs a pipeline      |
+
+The runtime never sees the DSL.
+
+## Installation
+
+```bash
+npm install ctx-router
+```
+
+## Minimal example
+
+### `router.ts`
+
+```typescript
+import { CtxRouter, TDefaultCtx } from "ctx-router";
+import * as api from "./api";
+
+export type TCtx = TDefaultCtx & {
+  user: { role: string[] };
+};
+
+export const router = new CtxRouter<TCtx>();
+
+router.route("GET /health/ping").to(api.health.ping);
+
+const userRouter = router.route("user").via(rateLimit, auth);
+
+userRouter.route("POST /update").to(api.user.update);
+userRouter.route("GET /:userId").to(api.user.detail);
+userRouter.route("detail").to(api.user.detail);
+```
+
+### `server.ts` (Express example)
+
+```typescript
+import express from "express";
+import { adapter } from "ctx-router";
+import { router, TCtx } from "./router";
+
+const app = express();
+app.use(express.json());
+
+app.use(async (req, res) => {
+  const ctx: TCtx = router.newCtx();
+  adapter.enrichFromExpress(ctx, req, res);
+
+  await router.exec(ctx);
+
+  res.status(ctx.res.code === "OK" ? 200 : 400).json(ctx.res);
+});
+
+app.listen(3000);
+```
+
+The same router works for Lambda, SQS, Kafka, cron jobs, etc.
+
+## Routing DSL
+
+### `route(segment)`
+
+Adds a prefix segment.
+
+```typescript
+router.route("user").route(":id").route("detail");
+```
+
+Builds the pattern:
+
+```
+user.:id.detail
+```
+
+### `via(...middleware)`
+
+Adds middleware to the pipeline.
+
+```typescript
+route("x").via(auth, validate).to(handler);
+```
+
+- Sequential
+- Awaited
+- Mutates ctx
+
+### `to(handler)`
+
+Registers the terminal handler.
+
+- Exactly one handler
+- Ends the pipeline
+- Build-time only
+- Returns void
+
+## Execution lifecycle (authoritative)
+
+```mermaid
+sequenceDiagram
+    participant Ingress
+    participant Router
+    participant Hooks
+    participant Handler
+
+    Ingress->>Router: newCtx()
+    Ingress->>Router: enrich(ctx)
+    Ingress->>Router: exec(ctx)
+
+    Router->>Router: init metrics & trace
+    Router->>Hooks: onExecBefore(ctx)
+
+    Router->>Router: match route
+    Router->>Handler: run pipeline
+
+    Handler-->>Router: ctx
+    Router->>Hooks: onExecAfter(ctx)
+
+    Router->>Hooks: onExecFinally(ctx)
+    Router-->>Ingress: ctx
+```
+
+## Hooks (system lifecycle)
+
+Hooks wrap execution, not routing DSL.
+
+```typescript
+router.hook.onExec.before(async (ctx) => {
+  console.log("request in", ctx.id);
+});
+
+router.hook.onExec.error(async (ctx, err) => {
+  ctx.res.code = "ERROR";
+});
+```
+
+Available hooks:
+
+- `onExec.before`
+- `onExec.after`
+- `onExec.error`
+- `onExec.finally`
+
+Hooks are side-effect only and mutate ctx directly.
+
+## Error handling
+
+ctx-router provides a structured error system.
+
+### Define your error class
+
+```typescript
+class AppError extends CtxBaseError {
+  constructor(e) {
+    super(e);
+  }
+}
+```
+
+### Create error map
+
+```typescript
+export const appErr = ctxErrMap(AppError, {
+  auth: {
+    UNAUTHORIZED: "Unauthorized",
+  },
+  general: {
+    UNKNOWN_ERROR: "Something went wrong",
+  },
+});
+```
+
+### Throw anywhere
+
+```typescript
+throw appErr.auth.UNAUTHORIZED({
+  data: { reason: "missing_token" },
+});
+```
+
+Router errors and app errors are cleanly separated.
+
+## Design guarantees
+
+- Transport-agnostic
+- Pattern-first routing
+- Low cardinality by design
+- Linear, deterministic execution
+- No hidden parallelism
+- No framework lock-in
+
+## When should you use ctx-router?
+
+Use it if you:
+
+- Share logic between HTTP + jobs
+- Want clean boundaries between transport and business logic
+- Care about observability and routing identity
+- Prefer explicit, boring execution models
+
+Do not use it if you want:
+
+- Automatic DI
+- Controllers / decorators
+- Magic middleware behavior
+
+## Status
+
+- First public release
+- API intentionally small
+- Focused on correctness over features
+
+## License
+
+MIT © Kaushik R Bangera

package/dist/adapter/express.v5.d.ts

@@ -0,0 +1,11 @@
+import { Request, Response } from "express";
+import { TDefaultCtx } from "../core";
+/**
+ * Enriches an existing context with Express request data.
+ * Modifies ctx in-place.
+ *
+ * @param ctx - Context created by router.getNewCtx()
+ * @param req - Express request object
+ */
+export declare function enrichFromExpress(ctx: TDefaultCtx, req: Request, res: Response): void;
+//# sourceMappingURL=express.v5.d.ts.map

package/dist/adapter/express.v5.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.v5.d.ts","sourceRoot":"","sources":["../../src/adapter/express.v5.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AA4BtC;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,WAAW,EAChB,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,GACZ,IAAI,CAiFN"}

package/dist/adapter/express.v5.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enrichFromExpress = enrichFromExpress;
+function getPath(url) {
+    const queryParamPos = url.indexOf("?");
+    if (queryParamPos === -1)
+        return url;
+    return url.substring(0, queryParamPos);
+}
+function extractBearerToken(authHeader) {
+    if (!authHeader)
+        return undefined;
+    const auth = Array.isArray(authHeader) ? authHeader[0] : authHeader;
+    if (auth?.startsWith("Bearer ")) {
+        return auth.substring(7);
+    }
+    return undefined;
+}
+function getHeader(headers, key) {
+    const value = headers[key];
+    if (!value)
+        return undefined;
+    return Array.isArray(value) ? value[0] : value;
+}
+/**
+ * Enriches an existing context with Express request data.
+ * Modifies ctx in-place.
+ *
+ * @param ctx - Context created by router.getNewCtx()
+ * @param req - Express request object
+ */
+function enrichFromExpress(ctx, req, res) {
+    const method = req.method;
+    const path = getPath(req.url);
+    // Build auth (only include fields that exist)
+    const bearerToken = extractBearerToken(req.headers.authorization);
+    const apiKey = getHeader(req.headers, "x-api-key");
+    const refreshToken = getHeader(req.headers, "x-ctx-refresh-token");
+    const auth = {};
+    if (bearerToken)
+        auth.bearerToken = bearerToken;
+    if (apiKey)
+        auth.apiKey = apiKey;
+    if (refreshToken)
+        auth.refreshToken = refreshToken;
+    // Build client (only include fields that exist)
+    const deviceName = getHeader(req.headers, "x-ctx-device-name");
+    const deviceId = getHeader(req.headers, "x-ctx-device-id");
+    const os = getHeader(req.headers, "x-ctx-os");
+    const appVersion = getHeader(req.headers, "x-ctx-app-version");
+    const apiVersion = getHeader(req.headers, "x-ctx-api-version");
+    const sessionId = getHeader(req.headers, "x-ctx-session-id");
+    const client = {};
+    if (deviceName)
+        client.deviceName = deviceName;
+    if (deviceId)
+        client.deviceId = deviceId;
+    if (os)
+        client.os = os;
+    if (appVersion)
+        client.appVersion = appVersion;
+    if (apiVersion)
+        client.apiVersion = apiVersion;
+    if (sessionId)
+        client.sessionId = sessionId;
+    // Build clientInvocation (only include fields that exist)
+    const invocationTraceId = getHeader(req.headers, "x-ctx-trace-id");
+    const invocationSeq = parseInt(getHeader(req.headers, "x-ctx-seq") || "0", 10);
+    const clientTsStr = getHeader(req.headers, "x-ctx-ts");
+    const clientTs = clientTsStr ? new Date(clientTsStr).getTime() : undefined;
+    const clientInvocation = {};
+    if (invocationTraceId)
+        clientInvocation.traceId = invocationTraceId;
+    if (invocationSeq)
+        clientInvocation.seq = invocationSeq;
+    if (clientTs && !isNaN(clientTs))
+        clientInvocation.ts = clientTs;
+    // Build transport meta (only include fields that exist)
+    const userAgent = getHeader(req.headers, "user-agent");
+    const contentType = getHeader(req.headers, "content-type");
+    const transportMeta = {};
+    if (userAgent)
+        transportMeta["user-agent"] = userAgent;
+    if (contentType)
+        transportMeta["content-type"] = contentType;
+    // Enrich ctx.req
+    ctx.req.data = { ...req.body, ...req.query, ...req.params };
+    ctx.req.route = {
+        op: method, // HTTP method (GET, POST, etc.)
+        raw: path, // Concrete path with "/" separator
+        pattern: "PENDING", // Router will set after matching
+    };
+    if (Object.keys(auth).length > 0)
+        ctx.req.auth = auth;
+    if (Object.keys(client).length > 0)
+        ctx.req.client = client;
+    if (Object.keys(clientInvocation).length > 0)
+        ctx.req.clientInvocation = clientInvocation;
+    ctx.req.transport = {
+        protocol: "http",
+        framework: "express",
+        request: {
+            method,
+            path,
+        },
+        ...(req.ip && {
+            network: {
+                originIp: req.ip,
+                hops: req.ips,
+            },
+        }),
+        ...(Object.keys(transportMeta).length > 0 && { meta: transportMeta }),
+        raw: {
+            req,
+            res,
+        },
+    };
+}
+//# sourceMappingURL=express.v5.js.map

package/dist/adapter/express.v5.js.map

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

package/dist/adapter/index.d.ts

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

package/dist/adapter/index.d.ts.map

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

package/dist/adapter/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// This file previously contained INSTANCE and utility functions
+// These have been moved to CtxRouter as instance properties and methods
+// Keeping this file for potential future adapter utilities
+//# sourceMappingURL=index.js.map

package/dist/adapter/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapter/index.ts"],"names":[],"mappings":";;AAAA,gEAAgE;AAChE,wEAAwE;AACxE,2DAA2D"}

package/dist/common/const.d.ts

@@ -0,0 +1,6 @@
+export declare const STATS_INTERVAL_MS = 5000;
+export declare const STATS: {
+    cpu: number;
+    mem: number;
+};
+//# sourceMappingURL=const.d.ts.map

package/dist/common/const.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"const.d.ts","sourceRoot":"","sources":["../../src/common/const.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,eAAO,MAAM,KAAK;;;CAGjB,CAAC"}

package/dist/common/const.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STATS = exports.STATS_INTERVAL_MS = void 0;
+exports.STATS_INTERVAL_MS = 5000; // Stats refresh interval in milliseconds
+exports.STATS = {
+    cpu: -1, // percentage (0-100), -1 if unavailable
+    mem: -1, // MB used by process, -1 if unavailable
+};
+//# sourceMappingURL=const.js.map

package/dist/common/const.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"const.js","sourceRoot":"","sources":["../../src/common/const.ts"],"names":[],"mappings":";;;AAAa,QAAA,iBAAiB,GAAG,IAAI,CAAC,CAAC,yCAAyC;AAEnE,QAAA,KAAK,GAAG;IACnB,GAAG,EAAE,CAAC,CAAC,EAAE,wCAAwC;IACjD,GAAG,EAAE,CAAC,CAAC,EAAE,wCAAwC;CAClD,CAAC"}

package/dist/common/helper.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Updates stats only if the interval has elapsed.
+ * Lazy update pattern - stats only refresh during traffic, not on background timer.
+ * This prevents setInterval from keeping serverless runtimes alive.
+ */
+export declare function updateStatsIfStale(): void;
+//# sourceMappingURL=helper.d.ts.map

package/dist/common/helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../../src/common/helper.ts"],"names":[],"mappings":"AAyBA;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAMzC"}

package/dist/common/helper.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateStatsIfStale = updateStatsIfStale;
+const const_1 = require("./const");
+let prevCpuUsage = process.cpuUsage();
+let prevTime = Date.now();
+let nextStatsAt = 0; // Force immediate update on first call
+function updateStats() {
+    // Memory: process RSS in MB
+    const memUsage = process.memoryUsage();
+    const_1.STATS.mem = Math.round(memUsage.rss / 1024 / 1024);
+    // CPU: percentage since last check
+    const currentCpuUsage = process.cpuUsage(prevCpuUsage);
+    const currentTime = Date.now();
+    const elapsedMs = currentTime - prevTime;
+    // CPU time is in microseconds, convert to percentage
+    const cpuPercent = ((currentCpuUsage.user + currentCpuUsage.system) / 1000 / elapsedMs) * 100;
+    const_1.STATS.cpu = Math.round(cpuPercent * 100) / 100;
+    prevCpuUsage = process.cpuUsage();
+    prevTime = currentTime;
+}
+/**
+ * Updates stats only if the interval has elapsed.
+ * Lazy update pattern - stats only refresh during traffic, not on background timer.
+ * This prevents setInterval from keeping serverless runtimes alive.
+ */
+function updateStatsIfStale() {
+    const now = Date.now();
+    if (now >= nextStatsAt) {
+        updateStats();
+        nextStatsAt = now + const_1.STATS_INTERVAL_MS;
+    }
+}
+//# sourceMappingURL=helper.js.map

package/dist/common/helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../../src/common/helper.ts"],"names":[],"mappings":";;AA8BA,gDAMC;AApCD,mCAAmD;AAEnD,IAAI,YAAY,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;AACtC,IAAI,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;AAC1B,IAAI,WAAW,GAAG,CAAC,CAAC,CAAC,uCAAuC;AAE5D,SAAS,WAAW;IAClB,4BAA4B;IAC5B,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACvC,aAAK,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC;IAEnD,mCAAmC;IACnC,MAAM,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;IACvD,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC/B,MAAM,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IAEzC,qDAAqD;IACrD,MAAM,UAAU,GACd,CAAC,CAAC,eAAe,CAAC,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,GAAG,CAAC;IAC7E,aAAK,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;IAE/C,YAAY,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAClC,QAAQ,GAAG,WAAW,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB;IAChC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC;QACvB,WAAW,EAAE,CAAC;QACd,WAAW,GAAG,GAAG,GAAG,yBAAiB,CAAC;IACxC,CAAC;AACH,CAAC"}

package/dist/core/index.d.ts

@@ -0,0 +1,25 @@
+import { CtxMeta } from "./meta";
+import { CtxReq } from "./req";
+import { CtxRes } from "./res";
+import { CtxUser } from "./user";
+import { CtxBaseError } from "../router/error";
+export type { CtxMeta } from "./meta";
+export type { CtxReq } from "./req";
+export type { CtxRes } from "./res";
+export type { CtxUser } from "./user";
+export declare const DEFAULT_USER_ROLE: {
+    readonly none: "none";
+    readonly user: "user";
+    readonly admin: "admin";
+    readonly service: "service";
+};
+export type TDefaultCtx = {
+    id: string;
+    req: CtxReq;
+    res: CtxRes;
+    user: CtxUser;
+    meta: CtxMeta;
+    locals: Record<string, unknown>;
+    err: CtxBaseError | null;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAG/C,YAAY,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,YAAY,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AACpC,YAAY,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AACpC,YAAY,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,eAAO,MAAM,iBAAiB;;;;;CAKpB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,GAAG,EAAE,YAAY,GAAG,IAAI,CAAC;CAC1B,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_USER_ROLE = void 0;
+exports.DEFAULT_USER_ROLE = {
+    none: "none",
+    user: "user",
+    admin: "admin",
+    service: "service",
+};
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":";;;AAYa,QAAA,iBAAiB,GAAG;IAC/B,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;CACV,CAAC"}

package/dist/core/meta.d.ts

@@ -0,0 +1,55 @@
+/**
+ * System-owned metadata describing runtime, timing, tracing, and logs
+ * for the current execution context.
+ */
+export type CtxMeta = {
+    /** Name of the running service (payment, payout, identity, etc.) */
+    readonly serviceName: string;
+    /** Runtime instance information */
+    readonly instance: {
+        /** Unique identifier of the instance */
+        readonly id: string;
+        /** Instance creation time (epoch ms) */
+        readonly createdAt: number;
+        /** Monotonic sequence number for this instance */
+        readonly seq: number;
+        /** In-flight executions when this request arrived */
+        readonly inflight: number;
+        /** CPU usage percentage, or -1 if unavailable */
+        readonly cpu: number;
+        /** Memory usage in MB, or -1 if unavailable */
+        readonly mem: number;
+    };
+    /** Execution timestamps (epoch ms, -1 if unavailable) */
+    ts: {
+        /** When execution entered the system */
+        readonly in: number;
+        /** When the client sent the request */
+        readonly clientIn: number;
+        /** When execution completed */
+        out: number;
+        /** Total execution time in ms */
+        execTime: number;
+        /** One-way network delay in ms */
+        readonly owd: number;
+    };
+    /** Distributed tracing identifiers */
+    readonly monitor: {
+        /** Trace identifier (origin-assigned, always present) */
+        readonly traceId: string;
+        /** Span identifier for this execution */
+        readonly spanId: string;
+    };
+    /** Logs collected during execution */
+    readonly log?: {
+        /** Standard output logs */
+        readonly stdout: readonly string[];
+        /** Database query logs */
+        readonly db?: readonly {
+            readonly q: string;
+            readonly p: readonly unknown[];
+            readonly ms: number;
+        }[];
+    };
+};
+//# sourceMappingURL=meta.d.ts.map