@konneal/engine 0.2.32 → 0.2.34

package/dist/apicalls.d.ts

@@ -0,0 +1,72 @@
+import { type DeclaredContext } from "./context.ts";
+export interface ApiCall {
+    method: "POST" | "PUT" | "PATCH" | "DELETE" | "GET";
+    path: string;
+    body?: unknown;
+}
+export interface ApiCallDraft {
+    kind: "draft";
+    act: "api_call";
+    version: 1;
+    title: string;
+    prepared_at: string;
+    /** ALWAYS true — the card's tap (or the standing grant, for the
+     *  preference family) is the only authority that executes. */
+    requires_confirmation: true;
+    call: ApiCall;
+    notes?: string[];
+}
+export type ApiCallRefusalReason = "sign_in_required" | "machine_read_only" | "no_matching_act" | "entity_unresolved" | "operation_unknown" | "operation_never_offered" | "body_untraced" | "pick_failed";
+export type ApiCallVerdict = {
+    status: "draft";
+    draft: ApiCallDraft;
+    answer: string;
+} | {
+    status: "refused";
+    reason: ApiCallRefusalReason;
+    answer: string;
+};
+/** A target the assistant never proposes: the never-offer prefixes match
+ *  the operation's declared (templated) path. */
+export declare function neverOffered(path: string): boolean;
+export interface ApiOp {
+    operation_id: string;
+    method: string;
+    path: string;
+    act_class: string | null;
+    summary: string | null;
+    tag: string | null;
+}
+/** Parse the declared context's route against the profile's entity-route
+ *  patterns (`/a/b/:id` segments; the LAST parameter captures the entity
+ *  id). Returns the store + id the entity write addresses, or null — a
+ *  route the table does not cover is an honest unresolved, never a guess. */
+export declare function resolveEntityRoute(route: string | undefined): {
+    store: string;
+    id: string;
+} | null;
+export type ApiCallIntent = "machine_act" | "preference";
+/** Which api_call family the ask aims at, or null. The machine facet
+ *  decides the machine family (no facet = no machine act, whatever the
+ *  verbs); the preference family needs no facet. */
+export declare function detectApiCallIntent(query: string, declared: DeclaredContext | null): ApiCallIntent | null;
+/** The body guard: every string value traces to the user's own words
+ *  (the never-invents doctrine, drafts.ts's primitive). Scalars the user
+ *  toggles (booleans, numbers) pass — they state no fact. */
+export declare function bodyTraces(body: unknown, userTurns: string[]): boolean;
+export interface ApiCallPrepareOpts {
+    intent: ApiCallIntent;
+    query: string;
+    history: Array<{
+        role: string;
+        content: string;
+    }>;
+    member: {
+        sub: string;
+    } | null;
+    declared: DeclaredContext | null;
+    /** the intent-mapping model (the profile's pick — the operations
+     *  deployment runs the stronger reasoning tier here) */
+    model: string;
+}
+export declare function prepareApiCall(env: any, opts: ApiCallPrepareOpts): Promise<ApiCallVerdict>;

package/dist/ask-BDD5TFNC.js

@@ -0,0 +1,12 @@
+import {
+  handleAsk
+} from "./chunk-MHA2OFWE.js";
+import "./chunk-DADOI4Q6.js";
+import "./chunk-R2V3X6SQ.js";
+import "./chunk-A3QHHUN5.js";
+import "./chunk-4GJGBGJK.js";
+import "./chunk-V46XM2GU.js";
+import "./chunk-3FYJM7LH.js";
+export {
+  handleAsk
+};

package/dist/{chunk-JGKSUSF5.js → chunk-4GJGBGJK.js}

@@ -1,7 +1,7 @@
 import {
   DATASETS,
   datasetAllowed
-} from "./chunk-OMXAE27N.js";
+} from "./chunk-V46XM2GU.js";
 import {
   P
 } from "./chunk-3FYJM7LH.js";
