log10x-mcp 1.29.11 → 1.29.12

package/README.md

@@ -18,6 +18,7 @@ This server is open source under MIT. A Log10x product license (API key) unlocks
 | "What's driving my cost right now?" | The repeating message types and services driving volume and cost, and what moved week over week. `log10x_top_patterns`, `log10x_whats_changing`, `log10x_services` |
 | "Why did payments-svc spike?" | A single-call investigation: timeline, correlated patterns, and the strongest temporal evidence, with confidence shown so nothing is presented as proven cause. `log10x_investigate`, `log10x_metrics_that_moved`, `log10x_metric_overlay` |
 | "This message type is noise, cut it." | Sample, drop, compact, tier down, or offload a chosen message type, with examples and trend so the action is clear. `log10x_pattern_mitigate`, `log10x_pattern_examples`, `log10x_pattern_trend` |
+| "We are 100% Lambda, no cluster. Install there." | The install plan comes back for the serverless estate: the engine as a Lambda extension paired with the function's OTel collector, a CDK construct, and an AWS-native recurring tick over an S3 config plane. `log10x_advise_install`, `log10x_setup_recurring` |
 | "Get me the actual events I offloaded." | Fetch the exact events back on demand from your own S3. `log10x_retriever_query`, `log10x_offload_add`, `log10x_retriever_register` |
 | "Recognize more of my message types." | Build a custom symbol library from your own logs so the engine finds more savings. `log10x_compile`, `log10x_compile_link`, `log10x_compile_status` |
 

package/build/product-kb/docs/apps/mcp/tools/install/advise-install.md

@@ -8,6 +8,8 @@ After [Discover env](discover-env.md) ran, pick the right Log10x app to deploy a
 
 It returns a ranked comparison across Reporter, Receiver, and [Retriever](advise-retriever.md) when no goal is set, or a single concrete checklist when a goal is given (`cut-cost`, `compact`, `archive`, `just-metrics`).
 
+On a serverless snapshot (Lambda functions running an OTel collector extension, no reachable cluster) the Kubernetes wizard is skipped entirely: the tool returns the [Extension](../../../../engine/launcher/extension.md) plan, collector splice, engine environment, CDK construct, and the Coralogix TCO policy path.
+
 ## :material-code-braces: Example
 
 !!! tenx-ask "You"
@@ -96,11 +98,11 @@ A fresh `snapshot_id` from [Discover env](discover-env.md). No Log10x components
               "prometheus"
             ]
           },
-          "description": "Where the engine emits TenXSummary metrics. Multi-destination, a user can report to log10x SaaS AND their own backend simultaneously, e.g. `[\"log10x\", \"datadog\"]`. Choices: **log10x** (Log10x-managed Prometheus, recommended; no infra to run), **datadog**, **elastic**, **cloudwatch**, **prometheus** (customer-owned). The wizard pre-fills detected backends from the snapshot. The only mutual exclusion is `airgapped: true` + `\"log10x\"` in this list."
+          "description": "Where the engine emits TenXSummary metrics. Multi-destination — a user can report to log10x SaaS AND their own backend simultaneously, e.g. `[\"log10x\", \"datadog\"]`. Choices: **log10x** (Log10x-managed Prometheus — recommended; no infra to run), **datadog**, **elastic**, **cloudwatch**, **prometheus** (customer-owned). The wizard pre-fills detected backends from the snapshot. The only mutual exclusion is `airgapped: true` + `\"log10x\"` in this list."
         },
         "airgapped": {
           "type": "boolean",
-          "description": "When true, the Log10x agents send nothing to log10x.com: engine metrics, license re-validation, and update checks all go silent. Use to reduce CISO friction. Conflicts with `\"log10x\"` in `backends` (the wizard surfaces the conflict). **Demo licenses cannot actually run airgapped.** The engine downgrades to online mode with a warning. The wizard surfaces this softly when both are picked."
+          "description": "When true, the Log10x agents send nothing to log10x.com — engine metrics, license re-validation, and update checks all go silent. Use to reduce CISO friction. Conflicts with `\"log10x\"` in `backends` (the wizard surfaces the conflict). **Demo licenses cannot actually run airgapped** — the engine downgrades to online mode with a warning. The wizard surfaces this softly when both are picked."
         },
         "backend_credentials": {
           "type": "object",
@@ -133,7 +135,7 @@ A fresh `snapshot_id` from [Discover env](discover-env.md). No Log10x components
               "prometheus"
             ]
           },
