@x12i/ai-gateway 7.9.1 → 9.0.0

package/README.md

@@ -1,14 +1,24 @@
 # @x12i/ai-gateway
 
-Unified gateway for LLM provider routing and management with production-ready features: context propagation, usage tier tracking, activity tracking, and comprehensive metadata. Built on top of `@x12i/ai-providers-router` with integrations for `@x12i/x-models`, `@x12i/activix` **v5.x** (xronox-activitix; this repo pins `^5.0.1` — see `package.json`), and `logs-gateway`.
+Unified gateway for LLM provider routing and management with production-ready features: context propagation, usage tier tracking, activity tracking, and comprehensive metadata. Built on top of `@x12i/ai-providers-router` with integrations for `@x12i/x-models`, `@x12i/activix` (see `package.json` for pinned versions), and **`@x12i/logxer`** for structured logging.
+
+## Mandatory runtime identity (v9+)
+
+Every **`invoke`** / **`invokeChat`** request **must** include **`identity`**: the full runtime envelope from the **upstream client** (not invented inside the gateway).
+
+- **`identity.jobId`** and **`identity.taskId`** are **only** taken from that upstream object. The gateway **never** generates, rewrites, or back-fills them from deprecated top-level `jobId` / `taskId` fields.
+- If `identity` is missing or `jobId` / `taskId` are empty, the gateway logs **`warn`** via Logxer (`missingRuntimeIdentityObject` / `missingUpstreamIdentityFields`) when a logger is configured, and still attaches the merged envelope so the rest of the pipeline can proceed.
+- The same merged object is **`request.identity`**, forwarded to the router, returned as **`response.metadata.identity`**, and persisted on Activix as **`runContext`** (same reference as `request.identity`).
+
+See [Identity contract](./docs/IDENTITY_OBJECT_CONTRACT.md) and [Logger initialization](./docs/LOGGER_INITIALIZATION.md).
 
 ## Features
 
 - **🔀 Provider Routing**: Dynamic provider registration and automatic routing with fallback support
 - **📊 Context Propagation**: `aiRequestId` and identity propagation for distributed tracing (see [Identity contract](./docs/IDENTITY_OBJECT_CONTRACT.md))
 - **⚡ Usage Tier Tracking**: RPM/TPM limit enforcement via `@x12i/x-models`
-- **📈 Activity Tracking**: Comprehensive activity logging via `@x12i/activix` v5 (xronox-activitix), fixed Mongo collections `ai-activities` / `bad-requests`, validated `structure` + `runContext` for Activix 5
-- **📝 Structured Logging**: Production-ready logging via `logs-gateway` with comprehensive diagnostic tracing for instruction resolution and propagation debugging
+- **📈 Activity Tracking**: Comprehensive activity logging via `@x12i/activix` v6 (xronox-activitix), fixed Mongo collections `ai-activities` / `bad-requests`, validated root-level **`outer` / `inner`** I/O plus **`runContext`** for Activix 6
+- **📝 Structured Logging**: Production-ready logging via **`@x12i/logxer`** (LogMeta `jobId` / `sessionId` / `correlationId`, optional `debugKind`, default `runtimeIdentity` from env) with diagnostic tracing for instruction resolution and propagation debugging
 - **📋 Rich Metadata**: Detailed execution metadata (latency, tokens, model, cost, `aiRequestId`, `identity`)
 - **🏥 Health Checks**: Monitor provider health and availability
 - **🔄 Request/Response Interceptors**: Modify requests and responses
@@ -122,24 +132,25 @@ gateway.register(new GrokProvider({
   apiKey: process.env.GROK_API_KEY
 }));
 
-// Invoke with context
+// Invoke with mandatory runtime identity (upstream job/task correlation)
 const response = await gateway.invoke({
-  messages: [{ role: 'user', content: 'Hello!' }],
-  jobId: 'job-123',  // Context propagation
+  aiRequestId: 'call-001',
   agentId: 'agent-456',
-  taskId: 'task-789'
+  instructions: 'Reply briefly.',
+  identity: {
+    sessionId: 'run-1',
+    instance: { instanceId: 'agent-456', type: 'ai-reasoner' },
+    aiRequestId: 'call-001',
+    jobId: 'job-123',
+    taskId: 'task-789',
+    agentId: 'agent-456'
+  },
+  workingMemory: { input: 'Hello!' }
+  // … primaryObjectType / flexMdFormat / messages as required by your request type
 });
 
-// Response includes comprehensive metadata
+// Response includes comprehensive metadata (including `identity`)
 console.log(response.metadata);