@@ -20,13 +20,13 @@ function standardKeysFrom(body) {
 function entitlementScope(keys) {
   return licenseDeclared() ? keys : null;
 }
-function resolveRequestScope(body, member) {
+function resolveRequestScope(body, member, opts) {
   const allIds = DATASETS().map((d) => d.id);
   const requested = Array.isArray(body?.datasets) ? body.datasets.filter((x) => typeof x === "string" && allIds.includes(x)) : null;
   if (requested !== null && requested.length === 0) return { error: "empty-datasets" };
   const permittedIds = allIds.filter((id) => {
     const d = DATASETS().find((x) => x.id === id);
-    return d.session ? datasetAllowed(d, member) : true;
+    return d.session ? datasetAllowed(d, member) || !!opts?.keyWithEntitlements : true;
   });
   const scopeIds = (requested ?? permittedIds).filter((id) => permittedIds.includes(id));
   const corpora = /* @__PURE__ */ new Set();

package/dist/{chunk-F66NYFUK.js → chunk-DADOI4Q6.js}

@@ -1,7 +1,7 @@
 import {
   bubbleConfirmPage,
   isAllowedBubbleOrigin
-} from "./chunk-2RKYO3OC.js";
+} from "./chunk-R2V3X6SQ.js";
 import {
   DATASETS,
   LIMITS,
@@ -12,7 +12,7 @@ import {
   processExpansion,
   sha256Hex,
   today
-} from "./chunk-OMXAE27N.js";
+} from "./chunk-V46XM2GU.js";
 import {
   P
 } from "./chunk-3FYJM7LH.js";
@@ -21952,6 +21952,27 @@ function refCodec() {
 
 // workers/worker_public/src/context.ts
 var NO_CONTEXT = { kind: "none", scoped_to: null };
+var MACHINE_STATE_MAX = 60;
+var MACHINE_ACT_MAX = 24;
+var MACHINE_FIELD_MAX = 60;
+function parseMachine(v) {
+  if (!v || typeof v !== "object") return void 0;
+  const state = typeof v.state === "string" ? v.state.trim().slice(0, MACHINE_STATE_MAX) : "";
+  if (!state) return void 0;
+  const acts = [];
+  for (const a of Array.isArray(v.acts) ? v.acts.slice(0, MACHINE_ACT_MAX) : []) {
+    const action = typeof a?.action === "string" ? a.action.trim().slice(0, MACHINE_FIELD_MAX) : "";
+    const to = typeof a?.to === "string" ? a.to.trim().slice(0, MACHINE_FIELD_MAX) : "";
+    if (!action || !to) continue;
+    const guard = typeof a?.guard === "string" && a.guard.trim() ? a.guard.trim().slice(0, MACHINE_FIELD_MAX) : void 0;
+    acts.push({ action, to, ...guard ? { guard } : {} });
+  }
+  return { state, acts };
+}
+function machineOffers(machine, action) {
+  if (!machine) return false;
+  return machine.acts.some((a) => a.action === action);
+}
 function parseContext(body) {
   const c = body?.context;
   if (!c || typeof c !== "object") return null;
@@ -21960,7 +21981,8 @@ function parseContext(body) {
   const route = typeof c.route === "string" && c.route.trim() ? c.route.trim().slice(0, 200) : void 0;
   const doc = typeof c.doc === "string" && c.doc.trim() ? c.doc.trim().slice(0, 80) : void 0;
   const edition = typeof c.edition === "string" && /^\d{4}$/.test(c.edition.trim()) ? c.edition.trim() : void 0;
-  return { kind: c.kind, label, ...route ? { route } : {}, ...doc ? { doc } : {}, ...edition ? { edition } : {} };
+  const machine = c.kind === "entity" ? parseMachine(c.machine) : void 0;
+  return { kind: c.kind, label, ...route ? { route } : {}, ...doc ? { doc } : {}, ...edition ? { edition } : {}, ...machine ? { machine } : {} };
 }
 function parseDocRef(doc, edition) {
   return refCodec().parse(doc, edition);
@@ -21987,7 +22009,11 @@ function appliedContext(declared, scope, note, live) {
     label: declared.label,
     scoped_to: scope ? scope.label : null,
     ...note ? { note } : {},
-    ...live ? { live } : {}
+    ...live ? { live } : {},
+    // the affordance echo (TODO.ai-platform/08): the machine's state +
+    // the offered-act COUNT (the acts themselves are the platform's
+    // vocabulary, echoed back only bounded on the draft path)
+    ...declared.machine ? { machine: { state: declared.machine.state, offered: declared.machine.acts.length } } : {}
   };
 }
 function parseAppliedContext(v) {
@@ -22003,7 +22029,8 @@ function parseAppliedContext(v) {
     standard: v.model.standard.slice(0, 40),
     ...typeof v.model.clause === "string" && v.model.clause.trim() ? { clause: v.model.clause.slice(0, 120) } : {}
   } : void 0;
-  return { kind: v.kind, ...label ? { label } : {}, scoped_to: scoped, ...note ? { note } : {}, ...live ? { live } : {}, ...model ? { model } : {} };
+  const machine = v.machine && typeof v.machine === "object" && typeof v.machine.state === "string" && typeof v.machine.offered === "number" ? { state: v.machine.state.slice(0, MACHINE_STATE_MAX), offered: Math.min(Math.max(0, Math.floor(v.machine.offered)), MACHINE_ACT_MAX) } : void 0;
+  return { kind: v.kind, ...label ? { label } : {}, scoped_to: scoped, ...note ? { note } : {}, ...live ? { live } : {}, ...model ? { model } : {}, ...machine ? { machine } : {} };
 }
 function contextNote(declared, scope) {
   if (!declared) return void 0;
@@ -22014,7 +22041,8 @@ function contextNote(declared, scope) {
     return `Context note: the user is viewing ${declared.label || "a page"}${declared.route ? ` (${declared.route})` : ""} in the ${P().publisher.product_name} platform. The passages come from the general corpus; frame procedural guidance for that page when relevant.`;
   }
   if (declared.kind === "entity") {
-    return scope ? `Context note: the user is asking about ${declared.label || "an entity"} \u2014 the passages are scoped to ${scope.label}, the publication that governs it. You do NOT have the entity's own data; answer what the publication requires and say when the question needs the record itself.` : `Context note: the user is asking about ${declared.label || "an entity"}. You do NOT have the entity's own data; answer from the corpus passages and say when the question needs the record itself.`;
+    const machineSentence = declared.machine ? declared.machine.acts.length ? ` The entity's lifecycle machine is at ${declared.machine.state}; the acts it offers this user's role there are exactly: ${declared.machine.acts.map((a) => a.action).join(", ")}. Never propose an act outside that set.` : ` The entity's lifecycle machine is at ${declared.machine.state}, and it offers this user's role NO acts there \u2014 the user can read but not act; say so when they ask for an act, and propose nothing.` : "";
+    return scope ? `Context note: the user is asking about ${declared.label || "an entity"} \u2014 the passages are scoped to ${scope.label}, the publication that governs it. You do NOT have the entity's own data; answer what the publication requires and say when the question needs the record itself.${machineSentence}` : `Context note: the user is asking about ${declared.label || "an entity"}. You do NOT have the entity's own data; answer from the corpus passages and say when the question needs the record itself.${machineSentence}`;
   }
   return scope ? `Context note: the user scoped this question to ${scope.label} \u2014 the passages come from that publication. If they cannot answer the question, say so instead of drawing on other documents.` : `Context note: the user named ${declared.label || declared.doc || "a document"} as context, but it is not in the indexed corpus \u2014 answer from the general corpus and say the document was not found.`;
 }
@@ -22153,6 +22181,9 @@ function cfVectorIndex(index) {
     }
   };
 }
+function cfStore(db) {
+  return db;
+}
 
 // workers/worker_public/src/env.ts
 function portModelRunner(env) {
@@ -22162,6 +22193,9 @@ function portIndex(env, which = "public") {
   const b = which === "public" ? env.VECTORIZE : which === "primmel" ? env.EXP_PRIMMEL : which === "composed" ? env.EXP_COMPOSED : which === "plain" ? env.EXP_PLAIN : which === "adoc" ? env.EXP_ADC : which === "mko" ? env.EXP_MKO : which === "pflat" ? env.EXP_PFLAT : env.GLOSSARY;
   return cfVectorIndex(b);
 }
+function portStore(env) {
+  return cfStore(env.DB);
+}
 function hasLane(env, which) {
   switch (which) {
     case "glossary":
@@ -24373,8 +24407,8 @@ function telemetry(env, ctx, tier, route, model, ok, answerChars, queryHash, lan
   ctx.waitUntil(
     env.DB.batch([
       env.DB.prepare(
-        "INSERT INTO queries (ts, day, tier, route, model, ok, answer_chars, query_hash, lang, cache, duration_ms, key_id) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9,?10,?11,?12)"
-      ).bind((/* @__PURE__ */ new Date()).toISOString(), day, tier, route, model, ok ? 1 : 0, answerChars, queryHash, lang ?? null, cache ?? null, meta?.durationMs ?? null, meta?.keyId ?? null),
+        "INSERT INTO queries (ts, day, tier, route, model, ok, answer_chars, query_hash, lang, cache, duration_ms, key_id, retries) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9,?10,?11,?12,?13)"
+      ).bind((/* @__PURE__ */ new Date()).toISOString(), day, tier, route, model, ok ? 1 : 0, answerChars, queryHash, lang ?? null, cache ?? null, meta?.durationMs ?? null, meta?.keyId ?? null, meta?.retries ?? 0),
       env.DB.prepare(
         "INSERT INTO spend (day, tier, model, requests) VALUES (?1,?2,?3,1) ON CONFLICT(day, tier, model) DO UPDATE SET requests = requests + 1"
       ).bind(day, tier, model ?? "none")
@@ -24426,6 +24460,7 @@ export {
   ftsMatchQuery,
   refCodec,
   NO_CONTEXT,
+  machineOffers,
   parseContext,
   namedDocumentIn,
   resolveDocScope,
@@ -24434,6 +24469,7 @@ export {
   contextNote,
   syntheticUnderstanding,
   portModelRunner,
+  portStore,
   promptVars,
   fill,
   retrievalQuery,

package/dist/{chunk-TDKNQPA2.js → chunk-MHA2OFWE.js}

@@ -14,9 +14,11 @@ import {
   identityNote,
   listwiseRerank,
   liveDataConfig,
+  machineOffers,
   namedDocumentIn,
   parseContext,
   portModelRunner,
+  portStore,
   rawSessionToken,
   refCodec,
   resolveDocScope,
@@ -28,14 +30,14 @@ import {
   syntheticUnderstanding,
   telemetry,
   understandQuery
-} from "./chunk-F66NYFUK.js";
+} from "./chunk-DADOI4Q6.js";
 import {
   corsHeaders,
   err,
   json,
   readJson,
   validateQuery
-} from "./chunk-2RKYO3OC.js";
+} from "./chunk-R2V3X6SQ.js";
 import {
   canonicalRefusal,
   refusalAnswer
@@ -43,8 +45,9 @@ import {
 import {
   entitlementScope,
   requestSalt,
-  resolveRequestScope
-} from "./chunk-JGKSUSF5.js";
+  resolveRequestScope,
+  standardKeysFrom
+} from "./chunk-4GJGBGJK.js";
 import {
   LIMITS,
   MODELS,
@@ -54,7 +57,7 @@ import {
   requestEffort,
   roleModel,
   sha256Hex
-} from "./chunk-OMXAE27N.js";
+} from "./chunk-V46XM2GU.js";
 import {
   P
 } from "./chunk-3FYJM7LH.js";
@@ -1196,6 +1199,11 @@ ${transcript}` }
 }
 var norm = (s) => s.toLowerCase().replace(/[^a-z0-9-]+/g, " ").replace(/\s+/g, " ").trim();
 var docNorm = (s) => norm(s).replace(/\s+/g, "");
+function valueTracesToUser(value, userTurns) {
+  if (typeof value !== "string" || !value.trim()) return false;
+  const haystack = norm(userTurns.join("\n"));
+  return haystack.includes(norm(value));
+}
 var DROP_REASON = "not stated in your own words";
 function traceabilityGuard(extraction, userTurns) {
   const haystack = norm(userTurns.join("\n"));
@@ -1385,6 +1393,263 @@ The draft opens in the real application form with every field editable \u2014 re
   };
 }
 
+// workers/worker_public/src/apicalls.ts
+function actsProfile() {
+  const acts = P().publisher?.acts;
+  return acts && typeof acts === "object" ? acts : null;
+}
+function neverOffered(path) {
+  const prefixes = actsProfile()?.never_offer ?? [];
+  return prefixes.some((p) => typeof p === "string" && path.startsWith(p));
+}
+async function operationById(store, id) {
+  try {
+    return await store.prepare("SELECT operation_id, method, path, act_class, summary, tag FROM api_ops WHERE operation_id = ?1").bind(id).first();
+  } catch {
+    return null;
+  }
+}
+async function operationByMethodPath(store, method, path) {
+  try {
+    return await store.prepare("SELECT operation_id, method, path, act_class, summary, tag FROM api_ops WHERE method = ?1 AND path = ?2").bind(method.toLowerCase(), path).first();
+  } catch {
+    return null;
+  }
+}
+async function preferenceOps(store) {
+  try {
+    const rows = await store.prepare("SELECT operation_id, method, path, act_class, summary, tag FROM api_ops WHERE act_class = 'preference' ORDER BY operation_id LIMIT 32").bind().all();
+    return rows.results ?? [];
+  } catch {
+    return [];
+  }
+}
+function resolveEntityRoute(route) {
+  const patterns = actsProfile()?.entity_routes ?? [];
+  if (!route) return null;
+  const segs = route.split("?")[0].split("/").filter(Boolean);
+  for (const p of patterns) {
+    const psegs = String(p.pattern ?? "").split("/").filter(Boolean);
+    if (psegs.length !== segs.length) continue;
+    let id = null;
+    let ok = true;
+    for (let i = 0; i < psegs.length; i++) {
+      const ps = psegs[i];
+      if (ps.startsWith(":")) {
+        id = decodeURIComponent(segs[i]);
+      } else if (ps !== segs[i]) {
+        ok = false;
+        break;
+      }
+    }
+    if (ok && id && id.length <= 120 && /^[A-Za-z0-9._~-]+$/.test(id)) return { store: String(p.store), id };
+  }
+  return null;
+}
+var MACHINE_INTENT_RE = /\b(accept|reject|submit|resubmit|withdraw|suspend|reinstate|renew|revise|transfer|issue|register|log|record|dispatch|complete|sign|approve|verify)\b[\s\S]{0,40}\b(this|that|the|it)\b|\b(this|that|the|it)\b[\s\S]{0,40}\b(accept|reject|submit|resubmit|withdraw|suspend|reinstate|renew|revise|transfer|issue|register|log|dispatch|complete|sign|approve|verify)\b/i;
+var PREFERENCE_INTENT_RE = /\b(mute|unmute|unsubscribe|subscribe|notification prefs?|notification rules?|email prefs?|email preferences|saved? filters?|save (?:this|the|that) filter|notify me|stop notifying|inbox)\b/i;
+var QUESTION_OPENER_RE = /^\s*(?:what|how|why|where|when|which|who|whose|explain|describe|define|is|are|does|do)\b/i;
+function detectApiCallIntent(query, declared) {
+  if (QUESTION_OPENER_RE.test(query)) return null;
+  if (declared?.kind === "entity" && declared.machine && MACHINE_INTENT_RE.test(query)) return "machine_act";
+  if (PREFERENCE_INTENT_RE.test(query)) return "preference";
+  return null;
+}
+function pickPrompt(kind, candidates) {
+  if (kind === "machine_act") {
+    return {
+      system: `You map the user's request to one machine act from the OFFERED list, or to none.
+
+Rules:
+- Output ONLY a JSON object \u2014 no prose, no code fence: {"target": "<action id or null>", "title": "<what the act does, plain words>"}.
+- The target must be one of the offered action ids, copied exactly, or null when the request matches none.
+- The title names what the act DOES for the user ("Accept the application"), never the wire (no method, no path, no "/api/").
+- Never invent an act that is not listed.
+
+Offered acts (action id \u2014 lands the entity on):
+${candidates.join("\n")}`,
+      max: 300
+    };
+  }
+  return {
+    system: `You map the user's request to one operation from the PREFERENCE list (the user's own settings), or to none.
+
+Rules:
+- Output ONLY a JSON object \u2014 no prose, no code fence: {"target": "<operation id or null>", "title": "<what the act does, plain words>", "body": {...}}.
+- The target must be one of the listed operation ids, copied exactly, or null when the request matches none.
+- "body" carries only values the user stated in their own words; omit it when the request names no values.
+- The title names what the act DOES for the user ("Save the filter", "Mute these emails"), never the wire (no method, no path, no "/api/").
+- Never invent an operation that is not listed.
+
+Preference operations (id \u2014 method path \u2014 summary):
+${candidates.join("\n")}`,
+    max: 800
+  };
+}
+async function pickTarget(runner, model, kind, candidates, userTurns) {
+  const { system, max } = pickPrompt(kind, candidates);
+  const transcript = userTurns.map((t, i) => `${i + 1}. ${t}`).join("\n").slice(0, 8e3);
+  try {
+    const res = await runner.run({
+      model,
+      messages: [
+        { role: "system", content: system },
+        { role: "user", content: `The user's messages, oldest first:
+${transcript}` }
+      ],
+      maxTokens: max,
+      effort: "low",
+      temperature: 0.1
+    });
+    const text = res.text;
+    if (typeof text !== "string") return null;
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start < 0 || end <= start) return null;
+    const parsed = JSON.parse(text.slice(start, end + 1));
+    if (!parsed || typeof parsed !== "object") return null;
+    return {
+      target: typeof parsed.target === "string" && parsed.target.trim() ? parsed.target.trim().slice(0, 120) : null,
+      title: typeof parsed.title === "string" && parsed.title.trim() ? parsed.title.trim().slice(0, 120) : void 0,
+      body: parsed.body && typeof parsed.body === "object" ? parsed.body : void 0
+    };
+  } catch {
+    return null;
+  }
+}
+function honestTitle(proposed, fallback) {
+  const t = (proposed ?? "").trim();
+  if (!t) return fallback;
+  if (/\b(GET|POST|PUT|PATCH|DELETE)\b/.test(t) || t.includes("/api/") || t.includes("{")) return fallback;
+  return t.slice(0, 120);
+}
+function bodyTraces(body, userTurns) {
+  if (body == null) return true;
+  if (typeof body === "boolean" || typeof body === "number") return true;
+  if (typeof body === "string") return valueTracesToUser(body, userTurns);
+  if (Array.isArray(body)) return body.every((v) => bodyTraces(v, userTurns));
+  if (typeof body === "object") return Object.values(body).every((v) => bodyTraces(v, userTurns));
+  return false;
+}
+function refusal2(reason, answer) {
+  return { status: "refused", reason, answer };
+}
+async function prepareApiCall(env, opts) {
+  if (!opts.member) {
+    return refusal2(
+      "sign_in_required",
+      "Preparing an act starts from your own account \u2014 sign in and ask again. The draft would still be yours alone: the card asks for your confirmation, and only your own tap executes it \u2014 I never hold a write credential."
+    );
+  }
+  const acts = actsProfile();
+  const store = portStore(env);
+  const runner = portModelRunner(env);
+  const userTurns = [...opts.history.filter((h) => h.role === "user").map((h) => h.content), opts.query];
+  if (opts.intent === "machine_act") {
+    const machine = opts.declared?.machine;
+    const label = opts.declared?.label || "this record";
+    if (!machine) {
+      return refusal2("no_matching_act", "This page did not declare the record's lifecycle state, so I cannot propose an act on it honestly. Open the record itself and ask again, or act from the platform's own controls \u2014 they always show exactly what your role may do.");
+    }
+    if (machine.acts.length === 0) {
+      return refusal2(
+        "machine_read_only",
+        `The record's lifecycle is at ${machine.state}, and the machine offers your role no acts there \u2014 you can read this record but not act on it. Nothing was drafted. If that looks wrong, an officer of your organization can check the role your account carries.`
+      );
+    }
+    const entity = resolveEntityRoute(opts.declared?.route);
+    if (!entity) {
+      return refusal2("entity_unresolved", "I cannot tell which record the act would land on from this page, so nothing was drafted. The platform's own controls on the record always act on the right one.");
+    }
+    const candidates2 = machine.acts.map((a) => `${a.action} \u2014 lands on ${a.to}${a.guard ? ` (requires ${a.guard})` : ""}`);
+    const pick2 = await pickTarget(runner, opts.model, "machine_act", candidates2, userTurns);
+    if (!pick2) {
+      return refusal2("pick_failed", "I could not map your request to an act reliably just now \u2014 nothing was drafted. Ask again in a moment, or act from the platform's own controls.");
+    }
+    if (!pick2.target || !machineOffers(machine, pick2.target)) {
+      const offered = machine.acts.map((a) => a.action).join(", ");
+      return refusal2(
+        "no_matching_act",
+        `None of the acts the machine offers your role at ${machine.state} matches that request \u2014 the offered set is exactly: ${offered}. I never propose an act outside it. Nothing was drafted.`
+      );
+    }
+    const act = machine.acts.find((a) => a.action === pick2.target);
+    const write = acts?.entity_write;
+    if (!write?.method || !write?.path) {
+      return refusal2("operation_unknown", "This deployment has not wired the entity write operation, so I cannot prepare the act here.");
+    }
+    const op2 = await operationByMethodPath(store, write.method, write.path);
+    if (!op2) {
+      return refusal2("operation_unknown", "The act's operation is not in this deployment's API directory, so I cannot prepare it honestly \u2014 nothing was drafted.");
+    }
+    if (neverOffered(op2.path)) {
+      return refusal2("operation_never_offered", "That act is not one the assistant may propose \u2014 nothing was drafted.");
+    }
+    const path = write.path.replace("{store}", entity.store).replace("{id}", entity.id);
+    const title2 = honestTitle(pick2.title, `${act.action} \u2014 ${label}`.slice(0, 120));
+    const notes = [
+      `The machine act ${act.action} moves the record from ${machine.state} to ${act.to}; the platform re-judges the act against the machine and your role when you confirm.`,
+      ...act.guard ? [`This act declares the ${act.guard} input \u2014 the confirmation card collects it; the draft carries none.`] : []
+    ];
+    const draft2 = {
+      kind: "draft",
+      act: "api_call",
+      version: 1,
+      title: title2,
+      prepared_at: (/* @__PURE__ */ new Date()).toISOString(),
+      requires_confirmation: true,
+      call: { method: write.method, path, body: { status: act.to } },
+      notes
+    };
+    const answer2 = `I've prepared the act "${title2}" for ${label}: the machine act ${act.action}, from ${machine.state} to ${act.to}.
+
+The confirmation card carries it \u2014 a record act, so your own confirmation signs it and the platform's gates judge the write as you. I never hold a write credential, and I never propose an act the machine does not offer your role.`;
+    return { status: "draft", draft: draft2, answer: answer2 };
+  }
+  const family = (await preferenceOps(store)).filter((o) => !neverOffered(o.path));
+  if (!family.length) {
+    return refusal2("operation_unknown", "This deployment's API directory lists no preference operations, so I cannot prepare that here \u2014 nothing was drafted.");
+  }
+  const candidates = family.map((o) => `${o.operation_id} \u2014 ${o.method.toUpperCase()} ${o.path} \u2014 ${o.summary ?? ""}`.slice(0, 300));
+  const pick = await pickTarget(runner, opts.model, "preference", candidates, userTurns);
+  if (!pick) {
+    return refusal2("pick_failed", "I could not map your request to a preference act reliably just now \u2014 nothing was drafted. Ask again in a moment, or change the setting on your account page directly.");
+  }
+  if (!pick.target) {
+    return refusal2("no_matching_act", "None of the preference acts I may propose matches that request \u2014 nothing was drafted. Your account's settings page carries the full set.");
+  }
+  const op = await operationById(store, pick.target);
+  if (!op || op.act_class !== "preference") {
+    return refusal2("operation_unknown", "I cannot match that request to a preference act the platform declares \u2014 nothing was drafted.");
+  }
+  if (neverOffered(op.path)) {
+    return refusal2("operation_never_offered", "That act is not one the assistant may propose \u2014 delegation and sign-in acts stay in your own hands on the settings page. Nothing was drafted.");
+  }
+  if (pick.body !== void 0 && !bodyTraces(pick.body, userTurns)) {
+    return refusal2(
+      "body_untraced",
+      "I can't prepare that change because the values I would set are not ones you stated \u2014 I never invent settings. Tell me exactly what to set, in your own words, and I'll prepare the draft."
+    );
+  }
+  const title = honestTitle(pick.title, (op.summary ?? op.operation_id).slice(0, 120));
+  const draft = {
+    kind: "draft",
+    act: "api_call",
+    version: 1,
+    title,
+    prepared_at: (/* @__PURE__ */ new Date()).toISOString(),
+    requires_confirmation: true,
+    call: { method: op.method.toUpperCase(), path: op.path, ...pick.body !== void 0 ? { body: pick.body } : {} },
+    notes: [
+      "A preference act: with your standing grant the card executes it straight away; without one, your own tap on the card confirms it. The grant is yours on the settings page \u2014 granted or revoked by your hand, never by a message."
+    ]
+  };
+  const answer = `I've prepared the act "${title}" \u2014 a preference act on your own settings.
+
+With your standing grant it executes under the grant's authority; without one, the card asks once and your tap confirms it. The platform re-checks the act against its own specification either way, and the grant never covers record acts.`;
+  return { status: "draft", draft, answer };
+}
+
 // workers/worker_public/src/memories.ts
 var MAX_FILES = 10;
 var MAX_CONTENT = 8e3;
@@ -1612,7 +1877,7 @@ async function* sseTokens(stream) {
 }
 async function handleAsk(env, ctx, req, tier, key) {
   const tStart = Date.now();
-  const telemetryMeta = () => ({ durationMs: Date.now() - tStart, keyId: key?.id ?? null });
+  const telemetryMeta = () => ({ durationMs: Date.now() - tStart, keyId: key?.id ?? null, retries: generateRetries });
   const stageTiming = {};
   let generateRetries = 0;
   const readAs = () => understanding ? {
@@ -1629,6 +1894,7 @@ async function handleAsk(env, ctx, req, tier, key) {
   if (!q) return err(400, "invalid_input", `query is required (1-${LIMITS.maxInputChars} chars)`);
   const declaredCtx = parseContext(body);
   const draftAct = P().publisher.features?.drafts ? detectDraftIntent(q.query) : null;
+  const apiCallIntent = !draftAct && P().publisher.features?.api_call_drafts ? detectApiCallIntent(q.query, declaredCtx) : null;
   const member = tier === "member" ? await sessionFrom(req, env) : null;
   const effort = requestEffort(env, member, body?.effort);
   const limit = tier === "key" ? key.day_limit : tier === "member" || member ? num(env, "MEMBER_DAY_ASK", 300) : num(env, "ANON_DAY_ASK", 20);
@@ -1649,14 +1915,15 @@ async function handleAsk(env, ctx, req, tier, key) {
     cookie: req.headers.get("cookie") ?? "",
     authorization: req.headers.get("authorization") ?? ""
   };
-  const scope = resolveRequestScope(body, member);
+  const keyLicensed = tier === "key" && standardKeysFrom(body).size > 0;
+  const scope = resolveRequestScope(body, member, { keyWithEntitlements: keyLicensed });
   if ("error" in scope) return err(400, "invalid_input", "datasets: at least one dataset must stay enabled");
   const { corpora, narrowed, isoOn } = scope;
   const standardKeys = entitlementScope(scope.standardKeys);
   const [memNote, memoryUsed] = member && scope.memoryIds.length ? await memoryNote(env, member.sub, scope.memoryIds) : [null, []];
   const requestSaltStr = requestSalt(scope, memoryUsed);
   const salt = requestSaltStr ? `${requestSaltStr}|effort:${effort}` : `effort:${effort}`;
-  const federate = member && service && isoOn ? (q2) => retrieveInternal(service, fedAuth, q2) : void 0;
+  const federate = (member || keyLicensed) && service && isoOn ? (q2) => retrieveInternal(service, fedAuth, q2) : void 0;
   const ns = tier === "key" ? `k:${key.id}` : member ? `m:${member.sub}` : "anon";
   const model = member ? MODELS.member : MODELS.anon;
   const prev = typeof body?.prev === "string" ? body.prev.slice(0, 800) : void 0;
@@ -1673,7 +1940,7 @@ async function handleAsk(env, ctx, req, tier, key) {
   let retrieved;
   const fresh = freshRequested(body);
   const gen = await corpusGen(env.CACHE);
-  const cached = fresh || contextual || declaredCtx || draftAct || userImage ? null : await cacheGet(env, gen, ns, q.query, q.lang, salt);
+  const cached = fresh || contextual || declaredCtx || draftAct || apiCallIntent || userImage ? null : await cacheGet(env, gen, ns, q.query, q.lang, salt);
   const wantsStream = body?.stream === true || tier === "anon" && body?.stream !== false;
   if (cached) {
     telemetry(env, ctx, tier, "ask", null, true, (cached.value.answer ?? "").length, cached.value.query_hash, q.lang, "exact", telemetryMeta());
@@ -1697,7 +1964,7 @@ async function handleAsk(env, ctx, req, tier, key) {
   }
   let understanding = null;
   const nodeScoped = !!modelNodeRefIn(q.query) || !!modelNodeRefIn(declaredCtx?.label);
-  if (!cached && !nodeScoped && !contextual && !declaredCtx && !draftAct && !q.lang && !userImage && !fresh) {
+  if (!cached && !nodeScoped && !contextual && !declaredCtx && !draftAct && !apiCallIntent && !q.lang && !userImage && !fresh) {
     const wv0 = await warmEmbed ?? null;
     if (wv0) {
       const sc0 = await semanticCacheGet(env, gen, wv0, salt);
@@ -1795,7 +2062,7 @@ async function handleAsk(env, ctx, req, tier, key) {
   console.log("understand:", understanding?.intent ?? "null", understanding?.doc_number ? `doc#${understanding.doc_number}${understanding.edition ? "@" + understanding.edition : ""}` : "nodoc", "|", q.query.slice(0, 50));
   const graphDocNumbers = await graphExpand(env, understanding);
   const eNote = await editionNote(env, understanding);
-  if (understanding?.intent !== "conversational" && !nodeScoped && !contextual && !declaredCtx && !draftAct && !userImage && !fresh) {
+  if (understanding?.intent !== "conversational" && !nodeScoped && !contextual && !declaredCtx && !draftAct && !apiCallIntent && !userImage && !fresh) {
     const warmVec = await warmEmbed ?? null;
     if (warmVec) {
       const sc = await semanticCacheGet(env, gen, warmVec, salt);
@@ -1900,6 +2167,33 @@ ${summary}` }] : [],
     }
     return json({ answer: verdict.answer, citations: citations2, model, query_hash: queryHash2, follow_ups: [], context_applied: draftCtxApplied, read: readAs(), ...draftPayload ? { draft: draftPayload } : {}, quota });
   }
+  if (apiCallIntent) {
+    const callCtxApplied = declaredCtx ? appliedContext(declaredCtx, null) : NO_CONTEXT;
+    const queryHash2 = await sha256Hex(q.query);
+    const verdict = await prepareApiCall(env, {
+      intent: apiCallIntent,
+      query: q.query,
+      history: keptHistory,
+      member,
+      declared: declaredCtx,
+      model: roleModel(env, "acts")
+    });
+    console.log("api_call draft:", apiCallIntent, "\u2192", verdict.status === "draft" ? `draft (${verdict.draft.call.method} ${verdict.draft.call.path})` : `refused (${verdict.reason})`);
+    const draftPayload = verdict.status === "draft" ? verdict.draft : void 0;
+    telemetry(env, ctx, tier, "ask", model, true, verdict.answer.length, queryHash2, q.lang, void 0, telemetryMeta());
+    if (wantsStream) {
+      return sseResponse(
+        [
+          ...readAs() ? [{ type: "read", read: readAs() }] : [],
+          { type: "citations", citations: [], context_applied: callCtxApplied, ...draftPayload ? { draft: draftPayload } : {}, quota },
+          { type: "token", v: verdict.answer },
+          { type: "done", model, query_hash: queryHash2, context_applied: callCtxApplied, read: readAs() }
+        ],
+        corsHeaders(req)
+      );
+    }
+    return json({ answer: verdict.answer, citations: [], model, query_hash: queryHash2, follow_ups: [], context_applied: callCtxApplied, read: readAs(), ...draftPayload ? { draft: draftPayload } : {}, quota });
+  }
   let liveRecords;
   let accountNote;
   const modelDocHint = named ?? docScope ?? namedDocumentIn(q.query);