-          "description": "Per-backend credential configuration, keyed by backend kind (must be one of: log10x, datadog, elastic, cloudwatch, prometheus). **Only set for non-`log10x` backends.** `log10x` SaaS uses the license JWT and needs no extra credentials. Each entry has a `secretName` (the Kubernetes Secret the user creates out-of-band holding sensitive env vars like `DD_API_KEY`; default per backend is `<backend>-credentials`) and optional `plainValues` (overrides for non-sensitive env vars like `DD_SITE`). Example: `{ \"datadog\": { \"secretName\": \"datadog-secret\", \"plainValues\": { \"DD_SITE\": \"us5.datadoghq.com\" } } }`."
+          "description": "Per-backend credential configuration, keyed by backend kind (must be one of: log10x, datadog, elastic, cloudwatch, prometheus). **Only set for non-`log10x` backends** — `log10x` SaaS uses the license JWT and needs no extra credentials. Each entry has a `secretName` (the Kubernetes Secret the user creates out-of-band holding sensitive env vars like `DD_API_KEY`; default per backend is `<backend>-credentials`) and optional `plainValues` (overrides for non-sensitive env vars like `DD_SITE`). Example: `{ \"datadog\": { \"secretName\": \"datadog-secret\", \"plainValues\": { \"DD_SITE\": \"us5.datadoghq.com\" } } }`."
         },
         "license_source": {
           "type": "string",
@@ -143,7 +145,7 @@ A fresh `snapshot_id` from [Discover env](discover-env.md). No Log10x components
             "paste"
           ],
           "default": "signin",
-          "description": "How the wizard should acquire the engine's license JWT. **Defaults to `\"signin\"`** when omitted. The wizard tries to mint a user-scoped license via the user's Auth0 session, and emits `signin_required` mode (chain through `log10x_signin_start` then re-invoke) when no session exists. Pass **`\"demo\"`** ONLY when the user explicitly asks for a quick 14-day anonymous demo (transient, can't run airgapped). Pass **`\"paste\"`** with `license_jwt_paste: \"<jwt>\"` when the user already has a JWT."
+          "description": "How the wizard should acquire the engine's license JWT. **Defaults to `\"signin\"`** when omitted — the wizard tries to mint a user-scoped license via the user's Auth0 session, and emits `signin_required` mode (chain through `log10x_signin_start` then re-invoke) when no session exists. Pass **`\"demo\"`** ONLY when the user explicitly asks for a quick 14-day anonymous demo (transient, can't run airgapped). Pass **`\"paste\"`** with `license_jwt_paste: \"<jwt>\"` when the user already has a JWT."
         },
         "license_jwt_paste": {
           "type": "string",
@@ -171,7 +173,8 @@ A fresh `snapshot_id` from [Discover env](discover-env.md). No Log10x components
       "required": [
         "snapshot_id"
       ],
-      "additionalProperties": false
+      "additionalProperties": false,
+      "$schema": "http://json-schema.org/draft-07/schema#"
     }
     ```
 
@@ -263,6 +266,7 @@ A fresh `snapshot_id` from [Discover env](discover-env.md). No Log10x components
       // `data.mode` and narrow to the per-mode shape.
       mode:
         | 'plan'
+        | 'serverless_plan'
         | 'next_question'
         | 'missing_snapshot'
         | 'session_error'
@@ -299,6 +303,12 @@ A fresh `snapshot_id` from [Discover env](discover-env.md). No Log10x components
       suggestions?: Array<{ unknown: string; did_you_mean: string | null }>;
       valid_keys?: string[];
 
+      // mode === 'serverless_plan'
+      estate?: 'serverless';
+      function_count?: number;
+      functions_with_otel_extension?: number;
+      log_groups_unsubscribed?: number;
+
       // mode === 'plan', fields below come from AdvisePlanSummary.
       app?: 'reporter' | 'receiver' | 'retriever';
       release_name?: string;

package/build/product-kb/docs/apps/mcp/tools/install/configure-engine.md

@@ -8,6 +8,8 @@ The unified per-pattern action-plan PR author. Derives a per-pattern policy from
 
 The engine hot-reloads the CSV on the next gitops poll, with no restart and no event drops.
 
+The rendered policy is two engine files: `caps.csv` (per-container byte caps) and a sibling `actions.csv` deciding each service's over-cap disposition. `kubectl_configmap` delivery writes both, plus `config-generation.csv` and `action-intent.json`, straight to the ConfigMap the engine's [Kubernetes lane](../../../../config/k8s.md) pulls.
+
 Two modes:
 
 - **configure** (default): derive a fresh policy and open a PR
@@ -63,6 +65,24 @@ Reporter deployed for metrics. GitOps repo configured (`gitops_repo` arg or `git
           "default": "configure",
           "description": "`configure` (default) = derive a fresh per-pattern policy and open a PR. `refresh` = re-pull TSDB metrics for an already-deployed policy, compare observed volume to the cap-CSV preamble baseline, and open a delta PR only when the volume has drifted beyond `tolerance_pct`. Use `refresh` from cron/agent loops after the engine is live and 10x metrics are flowing. Requires `current_csv` carrying the prior `# target_percent=N` preamble; if absent, falls back to `target_percent` arg or returns target_resolution."
         },
