deepdebug-local-agent 1.7.0 → 1.9.0

package/src/incident-detector/sources/webhook-source.js

@@ -0,0 +1,109 @@
+/**
+ * webhook-source.js - the incident detector as the LOCAL consumer of the webhooks the control plane strips and forwards (F3-12 consumer).
+ *
+ * `webhook.forward` hands the (rebuilt, sha256-verified) body here. It is turned into the same entries every other source produces
+ * ({severity, message, stacktrace, service, tsMs}) and goes through the SAME pipeline (Java rules, DLP-masked local store, candidates with
+ * metadata only): the text of the webhook never leaves this process except into the local store. The ack of the webhook waits for `deliver()`.
+ *
+ *   text/plain          lines, joined into records like a log file (EntryAssembler)
+ *   alertmanager        `alerts[]` with status firing: "alertname: summary", severity label critical -> CRITICAL, error/high/major -> ERROR,
+ *                       anything else WARN (the detector ignores it)
+ *   sentry              `data.event` / `event` (+ `data.issue`): "Type: value" and a stack from the exception frames, `level` as severity,
+ *                       project as service
+ *   other JSON          one log-shaped object (message/msg/level/stack... as in parse.js); a body that does not look like one is `unmapped`
+ * Only SYNTHETIC payloads in the tests: the real shapes of each tool should be confirmed with captured webhooks before relying on them.
+ * Bounded: at most `maxEntries` entries and `maxBytes` of text per webhook. Counters only; never a word of the body in a log.
+ */
+import { EntryAssembler, parseRecord, parseTime } from "../parse.js";
+
+const str = (v) => (typeof v === "string" && v !== "" ? v : undefined);
+
+function fromAlertmanager(o, maxEntries) {
+    const out = [];
+    for (const a of Array.isArray(o.alerts) ? o.alerts : []) {
+        if (out.length >= maxEntries) break;
+        if (!a || typeof a !== "object" || (a.status && a.status !== "firing")) continue;
+        const labels = a.labels && typeof a.labels === "object" ? a.labels : {};
+        const ann = a.annotations && typeof a.annotations === "object" ? a.annotations : {};
+        const name = str(labels.alertname) || "alert";
+        const text = str(ann.summary) || str(ann.description) || "";
+        const sev = String(labels.severity ?? "").toLowerCase();
+        out.push({
+            severity: sev === "critical" ? "CRITICAL" : ["error", "high", "major", "page"].includes(sev) ? "ERROR" : "WARN",
+            message: text ? `${name}: ${text}` : name,
+            stacktrace: null,
+            service: str(labels.service) || str(labels.job) || str(labels.app) || str(labels.namespace) || null,
+            tsMs: parseTime(a.startsAt),
+        });
+    }
+    return out;
+}
+
+function sentryStack(exc) {
+    const values = exc && Array.isArray(exc.values) ? exc.values : [];
+    const v = values[values.length - 1];
+    const frames = v && v.stacktrace && Array.isArray(v.stacktrace.frames) ? v.stacktrace.frames : [];
+    if (frames.length === 0) return null;
+    return frames.slice().reverse().slice(0, 100).map((f) => `    at ${str(f && f.function) || "?"} (${str(f && (f.filename || f.module)) || "?"}:${Number.isFinite(f && f.lineno) ? f.lineno : 0})`).join("\n");
+}
+
+function fromSentry(o) {
+    const data = o.data && typeof o.data === "object" ? o.data : o;
+    const ev = data.event && typeof data.event === "object" ? data.event : data.issue && typeof data.issue === "object" ? data.issue : null;
+    if (!ev) return [];
+    const exc = ev.exception && typeof ev.exception === "object" ? ev.exception : null;
+    const last = exc && Array.isArray(exc.values) ? exc.values[exc.values.length - 1] : null;
+    const head = last && str(last.type) ? `${last.type}${str(last.value) ? `: ${last.value}` : ""}` : str(ev.title) || str(ev.message) || str(ev.culprit);
+    if (!head) return [];
+    const proj = ev.project && typeof ev.project === "object" ? ev.project : null;
+    const ts = typeof ev.timestamp === "number" ? ev.timestamp : ev.datetime || ev.firstSeen;
+    return [{
+        severity: str(ev.level) ? String(ev.level).toUpperCase() : "ERROR",
+        message: head.split("\n")[0],
+        stacktrace: sentryStack(exc),
+        service: str(o.project_name) || str(proj && (proj.slug || proj.name)) || str(ev.project) || null,
+        tsMs: parseTime(ts),
+    }];
+}
+
+/** @returns {{entries:object[], unmapped:boolean}} */
+export function entriesFromWebhook({ source, contentType, body }, { maxEntries = 200, maxBytes = 1048576, maxEntryBytes, maxStackLines } = {}) {
+    const text = new TextDecoder("utf-8").decode(body.length > maxBytes ? body.subarray(0, maxBytes) : body);
+    if (contentType === "text/plain") {
+        const asm = new EntryAssembler({ maxEntryBytes, maxStackLines });
+        const out = [];
+        for (const line of text.split("\n")) { out.push(...asm.push(line.replace(/\r$/, ""))); if (out.length >= maxEntries) break; }
+        out.push(...asm.flush());
+        const entries = out.slice(0, maxEntries);
+        return { entries, unmapped: entries.length === 0 };
+    }
+    let o;
+    try { o = JSON.parse(text); } catch { return { entries: [], unmapped: true }; }
+    if (!o || typeof o !== "object" || Array.isArray(o)) return { entries: [], unmapped: true };
+    let entries = [];
+    if (source === "alertmanager" || Array.isArray(o.alerts)) entries = fromAlertmanager(o, maxEntries);
+    else if (source === "sentry") entries = fromSentry(o);
+    else { const r = parseRecord(text); entries = r ? [r] : []; }
+    return { entries, unmapped: entries.length === 0 };
+}
+
+export function createWebhookSource({ maxEntries = 200, maxBytes = 1048576, maxEntryBytes, maxStackLines, stats = {} } = {}) {
+    let consumer = null;
+    Object.assign(stats, { received: 0, entries: 0, unmapped: 0, ...stats });
+    return {
+        name: "webhook",
+        stats,
+        start(onEntries) { consumer = onEntries; },
+        stop() { consumer = null; },
+        /** The sink of the webhook receiver. Resolves when every entry went through the detector (its detail queued): the ack waits for it. */
+        async deliver(webhook) {
+            if (!consumer) { const e = new Error("webhook source is not started"); e.code = "internal"; throw e; }
+            stats.received++;
+            const { entries, unmapped } = entriesFromWebhook(webhook, { maxEntries, maxBytes, maxEntryBytes, maxStackLines });
+            if (unmapped) { stats.unmapped++; return { entries: 0 }; }
+            stats.entries += entries.length;
+            await consumer(entries);
+            return { entries: entries.length };
+        },
+    };
+}

