@konneal/engine 0.2.32 → 0.2.34

package/dist/{chunk-S7NLWPNX.js → chunk-MNNE7OIM.js}

@@ -7,24 +7,24 @@ import {
   sessionFrom,
   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 {
   entitlementScope,
   standardKeysFrom
-} from "./chunk-JGKSUSF5.js";
+} from "./chunk-4GJGBGJK.js";
 import {
   LIMITS,
   MODELS,
   num,
   sha256Hex
-} from "./chunk-OMXAE27N.js";
+} from "./chunk-V46XM2GU.js";
 
 // workers/worker_public/src/search.ts
 async function handleSearch(env, ctx, req, tier, key) {

package/dist/{chunk-2RKYO3OC.js → chunk-R2V3X6SQ.js}

@@ -1,7 +1,7 @@
 import {
   LIMITS,
   sha256Hex
-} from "./chunk-OMXAE27N.js";
+} from "./chunk-V46XM2GU.js";
 import {
   P
 } from "./chunk-3FYJM7LH.js";

package/dist/{chunk-OMXAE27N.js → chunk-V46XM2GU.js}

@@ -13,6 +13,10 @@ var MODELS = {
   member: "@cf/zai-org/glm-5.3-flash",
   // hot-path understanding/summarize stays on the cheap Qwen (cost-first lane)
   understand: "@cf/qwen/qwen3-30b-a3b-fp8",
+  // the api_call act's intent-to-act mapping (TODO.ai-platform/09) — the
+  // operations deployment points ACTS_MODEL at the stronger reasoning
+  // tier; the floor is the understand lane
+  acts: "@cf/qwen/qwen3-30b-a3b-fp8",
   // generation fallback when the answer model is unavailable
   fallback: "@cf/qwen/qwen3-30b-a3b-fp8",
   grader: "@cf/deepseek-ai/deepseek-v4-flash-0731",

package/dist/config.d.ts

@@ -4,6 +4,7 @@ export declare const MODELS: {
     readonly anon: "@cf/zai-org/glm-5.3-flash";
     readonly member: "@cf/zai-org/glm-5.3-flash";
     readonly understand: "@cf/qwen/qwen3-30b-a3b-fp8";
+    readonly acts: "@cf/qwen/qwen3-30b-a3b-fp8";
     readonly fallback: "@cf/qwen/qwen3-30b-a3b-fp8";
     readonly grader: "@cf/deepseek-ai/deepseek-v4-flash-0731";
     readonly enrich: "@cf/deepseek-ai/deepseek-v4-pro-0813";

package/dist/context.d.ts

@@ -1,3 +1,25 @@
+/** One act the declared entity's lifecycle machine offers at its current
+ *  state, FOR THE DECLARING USER'S ROLE (the platform filters before
+ *  publishing; the wire is advisory — the platform re-validates every
+ *  proposed act authoritatively on the way back). */
+export interface MachineAct {
+    /** the machine's own action id (the model's vocabulary) */
+    action: string;
+    /** the state the act lands the entity on */
+    to: string;
+    /** the declared guard (the caller-supplied computed input the
+     *  transition requires), when the transition declares one */
+    guard?: string;
+}
+/** The affordance channel (TODO.ai-platform/08): the entity declaration's
+ *  machine facet — the lifecycle machine's current state (the fact,
+ *  published even when the role fires nothing) + the acts offered to the
+ *  declaring user's role (EMPTY means "the user can read but not act").
+ *  Only ever present on the entity kind. */
+export interface MachineContext {
+    state: string;
+    acts: MachineAct[];
+}
 export interface DeclaredContext {
     kind: "page" | "entity" | "document" | "account";
     /** display label ("this certificate R60/2021-A-EX1-26.01") — echoed
@@ -10,6 +32,8 @@ export interface DeclaredContext {
      *  (urn:oiml:pub:r:60-1:2021) or the plain docidentifier */
     doc?: string;
     edition?: string;
+    /** the affordance channel's machine facet (entity kind only) */
+    machine?: MachineContext;
 }
 /** The account context's live-read echo (TODO.ai-platform/03): WHEN the
  *  live data was read, WHICH stores answered, and how many records the
@@ -44,8 +68,21 @@ export interface AppliedContext {
         standard: string;
         clause?: string;
     };
+    /** the affordance channel's echo (TODO.ai-platform/08): the declared
+     *  machine's state + how many acts it offered the declaring user's role
+     *  — the panel's honest context line reads THIS, never its own copy */
+    machine?: {
+        state: string;
+        offered: number;
+    };
 }
 export declare const NO_CONTEXT: AppliedContext;
+export declare function parseMachine(v: any): MachineContext | undefined;
+/** The proposal bound (TODO.ai-platform/08): a draft act the offered set
+ *  does not carry is never proposed. An absent facet is not a bound (the
+ *  page publishes none); a present facet with an empty acts array bounds
+ *  to NOTHING — the user can read but not act. */
+export declare function machineOffers(machine: MachineContext | undefined, action: string): boolean;
 /** Parse + bound the ask body's optional `context` field. Anything
  *  malformed degrades to null (no context), never to a 400 — a context
  *  the service can't parse is a context it must not apply. */

package/dist/drafts.d.ts

@@ -104,6 +104,11 @@ interface Extraction {
         source?: string;
     }>;
 }