+        "delivery": {
+          "type": "string",
+          "enum": [
+            "gitops",
+            "kubectl_configmap",
+            "stdout_only"
+          ],
+          "default": "gitops",
+          "description": "How the rendered policy is delivered. `gitops` (default) opens a PR against the customer gitops repo (requires `gitops_repo`). `kubectl_configmap` writes caps.csv + actions.csv + config-generation.csv + action-intent.json directly to a k8s ConfigMap on the active cluster (no GitHub needed; the engine's ConfigMap pull driver reads from the ConfigMap named via $K8S_CONFIGMAP, default `log10x-action-intent`). `stdout_only` returns the proposed config in the response without writing anywhere."
+        },
+        "kubectl_namespace": {
+          "type": "string",
+          "description": "k8s namespace for the policy ConfigMap when delivery=\"kubectl_configmap\". Defaults to `default` — pass the namespace the receiver runs in (the engine's ConfigMap pull driver reads from its own pod namespace)."
+        },
+        "kubectl_configmap_name": {
+          "type": "string",
+          "description": "k8s ConfigMap name when delivery=\"kubectl_configmap\". Defaults to `log10x-action-intent` (matching the engine's default $K8S_CONFIGMAP env var). The ConfigMap holds `caps.csv` (engine per-container byte caps), `actions.csv` (engine per-service action for the over-cap slice), `config-generation.csv` (policy-generation stamp), and `action-intent.json` (per-pattern intent read back by commitment_report / estimate_savings; the engine ignores it)."
+        },
         "tolerance_pct": {
           "type": "number",
           "minimum": 0,
@@ -103,11 +123,11 @@ Reporter deployed for metrics. GitOps repo configured (`gitops_repo` arg or `git
             "gcp-logging",
             "sumo"
           ],
-          "description": "Destination SIEM. Auto-detected from active env / snapshot recommendations when omitted; if auto-detect fails the tool returns a structured not-configured envelope."
+          "description": "Destination log platform. Auto-detect only works when a `snapshot_id` from log10x_discover_env is supplied (the snapshot carries `recommendations.destination`) or when the active env in `~/.log10x/envs.json` explicitly sets a `destination` field. Most active envs do NOT carry that field, so for typical use you should pass `destination` explicitly: `splunk` | `datadog` | `elasticsearch` | `clickhouse` | `cloudwatch` | `azure-monitor` | `gcp-logging` | `sumo`."
         },
         "es_pruned": {
           "type": "boolean",
-          "description": "Elasticsearch only: are compactable fields excluded from `_source` via index template? Default `false` (unpruned). Auto-detection requires reading the customer index template; this knob is the explicit override. See OPEN Q 2 in the 14d-24 spec."
+          "description": "Elasticsearch only: are compactable fields excluded from `_source` via index template? Default `false` (unpruned). Auto-detection requires reading the customer index template; this knob is the explicit override."
         },
         "contract_type": {
           "type": "string",
@@ -148,6 +168,19 @@ Reporter deployed for metrics. GitOps repo configured (`gitops_repo` arg or `git
         "action_defaults": {
           "type": "object",
           "properties": {
+            "error": {
+              "type": "string",
+              "enum": [
+                "pass",
+                "sample",
+                "compact",
+                "tier_down",
+                "offload",
+                "drop"
+              ],
+              "default": "pass",
+              "description": "Default action for error-tier patterns (severity `error`/`warn`/`warning`; `critical`/`fatal` are audit-tier and always `pass`). Defaults to `pass` — error-class lines are kept verbatim, which is what the POC report tells the customer. Set this explicitly to opt into reducing them, and prefer a lossless lever (`compact`/`tier_down`/`offload`) over `sample`/`drop`."
+            },
             "standard": {
               "type": "string",
               "enum": [
@@ -190,7 +223,12 @@ Reporter deployed for metrics. GitOps repo configured (`gitops_repo` arg or `git
           },
           "additionalProperties": false,
           "default": {},
-          "description": "Tier-to-action defaults. Audit-tier is always `pass`; error-tier is always `sample(N=2)`."
+          "description": "Tier-to-action defaults. Audit-tier is always `pass` and is not configurable. Error-tier defaults to `pass` (kept verbatim); standard defaults to `compact`; debug and synthetic default to `drop`. When a pinned `sample` is projected, N=10 (keep 1 in 10)."
+        },
+        "respect_default_action": {
+          "type": "boolean",
+          "default": false,
+          "description": "When false (default), the solver shortcuts to `pass` on error/standard/debug/synthetic rows once `target_percent` has already been met by higher-priority rows earlier in the greedy walk — minimum work, may ignore your configured `action_defaults`. When true, the solver applies `action_defaults` to EVERY non-floor row in the matching tier, even after target is already met. Use when you want a predictable action mix (e.g., \"I asked for offload, give me offload\") and are OK with the policy overshooting target_percent. Surfaces in `action_default_resolution.respect_default_action` for audit."
         },
         "reduction": {
           "type": "string",
@@ -232,7 +270,7 @@ Reporter deployed for metrics. GitOps repo configured (`gitops_repo` arg or `git
         },
         "from_poc_id": {
           "type": "string",
-          "description": "POC snapshot id returned by `log10x_poc_from_siem_submit` (or the from-local equivalent). When set and the snapshot carries a `cap_csv` (i.e., the POC was run with `target_percent_reduction`), the tool reads that CSV verbatim and renders it as the PR body, with no Prometheus pull and no greedy re-derivation. Falls back to the live-Prometheus derivation when the snapshot has no cap_csv (or no `target_percent_reduction` was supplied to the POC)."
+          "description": "POC snapshot id returned by `log10x_poc_from_siem_submit` (or the from-local equivalent). When set and the snapshot carries a `cap_csv` (i.e., the POC was run with `target_percent_reduction`), the tool reads that CSV verbatim and renders it as the PR body — no Prometheus pull, no greedy re-derivation. Falls back to the live-Prometheus derivation when the snapshot has no cap_csv (or no `target_percent_reduction` was supplied to the POC)."
         },
         "auto_apply": {
           "type": "boolean",
@@ -244,26 +282,6 @@ Reporter deployed for metrics. GitOps repo configured (`gitops_repo` arg or `git
           "default": false,
           "description": "When `true`, behaves as if `auto_apply=false` regardless of other flags. Use for evaluation, audit, or in MCP contexts without an approval surface (cron, headless agents). Mirrors `github/github-mcp-server --read-only`."
         },
-        "delivery": {
-          "type": "string",
-          "enum": [
-            "gitops",
-            "kubectl_configmap",
-            "stdout_only",
-            "auto"
-          ],
-          "default": "auto",
-          "description": "Which writer delivers the rendered action-intent + cap CSV. `gitops` opens a PR via gh (slow review loop, safest). `kubectl_configmap` applies a ConfigMap directly to the receiver namespace (fast iteration, requires kubectl access). `stdout_only` returns the rendered files in the envelope without writing. `auto` (default) picks based on snapshot: gitops if `gitops.repo` is known; else kubectl_configmap if a cluster was probed; else stdout_only."
-        },
-        "delivery_namespace": {
-          "type": "string",
-          "description": "kubectl_configmap delivery only: target k8s namespace for the ConfigMap. Defaults to the receiver pod namespace discovered in the snapshot (typically `demo` or `otel-demo`). Falls back to `default` when no snapshot."
-        },
-        "delivery_configmap": {
-          "type": "string",
-          "default": "log10x-action-intent",
-          "description": "kubectl_configmap delivery only: name of the ConfigMap to write. The engine's ConfigMap pull source reads this name in the receiver namespace. Default matches the canonical name the engine expects."
-        },
         "view": {
           "type": "string",
           "enum": [
@@ -272,13 +290,70 @@ Reporter deployed for metrics. GitOps repo configured (`gitops_repo` arg or `git
             "pr_command_only"
           ],
           "default": "summary",
-          "description": "Response shape. `summary` (default) returns a slim payload (~under 8K tokens for a 119-pattern policy): phase, target_percent, action_mix counts, the `totals` block (bytes_in / bytes_saved / dollars_saved monthly), the top-5 cost contributors, and a short PR-command prose summary. `detail` returns the full envelope with `pr_command`, `per_pattern_rows`, and `csv_diff` inlined. `pr_command_only` returns just the `gh pr create` string for copy-paste callers."
+          "description": "Response shape. `summary` (default) returns slim payload: phase, target_percent, action_mix counts, totals (bytes_in / bytes_saved / dollars_saved monthly), top_5_per_pattern, and a short PR-command prose summary. Target: under 8K tokens for a 119-pattern policy. `detail` returns the full envelope with pr_command, per_pattern_rows, and csv_diff included. `pr_command_only` returns ONLY the pr_command string for copy-paste callers."
+        },
+        "service_policy": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "standard_action": {
+                "type": "string",
+                "enum": [
+                  "pass",
+                  "sample",
+                  "compact",
+                  "tier_down",
+                  "offload",
+                  "drop"
+                ],
+                "description": "Pin this service (k8s_container) standard-tier action, overriding the auto-recommendation. An action that is illegal or zero-saving on the env destination (e.g. compact on Datadog, tier_down with no cheaper tier) is rejected with a warning and the service falls back to its normal resolution (the compressibility auto-recommendation, or the global action_defaults.standard when auto_recommend is off)."
+              },
+              "keep_queryable": {
+                "type": "boolean",
+                "description": "When true, force the in-platform compact action wherever compact is legal on the destination, keeping this service queryable in the destination rather than offloading to S3, even when its compaction is modest. No effect on destinations where compact is a no-op (Datadog/CloudWatch/Azure/GCP/Sumo); there the queryable lever is tier_down, already preferred when it has a priced cheaper tier."
+              }
+            },
+            "additionalProperties": false
+          },
+          "description": "Per-service override map keyed by k8s_container name. A service absent from the map is auto-recommended. Pinned actions win unless illegal on the destination."
+        },
+        "auto_recommend": {
+          "type": "boolean",
+          "default": true,
+          "description": "When true (default), services without a `service_policy` entry get a per-service auto-recommended standard-tier action (cost-optimal within the destination legal set, compressibility-driven). When false, every service falls back to the single global `action_defaults.standard` (legacy one-size behavior)."
+        },
+        "compact_worth_it_ratio": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "default": 0.6,
+          "description": "Compressibility threshold for the compact-vs-offload auto-recommendation: a service whose measured optimized/input ratio (or the destination modeled compaction band when no measured ratio is available) is at or below this keeps `compact` (queryable plus a meaningful cut); above it `offload` is recommended (compact would save little). Default 0.6."
+        },
+        "service_compaction": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "compaction_ratio_x": {
+                "type": "number",
+                "exclusiveMinimum": 0,
+                "description": "Measured aggregate compaction (original bytes / encoded bytes) for this service, from `log10x_measure_compaction.data.payload.aggregate_compaction_ratio_x`."
+              }
+            },
+            "required": [
+              "compaction_ratio_x"
+            ],
+            "additionalProperties": false
+          },
+          "description": "Per-service measured compaction from `log10x_measure_compaction`, keyed by k8s_container. Grounds the per-service advisory in the real codec BEFORE optimize mode is deployed (the live optimize-mode metric only exists after deployment). Precedence for each service compressibility signal: live production metric (when optimize mode is running) wins, else this on-demand sample, else the static destination band. Run `log10x_measure_compaction` per service first, then pass `{ \"<k8s_container>\": { compaction_ratio_x: N } }`."
         }
       },
       "required": [
         "service"
       ],