package/src/incident-detector/store.js

@@ -0,0 +1,119 @@
+/**
+ * store.js - the local detail store of detected errors (F3-11b). The TEXT of an error (message, stack trace) lives here and
+ * nowhere else: the control plane only ever gets metadata.
+ *
+ *   file        <storeDir>/incident-detail.jsonl, one JSON object per line, dir 0700 / file 0600, append only
+ *   rotation    at storeMaxBytes the file moves to incident-detail.jsonl.1 (one generation): disk use <= 2 x storeMaxBytes
+ *   record      {v, ts, errorHash, fingerprint, service, severity, windowStart, message, stack, stackBytes, truncated}
+ *               message/stack are masked by the DLP (when DLP is on) and cut to storeMessageChars/storeStackChars
+ *   sampling    samplesPerWindow records per errorHash and window (the count is in the candidate, not in this file)
+ *   queue       at most storeMaxQueue writes waiting; add() resolves when the record is queued OR dropped (never blocks the caller
+ *               for more than the queue allows: when full it waits for room, which slows the reading of the sources = backpressure)
+ *   getDetail   (errorHash, {limit}) reads the newest records back: this is the hook for `content.request` kind `incident.detail`
+ *               (F3-07 handler, NOT wired here: the contract/gateway kind and its ref scheme are not defined yet, see README.md)
+ *   never       logs a path, a message or a stack: counters only. A broken disk disables the store, not the detector.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { protectEgress } from "../dlp/index.js";
+
+const FILE = "incident-detail.jsonl";
+const cut = (s, n) => (typeof s === "string" && s.length > n ? s.slice(0, n) : s);
+
+export function createDetailStore({ dir, maxBytes, maxQueue, messageChars, stackChars, samplesPerWindow, env = process.env, now = Date.now }) {
+    const file = path.join(dir, FILE);
+    const stats = { written: 0, sampledOut: 0, dropped: 0, errors: 0, rotations: 0, redactions: 0, dlpDenied: 0 };
+    const samples = new Map();   // `${errorHash}|${windowStart}` -> records written
+    let queue = [];
+    let size = null;
+    let broken = false;
+    let writing = null;
+    let waiters = [];
+
+    async function ensure() {
+        if (size !== null) return;
+        await fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });
+        size = await fs.promises.stat(file).then((s) => s.size, () => 0);
+    }
+
+    async function drain() {
+        try {
+            await ensure();
+            while (queue.length) {
+                const batch = queue;
+                queue = [];
+                const lines = batch.map((r) => JSON.stringify(r) + "\n");
+                const bytes = lines.reduce((n, l) => n + Buffer.byteLength(l), 0);
+                if (size > 0 && size + bytes > maxBytes) {
+                    await fs.promises.rename(file, `${file}.1`).catch(() => {});
+                    size = 0;
+                    stats.rotations++;
+                }
+                await fs.promises.appendFile(file, lines.join(""), { mode: 0o600 });
+                size += bytes;
+                stats.written += batch.length;
+                const w = waiters; waiters = []; for (const f of w) f();
+            }
+        } catch {
+            broken = true;      // disk full, permissions...: the detector keeps going without a store
+            stats.errors++;
+            stats.dropped += queue.length;
+            queue = [];
+        } finally {
+            writing = null;
+            const w = waiters; waiters = []; for (const f of w) f();
+        }
+    }
+
+    const mask = (text) => {
+        if (typeof text !== "string" || text === "") return text;
+        const r = protectEgress(text, { env, source: "incident-store" });
+        if (r.denied) { stats.dlpDenied++; return "[DLP_DENIED]"; }
+        if (r.total) stats.redactions += r.total;
+        return r.text;
+    };
+
+    return {
+        stats,
+        get broken() { return broken; },
+        get queued() { return queue.length; },
+        /** @returns {Promise<boolean>} true = queued. */
+        async add({ errorHash, fingerprint, service, severity, windowStart, message, stack }) {
+            if (broken) { stats.dropped++; return false; }
+            const key = `${errorHash}|${windowStart}`;
+            const n = samples.get(key) || 0;
+            if (n >= samplesPerWindow) { stats.sampledOut++; return false; }
+            if (samples.size > 50_000) samples.clear();   // bounded: a reset only lets a few extra samples through
+            samples.set(key, n + 1);
+            while (queue.length >= maxQueue && !broken) await new Promise((res) => { waiters.push(res); if (!writing) writing = drain(); });
+            if (broken) { stats.dropped++; return false; }
+            const m = typeof message === "string" ? message : "";
+            const st = typeof stack === "string" ? stack : "";
+            queue.push({
+                v: 1, ts: new Date(now()).toISOString(), errorHash, fingerprint, service, severity, windowStart,
+                message: mask(cut(m, messageChars)), stack: st ? mask(cut(st, stackChars)) : null,
+                stackBytes: Buffer.byteLength(st), truncated: m.length > messageChars || st.length > stackChars,
+            });
+            if (!writing) writing = drain();
+            return true;
+        },
+        /** Newest first. Reads both generations; a bad line is skipped. */
+        async getDetail(errorHash, { limit = 5 } = {}) {
+            if (writing) await writing;
+            const out = [];
+            for (const f of [file, `${file}.1`]) {
+                let text;
+                try { text = await fs.promises.readFile(f, "utf8"); } catch { continue; }
+                const lines = text.split("\n");
+                for (let i = lines.length - 1; i >= 0 && out.length < limit; i--) {
+                    if (!lines[i].includes(errorHash)) continue;
+                    try { const r = JSON.parse(lines[i]); if (r.errorHash === errorHash) out.push(r); } catch { /* skip */ }
+                }
+                if (out.length >= limit) break;
+            }
+            return out;
+        },
+        /** Waits until everything queued is on disk (tests, shutdown). */
+        async flush() { if (!writing && queue.length) writing = drain(); if (writing) await writing; },
+    };
+}