-// {
-//   jobId: 'job-123',
-//   latencyMs: 1250,
-//   tokens: { prompt: 100, completion: 50, total: 150 },
-//   model: 'gpt-4o',
-//   provider: 'openai',
-//   cost: 0.002
-// }
 ```
 
 ### Using Base Router (Direct Access)
@@ -184,33 +195,26 @@ The AI Gateway can be configured in multiple ways:
    - `FLEX_MD_MIN_COMPLIANCE_LEVEL` - Minimum flex-md compliance level for output format validation (default: `L0`). Valid values: `L0`, `L1`, `L2`, `L3`. See [Output Format Validation](#output-format-validation) section for details. When set to `L0` (default), no format validation is required. When set to `L1` or higher, format specifications are required in instructions and validation errors will reject requests.
 4. **Request-Level** - Override gateway defaults per request
 
-### 1. Logging Configuration (logs-gateway)
-
-**Logger Initialization: Two Options**
-
-The gateway supports two ways to initialize the logger:
-
-1. **Option 1 (Recommended)**: Provide your project's logger instance - ensures consistent logging
-2. **Option 2 (Fallback)**: Let the gateway create a default logger - works out of the box
+### 1. Logging Configuration (@x12i/logxer)
 
-**📚 See [Logger Initialization Guide](./docs/LOGGER_INITIALIZATION.md) for complete instructions.**
+**Logger initialization:** The gateway uses **`@x12i/logxer`**. Pass a **`Logxer`** from **`createLogxer`**, or omit `logger` and let the gateway build a default (still Logxer-based). See **[Logger Initialization Guide](./docs/LOGGER_INITIALIZATION.md)** for mandatory **`identity`** on requests and **`LogMeta`** / **`debugKind`** usage.
 
 **Where to configure:**
-- Gateway constructor: `enableLogging`, `packageName`, `logger` (**logger is REQUIRED**)
-- Environment variables: **`{PREFIX}_LOGS_LEVEL`** (canonical per-package level; see below), legacy `{PREFIX}_LOG_LEVEL`, plus `{PREFIX}_LOG_FORMAT`, etc. Cross-cutting sink/format options are configured by the host app; see [logs-gateway](https://www.npmjs.com/package/logs-gateway) README and [`docs/package-usage.md`](https://github.com/nx-intelligence/logs-gateway/blob/main/docs/package-usage.md).
+- Gateway constructor: `enableLogging`, `packageName`, `logger`
+- Environment variables: **`{PREFIX}_LOGS_LEVEL`** (canonical per-package level), legacy **`{PREFIX}_LOG_LEVEL`**, plus **`{PREFIX}_LOG_FORMAT`**, file sinks, unified logger, etc., as documented for **`@x12i/logxer`**.
 
 **How to configure:**
 
 ```typescript
 import { AIGateway } from '@x12i/ai-gateway';
-import { createLogger } from 'logs-gateway';
+import { createLogxer } from '@x12i/logxer';
 
 // Create logger once at application startup