-      "additionalProperties": false
+      "additionalProperties": false,
+      "$schema": "http://json-schema.org/draft-07/schema#"
     }
     ```
 

package/build/product-kb/docs/apps/mcp/tools/install/setup-recurring.md

@@ -11,6 +11,7 @@ The scheduler manifest is one of:
 - Kubernetes CronJob
 - GitHub Actions workflow
 - crontab + wrapper script
+- EventBridge Scheduler + CodeBuild (CloudFormation template, S3 config plane)
 
 ## :material-code-braces: Example
 
@@ -31,10 +32,11 @@ The scheduler manifest is one of:
 - *"recurring policy: payments and checkout, 40%, daily 3am UTC"*
 - *"emit a k8s CronJob that trims 25% off cart-svc weekly"*
 - *"schedule a GitHub Actions tick every 6h against acme/log10x-config"*
+- *"AWS-native tick for our Lambda estate, no cluster, no GitHub"*
 
 ## :material-check-decagram-outline: Prerequisites
 
-Reporter deployed (metrics drive the per-pattern planner that the tick invokes). A reachable gitops repo or local path for `policy.yaml`, and credentials for the chosen scheduler (`kubectl` access for `k8s_cron`, repo write for `github_actions`, host shell for `crontab`).
+Reporter deployed (metrics drive the per-pattern planner that the tick invokes). A config plane for `policy.yaml`, a gitops repo, local path, or S3 prefix, and credentials for the chosen scheduler (`kubectl` access for `k8s_cron`, repo write for `github_actions`, host shell for `crontab`, CloudFormation deploy rights for `eventbridge`).
 
 ## :material-code-json: Schema and samples
 
@@ -63,7 +65,7 @@ Reporter deployed (metrics drive the per-pattern planner that the tick invokes).
       "properties": {
         "session_id": {
           "type": "string",
-          "description": "Wizard session handle. Omit on the first call; a new session is minted and returned. Pass it back unchanged on every subsequent call."
+          "description": "Wizard session handle. Omit on the first call — a new session is minted and returned. Pass it back unchanged on every subsequent call."
         },
         "target_services": {
           "type": "array",
@@ -102,14 +104,15 @@ Reporter deployed (metrics drive the per-pattern planner that the tick invokes).
           "enum": [
             "k8s_cron",
             "github_actions",
-            "crontab"
+            "crontab",
+            "eventbridge"
           ],
-          "description": "Where the recurring tick runs. k8s_cron = Kubernetes CronJob (default when kubectl reachable), github_actions = GHA workflow, crontab = crontab + wrapper script."
+          "description": "Where the recurring tick runs. k8s_cron = Kubernetes CronJob (default when kubectl reachable), github_actions = GHA workflow, crontab = crontab + wrapper script, eventbridge = AWS-native (EventBridge Scheduler + CodeBuild, S3 config plane — no cluster, no GitHub; the fit for serverless estates)."
         },
         "config_plane": {
           "type": "string",
           "minLength": 1,
-          "description": "Gitops repo URL (e.g. https://github.com/acme/log10x-config) or local path where the recurring CLI reads policy.yaml and writes updated cap CSVs."
+          "description": "Where the recurring CLI reads policy.yaml and writes updated cap CSVs: a gitops repo URL (e.g. https://github.com/acme/log10x-config), a local path, or — required when scheduler=eventbridge — an S3 prefix (e.g. s3://acme-logs/log10x-config)."
         },
         "exceptions": {
           "type": "array",
@@ -117,7 +120,7 @@ Reporter deployed (metrics drive the per-pattern planner that the tick invokes).
             "type": "string",
             "minLength": 1
           },
-          "description": "Service names the policy must never touch (audit / regulatory / executive). Optional, defaults to empty. Pass [] to explicitly clear all exceptions."
+          "description": "Service names the policy must never touch (audit / regulatory / executive). Optional — defaults to empty. Pass [] to explicitly clear all exceptions."
         },
         "min_delta_pp": {
           "type": "integer",

package/build/product-kb/docs/engine/launcher/extension.md

@@ -0,0 +1,228 @@
+---
+icon: material/puzzle-outline
+---
+
+Extension runs the 10x Engine as its own [Lambda extension](https://docs.aws.amazon.com/lambda/latest/dg/lambda-extensions.html){target="\_blank"} inside each function's execution environment, paired over loopback with the [OTel collector extension](https://github.com/open-telemetry/opentelemetry-lambda){target="\_blank"} the function already runs. The collector hands every log record to the engine and receives it back regulated, routed, and hashed. No code changes, no new infrastructure, and nothing leaves the sandbox.
+
+:material-ice-cream: This launcher employs the [Runtime flavor](https://doc.log10x.com/engine/flavors/#runtime) (native binary).
+
+***Use-case***:
+
+Per-pattern regulation on serverless estates. A 100% Lambda shop has no node, no DaemonSet, and no forwarder host to install onto; the execution environment itself is the edge. The extension applies the same receive pipeline the [Receiver](https://doc.log10x.com/apps/receiver/) runs on Kubernetes: tag noisy patterns for cheaper storage tiers, offload slices to your own S3, and mute what nobody reads, before the first byte leaves the function.
+
+## :material-puzzle-outline: Benefits
+
+### :material-layers-outline: A Layer, Not a Rebuild
+
+The engine ships as a single Lambda layer: the native bootstrap under `extensions/`, with modules, config, and the symbol library under `/opt/tenx`. Attaching it to a function is a layer ARN plus environment variables; removing it is removing them. The layer unpacks to ~180 MB of Lambda's 250 MB shared layer budget.
+
+### :material-target: Per-Pattern Control
+
+Dispositions are keyed by pattern identity (`message_pattern`), not by function. A mute file decides each pattern's rate, with an explicit expiry and reason per entry, and a severity retention floor keeps ERROR/FATAL traffic flowing even under a full mute.
+
+### :material-cloud-sync-outline: Policy Without Redeploys
+
+`TENX_RECEIVE_MUTE_S3_URI` points the extension at a mute file in your own bucket. It fetches at INIT and refreshes on invoke (default 5 minutes), so one `aws s3 cp` converges every function. A failed fetch keeps the last good copy; dispositions degrade to the previous state, never to none.
+
+### :material-lock-outline: Nothing Leaves the Sandbox
+
+The collector pairing is loopback-only, and `TENX_AIRGAPPED=true` silences all engine egress to log10x. The only network path the extension adds is to your own S3 bucket, and only when you configure one.
+
+## :material-hexagon-multiple-outline: Architecture Flow
+
+<div style="text-align: center;">
+
+```mermaid
+graph LR
+    A["Function<br/>Code"] -->|"Logs"| B["OTel Collector<br/>Extension"]
+    B -->|"1. OTLP<br/>127.0.0.1:4317"| C["10x Engine<br/>Extension"]
+    C -->|"2. Regulated events<br/>127.0.0.1:24225"| B
+    B -->|"3. routeState<br/>routing"| D["Destination<br/>(SIEM)"]
+    B -->|"offload slice"| E["Your S3<br/>Bucket"]
+
+    classDef aws fill:#ff9900,stroke:#cc7a00,color:#ffffff,stroke-width:2px,rx:8,ry:8
+    classDef tenx fill:#059669,stroke:#047857,color:#ffffff,stroke-width:2px,rx:8,ry:8
+    classDef forwarder fill:#3b82f6,stroke:#1d4ed8,color:#ffffff,stroke-width:2px,rx:8,ry:8
+    classDef destination fill:#6b7280,stroke:#4b5563,color:#ffffff,stroke-width:2px,rx:8,ry:8
+
+    class A aws
+    class B forwarder
+    class C tenx
+    class D destination
+    class E aws
+```
+
+</div>
+
+<div class="diagram-controls">
+    <button class="md-button md-button--primary enlarge-diagram"
+            onclick="enlargeDiagram(this)"
+            data-diagram="extension"
+            data-tooltip="Click to enlarge diagram">
+        <span class="twemoji">
+            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="16" height="16">
+                <path d="M10 2c4.42 0 8 3.58 8 8 0 1.85-.63 3.55-1.69 4.9L20.59 19l-1.41 1.41-4.09-4.09A7.84 7.84 0 0 1 10 18c-4.42 0-8-3.58-8-8s3.58-8 8-8m0 2a6 6 0 1 0 0 12 6 6 0 0 0 0-12m1 3h2v2h-2V7m-4 0h2v2H7V7m2 4h2v2H9v-2Z"/>
+            </svg>
+        </span>
+        Enlarge Diagram
+    </button>
+</div>
+<!-- Mermaid enhanced diagram functionality loaded via external files -->
+
+**1. The function logs** as it always has. The collector extension picks events up through its existing receivers.
+
+**2. The collector hands each record** to the engine over loopback OTLP/gRPC (`127.0.0.1:4317`) and receives it back on `127.0.0.1:24225`, now carrying `tenx_hash` (stable pattern identity) and `routeState` (the pattern's disposition) as log attributes.
+
+**3. A routing connector fans out** on `routeState`: the SIEM slice ships through the existing exporter unchanged, the offload slice lands in your S3 bucket in the layout the [Retriever](https://doc.log10x.com/apps/retriever/) indexes, and drops end at the sandbox.
+
+## :material-rocket-launch: Deployment
+
+The [log10x MCP](https://doc.log10x.com/apps/mcp/) emits this entire plan from a discovery snapshot ([Advise](https://doc.log10x.com/apps/mcp/tools/install/advise-install/) returns it directly on a serverless estate, including a CDK construct). The steps below are the manual path.
+
+??? tenx-bootstrap "Step 1: Prerequisites"
+
+    | Requirement | Description |
+    |-------------|-------------|
+    | Log10x License | A full (non-demo) license ([get one](https://doc.log10x.com/run/bootstrap/#apikey)). Demo licenses cannot run airgapped, and `TENX_AIRGAPPED=true` is required here |
+    | AWS CLI | [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html){target="\_blank"} configured with Lambda and S3 permissions |
+    | GitHub CLI | [gh](https://cli.github.com){target="\_blank"} for pulling release artifacts |
+    | OTel Collector Extension | The target functions already run a collector extension with `routing` and `decouple` components (the community Lambda collector layer has both; a minimal custom build may not) |
+    | S3 Bucket | Optional. One bucket serves both the offload slice and live mute-file delivery |
+
+??? tenx-cloud "Step 2: Build and Publish the Layer"
+
+    The layer builds from the published release artifacts. Engine 1.1.68 or later carries the S3 mute fetch:
+
+    ``` { .console .copy }
+    gh release download 1.1.68 -R log-10x/pipeline-releases \
+      -p 'tenx-edge-1.1.68-amd64-native' -p 'tenx-modules-1.1.68.tar.gz' \
+      -p 'tenx-config-1.1.68.tar.gz' -p 'tenx-symbols-1.1.68.10x.tar' \
+      -p 'build-receive-layer.sh'
+
+    mkdir modules config symbols
+    tar xzf tenx-modules-1.1.68.tar.gz -C modules
+    tar xzf tenx-config-1.1.68.tar.gz -C config
+    cp tenx-symbols-1.1.68.10x.tar symbols/
+
+    chmod +x build-receive-layer.sh
+    ./build-receive-layer.sh \
+      ./tenx-edge-1.1.68-amd64-native ./modules ./config ./symbols \
+      ./tenx-receive.zip
+
+    # Bake your license into the layer at /opt/tenx/license.jwt
+    mkdir -p tenx && cp license.jwt tenx/
+    zip -ur tenx-receive.zip tenx/license.jwt
+
+    # The zip is ~90 MB; direct upload caps at ~70 MB, so stage through S3
+    aws s3 cp tenx-receive.zip s3://<your-bucket>/layers/tenx-receive.zip
+    aws lambda publish-layer-version \
+      --layer-name tenx-receive \
+      --compatible-architectures x86_64 \
+      --content S3Bucket=<your-bucket>,S3Key=layers/tenx-receive.zip
+    ```
+
+??? tenx-config "Step 3: Attach the Layer and Environment"
+
+    Write the environment as a JSON file. `TENX_RECEIVE_APPS` contains commas, which the AWS CLI's `--environment Variables={...}` shorthand silently mis-parses; `file://` is the reliable form.
+
+    ``` { .json title="env.json" }
+    {
+      "Variables": {
+        "TENX_MODULES": "/opt/tenx/modules",
+        "TENX_CONFIG": "/opt/tenx/config",
+        "TENX_SYMBOLS_PATH": "/opt/tenx/symbols",
+        "TENX_LICENSE_FILE": "/opt/tenx/license.jwt",
+        "TENX_AIRGAPPED": "true",
+        "TENX_LOG_PATH": "/tmp/tenx/",
+        "outputOffload": "true",
+        "symbolMessageHashField": "tenx_hash",
+        "log10xMetricsEnabled": "false"
+      }
+    }
+    ```
+
+    ``` { .console .copy }
+    aws lambda update-function-configuration --function-name <fn> \
+      --layers <tenx-receive-layer-arn> <otel-collector-layer-arn> \
+      --environment file://env.json
+    ```
+
+    `TENX_LOG_PATH` matters: Lambda's filesystem is read-only outside `/tmp`, and a log appender that cannot create its directory poisons the pipeline launch.
+
+??? tenx-forwarderinputs "Step 4: Splice the Collector Config"
+
+    Merge the loopback pairing into the collector config the functions already run. Existing receivers, processors, and the destination exporter stay untouched:
+
+    ```yaml
+    receivers:
+      # Return path from the engine extension (loopback, same sandbox)
+      otlp/tenx:
+        protocols:
+          grpc:
+            endpoint: 127.0.0.1:24225
+
+    exporters:
+      # Hand-off to the engine extension
+      otlp/tenx:
+        endpoint: 127.0.0.1:4317
+        tls:
+          insecure: true
+        # The collector's first dial happens before the engine listens, and
+        # default exponential retry intervals stretch across freeze until
+        # exports fail forever. Bounded intervals keep retries inside a
+        # thaw window.
+        retry_on_failure:
+          enabled: true
+          initial_interval: 200ms
+          max_interval: 1s
+          max_elapsed_time: 0s
+
+    connectors:
+      routing/tenx:
+        default_pipelines: [logs/tenx-siem]
+        table:
+          # context: log is required -- routeState is a LOG attribute; the
+          # resource context never matches it.
+          - context: log
+            condition: attributes["routeState"] == "offload"
+            pipelines: [logs/tenx-offload]
+          - context: log
+            condition: attributes["routeState"] == "drop"
+            pipelines: [logs/tenx-drop]
+    ```
+
+    The full config, including the offload pipeline, the `decouple` processor placement, and the destination-side storage-tier policy, is emitted per estate by [Advise](https://doc.log10x.com/apps/mcp/tools/install/advise-install/).
+
+??? tenx-mainconfig "Step 5: Per-Pattern Dispositions (Optional)"
+
+    Without a mute file every lever is estate-wide. With one, each pattern gets its own disposition. Entries are `<pattern>,<rate>:<untilEpochSec>:<reason>`; rate `0` is a full mute, `0.25` keeps 25%, and past the epoch the entry expires on its own. The first line is a header row the engine's lookup consumes as column names:
+
+    ```
+    pattern,disposition
+    heartbeat_check_ok,0:1786400000:liveness spam OPS-4821
+    jwt_validated,0.25:1786400000:auth flood after deploy
+    ```
+
+    Upload it to your bucket and add three variables to `env.json`:
+
+    ```
+    TENX_RECEIVE_APPS=@run/input/forwarder/otel-collector,@apps/receiver,@run/receive/rate
+    rateReceiverFieldNames=message_pattern
+    rateReceiverLookupFile=/tmp/tenx/mutes.csv
+    TENX_RECEIVE_MUTE_S3_URI=s3://<your-bucket>/<prefix>/pipelines/run/receive/rate/mutes.csv
+    ```
+
+    The extension fetches the file at INIT and refreshes on invoke (`TENX_RECEIVE_MUTE_REFRESH_MS`, default 5 minutes), so changing a disposition is one `aws s3 cp` with no redeploy. The function role needs `s3:GetObject` on that key. Alternatively, bake the file into the layer with `build-receive-layer.sh`'s sixth argument; the policy is then static and a change means republishing the layer.
+
+    For a recurring loop that recomputes dispositions from cost data on a schedule, [Setup recurring](https://doc.log10x.com/apps/mcp/tools/install/setup-recurring/) with `scheduler: "eventbridge"` emits an EventBridge Scheduler + CodeBuild stack that writes this same S3 key.
+
+??? tenx-monitoring "Step 6: Verify"
+
+    The extension logs its lifecycle to the function's log group:
+
+    ``` { .console .copy }
+    aws logs filter-log-events --log-group-name /aws/lambda/<fn> \
+      --filter-pattern "tenx-receive" --max-items 10
+    ```
+
+    At the destination, processed records carry `tenx_hash` and `routeState` as log attributes; a muted pattern shows `routeState` of `drop` on all but its retention floor. If dispositions have no effect, check that the mute file's first line is the header row and that `rateReceiverFieldNames` is `message_pattern`.

package/build/product-kb/docs/engine/launcher/index.md

@@ -54,4 +54,12 @@ The 10x Engine uses an extensible launcher framework to run [apps](https://doc.l
 
     [:octicons-arrow-right-24: Learn more](https://doc.log10x.com/engine/launcher/lambda)
 
+-   :material-puzzle-outline:{ .lg .middle } __Extension__
+
+    ---
+
+    Run the 10x Engine as a Lambda extension paired with the function's OTel collector.
+
+    [:octicons-arrow-right-24: Learn more](https://doc.log10x.com/engine/launcher/extension)
+
 </div>

package/build/product-kb/docs/summary.md

@@ -239,6 +239,7 @@
         * [Trigger](engine/launcher/trigger.md)
         * [Sidecar](engine/launcher/sidecar.md)
         * [Lambda](engine/launcher/lambda.md)
+        * [Extension](engine/launcher/extension.md)
     * [Flavors](engine/flavors.md)
     * [Pipelines](engine/pipeline.md)
     * [Modules](engine/module.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "log10x-mcp",
-  "version": "1.29.11",
+  "version": "1.29.12",
   "description": "Log10x MCP Server \u2014 per-pattern log cost attribution, root-cause investigation, pasted-batch triage, archive query/backfill, and cross-pillar correlation against customer metric backends (Grafana Cloud, Mimir, Thanos, AMP) with structural validation that refuses when it cannot prove linkage",
   "type": "module",
   "main": "build/index.js",