package/src/la-protocol-v2/contract/CONTRACT_SOURCE.json

@@ -2,15 +2,15 @@
   "repo": "VISIONHAMMER/vh-api-gateway",
   "path": "docs/contracts/la-protocol-v2",
   "branch": "release/qa",
-  "commit": "b9176054337eeabe416117bafd90ce484a71968e",
+  "commit": "c0d6b44a89d2d18a2627493403c06b9caa7d1a96",
   "note": "Copied by scripts/sync-la-protocol-v2-contract.mjs. Do not edit: change the gateway folder and sync again.",
   "files": {
-    "README.md": "93fe7d94f212c36d5402a20cd1397e5236012c6bf1f6bb81546a65033703a88f",
+    "README.md": "e247945f859f777a705c5baebecf2a216462a7c2fe1c30598099c96c88cd432b",
     "ack.schema.json": "d6dfdaa8b1ec2dd47db9e858cd047ca860196ab6b0ad350f8ccb5d2596441ccf",
     "alert.schema.json": "01a8a77840be8ab7901ed7d07c3d68a2295bfaeb638694564e19e60be1747054",
     "approval.decision.schema.json": "a9c7bc74d146465afde1d5830839165a02f232b830b5f6cfd8c8e91fb6da1563",
     "audit.event.schema.json": "e9ceb58ea00077151373955957b8319324de488c80da4063f6d0dcb40a8b3ed0",
-    "config.update.schema.json": "f5318f24230f542c76a3cb996d08f33210c0b2cc2fc55ad73c4f95648582033f",
+    "config.update.schema.json": "432438b0c93ddafa0741e47f99b7357ad5f2b06b606779bf846c282e2f8a5639",
     "content.index.schema.json": "1abc24344435f0f392d5b626c3abb6879d8f9dd2c1d0463840a67634a5caa71e",
     "content.request.schema.json": "440e3675246657e9aae23e51176168bc21c91283b5fcaf6782111a18110bf76e",
     "content.response.schema.json": "c9a66ac9cbbcaec7fc182b3e3fa23b34877bd342592521c7e393779230332231",
@@ -19,24 +19,24 @@
     "error.schema.json": "b1fd663d4a1ea73d88cb575422f15f8c7279001f9385ebb2d5e1889b5d5ef878",
     "file.list.body.schema.json": "dd58ac2af91bbde53e0fd585dc55af0adb01380492d1604f21ed8e972d7ba8d1",
     "heartbeat.schema.json": "8aff84a1ef3ca56bdff8819abb3b0ab01a2547814c2ea2f9ee893cb08f7a08f1",
-    "hello.schema.json": "bd500320f01ff10da49ded6f99c7e8081252019984afb3c178e27003df20b963",
-    "incident.candidate.schema.json": "b292a85917b5958fc6de10a2895732e30a35420385623930c78e47341862dc62",
-    "index.json": "cf8f05e70b6265a169b0117d4577f78b699818eb5091df6cd4c7c7416385582a",
+    "hello.schema.json": "a90a6bf0e9a8a20e4c6edcf2137931cf044846e7924977228275ef648a48934f",
+    "incident.candidate.schema.json": "ffec36aca6916079debc2c6060d093819ea3ea660b57c0c92ac3b541a0e99000",
+    "index.json": "de79c065217e1fa8430c4266ec19fd57df35fc4182eb7c7246b6f1ea03d2630c",
     "job.assign.schema.json": "fdebb4ae98bf38a2c723281c1cf9477f71d877171df9a55b0baeb0b65244f60c",
     "job.cancel.schema.json": "40ef64373283e17306d857c9a40081689786015294b0b88ab8f68f063bd2cfb8",
     "job.event.schema.json": "493d08f9db4f7ffd4a97403ee33ca4a73a65dc8f774d8f18ef0a137fdb5fc470",
     "job.result.schema.json": "9cbc61211482557283b8f4df44e79011ead1abbacdb2d986138199c747edc043",
     "log.stats.schema.json": "4b33b111946a19793a60756793294e90911b06f7050e48821759f2497ec17641",
-    "ready.schema.json": "6e8bd8e1a5ce1b840d35af911ae09b8f58ad9de59eb33cd2b7777859892813f4",
-    "register.schema.json": "e75a4aa9d5d750e1473f71ab2f37d8e9a82fcfab3e8ff1c35118d0c08916e795",
+    "ready.schema.json": "02e51ba5aad3357c9840c14eb45cb86b7aab0c10e349c94c720cda1a0b5b8366",
+    "register.schema.json": "bec30062cf99657a1ecb94bad004f502615901e36bc2b0ba62351ed021e059ac",
     "scan.upload.schema.json": "b1bba86ee362f73afc94c8c216977c12f67f770490e81002d14789397692f23b",
     "scan.uploaded.schema.json": "f4c6aed7b9363b3ce1a9e14f9c4f4fb003bcf104b60acf74421dd0c75fc5d229",
-    "webhook.forward.schema.json": "33d4ee238855339850ff198d1078087f3b2f48c8f290b71def93cc02dd32c985",
-    "vectors/ack.vectors.json": "242ec2b8ff0c748eaaedce63e0015cf5bd9a7092d1055b0670ce6b95403b54b2",
+    "webhook.forward.schema.json": "9ab66adf31386445c2b76930155ffa6874326395d968582d2345ee7fb5b77f82",
+    "vectors/ack.vectors.json": "1756c1169cf5f42c0ab6b1c094071d1f8ccf2fe9efdbc97101e402e93bd65a67",
     "vectors/alert.vectors.json": "0bf179ff390bbecf07a117b80237cb7ac8778864e5780f36d68c8c9a64db8f04",
     "vectors/approval.decision.vectors.json": "338115973bf2c4390d2bb33ce8f4079f3132cd739cd5505e1e873fdc252d2271",
     "vectors/audit.event.vectors.json": "d05c1820103eef041a84eb8b13d9a67a8a5b54b9b54ee3b6e43fd4ef15ed7000",
-    "vectors/config.update.vectors.json": "8a5088d547e3eb4e460b25a5e413caaa02d4402a601340e279166d8c17758e1c",
+    "vectors/config.update.vectors.json": "e61865fad9b4efa808e02877c4352d3720c8069a0b31261701b369d8ae11f9cf",
     "vectors/content.index.vectors.json": "f167db30910989c46f317313d651ca59f9cd9d881d2ea81b84912155d18227b7",
     "vectors/content.request.vectors.json": "fdf0f4d9e19f6480e20e40f4652bf8205da2b113620f8461dfaeb0d61add36a0",
     "vectors/content.response.vectors.json": "cbb47cbf8a9512aa5360eea425f0cdd9064334311d37834dc75bddff07dadc5d",
@@ -44,15 +44,15 @@
     "vectors/error.vectors.json": "f5fd7954f2c1736ee0943eb330c2f85b7fdd7a8959e4f043f9cc9e9bcda39aa5",
     "vectors/file.list.body.vectors.json": "da1dcc5d4ec976853161bef4b3947572f36b5526cbe16b838ac4ef72ddded403",
     "vectors/heartbeat.vectors.json": "cfd2e048139c67aa925f1fa94c05326e75248839645c1a1e4d6d3bb60cafa624",
-    "vectors/hello.vectors.json": "51067dc645a2e9d8116997b36e6f3fe36401d27f3ee3c18de32ec30f8a052c5f",
-    "vectors/incident.candidate.vectors.json": "0dd75ef396bf7b7911d20b3ab220469701f07866bb032ee31af58523c3633ab6",
+    "vectors/hello.vectors.json": "7a50c4e54e6a4ef1227fd7485071bca8ec7b797c3b2907fddda3d8836c3feab6",
+    "vectors/incident.candidate.vectors.json": "a78eb4b103f411f1ec64d9eeb4c39623851e710ac0cc20b4d78b2739b7ff78d5",
     "vectors/job.assign.vectors.json": "e510c2cc6d17238d477429c255d828c0339b504e39a3a50d4b6ca980e262d9ef",
     "vectors/job.cancel.vectors.json": "0fc9f99c8662435e9425389068adf418273489dc73928a21eae1b283256b9bc5",
     "vectors/job.event.vectors.json": "03a2a2435918ba561821916bf4e435f2780210900139ecf68091acac6abf200c",
     "vectors/job.result.vectors.json": "05995fbe65e5357705d75e9b660b517f54c6902069d36b62190b1b79f283e7a5",
     "vectors/log.stats.vectors.json": "a8a67e09ef0f87b81f4028b77427ed7afd809c3f8534b8423a712b2ceef9a27f",
-    "vectors/ready.vectors.json": "a584da17e714a13c3583256773ef0be007660c33c62a456e27568def391e7cef",
-    "vectors/register.vectors.json": "e2a696efc547aa2f7242128d1a860238954f9e9a1330f10b567122d7b3da0365",
+    "vectors/ready.vectors.json": "16327f5e5eccc57a0ec635bcde96116feeeeec7ddbc4b621d4d070738cdc48d5",
+    "vectors/register.vectors.json": "b612e9462b1e2ac198442afccf450f1535daadc4c32d87f6a99b9752c343c486",
     "vectors/scan.upload.vectors.json": "e8a6f73fe91ac58a3222b68cf28124c1254aa4f00c3ef8f472deb7de31cab76e",
     "vectors/scan.uploaded.vectors.json": "7314ea15b1afa7b9625048fb7e245492d8910bc0dae8a52ea62afe2a1e240382",
     "vectors/traces/invalid-agent-mismatch.json": "5f17b867de71c1bcc6c42723acb53a50338c0e491193499ea25c2220ea4fa558",
@@ -76,11 +76,19 @@
     "vectors/traces/invalid-signature-warn-with-enforce-required.json": "71b5b3dc5dce52417173934db1e0de6542ecae5798e87124d54a8017493312e1",
     "vectors/traces/invalid-tenant-mismatch.json": "dcc04ea423bddef20524ead7bfd146a5d9c42fe474c9216dc38c90544d291151",
     "vectors/traces/invalid-type-outside-allowlist.json": "e492d326cfa044d3fc9f7e48dee63a52b715a62ba4867fc5ce21f1d86e3c435f",
+    "vectors/traces/invalid-webhook-chunk-after-last.json": "9a35faaeeafce045a887e643f603ca69950872d62d27d17086513103999aefd6",
+    "vectors/traces/invalid-webhook-chunk-body-hash-changes.json": "7ade576a8dc8e9671383e85fbe6aae414863cbb1cde38737a2cb78efce9c9528",
+    "vectors/traces/invalid-webhook-chunk-last-flag-wrong.json": "8505b5fbbc0a8dc97021a1c02f9883df95f9401bc18eaa2498331b0b6b7d155c",
+    "vectors/traces/invalid-webhook-chunk-non-last-too-short.json": "ff1d64b019c082e7a5c6537fdbf069025a532c764e62c532a24a3b7257f4b6ab",
+    "vectors/traces/invalid-webhook-chunk-out-of-order.json": "b6baa056b4e3347deaf0a4b901a126a3f93d20627faaa3951028bd47894715f4",
+    "vectors/traces/invalid-webhook-chunk-sha-mismatch.json": "1bb79d0e1794cd791625ed2a7eab154e20150c5d7bee7c86aa97f9bf4aaeab6d",
+    "vectors/traces/invalid-webhook-chunk-total-changes.json": "5edf3c1916927f94ef15061a13a6ded8a0168cb0492158f34db8160c0d6bdbe4",
     "vectors/traces/valid-content-chunks-in-order.json": "c5fc301527b062b30c625da2798c7cfab3e3debac29a36f6ec7c699705267ab3",
     "vectors/traces/valid-content-index.json": "9305dc955c4cca1f09158a9c8cf21d9e89d6a6b03646088c547f64a61cd59c30",
     "vectors/traces/valid-handshake-and-job.json": "9aa3c423c496403ca77d63965f1805f0a57ea9f6f8a01351310515b265aeb9cc",
     "vectors/traces/valid-resume-continues-seq.json": "8aa90f24598f8f2d87a5355ec58c3531d16fd11ad41c782f53eca063372b704a",
     "vectors/traces/valid-retransmit-is-idempotent.json": "924e9d296a67f0006c289e7cc978b9529ae1aa03bec2cd331a62f31354a90257",
-    "vectors/webhook.forward.vectors.json": "38d5b53b8fb4ecdb051e2c594afc52eb8b2044e4e6aae6ffb0057fbda33bcd46"
+    "vectors/traces/valid-webhook-chunks-in-order.json": "2e5e6313a7fe9b3f7fea23d6a0c928d6bfef69b2a7179f1578230425f451ada9",
+    "vectors/webhook.forward.vectors.json": "991a677d72a9c698ed3c8d960af532daf8f3158d77a4bea7d08750ccd8693250"
   }
 }