+/** The traceability primitive, shared with the api_call act's body guard
+ *  (apicalls.ts): a value traces when it appears in the user's own
+ *  messages (normalized). The proposing model never gets the benefit of
+ *  the doubt — the user's words are the only source. */
+export declare function valueTracesToUser(value: unknown, userTurns: string[]): boolean;
 export interface GuardedFields {
     standard?: string;
     family_designation?: string;

package/dist/env.d.ts

@@ -47,10 +47,12 @@ import type { VectorIndex } from "./ports/vector.ts";
 import type { Kv } from "./ports/kv.ts";
 import type { Blobs } from "./ports/blobs.ts";
 import type { Runtime } from "./ports/runtime.ts";
+import type { StoreQuery } from "./ports/store.ts";
 export declare function portModelRunner(env: Env): ModelRunner;
 export declare function portIndex(env: Env, which?: "public" | "primmel" | "composed" | "plain" | "adoc" | "mko" | "pflat" | "glossary"): VectorIndex;
 export declare function portKv(env: Env): Kv;
 export declare function portBlobs(env: Env): Blobs;
+export declare function portStore(env: Env): StoreQuery;
 /** Does the deployment bind this lane index? Presence wiring stays in
  *  the ports layer so domain stages never touch raw bindings. */
 export declare function hasLane(env: Env, which: "glossary"): boolean;

package/dist/quota.d.ts

@@ -13,4 +13,5 @@ export declare function checkQuota(env: Env, bucket: string, id: string, limit:
 export declare function telemetry(env: Env, ctx: Background, tier: string, route: string, model: string | null, ok: boolean, answerChars: number, queryHash: string, lang?: string, cache?: "exact" | "semantic", meta?: {
     durationMs?: number;
     keyId?: string | null;
+    retries?: number;
 }): void;

package/dist/requestScope.d.ts

@@ -32,8 +32,16 @@ export declare function entitlementScope(keys: Set<string>): Set<string> | null;
 /** Validate + intersect. Returns { error } when the request explicitly
  *  disables every dataset (a user error, not a scope). The corpora a
  *  dataset searches travel WITH the declaration (profile datasets.yaml,
- *  `corpora:`) — the engine maps no publisher names. */
-export declare function resolveRequestScope(body: any, member: unknown): RequestScope | {
+ *  `corpora:`) — the engine maps no publisher names.
+ *
+ *  `opts.keyWithEntitlements` (the key-tier licensed federation): an
+ *  API-key caller whose request carries a VALIDATED entitlement set is
+ *  admitted to the session-gated (federated) datasets — the key's
+ *  entitlement set is the licensed scope the internal lane honors; the
+ *  internal worker re-validates the key server-side before it answers. */
+export declare function resolveRequestScope(body: any, member: unknown, opts?: {
+    keyWithEntitlements?: boolean;
+}): RequestScope | {
     error: "empty-datasets";
 };
 /** The answer-cache salt: request-scoped context that materially changes

package/dist/search-EADF54TY.js

@@ -0,0 +1,12 @@
+import {
+  handleSearch
+} from "./chunk-MNNE7OIM.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 {
+  handleSearch
+};

package/dist/worker_mcp/src/index.js

@@ -1,7 +1,7 @@
 import {
   authenticate
-} from "../../chunk-2RKYO3OC.js";
-import "../../chunk-OMXAE27N.js";
+} from "../../chunk-R2V3X6SQ.js";
+import "../../chunk-V46XM2GU.js";
 import {
   P,
   setProfile

package/dist/worker_public/src/config.js

@@ -16,7 +16,7 @@ import {
   roleModel,
   sha256Hex,
   today
-} from "../../chunk-OMXAE27N.js";
+} from "../../chunk-V46XM2GU.js";
 import "../../chunk-3FYJM7LH.js";
 export {
   DATASETS,

package/dist/worker_public/src/index.js

@@ -1,6 +1,6 @@
 import {
   handleSearch
-} from "../../chunk-S7NLWPNX.js";
+} from "../../chunk-MNNE7OIM.js";
 import {
   bindModelNode,
   checkQuoteAnchors,
@@ -9,7 +9,7 @@ import {
   modelGroundingBlock,
   scoreJudge,
   standardForDocNumber
-} from "../../chunk-TDKNQPA2.js";
+} from "../../chunk-MHA2OFWE.js";
 import {
   buildMessages,
   citations,
@@ -32,7 +32,7 @@ import {
   sessionFrom,
   telemetry,
   understandQuery
-} from "../../chunk-F66NYFUK.js";
+} from "../../chunk-DADOI4Q6.js";
 import {
   authenticate,
   corsHeaders,
@@ -41,14 +41,14 @@ import {
   readJson,
   validateQuery,
   withCors
-} from "../../chunk-2RKYO3OC.js";
+} from "../../chunk-R2V3X6SQ.js";
 import {
   canonicalRefusal
 } from "../../chunk-A3QHHUN5.js";
 import {
   entitlementScope,
   standardKeysFrom
-} from "../../chunk-JGKSUSF5.js";
+} from "../../chunk-4GJGBGJK.js";
 import {
   LIMITS,
   MODELS,
@@ -59,7 +59,7 @@ import {
   roleModel,
   sha256Hex,
   today
-} from "../../chunk-OMXAE27N.js";
+} from "../../chunk-V46XM2GU.js";
 import {
   P,
   setProfile
@@ -996,7 +996,7 @@ async function handleMcp(env, ctx, req, tier, key) {
       // stream:false forces the JSON lane (anon defaults to SSE)
       body: JSON.stringify({ ...args, stream: false })
     });
-    const res = name === "ask" ? await (await import("../../ask-43C2WZZO.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-NHTT5DDI.js")).handleSearch(env, ctx, inner, tier, key);
+    const res = name === "ask" ? await (await import("../../ask-BDD5TFNC.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-EADF54TY.js")).handleSearch(env, ctx, inner, tier, key);
     return res.json().catch(() => ({ error: { message: "tool transport failed", status: res.status } }));
   });
   if (out.ok && "accepted" in out) return new Response(null, { status: 202 });
@@ -1382,14 +1382,16 @@ async function adminStatsRoute(c) {
   if (!env.ADMIN_TOKEN) return err(501, "admin_disabled", "ADMIN_TOKEN secret is not configured");
   const auth = req.headers.get("authorization") ?? "";
   if (auth !== `Bearer ${env.ADMIN_TOKEN}`) return err(401, "unauthorized", "Invalid admin token");
-  const [byDay, byModel, feedback, convCount, cacheMix, durations] = await Promise.all([
+  const [byDay, byModel, feedback, convCount, cacheMix, durations, retriesRow] = await Promise.all([
     env.DB.prepare("SELECT day, tier, COUNT(*) as n, SUM(ok) as ok FROM queries WHERE day >= date('now','-7 days') GROUP BY day, tier ORDER BY day DESC").all(),
     env.DB.prepare("SELECT model, SUM(requests) as requests FROM spend WHERE day >= date('now','-7 days') GROUP BY model ORDER BY requests DESC").all(),
     env.DB.prepare("SELECT rating, COUNT(*) as n FROM feedback GROUP BY rating").all(),
     env.DB.prepare("SELECT COUNT(*) as n FROM conversations").first(),
     env.DB.prepare("SELECT COALESCE(cache, 'miss') AS cache, COUNT(*) AS n FROM queries WHERE day >= date('now','-7 days') AND route = 'ask' GROUP BY cache").all(),
-    env.DB.prepare("SELECT duration_ms FROM queries WHERE day >= date('now','-7 days') AND route = 'ask' AND duration_ms IS NOT NULL").all()
+    env.DB.prepare("SELECT duration_ms FROM queries WHERE day >= date('now','-7 days') AND route = 'ask' AND duration_ms IS NOT NULL").all(),
+    env.DB.prepare("SELECT COALESCE(SUM(retries), 0) AS total, SUM(CASE WHEN retries > 0 THEN 1 ELSE 0 END) AS answers FROM queries WHERE day >= date('now','-7 days') AND route = 'ask'").all()
   ]);
+  const retries = retriesRow?.results?.[0] ?? { total: 0, answers: 0 };
   const ds = durations.results.map((r) => r.duration_ms).sort((a, b) => a - b);
   const pct = (q) => ds.length ? ds[Math.min(ds.length - 1, Math.floor(q * ds.length))] : null;
   const totalQueries = byDay.results.reduce((a, r) => a + (r.n || 0), 0) || 0;
@@ -1407,6 +1409,7 @@ async function adminStatsRoute(c) {
     feedback: feedback.results,
     cache_mix_7d: cacheMix.results,
     latency_ms: ds.length ? { n: ds.length, p50: pct(0.5), p95: pct(0.95) } : null,
+    generate_retries_7d: { total: Number(retries.total) || 0, answers_retried: Number(retries.answers) || 0 },
     conversations: convCount?.n ?? 0,
     error_rate_pct: errorRate,
     index_version: env.INDEX_VERSION,

package/dist/worker_public/src/requestScope.js

@@ -4,8 +4,8 @@ import {
   requestSalt,
   resolveRequestScope,
   standardKeysFrom
-} from "../../chunk-JGKSUSF5.js";
-import "../../chunk-OMXAE27N.js";
+} from "../../chunk-4GJGBGJK.js";
+import "../../chunk-V46XM2GU.js";
 import "../../chunk-3FYJM7LH.js";
 export {
   entitlementScope,

package/docs/API.md

@@ -117,6 +117,43 @@ a corpus document. The service applies it honestly:
   declaration, not just the query) and is never written into them.
 - Conversational turns (greetings, identity) never ground in a declared
   context — the echo reports `none`.
+- The entity declaration may carry the affordance channel's `machine`
+  facet (TODO.ai-platform/08): the lifecycle machine's current `state`
+  (the fact) and the `acts` it offers there for the declaring user's
+  role (already role-filtered by the platform). The facet parses bounded
+  (state ≤ 60 chars, ≤ 24 acts, each `action`/`to`/`guard` ≤ 60), rides
+  the entity kind only, and BOUNDS the proposal grammar: a draft act the
+  set does not offer is never proposed, and an empty `acts` array is the
+  honest "the user can read but not act" — the answer says so and no
+  draft rides. The facet is advisory; the platform re-validates every
+  draft act authoritatively on the way back.
+
+```jsonc
+"context": {
+  "kind": "entity",
+  "label": "this application R60-2026-0042",
+  "route": "/app/ia/applications/R60-2026-0042",
+  "machine": {                            // the affordance channel — entity kind only
+    "state": "UNDER_REVIEW",              // the machine's current state (the fact)
+    "acts": [                             // offered FOR THE DECLARING USER'S ROLE — may be []
+      { "action": "ia_accepts", "to": "ACCEPTED" },
+      { "action": "ia_logs_samples", "to": "SAMPLES_RECEIVED", "guard": "receipt_complete" }
+    ]
+  }
+}
+```
+
+The echo carries the facet's fact + count, so the panel's honest context
+line reads the service's applied truth, never its own copy:
+
+```jsonc
+"context_applied": {
+  "kind": "entity",
+  "label": "this application R60-2026-0042",
+  "scoped_to": "OIML R 60:2021",
+  "machine": { "state": "UNDER_REVIEW", "offered": 2 }
+}
+```
 
 Every ask response — the SSE `citations`/`done` events and the JSON body —
 echoes what was APPLIED, so the panel's context line never invents a
@@ -245,6 +282,52 @@ The honest rules, all eval-gated (the golden suite's `draft-*` legs):
 
 **SSE**: the `draft` rides the first (`citations`) frame beside
 `context_applied`; `token` frames carry the answer; `done` as usual.
+
+##### The api_call act (TODO.ai-platform/09 — the operations deployment)
+
+The second draft act proposes ONE platform operation — the operations
+assistant's grammar, feature-flagged (`features.api_call_drafts`; the
+corpus-only deployment leaves it off):
+
+```jsonc
+"draft": {
+  "kind": "draft",
+  "act": "api_call",
+  "version": 1,
+  "title": "Save the R 60 filter",        // what the act DOES — never the wire shape
+  "prepared_at": "2026-09-26T09:00:00Z",
+  "requires_confirmation": true,           // ALWAYS
+  "call": {
+    "method": "PUT",                       // a real operation from the plane —
+    "path": "/api/notify/preferences",     // an invented path is a service bug
+    "body": { }                            // optional; preference bodies trace
+  }                                        // to the user's own words
+}
+```
+
+The honest rules (the module is structurally write-free — it reads the
+operation directory and calls the pick model; there is no platform IO):
+
+- **The directory is the closed world**: the call names an operation the
+  deployment's `api_ops` directory (loaded from the OpenAPI plane at
+  ingest) actually carries. The model proposes an operation id; the
+  guard resolves it against the directory AFTER the fact — an invented
+  id or path never rides.
+- **The machine facet bounds the machine acts** (§2.1.1): the entity
+  write composes only for an act the offered set carries, addressed to
+  the declared entity (the profile's route-pattern table maps the
+  page's route to the store and id). An empty offered set answers the
+  honest "you can read but not act" and proposes nothing.
+- **The never-offer list holds** (profile data, `publisher.acts
+  .never_offer`): the auth family (signout is the user's own, forever)
+  and the grant's own mint/revoke (delegation is granted by the user's
+  hand on the settings page, never by a chat message) are excluded from
+  the pick prompt AND refused at the guard.
+- **The act class is the platform's word, not the draft's**: the panel
+  pre-flights every api_call draft against the plane and the class
+  decides the arc — preference rides the standing grant's seam, record
+  confirms per act and executes as the user.
+
 The draft is ephemeral — the conversations API never persists it (a
 resumed session keeps the honest context line, not a stale draft).
 

package/package.json

@@ -27,7 +27,7 @@
     "playwright": "^1.62.1",
     "yaml": "^2.9.1"
   },
-  "version": "0.2.32",
+  "version": "0.2.34",
   "description": "The Konneal engine: the publisher-agnostic build pipeline and API plane for standards intelligence (retrieval, answer contract, verdicts, evaluation).",
   "license": "BSD-3-Clause",
   "type": "module",

package/workers/worker_public/migrations/0015_ask_retries.sql

@@ -0,0 +1,4 @@
+-- the latency program's aggregate: how many generation retries each ask
+-- needed (Server-Timing carried the count per answer; this column makes
+-- it rollup-able). Existing rows read 0 — they predate the column.
+ALTER TABLE queries ADD COLUMN retries INTEGER NOT NULL DEFAULT 0;