@warmdrift/kgauto-compiler 2.0.0-alpha.54 → 2.0.0-alpha.56

package/dist/brain-proxy.d.mts

@@ -58,6 +58,32 @@
  * must be the base that resolves to `.../api/kgauto/v2` — i.e. the last path
  * segment of each library POST (`outcomes`, `probe_outcomes`, …) is what
  * `handle()` receives as `segment`.
+ *
+ * ## Prefer-header relay (alpha.56)
+ *
+ * `record()` sends `Prefer: return=representation` on its `/outcomes` POST and
+ * parses the inserted row id from the PROXY's response to fire the secondary
+ * `compile_outcome_advisories` POST. alpha.54/.55 hardcoded
+ * `Prefer: return=minimal` toward the brain and returned `{ok:true}` — so the
+ * id-parse found nothing and the advisory secondary silently never fired for
+ * factory-mounted consumers (PB + GE convergent finding, 2026-07-06). The
+ * factory now honors a caller `Prefer: return=representation` header: it is
+ * forwarded to the brain and the brain's response body (the inserted row(s))
+ * is relayed verbatim on success. Callers that don't send the header keep the
+ * `return=minimal` + `{ok:true}` behavior.
+ *
+ * ## Quality-segment handle resolution (alpha.55)
+ *
+ * `recordOutcome()` sends `outcome_id` as `CompileResult.handle` (a string),
+ * but `compile_outcome_quality.outcome_id` is a BIGINT FK →
+ * `compile_outcomes(id)`. A verbatim forward would 400 every handle-shaped
+ * verdict (tt-intel + IC convergent finding, 2026-07-06). On the
+ * `compile_outcome_quality` segment the factory resolves non-numeric
+ * `outcome_id` values to their BIGINT row ids via
+ * `compile_outcomes?handle=eq.<v>` (latest row wins) before forwarding.
+ * Numeric ids pass through untouched; an unresolvable handle returns
+ * `404 handle_not_found` so the library's route-404 observability names the
+ * failure instead of the brain's opaque FK error.
  */
 interface BrainForwardConfig {
     /** Bearer token consumers' callers must present (usually KGAUTO_INGEST_SECRET). */

package/dist/brain-proxy.d.ts

@@ -58,6 +58,32 @@
  * must be the base that resolves to `.../api/kgauto/v2` — i.e. the last path
  * segment of each library POST (`outcomes`, `probe_outcomes`, …) is what
  * `handle()` receives as `segment`.
+ *
+ * ## Prefer-header relay (alpha.56)
+ *
+ * `record()` sends `Prefer: return=representation` on its `/outcomes` POST and
+ * parses the inserted row id from the PROXY's response to fire the secondary
+ * `compile_outcome_advisories` POST. alpha.54/.55 hardcoded
+ * `Prefer: return=minimal` toward the brain and returned `{ok:true}` — so the
+ * id-parse found nothing and the advisory secondary silently never fired for
+ * factory-mounted consumers (PB + GE convergent finding, 2026-07-06). The
+ * factory now honors a caller `Prefer: return=representation` header: it is
+ * forwarded to the brain and the brain's response body (the inserted row(s))
+ * is relayed verbatim on success. Callers that don't send the header keep the
+ * `return=minimal` + `{ok:true}` behavior.
+ *
+ * ## Quality-segment handle resolution (alpha.55)
+ *
+ * `recordOutcome()` sends `outcome_id` as `CompileResult.handle` (a string),
+ * but `compile_outcome_quality.outcome_id` is a BIGINT FK →
+ * `compile_outcomes(id)`. A verbatim forward would 400 every handle-shaped
+ * verdict (tt-intel + IC convergent finding, 2026-07-06). On the
+ * `compile_outcome_quality` segment the factory resolves non-numeric
+ * `outcome_id` values to their BIGINT row ids via
+ * `compile_outcomes?handle=eq.<v>` (latest row wins) before forwarding.
+ * Numeric ids pass through untouched; an unresolvable handle returns
+ * `404 handle_not_found` so the library's route-404 observability names the
+ * failure instead of the brain's opaque FK error.
  */
 interface BrainForwardConfig {
     /** Bearer token consumers' callers must present (usually KGAUTO_INGEST_SECRET). */

package/dist/brain-proxy.js

@@ -45,11 +45,65 @@ function requireString(name, value) {
   }
   return value;
 }
+function isNumericOutcomeId(value) {
+  return typeof value === "number" || typeof value === "string" && /^\d+$/.test(value);
+}
 function createBrainForwardRoutes(config) {
   const ingestSecret = requireString("ingestSecret", config.ingestSecret);
   const brainUrl = requireString("brainUrl", config.brainUrl).replace(/\/+$/, "");
   const serviceKey = requireString("serviceKey", config.serviceKey);
   const fetchFn = config.fetchImpl ?? fetch;
+  async function resolveQualityOutcomeIds(body) {
+    const rows = Array.isArray(body) ? body : [body];
+    const handles = [
+      ...new Set(
+        rows.map((r) => r?.outcome_id).filter(
+          (v) => typeof v === "string" && !isNumericOutcomeId(v)
+        )
+      )
+    ];
+    if (handles.length === 0) return body;
+    const list = handles.map((h) => `"${h.replace(/"/g, "")}"`).join(",");
+    const url = `${brainUrl}/rest/v1/compile_outcomes?select=id,handle&handle=in.(${encodeURIComponent(list)})&order=id.desc`;
+    let idByHandle;
+    try {
+      const res = await fetchFn(url, {
+        headers: { apikey: serviceKey, Authorization: `Bearer ${serviceKey}` }
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "<no body>");
+        return jsonResponse(502, {
+          error: "handle-resolution-failed",
+          table: "compile_outcome_quality",
+          status: res.status,
+          detail: text
+        });
+      }
+      const found = await res.json();
+      idByHandle = /* @__PURE__ */ new Map();
+      for (const r of found) {
+        if (!idByHandle.has(r.handle)) idByHandle.set(r.handle, r.id);
+      }
+    } catch (err) {
+      return jsonResponse(502, {
+        error: "handle-resolution-failed",
+        table: "compile_outcome_quality",
+        detail: err instanceof Error ? err.message : String(err)
+      });
+    }
+    const unresolved = handles.filter((h) => !idByHandle.has(h));
+    if (unresolved.length > 0) {
+      return jsonResponse(404, {
+        error: "handle_not_found",
+        table: "compile_outcome_quality",
+        unresolved
+      });
+    }
+    const rewritten = rows.map(
+      (r) => typeof r?.outcome_id === "string" && idByHandle.has(r.outcome_id) ? { ...r, outcome_id: idByHandle.get(r.outcome_id) } : r
+    );
+    return Array.isArray(body) ? rewritten : rewritten[0];
+  }
   async function handle(req, segment) {
     try {
       if (req.method !== "POST") {
@@ -76,7 +130,15 @@ function createBrainForwardRoutes(config) {
       } catch {
         return jsonResponse(400, { error: "invalid-json" });
       }
-      const row = Array.isArray(body) ? body : { ...body };
+      let row = Array.isArray(body) ? body : { ...body };
+      if (table === "compile_outcome_quality") {
+        const outcome = await resolveQualityOutcomeIds(row);
+        if (outcome instanceof Response) return outcome;
+        row = outcome;
+      }
+      const wantsRepresentation = /return=representation/i.test(
+        req.headers.get("Prefer") ?? ""
+      );
       let brainRes;
       try {
         brainRes = await fetchFn(`${brainUrl}/rest/v1/${table}`, {
@@ -85,7 +147,7 @@ function createBrainForwardRoutes(config) {
             apikey: serviceKey,
             Authorization: `Bearer ${serviceKey}`,
             "Content-Type": "application/json",
-            Prefer: "return=minimal"
+            Prefer: wantsRepresentation ? "return=representation" : "return=minimal"
           },
           body: JSON.stringify(row)
         });
@@ -97,6 +159,12 @@ function createBrainForwardRoutes(config) {
         });
       }
       if (brainRes.ok) {
+        if (wantsRepresentation) {
+          const text2 = await brainRes.text().catch(() => "");
+          if (text2.length > 0) {
+            return new Response(text2, { status: 201, headers: JSON_HEADERS });
+          }
+        }
         return jsonResponse(201, { ok: true });
       }
       const text = await brainRes.text().catch(() => "<no body>");

package/dist/brain-proxy.mjs

@@ -1,6 +1,6 @@
 import {
   createBrainForwardRoutes
-} from "./chunk-NGPB3D53.mjs";
+} from "./chunk-IUWFML6Z.mjs";
 export {
   createBrainForwardRoutes
 };

package/dist/{chunk-NGPB3D53.mjs → chunk-IUWFML6Z.mjs}

@@ -21,11 +21,65 @@ function requireString(name, value) {
   }
   return value;
 }
+function isNumericOutcomeId(value) {
+  return typeof value === "number" || typeof value === "string" && /^\d+$/.test(value);
+}
 function createBrainForwardRoutes(config) {
   const ingestSecret = requireString("ingestSecret", config.ingestSecret);
   const brainUrl = requireString("brainUrl", config.brainUrl).replace(/\/+$/, "");
   const serviceKey = requireString("serviceKey", config.serviceKey);
   const fetchFn = config.fetchImpl ?? fetch;
+  async function resolveQualityOutcomeIds(body) {
+    const rows = Array.isArray(body) ? body : [body];
+    const handles = [
+      ...new Set(
+        rows.map((r) => r?.outcome_id).filter(
+          (v) => typeof v === "string" && !isNumericOutcomeId(v)
+        )
+      )
+    ];
+    if (handles.length === 0) return body;
+    const list = handles.map((h) => `"${h.replace(/"/g, "")}"`).join(",");
+    const url = `${brainUrl}/rest/v1/compile_outcomes?select=id,handle&handle=in.(${encodeURIComponent(list)})&order=id.desc`;
+    let idByHandle;
+    try {
+      const res = await fetchFn(url, {
+        headers: { apikey: serviceKey, Authorization: `Bearer ${serviceKey}` }
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "<no body>");
+        return jsonResponse(502, {
+          error: "handle-resolution-failed",
+          table: "compile_outcome_quality",
+          status: res.status,
+          detail: text
+        });
+      }
+      const found = await res.json();
+      idByHandle = /* @__PURE__ */ new Map();
+      for (const r of found) {
+        if (!idByHandle.has(r.handle)) idByHandle.set(r.handle, r.id);
+      }
+    } catch (err) {
+      return jsonResponse(502, {
+        error: "handle-resolution-failed",
+        table: "compile_outcome_quality",
+        detail: err instanceof Error ? err.message : String(err)
+      });
+    }
+    const unresolved = handles.filter((h) => !idByHandle.has(h));
+    if (unresolved.length > 0) {
+      return jsonResponse(404, {
+        error: "handle_not_found",
+        table: "compile_outcome_quality",
+        unresolved
+      });
+    }
+    const rewritten = rows.map(
+      (r) => typeof r?.outcome_id === "string" && idByHandle.has(r.outcome_id) ? { ...r, outcome_id: idByHandle.get(r.outcome_id) } : r
+    );
+    return Array.isArray(body) ? rewritten : rewritten[0];
+  }
   async function handle(req, segment) {
     try {
       if (req.method !== "POST") {
@@ -52,7 +106,15 @@ function createBrainForwardRoutes(config) {
       } catch {
         return jsonResponse(400, { error: "invalid-json" });
       }
-      const row = Array.isArray(body) ? body : { ...body };
+      let row = Array.isArray(body) ? body : { ...body };
+      if (table === "compile_outcome_quality") {
+        const outcome = await resolveQualityOutcomeIds(row);
+        if (outcome instanceof Response) return outcome;
+        row = outcome;
+      }
+      const wantsRepresentation = /return=representation/i.test(
+        req.headers.get("Prefer") ?? ""
+      );
       let brainRes;
       try {
         brainRes = await fetchFn(`${brainUrl}/rest/v1/${table}`, {
@@ -61,7 +123,7 @@ function createBrainForwardRoutes(config) {
             apikey: serviceKey,
             Authorization: `Bearer ${serviceKey}`,
             "Content-Type": "application/json",
-            Prefer: "return=minimal"
+            Prefer: wantsRepresentation ? "return=representation" : "return=minimal"
           },
           body: JSON.stringify(row)
         });
@@ -73,6 +135,12 @@ function createBrainForwardRoutes(config) {
         });
       }
       if (brainRes.ok) {
+        if (wantsRepresentation) {
+          const text2 = await brainRes.text().catch(() => "");
+          if (text2.length > 0) {
+            return new Response(text2, { status: 201, headers: JSON_HEADERS });
+          }
+        }
         return jsonResponse(201, { ok: true });
       }
       const text = await brainRes.text().catch(() => "<no body>");

package/dist/index.d.mts

@@ -317,7 +317,10 @@ interface CompileForAISDKv6Result {
     /**
      * Index (into post-strip history) for the Anthropic history cache marker
      * (alpha.33). Mirror of `result.diagnostics.historyCacheMarkIndex` — no
-     * consumer re-derivation needed. Undefined when no marker fires.
+     * consumer re-derivation needed. Undefined when no marker fires, and (since
+     * alpha.55) always undefined for non-Anthropic targets: the marker is an
+     * Anthropic wire concept, other providers cache prefixes implicitly. The
+     * ungated value remains on `diagnostics.historyCacheMarkIndex`.
      */
     historyCacheMarkIndex?: number;
     /** Compile handle — pass to `record()` after the call. */

package/dist/index.d.ts

@@ -317,7 +317,10 @@ interface CompileForAISDKv6Result {
     /**
      * Index (into post-strip history) for the Anthropic history cache marker
      * (alpha.33). Mirror of `result.diagnostics.historyCacheMarkIndex` — no
-     * consumer re-derivation needed. Undefined when no marker fires.
+     * consumer re-derivation needed. Undefined when no marker fires, and (since
+     * alpha.55) always undefined for non-Anthropic targets: the marker is an
+     * Anthropic wire concept, other providers cache prefixes implicitly. The
+     * ungated value remains on `diagnostics.historyCacheMarkIndex`.
      */
     historyCacheMarkIndex?: number;
     /** Compile handle — pass to `record()` after the call. */

package/dist/index.js

@@ -6734,7 +6734,12 @@ function compileForAISDKv6(ir, opts) {
     },
     keptToolNames,
     ...providerOptions ? { providerOptions } : {},
-    ...result.diagnostics.historyCacheMarkIndex !== void 0 ? { historyCacheMarkIndex: result.diagnostics.historyCacheMarkIndex } : {},
+    // Provider-gated (alpha.55, IC finding): the marker is an Anthropic
+    // concept — Gemini/OpenAI/DeepSeek cache prefixes implicitly, and a
+    // consumer attaching Anthropic providerOptions at this index on a
+    // non-Anthropic call would ship a no-op-at-best marker. The ungated value
+    // stays on diagnostics.historyCacheMarkIndex for observability.
+    ...result.provider === "anthropic" && result.diagnostics.historyCacheMarkIndex !== void 0 ? { historyCacheMarkIndex: result.diagnostics.historyCacheMarkIndex } : {},
     mutationsApplied: result.mutationsApplied.map((m) => m.id),
     advisories: result.advisories ?? [],
     diagnostics,
@@ -6785,11 +6790,65 @@ function requireString(name, value) {
   }
   return value;
 }
+function isNumericOutcomeId(value) {
+  return typeof value === "number" || typeof value === "string" && /^\d+$/.test(value);
+}
 function createBrainForwardRoutes(config) {
   const ingestSecret = requireString("ingestSecret", config.ingestSecret);
   const brainUrl = requireString("brainUrl", config.brainUrl).replace(/\/+$/, "");
   const serviceKey = requireString("serviceKey", config.serviceKey);
   const fetchFn = config.fetchImpl ?? fetch;
+  async function resolveQualityOutcomeIds(body) {
+    const rows = Array.isArray(body) ? body : [body];
+    const handles = [
+      ...new Set(
+        rows.map((r) => r?.outcome_id).filter(
+          (v) => typeof v === "string" && !isNumericOutcomeId(v)
+        )
+      )
+    ];
+    if (handles.length === 0) return body;
+    const list = handles.map((h) => `"${h.replace(/"/g, "")}"`).join(",");
+    const url = `${brainUrl}/rest/v1/compile_outcomes?select=id,handle&handle=in.(${encodeURIComponent(list)})&order=id.desc`;
+    let idByHandle;
+    try {
+      const res = await fetchFn(url, {
+        headers: { apikey: serviceKey, Authorization: `Bearer ${serviceKey}` }
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "<no body>");
+        return jsonResponse(502, {
+          error: "handle-resolution-failed",
+          table: "compile_outcome_quality",
+          status: res.status,
+          detail: text
+        });
+      }
+      const found = await res.json();
+      idByHandle = /* @__PURE__ */ new Map();
+      for (const r of found) {
+        if (!idByHandle.has(r.handle)) idByHandle.set(r.handle, r.id);
+      }
+    } catch (err) {
+      return jsonResponse(502, {
+        error: "handle-resolution-failed",
+        table: "compile_outcome_quality",
+        detail: err instanceof Error ? err.message : String(err)
+      });
+    }
+    const unresolved = handles.filter((h) => !idByHandle.has(h));
+    if (unresolved.length > 0) {
+      return jsonResponse(404, {
+        error: "handle_not_found",
+        table: "compile_outcome_quality",
+        unresolved
+      });
+    }
+    const rewritten = rows.map(
+      (r) => typeof r?.outcome_id === "string" && idByHandle.has(r.outcome_id) ? { ...r, outcome_id: idByHandle.get(r.outcome_id) } : r
+    );
+    return Array.isArray(body) ? rewritten : rewritten[0];
+  }
   async function handle(req, segment) {
     try {
       if (req.method !== "POST") {
@@ -6816,7 +6875,15 @@ function createBrainForwardRoutes(config) {
       } catch {
         return jsonResponse(400, { error: "invalid-json" });
       }
-      const row = Array.isArray(body) ? body : { ...body };
+      let row = Array.isArray(body) ? body : { ...body };
+      if (table === "compile_outcome_quality") {
+        const outcome = await resolveQualityOutcomeIds(row);
+        if (outcome instanceof Response) return outcome;
+        row = outcome;
+      }
+      const wantsRepresentation = /return=representation/i.test(
+        req.headers.get("Prefer") ?? ""
+      );
       let brainRes;
       try {
         brainRes = await fetchFn(`${brainUrl}/rest/v1/${table}`, {
@@ -6825,7 +6892,7 @@ function createBrainForwardRoutes(config) {
             apikey: serviceKey,
             Authorization: `Bearer ${serviceKey}`,
             "Content-Type": "application/json",
-            Prefer: "return=minimal"
+            Prefer: wantsRepresentation ? "return=representation" : "return=minimal"
           },
           body: JSON.stringify(row)
         });
@@ -6837,6 +6904,12 @@ function createBrainForwardRoutes(config) {
         });
       }
       if (brainRes.ok) {
+        if (wantsRepresentation) {
+          const text2 = await brainRes.text().catch(() => "");
+          if (text2.length > 0) {
+            return new Response(text2, { status: 201, headers: JSON_HEADERS });
+          }
+        }
         return jsonResponse(201, { ok: true });
       }
       const text = await brainRes.text().catch(() => "<no body>");

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import {
   createBrainForwardRoutes
-} from "./chunk-NGPB3D53.mjs";
+} from "./chunk-IUWFML6Z.mjs";
 import {
   ALL_ARCHETYPES,
   DIALECT_VERSION,
@@ -4175,7 +4175,12 @@ function compileForAISDKv6(ir, opts) {
     },
     keptToolNames,
     ...providerOptions ? { providerOptions } : {},
-    ...result.diagnostics.historyCacheMarkIndex !== void 0 ? { historyCacheMarkIndex: result.diagnostics.historyCacheMarkIndex } : {},
+    // Provider-gated (alpha.55, IC finding): the marker is an Anthropic
+    // concept — Gemini/OpenAI/DeepSeek cache prefixes implicitly, and a
+    // consumer attaching Anthropic providerOptions at this index on a
+    // non-Anthropic call would ship a no-op-at-best marker. The ungated value
+    // stays on diagnostics.historyCacheMarkIndex for observability.
+    ...result.provider === "anthropic" && result.diagnostics.historyCacheMarkIndex !== void 0 ? { historyCacheMarkIndex: result.diagnostics.historyCacheMarkIndex } : {},
     mutationsApplied: result.mutationsApplied.map((m) => m.id),
     advisories: result.advisories ?? [],
     diagnostics,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmdrift/kgauto-compiler",
-  "version": "2.0.0-alpha.54",
+  "version": "2.0.0-alpha.56",
   "description": "Prompt compiler + central learning brain for multi-model AI apps. Swap models without rewriting prompts.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",