package/src/la-protocol-v2/contract/README.md

@@ -5,13 +5,16 @@ sides. Design: vault `10 Library/Plans/Fase 3 Desenho Tecnico 2026-10-28.md` sec
 implements it behind `deepdebug.agent-ws.protocol-v2.enabled` (default off, F3-05a); the LA side (F3-05b) does not
 exist yet. v1 is untouched. The gateway packages `*.schema.json` + `index.json` from this folder as classpath
 `la-protocol-v2/` (pom resource; both Dockerfiles copy this folder), so this folder stays the only source.
+**Revision 2.1** (`index.json` `revision`, Fase 3, last section): optional LLM key delivery, chunked webhooks, size/model in `incident.candidate`, `ready.capabilities`.
 
 ## Files
 - `envelope.schema.json`: common frame, closed (`additionalProperties:false`). `<type>.schema.json` (22):
   one per allowlisted type, each `$ref`s the envelope and closes `payload`. `defs.schema.json`: shared types.
 - `file.list.body.schema.json` (F3-07c): not a frame type; the schema of the DECODED body of a `content.response` for kind `file.list`
   (below). `vectors/file.list.body.vectors.json` holds its vectors (same format, `schema` names that file).
-- `index.json`: allowlist, direction, signed/control flags, content class per type, and the limits below.
+- `index.json`: allowlist, direction, signed/control flags, content class per type (`none`, `relay`, `transit`, `secret`), the limits below and the contract `revision`.
+- Vector files of a BODY that travels inside a frame (not a frame) are named `*.body.vectors.json` and their schema `*.body.schema.json`; the frame
+  suites skip them (`ProtocolV2ContractTest` checks them against their own schema, `SchemaLaV2ContractTest` does not read them as frames).
 - `vectors/<type>.vectors.json` (+ `cross-type`): valid and invalid messages with `expect` (`valid`, error `code`,
   optional JSON Schema `keyword`, optional session `rule`). `vectors/traces/*.json`: whole sessions for the stateful rules.
 