-const logger = createLogger(
-  { packageName: 'MY_APP', envPrefix: 'MY_APP' },
+const logger = createLogxer(
+  { packageName: 'MY_APP', envPrefix: 'MY_APP', debugNamespace: 'my-app' },
   {
     logLevel: 'info',           // verbose|debug|info|warn|error
-    logFormat: 'json',          // text|json|yaml
+    logFormat: 'json',          // text|json|yaml|table
     logToFile: true,
     logFilePath: '/var/log/app.log',
     enableUnifiedLogger: true,
@@ -218,27 +222,31 @@ const logger = createLogger(
       transports: { papertrail: true },
       service: 'my-app',
       env: 'production'
+    },
+    runtimeIdentity: {
+      service: 'my-app',
+      env: process.env.NODE_ENV,
+      version: process.env.npm_package_version
     }
   }
 );
 
-// Pass the SAME logger instance to gateway (REQUIRED)
 const gateway = new AIGateway({
   enableLogging: true,
-  logger: logger,  // REQUIRED: Use your project's logger instance
+  logger,
   packageName: 'MY_APP'
 });
 ```
 
-**Why Use the Same Logger?**
+**Why use the same Logxer?**
 - Consistent log format across your application
 - Unified logging destination
-- Proper context and metadata
+- **`LogMeta`** correlation (`jobId`, `sessionId`, `correlationId`, `debugKind`, `runtimeIdentity`) matches gateway and Activix fields
 - Single point of control for log levels
 
-**Per-package log level (logs-gateway ≥ 3.5.x):**
+**Per-package log level (`@x12i/logxer`):**
 
-- **Canonical:** `{PREFIX}_LOGS_LEVEL` — use the same `envPrefix` you pass to `createLogger` / your `packageName` (e.g. `MY_APP` → `MY_APP_LOGS_LEVEL`).
+- **Canonical:** `{PREFIX}_LOGS_LEVEL` — same `envPrefix` as **`createLogxer`** / your `packageName` (e.g. `MY_APP` → `MY_APP_LOGS_LEVEL`).
 - **Legacy:** `{PREFIX}_LOG_LEVEL` is used only if `{PREFIX}_LOGS_LEVEL` is **not** set.
 - **Default** when both are unset: **`warn`** (not `info`, not silent).
 - **Silence** this package’s diagnostics: `off`, `none`, or `silent` (case-insensitive).
@@ -246,27 +254,26 @@ const gateway = new AIGateway({
 
 If the gateway builds the default logger and you omit `packageName`, the prefix is **`AI_GATEWAY`** → e.g. **`AI_GATEWAY_LOGS_LEVEL`**.
 
-**Environment Variables (examples):**
+**Environment variables (examples):**
 ```bash
 MY_APP_LOGS_LEVEL=info             # raise verbosity (or use debug / verbose)
 MY_APP_LOGS_LEVEL=off              # silence this package’s logs
 # MY_APP_LOG_LEVEL=info            # legacy; ignored if MY_APP_LOGS_LEVEL is set
 
-MY_APP_LOG_FORMAT=json             # text|json|yaml
+MY_APP_LOG_FORMAT=json             # text|json|yaml|table
 MY_APP_LOG_TO_FILE=true
 MY_APP_LOG_FILE=/var/log/app.log
 MY_APP_LOG_TO_UNIFIED=true
 DEBUG=my-app                       # elevates verbose/debug when package is not fully silent
 ```
 
-**🔍 Diagnostic Logging:** When debug level is enabled, the gateway provides comprehensive diagnostic logs for instruction resolution and propagation. See the debugging section above for details on the diagnostic events logged.
+**Diagnostic logging:** When debug level is enabled, the gateway emits diagnostic logs for instruction resolution and propagation through the same Logxer pipeline.
 
-**What Happens If Logger is Not Provided:**
-If `logger` is not provided, the gateway will automatically create a default logger. However, for best results (consistent format, unified destination), it's recommended to provide your project's logger instance.
+**What happens if `logger` is not provided:** The gateway creates a default **`Logxer`** via **`createLogxer`**. For production, prefer passing your app’s logger so levels, transports, and **`runtimeIdentity`** stay aligned with the rest of your stack.
 
-### 2. Activity Tracking Configuration (xronox-activitix via @x12i/activix v5)
+### 2. Activity Tracking Configuration (xronox-activitix via @x12i/activix v6)
 
-**Activix version:** This gateway targets **`@x12i/activix` v5.x** (built on `@xronoces/xronox-store`). The dependency range is declared in `package.json` (currently `^5.0.1`).
+**Activix version:** This gateway targets **`@x12i/activix` v6.x** (built on `@xronoces/xronox-store`). The dependency range is declared in `package.json` (currently `^6.5.1`). Activity I/O is stored at the **document root** as **`outer`** (and optional **`inner`**); the deprecated nested **`structure`** wrapper is not used.
 
 **Where to configure:**
 - Gateway constructor: `enableActivityTracking`, `activityTracker`
@@ -285,8 +292,8 @@ The gateway resolves activity tracking from environment variables via `src/confi
 **⚠️ CRITICAL: correlation and identity**
 
 - **`aiRequestId`** (required on each gateway request): Primary correlation id for this LLM call; the gateway does **not** invent a `jobId` for you.
-- **Run context** (Activix BSON field `runContext`): `sessionId` plus nested `instance: { instanceId, type }`, plus gateway correlation fields; see [Identity contract](./docs/IDENTITY_OBJECT_CONTRACT.md) (request still uses `identity`; persisted row uses `runContext`).
-- **`jobTypeId`**, **`taskId`**, **`taskTypeId`**: Optional aggregation / grouping fields (unchanged semantics).
+- **Run context** (Activix BSON field `runContext`): Same object as **`request.identity`** (including required upstream **`jobId`** and **`taskId`**), plus `sessionId` and nested `instance: { instanceId, type }` when present; see [Identity contract](./docs/IDENTITY_OBJECT_CONTRACT.md).
+- **`jobTypeId`**, **`taskTypeId`**: Optional aggregation / grouping fields (unchanged semantics).
 - **Each activity**: Gets its own **unique database record** with unique `_id` (MongoDB ObjectId).
 - **Two-phase tracking**: `startActivity()` creates a new record; `logSuccess()` / `logFailure()` update the same record by that record’s id.
 
@@ -339,7 +346,7 @@ gateway.register(new OpenAIProvider({
 }));
 ```
 
-**Advanced (custom Activix v5 instance):**
+**Advanced (custom Activix v6 instance):**
 
 If you pass your own `Activix`, configure **the same collection names** the gateway expects so routing matches persistence:
 
@@ -370,7 +377,7 @@ const gateway = new AIGateway({
 ```
 
 **What gets tracked (persisted when DB is configured):**
-- **Identity**: `sessionId`, `instance`, **`aiRequestId`** (correlation), optional deprecated `jobId` for compatibility, plus `jobTypeId`, `agentId`, `taskId`, `taskTypeId` as provided
+- **Identity**: Fields aligned with **`request.identity`** / Activix **`runContext`**: **`aiRequestId`**, upstream **`jobId`** and **`taskId`**, `sessionId`, `instance`, plus optional `jobTypeId`, `agentId`, `taskTypeId`, etc., as provided
 - **Timing**: `startTime`, `endTime`, `duration`, `status` (`started|success|failed`)
 - **Request data**: Stored in `request` object (instructions, prompt, input, messages, workingMemory)
 - **Config data**: Stored in `config` object (model, provider, temperature, maxTokens)
@@ -385,18 +392,18 @@ const gateway = new AIGateway({
 
 **Key design points:**
 - ✅ Each activity = separate database record with unique `_id`
-- ✅ **`aiRequestId`** = per-request correlation (required); optional `jobId` only if you supply it for grouping
+- ✅ **`aiRequestId`** = per-request correlation (required); **`jobId`** / **`taskId`** come from upstream **`identity`** (required on each request; see v9+ contract above)
 - ✅ Request data sent once in `startActivity()` (creates new record)
 - ✅ Response data sent once in `logSuccess()` (updates same record by `_id`)
 
 **Default:** Activity tracking is enabled by default; without DB config it will log but not persist.
 
-**✅ Activix v5 integration**
+**✅ Activix v6 integration**
 
 1. **Configuration** (`activity-tracking-config.ts`):
    - Mongo connection from env; **collection names** `ai-activities` and `bad-requests` are fixed for consistency across deployments.
 
-2. **Lifecycle** (`@x12i/activix` v5):
+2. **Lifecycle** (`@x12i/activix` v6):
    - ✅ `startRecord` / `completeRecord` / `failRecord` (two-phase lifecycle)
    - ✅ Status transitions: `started` → `success` or `failed` (per your `statusValues` mapping)
    - ✅ Persistence via xronox-store queue semantics (see Activix package docs)
@@ -778,15 +785,15 @@ If a provider package is not installed, auto-registration will skip it gracefull
 
 ```typescript
 import { AIGateway } from '@x12i/ai-gateway';
-import { createLogger } from 'logs-gateway';
+import { createLogxer } from '@x12i/logxer';
 import { Activix } from '@x12i/activix';
 import { OpenAIProvider } from '@x12i/ai-provider-openai';
 
 // 1. Configure activity tracker (and reuse its logger)
 // Single source of truth: set up the logger once, pass it to the tracker,
 // then reuse the same logger for the gateway.
-const logger = createLogger(
-  { packageName: 'MY_APP', envPrefix: 'MY_APP' },
+const logger = createLogxer(
+  { packageName: 'MY_APP', envPrefix: 'MY_APP', debugNamespace: 'my-app' },
   {
     logLevel: 'info',
     logFormat: 'json',
@@ -949,26 +956,27 @@ console.log(`RPM Limit: ${tierInfo?.rpm}, TPM Limit: ${tierInfo?.tpm}`);
 - `tier-4`: 10,000 RPM, 4M TPM
 - `tier-5`: 15,000 RPM, 40M TPM
 
-### 3. Activity Tracking (xronox-activitix via @x12i/activix v5)
+### 3. Activity Tracking (xronox-activitix via @x12i/activix v6)
 
-The gateway uses **`@x12i/activix` v5** (xronox-activitix) for full lifecycle logging. Recommended: enable MongoDB persistence so tracking is automatic. Default collections: **`ai-activities`**, **`bad-requests`**, **`skill-executions`** (see section 2).
+The gateway uses **`@x12i/activix` v6** (xronox-activitix) for full lifecycle logging. Recommended: enable MongoDB persistence so tracking is automatic. Default collections: **`ai-activities`**, **`bad-requests`**, **`skill-executions`** (see section 2).
 
 #### ⚠️ CRITICAL: correlation, identity, and unique record ids
 
 **IMPORTANT DESIGN CONCEPTS:**
 
 1. **Per-request correlation**
-   - **`aiRequestId`** (required): One id per gateway invocation; used as the primary leaf correlation field (stored on the activity row and inside Activix `runContext`; the gateway does not generate a `jobId` for you).
-   - **`jobTypeId`**, **`taskId`**, **`taskTypeId`**: Optional aggregation fields (same ideas as before).
+   - **`aiRequestId`** (required): One id per gateway invocation; used as the primary leaf correlation field (stored on the activity row and inside Activix `runContext`).
+   - **`identity.jobId`** and **`identity.taskId`** (required): Taken only from the upstream **`identity`** object; the gateway does not invent them.
+   - **`jobTypeId`**, **`taskTypeId`**: Optional aggregation fields (same ideas as before).
    - **Activity**: Each individual LLM request is a separate **activity** with its own unique record.
 
 2. **Mongo `_id` is the unique row key**
-   - Optional **`jobId`** (if you pass it) is only grouping metadata — multiple activities may share it.
+   - **`jobId`** / **`taskId`** on the row mirror upstream **`identity`** for correlation; multiple activities may share a **`jobId`** when you intend grouping.
    - Activix updates rows by the **record id** from the start phase, not by `jobId`.
 
-3. **Two-phase tracking (Activix v5)**
+3. **Two-phase tracking (Activix v6)**
    - **Phase 1 (start)**: Creates a NEW database record with unique `_id`
-     - Sends request-side data: `request`, `config`, `runContext`, `structure`, `startTime`, `status: 'started'` (plus other gateway metadata)
+     - Sends request-side data: `request`, `config`, `runContext`, root-level **`outer`** (and optional **`inner`**) I/O, `startTime`, `status: 'started'` (plus other gateway metadata)
      - Returns metadata containing the unique record id for completion
    - **Phase 2 (complete / fail)**: Updates the SAME record by that id
      - Sends response/error data: `response`, `endTime`, `duration`, `cost`, `status`
@@ -982,7 +990,7 @@ The gateway uses **`@x12i/activix` v5** (xronox-activitix) for full lifecycle lo
 
 **Example: same logical job, three LLM calls**
 
-Each call must have a **distinct `aiRequestId`**. Optionally pass the same `jobId` (or only `jobTypeId`) if you want to group rows in Mongo.
+Each call must have a **distinct `aiRequestId`** and a full **`identity`** (including **`jobId`** and **`taskId`** from upstream). Use the same **`identity.jobId`** (and distinct **`taskId`** per call, or your own convention) if you want to group rows in Mongo.
 
 ```typescript
 import * as crypto from 'crypto';
@@ -993,29 +1001,31 @@ function md5(text: string): string {
 
 const jobTypeId = md5('data-processing-job');
 
+const identityBase = {
+  jobId: 'job-123',
+  sessionId: 'sess-1',
+  instance: { instanceId: 'inst-1', type: 'gateway' }
+};
+
 await gateway.invoke({
   aiRequestId: 'req-001',
-  jobId: 'job-123',       // optional grouping
+  identity: { ...identityBase, taskId: 'task-001' },
   jobTypeId,
   agentId: 'agent-1',
-  sessionId: 'sess-1',
-  instance: { instanceId: 'inst-1', type: 'gateway' },
-  // ...
+  // objectTypes, messages, ...
 });
 
 await gateway.invoke({
   aiRequestId: 'req-002',
-  jobId: 'job-123',
+  identity: { ...identityBase, taskId: 'task-002' },
   jobTypeId,
   agentId: 'agent-1',
-  sessionId: 'sess-1',
-  instance: { instanceId: 'inst-1', type: 'gateway' },
-  // ...
+  // objectTypes, messages, ...
 });
 
 // Query in Mongo (main collection name is ai-activities):
 // db.getCollection('ai-activities').find({ 'runContext.aiRequestId': 'req-001' })
-// db.getCollection('ai-activities').find({ 'runContext.jobId': 'job-123' })  // if you set jobId
+// db.getCollection('ai-activities').find({ 'runContext.jobId': 'job-123' })
 ```
 
 #### Configuration
@@ -1059,7 +1069,7 @@ const gateway = new AIGateway({
   // Unique identifier (MongoDB auto-generated)
   _id: ObjectId('693970636e8d0f171e4aa528'),  // ← UNIQUE per activity
   
-  // Activix v5: canonical correlation BSON object `runContext` (gateway builds it from `request.identity`)
+  // Activix v6: canonical correlation BSON object `runContext` (same reference as `request.identity`, merged with gateway fields)
   runContext: {
     sessionId: 'sess-1',
     instance: { instanceId: 'gw-1', type: 'gateway' },
@@ -1086,11 +1096,9 @@ const gateway = new AIGateway({
   graphId: 'graph-456',
   nodeId: 'node-789',
 
-  // Required activity I/O envelope (`structure` required since Activix v4; unchanged in v5 — see @x12i/activix docs)
-  structure: {
-    outer: { input: { ... }, output: { ... } | null, metadata: { ... } },
-    // inner?: { input, output, metadata }
-  },
+  // Required activity I/O: root-level `outer` (optional `inner[]` for steps) — Activix v6 (see @x12i/activix docs)
+  outer: { input: { ... }, output: { ... } | null, metadata: { ... } },
+  // inner: [ { input, output, metadata, startedAt, endedAt, ... }, ... ],
   
   // Timing
   startTime: 1765372020804,
@@ -1142,11 +1150,11 @@ const gateway = new AIGateway({
 **Key points:**
 - ✅ Each activity = separate record with unique `_id`
 - ✅ **`aiRequestId`** = per-request correlation (required on invoke)
-- ✅ Optional `jobId` = grouping metadata only
+- ✅ **`runContext.jobId`** / **`runContext.taskId`** = upstream identity (required on invoke since v9+)
 - ✅ Request data sent once at activity start; response data on completion
 - ✅ Updates use Activix record id / `_id`, not `jobId`
 
-#### Retry Tracking (@x12i/activix v5)
+#### Retry Tracking (@x12i/activix v6)
 
 The gateway automatically retries network errors, server errors (5xx), and throttling (429) with exponential backoff. Retry attempts are tracked and stored in activity records.
 
@@ -1374,14 +1382,16 @@ const response = await gateway.invoke({
 
 ### 5. Structured Logging
 
-The gateway uses `logs-gateway` for production-ready structured logging with correlation support.
+The gateway uses **`@x12i/logxer`** for structured logging with **`LogMeta`** correlation. See [Logger initialization](./docs/LOGGER_INITIALIZATION.md).
 
 ```typescript
+import { createLogxer } from '@x12i/logxer';
+
 const gateway = new AIGateway({
   enableLogging: true,
   packageName: 'MY_APP',
-  logger: createLogger(
-    { packageName: 'MY_APP', envPrefix: 'MY_APP' },
+  logger: createLogxer(
+    { packageName: 'MY_APP', envPrefix: 'MY_APP', debugNamespace: 'my-app' },
     {
       logLevel: 'info',
       logFormat: 'json',
@@ -2897,7 +2907,7 @@ const result = await gateway.call({
 
 #### Integration with Activity Tracking
 
-Contract output parsing integrates seamlessly with `@x12i/activix` v5 (xronox-activitix):
+Contract output parsing integrates seamlessly with `@x12i/activix` v6 (xronox-activitix):
 
 - **Automatic Processing**: Parsing happens automatically when `expectedSchema` is provided
 - **Error Resilience**: Parsing failures don't break activity recording
@@ -2925,10 +2935,13 @@ const schema = {
 
 const response = await gateway.invoke({
   aiRequestId: 'analysis-req-001',
-  jobId: 'analysis-123',
+  identity: {
+    jobId: 'analysis-123',
+    taskId: 'analysis-task-001',
+    sessionId: 'sess-analyzer',
+    instance: { instanceId: 'analyzer-1', type: 'gateway' }
+  },
   agentId: 'analyzer-bot',
-  sessionId: 'sess-analyzer',
-  instance: { instanceId: 'analyzer-1', type: 'gateway' },
   instructions: 'Analyze the provided data...',
   expectedSchema: schema,
   messages: [{ role: 'user', content: data }]
@@ -2956,8 +2969,8 @@ interface GatewayConfig extends RouterConfig {
   enableUsageTracking?: boolean;      // Default: true
   enableLogging?: boolean;            // Default: true
   contentRegistryConfig?: any;         // Content registry config for instruction key resolution
-  logger?: LogsGateway;               // Custom logger
-  activityTracker?: Activix;           // Custom Activix v5 instance (match collection names: ai-activities, bad-requests, skill-executions)
+  logger?: import('@x12i/logxer').Logxer;  // Custom Logxer (from createLogxer)
+  activityTracker?: Activix;           // Custom Activix v6 instance (match collection names: ai-activities, bad-requests, skill-executions)
   packageName?: string;               // Default: 'AI_GATEWAY'
   // ... all RouterConfig options
 }
@@ -2978,7 +2991,7 @@ interface GatewayConfig extends RouterConfig {
 - `checkHealth(provider: LLMProvider): Promise<HealthCheckResult>` - Check provider health
 - `checkAllHealth(): Promise<Map<LLMProvider, HealthCheckResult>>` - Check all providers' health
 - `getRouter(): LLMProviderRouter` - Get underlying router instance
-- `getLogger(): LogsGateway` - Get logger instance
+- `getLogger(): Logxer` - Get logger instance (`@x12i/logxer`)
 - `setActivityManager(activityManager)` - Advanced/test hook to replace the internal activity manager; typical apps inject **`Activix` via `activityTracker`** in the constructor instead
 - `getContentRegistry(): ContentRegistry | undefined` - Get underlying content-registry instance (returns undefined if not enabled)
 - `resolveInstructionKey(key: string, variables?: Record<string, unknown>): Promise<string>` - Resolve instruction key with variables (without making LLM call)
@@ -3727,10 +3740,10 @@ const gateway = new AIGateway({
 ### Custom Logger
 
 ```typescript
-import { createLogger } from 'logs-gateway';
+import { createLogxer } from '@x12i/logxer';
 
-const customLogger = createLogger(
-  { packageName: 'MY_APP', envPrefix: 'MY_APP' },
+const customLogger = createLogxer(
+  { packageName: 'MY_APP', envPrefix: 'MY_APP', debugNamespace: 'my-app' },
   {
     logLevel: 'debug',
     logFormat: 'json',
@@ -4155,8 +4168,8 @@ This package integrates with:
 - **@x12i/ai-providers-router**: Core routing functionality
 - **@xronoces/content-registry**: Instruction key resolution and content management (optional)
 - **@x12i/x-models**: Usage tier tracking and model metadata
-- **@x12i/activix** v5 (xronox-activitix): Activity logging and tracking (`^5.0.1` in this package)
-- **logs-gateway**: Structured logging with correlation
+- **@x12i/activix** v6 (xronox-activitix): Activity logging and tracking (`^6.5.1` in this package)
+- **@x12i/logxer**: Structured logging with correlation (`^4.2.1` in this package)
 - **nx-config2**: Configuration management (via dependencies)
 
 ## Related Packages Status

package/dist/activity-manager.d.ts

@@ -15,8 +15,10 @@ type Request = ChatRequest | AIRequest;
  * **Execution context:** treats `request.identity` as received from upstream. Root fields (`sessionId`,
  * `instance`, and any keys already set on that object) are not replaced by gateway defaults; the gateway
  * only fills missing required pieces and adds local context (e.g. graph linkage) where absent.
+ *
+ * @param logger - Optional Logxer used to WARN when mandatory upstream `identity.jobId` / `identity.taskId` are absent.
  */
-export declare function ensureGatewayRequestIdentity(request: ChatRequest | AIRequest, extras?: Partial<ActivityIdentity>): ActivityIdentity;
+export declare function ensureGatewayRequestIdentity(request: ChatRequest | AIRequest, extras?: Partial<ActivityIdentity>, logger?: Logxer): ActivityIdentity;
 type ActivityMetadata = Record<string, any> & {
     activityId?: string;
     recordId?: string;

package/dist/activity-manager.js

@@ -6,6 +6,7 @@
  */
 import { Activix, activixActivityIo, activixOuterTier } from '@x12i/activix';
 import { resolveActivityTrackingConfig } from './config/activity-tracking-config.js';
+import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
 function readAiRequestIdFromRequest(request) {
     const aiRequestId = request.aiRequestId;
     if (typeof aiRequestId === 'string' && aiRequestId.trim().length > 0) {
@@ -102,40 +103,64 @@ function buildInstanceEnvelope(request) {
 function resolveSessionIdForRequest(request, incomingIdentity, aiRequestId) {
     const fromIdentity = trimIdentityString(incomingIdentity?.sessionId);
     const topLevel = trimIdentityString(request.sessionId);
-    const jobId = trimIdentityString(request.jobId);
+    const identityJobId = trimIdentityString(incomingIdentity?.jobId);
     if (fromIdentity !== undefined && topLevel !== undefined && fromIdentity !== topLevel) {
         throw new Error(`identity.sessionId (${fromIdentity}) and top-level sessionId (${topLevel}) must agree`);
     }
-    return fromIdentity ?? topLevel ?? jobId ?? aiRequestId;
+    return fromIdentity ?? topLevel ?? identityJobId ?? aiRequestId;
+}
+function logUpstreamIdentityWarnings(logger, incomingIdentity, merged) {
+    const aiRequestId = merged.aiRequestId;
+    if (!incomingIdentity || typeof incomingIdentity !== 'object') {
+        logger?.warn('missingRuntimeIdentityObject', withActivityIdentity(merged, {
+            message: 'request.identity is missing; upstream must send the mandatory runtime identity object',
+            aiRequestId,
+            debugKind: gatewayLogDebug.anomaly
+        }));
+        return;
+    }
+    const missing = [];
+    if (!trimIdentityString(incomingIdentity.jobId))
+        missing.push('jobId');
+    if (!trimIdentityString(incomingIdentity.taskId))
+        missing.push('taskId');
+    if (missing.length > 0) {
+        logger?.warn('missingUpstreamIdentityFields', withActivityIdentity(merged, {
+            message: `Upstream identity is missing required field(s): ${missing.join(', ')}. jobId and taskId must be set on request.identity by the client; the gateway does not generate them.`,
+            missingFields: missing,
+            aiRequestId,
+            debugKind: gatewayLogDebug.anomaly
+        }));
+    }
 }
 function mergeGatewayActivityIdentity(request, aiRequestId, extras) {
     const incomingIdentity = request.identity;
     const sessionId = resolveSessionIdForRequest(request, incomingIdentity, aiRequestId);
-    const legacyJobId = trimIdentityString(incomingIdentity?.jobId) ?? trimIdentityString(request.jobId);
+    const upstreamJobId = trimIdentityString(incomingIdentity?.jobId) ?? '';
+    const upstreamTaskId = trimIdentityString(incomingIdentity?.taskId) ?? '';
     const combinedEnrichment = pickGatewayEnrichmentFields({
         ...graphIdentityExtrasFromRequest(request),
         ...(extras || {})
     });
     const safeEnrichment = mergeActivixEnrichment(incomingIdentity, combinedEnrichment);
-    // Request fields are defaults for this hop; incoming `identity` from upstream wins on conflict.
-    // Gateway enrichment (graph/skill, etc.) fills only keys the outer envelope did not already set.
+    // jobId / taskId: upstream `request.identity` only (never top-level request.jobId / request.taskId).
     const merged = {
         jobTypeId: request.jobTypeId,
         agentId: request.agentId,
-        taskId: request.taskId,
         taskTypeId: request.taskTypeId,
         ...safeEnrichment,
         ...(incomingIdentity || {}),
         sessionId,
         instance: buildInstanceEnvelope(request),
-        aiRequestId
+        aiRequestId,
+        jobId: upstreamJobId,
+        taskId: upstreamTaskId
     };
     merged.sessionId = sessionId;
     merged.instance = buildInstanceEnvelope(request);
     merged.aiRequestId = aiRequestId;
-    if (legacyJobId !== undefined) {
-        merged.jobId = legacyJobId;
-    }
+    merged.jobId = upstreamJobId;
+    merged.taskId = upstreamTaskId;
     return merged;
 }
 /**
@@ -145,13 +170,16 @@ function mergeGatewayActivityIdentity(request, aiRequestId, extras) {
  * **Execution context:** treats `request.identity` as received from upstream. Root fields (`sessionId`,
  * `instance`, and any keys already set on that object) are not replaced by gateway defaults; the gateway
  * only fills missing required pieces and adds local context (e.g. graph linkage) where absent.
+ *
+ * @param logger - Optional Logxer used to WARN when mandatory upstream `identity.jobId` / `identity.taskId` are absent.
  */
-export function ensureGatewayRequestIdentity(request, extras) {
+export function ensureGatewayRequestIdentity(request, extras, logger) {
     const aiRequestId = readAiRequestIdFromRequest(request);
     const identity = mergeGatewayActivityIdentity(request, aiRequestId, {
         ...graphIdentityExtrasFromRequest(request),
         ...(extras || {})
     });
+    logUpstreamIdentityWarnings(logger, request.identity, identity);
     request.identity = identity;
     return identity;
 }
@@ -287,7 +315,7 @@ export class ActivityManager {
      * @returns Activity metadata (contains unique _id/recordId) or undefined if tracking is disabled
      */
     async startActivity(request, startTime) {
-        const identity = ensureGatewayRequestIdentity(request);
+        const identity = ensureGatewayRequestIdentity(request, undefined, this.logger);
         const aiRequestId = identity.aiRequestId;
         // Capture ONLY request data - NO response data at this stage
         // Note: v2.3.2+ excludes flat request/config fields from root level
@@ -307,9 +335,10 @@ export class ActivityManager {
         }
         const activityMetadata = {
             aiRequestId,
+            jobId: identity.jobId,
             jobTypeId: request.jobTypeId,
             agentId: request.agentId,
-            taskId: request.taskId,
+            taskId: identity.taskId,
             taskTypeId: request.taskTypeId,
             startTime,
             status: 'started',
@@ -503,7 +532,7 @@ export class ActivityManager {
         }
         // Determine inference type (will be extracted in gateway.ts and passed via request metadata)
         const inferenceType = aiRequest.inferenceType || 'question-answer';
-        const identity = ensureGatewayRequestIdentity(request);
+        const identity = ensureGatewayRequestIdentity(request, undefined, this.logger);
         const aiRequestId = identity.aiRequestId;
         if (!this.activix) {
             return undefined;
@@ -521,9 +550,10 @@ export class ActivityManager {
             skillId: skillId ?? skillKey,
             inferenceType, // ✅ Recommended: type of inference
             aiRequestId,
+            jobId: identity.jobId,
             jobTypeId: request.jobTypeId,
             agentId: request.agentId,
-            taskId: request.taskId,
+            taskId: identity.taskId,
             taskTypeId: request.taskTypeId,
             startTime,
             status: 'started',
@@ -897,7 +927,7 @@ export class ActivityManager {
      * @param startTime - When the request started
      */
     async logBadRequest(request, error, details, startTime) {
-        const identity = ensureGatewayRequestIdentity(request);
+        const identity = ensureGatewayRequestIdentity(request, undefined, this.logger);
         const aiRequestId = identity.aiRequestId;
         const endTime = details.endTime;
         const duration = details.duration;
@@ -922,9 +952,10 @@ export class ActivityManager {
         const badRequestMetadata = {
             activityType: 'bad-request',
             aiRequestId,
+            jobId: identity.jobId,
             jobTypeId: request.jobTypeId,
             agentId: request.agentId,
-            taskId: request.taskId,
+            taskId: identity.taskId,
             taskTypeId: request.taskTypeId,
             startTime,
             status: 'started',