@@ -30,7 +33,8 @@ ack timeout 5 s, <= 3 retransmissions; handshake steps 10 s; `ping`/`heartbeat`
 (= Redis `la:session` TTL); clock skew <= 60 s. Duplicate detection (gateway, F3-05a): the last 512 `seq`->`msgId` pairs
 per session, in memory (`dedupe-entries`); the 10 min Redis window of the design (`dedupeWindowSeconds` in `index.json`)
 is NOT implemented, a replay older than those 512 frames is `seq_replayed`. CP->LA frames repeat the payload in
-`paramsRaw`, so their effective payload budget is about 20 KiB; larger inputs travel by `ref`.
+`paramsRaw`, so their effective payload budget is about 20 KiB; larger inputs travel by `ref`. Webhook chunking (2.1) has its own limits
+(`webhook*` in `index.json`: 16 KiB raw per chunk, 64 chunks, 1 MiB per webhook, see the last section).
 
 ## State machine
 `AWAIT_REGISTER -> AWAIT_HELLO -> AWAIT_READY -> READY`, after the WS upgrade authenticates (Bearer, as v1).
@@ -45,7 +49,9 @@ is NOT implemented, a replay older than those 512 frames is `seq_replayed`. CP->
   handshake state, `seq` (same seq + same `msgId` = idempotent duplicate, re-ack; same seq + other `msgId` =
   `seq_replayed`; skip = `seq_gap`), chunks (index 0.., `total` constant, `last` iff last index, none after last; then `payload.byteLength` must equal the size of
   the base64-DECODED `payload.data`, else `chunk_inconsistent`: JSON Schema cannot state it, so the vector files carry
-  `expect.rule:"byteLength-decoded"` and both validators apply it).
+  `expect.rule:"byteLength-decoded"` and both validators apply it). Since 2.1 two more stateless rules of the same kind:
+  `webhook-chunk-size` and `llmKey-id-sha256` (last section); `webhook.forward` chunks are also grouped by `payload.webhookId` and the reassembled
+  body must hash to `bodySha256` (`chunk_inconsistent` otherwise).
 - **Errors** (`error{code,retryable}`, then WS close 4400-4499 when fatal): `bad_frame unknown_type schema_violation
   frame_too_large payload_too_large wrong_direction handshake_violation not_ready seq_gap seq_replayed
   chunk_out_of_order chunk_inconsistent tenant_mismatch agent_mismatch params_mismatch signature_mode_insufficient
@@ -64,6 +70,7 @@ Everything is closed: no free-text fields, no extra properties, free strings <=
 hashes, counts). Client content may exist only in three declared fields (`x-content-class`, pinned by the test):
 `content.response.data` (relay, LA->CP, never persisted or logged by the CP), `job.assign.inputs[].inline` and
 `webhook.forward.bodyB64` (transit, CP->LA, `transient:true`, not persisted; `paramsRaw` echoes them).
+Since 2.1 there is one more classified field and it is the only SECRET: `config.update.llmKey.key` (`x-content-class: secret`, see the last section).
 Long non-content strings are marked `x-large-metadata` (`paramsRaw`, `signedPutUrl`, `vhapr1` token). `error.detail` <= 200 chars
 and `audit.event` have no summary text; stack traces, diffs, logs and paths go only through `content.*`.
 
@@ -186,3 +193,96 @@ existing kinds, `ref` convention, ids, envelope and chunking are reused; the cha
   answer is HTTP 501 `not_supported`. That announcement is also how the front/CP discovers that listing exists on a given agent.
 - **Compatibility.** Additive: the kind is added to the `content.request` and `content.index` enums, nothing else changes there. The
   `content.request` payload gained no field. With `deepdebug.content-relay.enabled` off nothing is mapped, as before.
+
+## Revision 2.1 (Fase 3, contract v2.1): LLM key, chunked webhooks, size and model of a candidate
+Decisions of Edu 2026-11-03 (ADR-0017, adenda (c)). **No new frame type** (still 22), every change is additive and optional, and each is gated by a
+capability so a 2.0 peer keeps working unchanged. The gateway code that uses these fields is a later task (G); here only the contract moved.
+
+**Capabilities (negotiation).** The LA announces, in `register` and `hello` `capabilities`: `contract.v2.1` (it has the 2.1 schemas, so it can read the
+new optional `ready.payload.capabilities`), `llm.key` (it handles `config.update.llmKey`) and `webhook.chunked` (it reassembles chunked `webhook.forward`;
+it announces `webhook.forward` too). The CP announces, in `ready.payload.capabilities` (array, <= 32, same name pattern): `incident.candidate.size-model` (it
+accepts `stackBytes` and `model`). Rules: the CP sends `llmKey` only to a session that announced `llm.key`, a chunked webhook only to one that announced
+`webhook.chunked`, and `ready.capabilities` only to one that announced `contract.v2.1` (a 2.0 LA's closed `ready` schema does not know the field, so without
+`contract.v2.1` the `ready` is exactly the 2.0 one); an LA sends `stackBytes`/`model` only if `ready` listed `incident.candidate.size-model` (a 2.0 CP would
+answer the closed schema with `schema_violation`). A name that is absent means 2.0 behaviour.
+One more LA capability, `llm.key.held` (section (e)), tells the CP the LA holds a valid key right now; it is optional and only informs the CP.
+
+### (a) LLM key delivery: `config.update.payload.llmKey`
+`config.update` already carried only flags, a DLP hash, a minimum version, a retention and the data-plane mode: it had no way to hand the LA the virtual
+LiteLLM key (F3-09). `llmKey` is a closed `oneOf`:
+- `{op:"set", keyId, endpoint, key, models[], expiresAt}`, all required. `keyId` is the 64-hex lower-case sha256 of the UTF-8 bytes of `key` (it is
+  LiteLLM's token id and the CP's `la_llm_keys.key_id`; semantic rule `llmKey-id-sha256`: the LA recomputes it and refuses a mismatch). `endpoint` is the AI
+  gateway base URL, `https://` only, host[:port][/path], no credentials, no query, no fragment, <= 256 chars. `key` is 16..256 chars of
+  `[A-Za-z0-9._~+/=-]` (no whitespace, no control character). `models` is 1..32 unique aliases (the scope of the key). `expiresAt` is UTC.
+- `{op:"revoke", keyId}`: names the key by id, never repeats it.
+- A `config.update` that carries `llmKey` carries NOTHING else (`maxProperties: 1`), so the frame can be recognised and redacted as a whole.
+- **The key is a secret.** `x-content-class: secret` on `llmKey.key`; `index.json` marks `config.update` `contentClass: "secret"`. It travels only on the v2
+  channel (TLS plus the Ed25519 signature) and, between gateway instances, only inside the AEAD-sealed relay (F3-04). It appears twice in the frame, in
+  `payload` and in the `paramsRaw` copy: BOTH are secret. The CP never writes it to a log, a metric, a trace, the audit trail, a table or an unsealed Redis
+  value (it keeps it only in the in-memory unacked frame until acked or the session ends). The LA keeps it **only in memory or in a file mode `0600`
+  (directory `0700`) outside every workspace and outside what the content handlers can serve**, never logs it, never puts it in `hello`, `alert`,
+  `audit.event`, `job.event`, `content.response` or an error, and never passes it on a command line.
+- **The ack never returns it.** The answer is the plain `ack` (its payload is only `ackSeq`, `status`, `errorCode`; the contract test pins that no LA->CP
+  frame has a field named `key`, `llmKey` or `keyId`): `accepted`, or `rejected` + `schema_violation` when the LA refuses the key (expired
+  `expiresAt`, `keyId` not the sha256 of `key`).
+- **Rotation.** A `set` with another `keyId` replaces the key the LA holds, atomically (one key per LA); the same `keyId` again is idempotent. The CP should
+  revoke the old key at the AI gateway only after the `accepted` ack of the new one.
+- **Revocation.** The key revoked at the AI gateway is the authoritative revocation; the `revoke` frame only makes the LA drop its copy (delete from memory,
+  unlink and overwrite the file) and stop using it. A `revoke` of an id the LA does not hold is a no-op and is acked `accepted` (it never tells which key it
+  has). The LA also drops the key at `expiresAt`.
+
+### (b) Chunking of `webhook.forward` (CP -> LA)
+2.0 allowed one frame with `bodyB64` <= 12288 chars (9216 raw bytes). That stays: **a body of at most 9216 bytes is sent as ONE frame without `chunk`, exactly
+as in 2.0** (a 2.0 LA reads it). A bigger body (up to **1 MiB**) is chunked, reusing the `content.response` pattern but CP -> LA:
+- Each chunk is a signed `webhook.forward` frame with the envelope `chunk{index,total,last}` (index from 0), its own `seq` and `msgId`, and the same
+  `webhookId`, `source`, `contentType`, **`bodyBytes`** (size of the WHOLE decoded body, 0..1048576) and **`bodySha256`** (sha256 of the whole decoded body,
+  lower-case hex). `bodyBytes` and `bodySha256` are required in a chunked frame and forbidden in an unchunked one (schema `if/then/else` on `chunk`).
+- **Fixed chunk size**: 16384 raw bytes (`bodyB64` <= 21848 chars; twice in the frame with `paramsRaw` it still fits 48 KiB: a vector pins it).
+  `total = max(1, ceil(bodyBytes / 16384))` (<= 64); every non-last chunk has exactly 16384 bytes; the last has `bodyBytes - 16384 * (total - 1)`. That is the
+  stateless rule `webhook-chunk-size` (`chunk_inconsistent` when a frame breaks it), so the LA can size the buffer from the first chunk. A body above
+  9216 bytes is never sent unchunked; a chunked frame with a small body (`total` 1) is valid.
+- **Order and integrity** (reference model, same codes as `content.response`): chunks in index order, `total` constant, `last` iff the last index, none after
+  the last (`chunk_out_of_order` / `chunk_inconsistent`); `bodyBytes`, `bodySha256`, `source`, `contentType` must not change between chunks; on the last
+  chunk the reassembled body must have `bodyBytes` bytes and hash to `bodySha256`, else `chunk_inconsistent`. Each chunk is also authentic on its own (signature).
+- **Acks.** Every chunk is a normal v2 frame: the LA acks each by `seq` (piggyback or `ack{ackSeq,status}`), `accepted` = stored. The `accepted` ack of the
+  LAST chunk means the body was reassembled and its hash verified: that is the ack the CP waits for before answering the webhook (decision: ack AFTER the
+  forward). The LA answers `rejected` + `chunk_inconsistent` / `chunk_out_of_order` / `payload_too_large` / `rate_limited` and drops the assembly; the CP then
+  stops sending chunks of that `webhookId` and treats the webhook as not delivered.
+- **LA limits** (`index.json`): an assembly older than 30 s (`webhookAssemblySeconds`) without its last chunk is dropped; at most 4 open assemblies per session
+  (`webhookMaxOpenAssemblies`; the CP sends one chunked webhook at a time per session) and 4 MiB buffered; beyond that `rejected` + `rate_limited`. The body
+  stays in memory, is never written or logged by the CP, and the LA applies its DLP to it as to any client content.
+- `webhookId` is the group key; a retransmitted chunk (same `seq` and `msgId`) is the existing idempotent duplicate; the same `webhookId` redelivered as a
+  whole is the application's dedup (a deterministic `webhookId` is the consumer's job).
+
+### (c) `incident.candidate`: `stackBytes` and `model`
+Two OPTIONAL fields, no required field added: `stackBytes` (integer 0..16777216: size in bytes of the stack the LA saw; the LA saturates at the cap) and
+`model` (string 1..48, `^[A-Za-z0-9][A-Za-z0-9._:+-]{0,47}$`: detector/parser version, e.g. `stack-detector-1.8.0`; no space, no slash, so no name, path or
+error text fits). The frame still carries no stack, no message and no name. Sent only after `ready` announced `incident.candidate.size-model`.
+
+### (d) `ready.payload.capabilities`
+Optional array (<= 32 capability names). It is what lets (c) be sent safely; it carries no limit and no content. A CP that does not send it is a 2.0 CP, or the
+session did not announce `contract.v2.1`.
+
+### (e) `llm.key.held`: the LA says whether it still has its key
+Problem it solves: an LA that keeps the key only in memory (the default) loses it on restart, but the CP's table still says ACTIVE, and the CP only
+delivers again when the key is close to expiry (< 14 days), so the LA would stay without a key. Rather than the CP guessing, the LA announces it.
+- **Name and place.** The capability string `llm.key.held` (it already matches the `capability` pattern, so no schema enum changes), announced in
+  `register.payload.capabilities` and in `hello.payload.capabilities`, never in `ready.payload.capabilities` (that list is the CP's). It is optional and
+  needs no `contract.v2.1` decision of its own: a CP that does not know it ignores an unknown capability name, as it ignores any other.
+- **Rule for the LA.** It announces `llm.key.held` ONLY when it holds a key that is still valid (`expiresAt` in the future, accepted and
+  `keyId`-verified through `config.update.llmKey`) and that it is IN USE (it is the key its LLM calls would use). No key, an expired key, a revoked key
+  or a key it refused: it does not announce it. The announcement is a snapshot at connect time: `register` and `hello` of one session carry the same
+  answer, and the LA never announces it without also announcing `llm.key` (an LA that cannot receive a key cannot hold one). That dependency is in the
+  schema (`if capabilities contains llm.key.held then it must contain llm.key`, `register` and `hello`), so `llm.key.held` alone is `schema_violation`.
+- **Rule for the CP.** At connect, if the capability is NOT announced (in `register` and `hello`; the CP should treat the key as held only when both
+  say so), the CP delivers a key (mint, then `config.update.llmKey set`) even when an ACTIVE row exists for that agent; the previous key follows the
+  rotation rule of (a) (revoked at the AI gateway only after the `accepted` ack of the new one). If it IS announced, the CP keeps the existing rule:
+  nothing to deliver until the key is within 14 days of `expiresAt`. A 2.0 LA, or a 2.1 LA that does not know the capability, never announces it, so
+  the CP treats it as "holds no key" and delivers one if the channel is on (`llm.key` announced): the safe direction.
+- **Compatible.** Optional and additive: a register/hello without it is valid (2.0, or 2.1 after a restart), and one with it is valid under 2.1 only
+  together with `llm.key`. No frame type, no new field and no new limit. The CP side of this rule is gateway runtime code (a later task, not this contract).
+
+### Compatibility and roll-out order
+Everything is additive and optional: a 2.0 frame is valid under the 2.1 schemas (the vectors of 2.0 are unchanged and still pass), and a 2.1 peer talking to a
+2.0 peer sends nothing the 2.0 peer cannot read, because each new field is gated by a capability the other side announced (above). Roll out the gateway that
+has the 2.1 schemas first (it accepts both shapes), then the LAs. The files changed by 2.1 are listed with their sha256 in the PR; the LA re-syncs exactly those.

package/src/la-protocol-v2/contract/config.update.schema.json

@@ -52,9 +52,93 @@
         },
         "dataPlaneMode": {
           "$ref": "defs.schema.json#/$defs/dataPlaneMode"
+        },
+        "llmKey": {
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "op": {
+                  "const": "set"
+                },
+                "keyId": {
+                  "$ref": "defs.schema.json#/$defs/sha256"
+                },
+                "endpoint": {
+                  "type": "string",
+                  "minLength": 12,
+                  "maxLength": 256,
+                  "pattern": "^https://[A-Za-z0-9]([A-Za-z0-9.-]{0,251}[A-Za-z0-9])?(:[0-9]{1,5})?(/[A-Za-z0-9._~/-]{0,200})?$"
+                },
+                "key": {
+                  "type": "string",
+                  "minLength": 16,
+                  "maxLength": 256,
+                  "pattern": "^[A-Za-z0-9._~+/=-]{16,256}$",
+                  "x-content-class": "secret"
+                },
+                "models": {
+                  "type": "array",
+                  "minItems": 1,
+                  "maxItems": 32,
+                  "uniqueItems": true,
+                  "items": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 96,
+                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,95}$"
+                  }
+                },
+                "expiresAt": {
+                  "$ref": "defs.schema.json#/$defs/ts"
+                }
+              },
+              "required": [
+                "op",
+                "keyId",
+                "endpoint",
+                "key",
+                "models",
+                "expiresAt"
+              ]
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "op": {
+                  "const": "revoke"
+                },
+                "keyId": {
+                  "$ref": "defs.schema.json#/$defs/sha256"
+                }
+              },
+              "required": [
+                "op",
+                "keyId"
+              ]
+            }
+          ]
         }
       },
-      "minProperties": 1
+      "minProperties": 1,
+      "if": {
+        "type": "object",
+        "properties": {
+          "llmKey": true
+        },
+        "required": [
+          "llmKey"
+        ]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "llmKey": true
+        },
+        "maxProperties": 1
+      }
     },
     "seq": {
       "type": "integer",

package/src/la-protocol-v2/contract/hello.schema.json

@@ -94,7 +94,32 @@
         "clockEpochMs",
         "diskFreeBytes",
         "queueDepth"
-      ]
+      ],
+      "if": {
+        "properties": {
+          "capabilities": {
+            "type": "array",
+            "maxItems": 32,
+            "contains": {
+              "const": "llm.key.held"
+            }
+          }
+        },
+        "required": [
+          "capabilities"
+        ]
+      },
+      "then": {
+        "properties": {
+          "capabilities": {
+            "type": "array",
+            "maxItems": 32,
+            "contains": {
+              "const": "llm.key"
+            }
+          }
+        }
+      }
     },
     "seq": {
       "const": 0

package/src/la-protocol-v2/contract/incident.candidate.schema.json

@@ -72,6 +72,17 @@
             "security",
             "other"
           ]
+        },
+        "stackBytes": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 16777216
+        },
+        "model": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 48,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:+-]{0,47}$"
         }
       },
       "required": [