@konneal/engine 0.1.0

package/dist/config.d.ts

@@ -0,0 +1,154 @@
+export declare const MODELS: {
+    readonly embed: "@cf/qwen/qwen3-embedding-0.6b";
+    readonly rerank: "@cf/baai/bge-reranker-base";
+    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 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";
+    readonly listwise: "@cf/zai-org/glm-4.7-flash";
+    readonly research: "@cf/zai-org/glm-5.3-flash";
+};
+export declare const LIMITS: {
+    readonly maxInputChars: 8000;
+    readonly maxOutputTokens: 3072;
+    readonly retrieveK: 50;
+    readonly rerankKeep: 10;
+    readonly cacheTtlSec: number;
+    readonly inputTokenBudget: 16000;
+    readonly maxPassageTokens: 900;
+};
+/** Tuned retrieval thresholds — every number the pipeline steers by.
+ *  Each carries the measurement that justifies it; changing one without
+ *  re-running the gates (golden ×3 + annealment ×6) is a guess. */
+export declare const THRESHOLDS: {
+    /** HyDE candidate score discount — hypothetical-answer vectors match
+     *  differently than question vectors; 0.7 keeps them competitive
+     *  without letting a bad hypothetical outrank the real query. */
+    readonly hydeDiscount: 0.7;
+    /** Graph-lane candidate discount — graph-filtered chunks enter the
+     *  pool below the primary dense lane; they must earn their window
+     *  slot under the cross-encoder, not by graph membership alone. */
+    readonly graphLaneDiscount: 0.75;
+    /** Concept-graph candidate discount — same rationale as the graph
+     *  lane: definitional content enters discounted. */
+    readonly conceptGraphDiscount: 0.75;
+    /** Multi-hop sub-query discount — sub-question hits are unioned, not
+     *  RRF-fused; the discount keeps them from dominating the primary
+     *  ranking on their first appearance. */
+    readonly subQueryDiscount: 0.8;
+    /** Federated-ISO discount — the public corpus answers by default;
+     *  internal ISO passages compete but don't preempt. */
+    readonly federateDiscount: 0.95;
+    /** Standard-reference nudge (L5): when the question asks about an
+     *  invoked ISO/IEC standard, chunks that CARRY such a citation (their
+     *  text contains an ISO/IEC identifier) get a spread-scaled boost —
+     *  the citing clause is the answer, and generic family prose otherwise
+     *  fills the window (measured: l5a-iso-humidity flips ~1/6 runs). */
+    readonly stdRefNudgeSpread: 0.35;
+    /** Edition cover — the score multiplier for current-edition chunks the
+     *  cover stage fetches when a pool holds ONLY stale editions of a
+     *  document. Just under the top: the point is REPRESENTATION (so
+     *  edition steering can demote the stale siblings and diversity keeps
+     *  the current overview), not free ranking. */
+    readonly editionCoverDiscount: 0.9;
+    /** Overview-chunk demotion — overview chunks repeat title/doctype
+     *  boilerplate and embed strongly for name-like queries, crowding
+     *  clause chunks out of the rerank window. */
+    readonly overviewDemotion: 0.85;
+    /** Glossary-link cosine floor — below this the dense match to a
+     *  defined term is noise, not a candidate. Calibrated on the
+     *  drifting→durability probe (durability-def 0.542, noise ~0.3). */
+    readonly glossaryCosineFloor: 0.5;
+    /** Exact-term nudge (spread multiplier) — clause chunks whose head IS
+     *  the asked-for term get a decisive nudge because publication headers
+     *  contain the title words and the reranker alone is unreliable there;
+     *  >1 so it dominates the spread, unlike the additive steering boosts. */
+    readonly termNudgeSpread: 1.5;
+    /** Concept-steering rerank boost (spread fraction) — the vocabulary
+     *  link's defining families get the edition-steering boost idiom.
+     *  0.15 is enough to lift in-family content past the cross-encoder's
+     *  vocabulary bias without overriding genuine relevance. */
+    readonly conceptSteerSpread: 0.15;
+    /** Cross-publication recency boost (spread fraction) — a
+     *  current-edition publication ranks over stale ones; composed with
+     *  the family-relative demotion below. */
+    readonly crossPubRecencySpread: 0.1;
+    /** Family-relative edition demotion (spread fraction) — superseded
+     *  editions are demoted when a newer edition of the same publication
+     *  is in the pool; a sibling one revision back still competes. */
+    readonly familyDemoteSpread: 0.4;
+    /** Relevance-floored window — passages below this fraction of the
+     *  top rerank score leave the window (the evidence-budget principle;
+     *  structural units are exempt). */
+    readonly windowFloorFraction: 0.25;
+    /** Small-to-big parent fetch discount — the parent clause enters at
+     *  a discount because it's supplementary grounding, not the answer. */
+    readonly smallToBigDiscount: 0.7;
+    /** Section-descent child discount — children fetched from a ranked
+     *  depth-1 summary enter discounted. */
+    readonly sectionDescentDiscount: 0.8;
+    /** History budget share — the fraction of the context budget the
+     *  conversation slice may consume; older turns overflow into the
+     *  compacted summary instead of starving the passages. */
+    readonly historyBudgetShare: 0.3;
+};
+/** Process-expansion — appended to process-intent queries; publisher
+ *  vocabulary from the profile (read at request time — see profile.ts). */
+export declare function processExpansion(): string;
+/** Per-deployment model override: <ROLE>_MODEL (e.g. UNDERSTAND_MODEL)
+ *  replaces the pinned default for that role. Ops lever for A/B-ing a
+ *  role's model without a code change; absent/invalid = the default. */
+export declare function roleModel(env: any, role: keyof typeof MODELS): string;
+/** Per-deployment effort override for the answer lane (ANSWER_EFFORT).
+ *  The effort–accuracy curve is front-loaded (DeepSeek-V4.1-Flash report,
+ *  Fig. 9): serving pins "low" for latency, and any move up must be
+ *  measured on the golden set — this lever makes that measurable live,
+ *  same pattern as roleModel. Absent/invalid = "low". */
+export declare function answerEffort(env: any): string;
+/** Per-request effort for the answer lane (the user-facing depth toggle).
+ *  The vocabulary is validated; elevated efforts (medium+) are a member
+ *  lane — same cost rule as research — and degrade to the deployment
+ *  lever for anonymous or silent requests. */
+/** Elevated effort reasons longer — the output budget must grow with it
+ *  or reasoning starves the content (the GLM-5 rule; measured
+ *  2026-09-12: medium at the flat 3072 budget scored 5/38 on the golden
+ *  set — empty answers — versus 37–38/38 at low). */
+export declare function effortBudget(effort: string): number;
+export declare function requestEffort(env: any, session: unknown, requested: unknown): string;
+/** The corpus catalog — single source for /api/datasets, the assistant's
+ *  self-description, and per-corpus model guidance. `session: true`
+ *  datasets are enabled for signed-in members (federated via the internal
+ *  service binding). `note` (optional) is injected into the system prompt
+ *  when passages from this corpus are present — corpus behavior travels
+ *  with the dataset, not with pipeline code. */
+export interface Dataset {
+    id: string;
+    label: string;
+    description: string;
+    /** member-session gated (federated via the internal service binding) */
+    session?: boolean;
+    /** the estate permission (a role code set in the publisher's
+     *  identity provider) the session must carry for a session-gated
+     *  dataset — membership alone is not the bar */
+    permission?: string;
+    /** the corpora this dataset searches (profile datasets.yaml) — the
+     *  engine maps no publisher names */
+    corpora?: string[];
+    note?: string;
+}
+export declare function DATASETS(): readonly Dataset[];
+/** The estate permission gate: a session-gated dataset requires BOTH
+ *  membership and the named permission (a role code the account carries
+ *  in id.oimlsmart.org). Enforcement is server-side — the UI's lock is
+ *  cosmetic; /api/ask federation and the scope intersect here too. */
+export declare function hasPermission(session: unknown, code: string): boolean;
+export declare function datasetAllowed(d: Dataset, session: unknown): boolean;
+export declare function datasetsFor(session: unknown): unknown[];
+/** Empty-state starter questions, served by /api/datasets — UI content
+ *  comes from the API, never hardcoded in the client. */
+export declare function SUGGESTIONS(): string[];
+export declare function num(env: Record<string, unknown>, key: string, fallback: number): number;
+export declare function today(): string;
+export declare function sha256Hex(s: string): Promise<string>;

package/dist/config.js

@@ -0,0 +1,37 @@
+import {
+  DATASETS,
+  LIMITS,
+  MODELS,
+  SUGGESTIONS,
+  THRESHOLDS,
+  answerEffort,
+  datasetAllowed,
+  datasetsFor,
+  effortBudget,
+  hasPermission,
+  num,
+  processExpansion,
+  requestEffort,
+  roleModel,
+  sha256Hex,
+  today
+} from "./chunk-WOGQM7DJ.js";
+import "./chunk-MB74PTRM.js";
+export {
+  DATASETS,
+  LIMITS,
+  MODELS,
+  SUGGESTIONS,
+  THRESHOLDS,
+  answerEffort,
+  datasetAllowed,
+  datasetsFor,
+  effortBudget,
+  hasPermission,
+  num,
+  processExpansion,
+  requestEffort,
+  roleModel,
+  sha256Hex,
+  today
+};

package/dist/context.d.ts

@@ -0,0 +1,115 @@
+export interface DeclaredContext {
+    kind: "page" | "entity" | "document" | "account";
+    /** display label ("this certificate R60/2021-A-EX1-26.01") — echoed
+     *  into context_applied for the panel's context line */
+    label: string;
+    /** the publishing page's route (page/entity contexts) */
+    route?: string;
+    /** the corpus reference to scope retrieval to (entity/document
+     *  contexts): the URN the SMART models carry as clause provenance
+     *  (urn:oiml:pub:r:60-1:2021) or the plain docidentifier */
+    doc?: string;
+    edition?: string;
+}
+/** 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
+ *  answer could ground in. Present only on a successful read — a failed
+ *  or refused read reports through `note` instead, never silently. */
+export interface LiveEcho {
+    read_at: string;
+    stores: string[];
+    records: number;
+}
+export interface AppliedContext {
+    kind: "page" | "entity" | "document" | "account" | "none";
+    label?: string;
+    /** the publication the DECLARED context actually scoped retrieval to
+     *  ("OIML R 60:2021"); null when the declaration did not scope this
+     *  answer (see `note` for the honest why) */
+    scoped_to?: string | null;
+    /** why a doc-carrying declaration did not scope the answer:
+     *  the corpus does not carry it, or the question named its own
+     *  publication (the user's explicit words always win over the chip);
+     *  for the account kind: why the live data was NOT read (the honest
+     *  degradation — sign in, the window lapsed, the cone refused) */
+    note?: "document-not-in-corpus" | "question-document-wins" | "sign-in-required" | "live-window-expired" | "live-unavailable";
+    /** the account kind's live-read echo (TODO.ai-platform/03) */
+    live?: LiveEcho;
+    /** the model plane's bound node (TODO.ai-platform/05): the model-aware
+     *  chip grounded this answer in the model node itself — its constraint,
+     *  its provenance, its tests */
+    model?: {
+        node_id: string;
+        kind: string;
+        standard: string;
+        clause?: string;
+    };
+}
+export declare const NO_CONTEXT: AppliedContext;
+/** 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. */
+export declare function parseContext(body: any): DeclaredContext | null;
+export interface DocScope {
+    /** the Vectorize doc_number filter value (the publication FAMILY —
+     *  an entity's clause provenance spans parts: R 60-1 requirements,
+     *  R 60-2 tests) */
+    doc_number: string;
+    edition?: string;
+    /** the canonical label form for the echo + the prompt note */
+    label: string;
+}
+/** Parse the two reference forms the estate speaks: the URN the SMART
+ *  models carry as clause provenance (urn:oiml:pub:r:60-1:2021) and the
+ *  plain docidentifier (OIML R 60-1:2021 / R 60). Part designations
+ *  parse but do not narrow the scope (the family IS the scope). */
+export declare function parseDocRef(doc: string, edition?: string): DocScope | null;
+/** Read the FIRST publication the question's own text names, in the
+ *  letter+number forms the corpus speaks ("R 76", "r76-1", "OIML B 18",
+ *  "R 60:2021"). "A document named in the question wins over the declared
+ *  chip" is only honest when it is the user's own words that win — the
+ *  understand stage's doc_number is an LLM extraction that also fires on
+ *  domain priors ("maximum permissible errors" → R 76, no document named
+ *  — the merged tree's ctx-document-r111 flake) and can miss a naming the
+ *  text plainly carries; both directions are decided from the TEXT here.
+ *  A glued single digit is a class/designation ("E2 weights"), never a
+ *  naming; part designations parse but do not narrow the family. */
+export declare function namedDocumentIn(query: string): DocScope | null;
+/** Resolve the declared document against the publications registry: the
+ *  family must exist in the corpus, else the scope honestly does not
+ *  apply (the answer runs on the general corpus and context_applied's
+ *  scoped_to stays null). A registry READ failure proceeds with the
+ *  parsed scope — a scoped refusal is more honest than silently
+ *  widening to the whole corpus. */
+export declare function resolveDocScope(env: any, ctx: DeclaredContext): Promise<DocScope | null>;
+export declare function appliedContext(declared: DeclaredContext | null, scope: DocScope | null, note?: AppliedContext["note"], live?: LiveEcho): AppliedContext;
+/** Validate a context_applied object arriving from a client (the
+ *  conversations API stores the echo with the message). Bounded and
+ *  shape-checked; garbage degrades to null (nothing stored). */
+export declare function parseAppliedContext(v: any): AppliedContext | null;
+/** The prompt note the declared context contributes (rides the
+ *  retrieval-note slot buildMessages already carries). The entity note
+ *  is explicit about the wave-02 boundary: the entity's OWN DATA is not
+ *  in scope (that is wave 03's live-data exchange) — the grounding is
+ *  the governing publication's clauses. */
+export declare function contextNote(declared: DeclaredContext | null, scope: DocScope | null): string | undefined;
+/** A minimal knowledge-intent understanding for when the understand
+ *  call failed but a declared document still scopes retrieval: the
+ *  whole doc-scoped machinery (the family boost, the typed pin, the
+ *  grade skip) keys off understanding.doc_number. */
+export declare function syntheticUnderstanding(scope: DocScope): {
+    intent: "knowledge";
+    docidentifier: string;
+    doc_number: string;
+    edition: string | null;
+    language: null;
+    process_intent: boolean;
+    term: null;
+    defined_terms: never[];
+    standalone_query: string;
+    complexity: "simple";
+    query_variants: never[];
+    sub_queries: never[];
+    hypothetical_answer: string;
+    follow_ups: never[];
+};

package/dist/conversations.d.ts

@@ -0,0 +1,5 @@
+export declare function handleConversations(env: any, sub: string, req: Request, route: {
+    method: string;
+    id?: string;
+}): Promise<Response>;
+export declare function handleAppendMessage(env: any, sub: string, req: Request, convId: string): Promise<Response>;

package/dist/drafts.d.ts

@@ -0,0 +1,129 @@
+export interface DraftSample {
+    serial: string;
+    condition?: string;
+}
+export interface ApplicationPrefillFields {
+    /** the Recommendation, as the estate URN (urn:oiml:pub:r:60:2021) */
+    standard_doc: string;
+    /** display label ("OIML R 60:2021") */
+    standard_label?: string;
+    family_designation?: string;
+    group_label?: string;
+    model_designation?: string;
+    description?: string;
+    samples?: DraftSample[];
+    scheme?: "A" | "B";
+}
+export interface DraftDrop {
+    field: string;
+    value: string;
+    reason: string;
+}
+export interface DraftAct {
+    kind: "draft";
+    act: "application_prefill";
+    version: 1;
+    title: string;
+    prepared_at: string;
+    /** ALWAYS true — the draft is an input to the real form, never a
+     *  channel; the user's own click is the only commit. */
+    requires_confirmation: true;
+    fields: ApplicationPrefillFields;
+    dropped?: DraftDrop[];
+    notes?: string[];
+}
+export interface DraftCitation {
+    docidentifier: string;
+    edition?: string;
+    status?: string;
+}
+export type DraftRefusalReason = "sign_in_required" | "not_configured" | "window_expired" | "exchange_refused" | "role_refused" | "standard_unresolved" | "extraction_failed";
+export type DraftVerdict = {
+    status: "draft";
+    draft: DraftAct;
+    answer: string;
+    citation: DraftCitation | null;
+} | {
+    status: "refused";
+    reason: DraftRefusalReason;
+    answer: string;
+    citation: DraftCitation | null;
+};
+/** The delegation outcome the ask handler computed (livedata.ts's
+ *  exchange; this module never performs it). */
+export type DraftDelegation = {
+    status: "ok";
+    token: string;
+} | {
+    status: "unsigned" | "not_configured" | "window_expired" | "refused" | "op_unreachable";
+};
+export interface PrepareOpts {
+    act: "application_prefill";
+    query: string;
+    history: Array<{
+        role: string;
+        content: string;
+    }>;
+    member: {
+        sub: string;
+    } | null;
+    delegation: DraftDelegation;
+    /** the platform's client id at the OP (the service_roles key) */
+    platformClientId?: string;
+    /** the extraction model (the cheap understand lane) */
+    model: string;
+}
+/** The draft intent, or null. "What documents does an application
+ *  need?" and "where is my application?" never trigger — no act verb. */
+export declare function detectDraftIntent(query: string): "application_prefill" | null;
+interface Extraction {
+    standard?: string;
+    family_designation?: {
+        value?: string;
+        source?: string;
+    };
+    group_label?: {
+        value?: string;
+        source?: string;
+    };
+    model_designation?: {
+        value?: string;
+        source?: string;
+    };
+    description?: {
+        value?: string;
+        source?: string;
+    };
+    scheme?: {
+        value?: string;
+        source?: string;
+    };
+    samples?: Array<{
+        serial?: string;
+        condition?: string;
+        source?: string;
+    }>;
+}
+export interface GuardedFields {
+    standard?: string;
+    family_designation?: string;
+    group_label?: string;
+    model_designation?: string;
+    description?: string;
+    scheme?: "A" | "B";
+    samples?: DraftSample[];
+}
+/**
+ * THE GUARD: a proposed field rides the draft only when its source span
+ * appears in the user's own messages AND the value appears in the span —
+ * the proposal must be the user's words, never the model's completion.
+ * Every rejection is a named drop (the answer accounts for each). */
+export declare function traceabilityGuard(extraction: Extraction, userTurns: string[]): {
+    kept: GuardedFields;
+    dropped: DraftDrop[];
+};
+/** The draft act's full path: the member gate → the delegation's honest
+ *  states → the role permission (the platform's vocabulary) → the
+ *  extraction → the guard → the registry anchor → the draft. */
+export declare function prepareDraft(env: any, opts: PrepareOpts): Promise<DraftVerdict>;
+export {};

package/dist/env.d.ts

@@ -0,0 +1,57 @@
+/** The Workers AI binding — run() only. Domain code goes through
+ *  portModelRunner(env); a precisely-typed AI closes the door on passing
+ *  the raw binding where a ModelRunner is expected (the v2.107 outage). */
+export interface AiBinding {
+    run(model: string, body: unknown): Promise<unknown>;
+}
+export interface Env {
+    AI: AiBinding;
+    VECTORIZE: any;
+    EXP_PRIMMEL: any;
+    EXP_COMPOSED: any;
+    EXP_PLAIN: any;
+    EXP_ADC: any;
+    EXP_MKO: any;
+    EXP_PFLAT: any;
+    GLOSSARY: any;
+    EXP_DB: D1Database;
+    CACHE: KVNamespace;
+    DB: D1Database;
+    ASSETS: Fetcher;
+    INDEX_VERSION: string;
+    UNIT_ASSETS: R2Bucket;
+    ANON_DAY_ASK: string;
+    ANON_DAY_SEARCH: string;
+    KEY_DAY_ASK_DEFAULT: string;
+    ANON_DAY_HARD_CAP: string;
+    ADMIN_TOKEN?: string;
+    MEMBER_DAY_ASK?: string;
+    ENRICH_MODEL?: string;
+    OIDC_ISSUER?: string;
+    OIDC_CLIENT_ID?: string;
+    OIDC_CLIENT_SECRET?: string;
+    OIDC_REDIRECT_URI?: string;
+    SESSION_SECRET?: string;
+    /** TODO.ai-platform/03 — the "my account" live-data delegation: the
+     *  platform instance's API base + its client id at the OP (the
+     *  delegation's scope target). Absent = the account chip honestly
+     *  reports the live read unwired on this deployment. */
+    SMART_PLATFORM_API?: string;
+    SMART_PLATFORM_CLIENT_ID?: string;
+    INTERNAL_SERVICE?: {
+        fetch(input: RequestInfo, init?: RequestInit): Promise<Response>;
+    };
+}
+import type { ModelRunner } from "./ports/model.ts";
+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";
+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;
+/** 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;
+export declare function portRuntime(ctx: ExecutionContext | undefined): Runtime;

package/dist/faithfulness.d.ts

@@ -0,0 +1,5 @@
+export interface FaithfulnessResult {
+    score: number;
+    ungrounded_claims: string[];
+}
+export declare function scoreFaithfulness(ai: any, model: string, answer: string, passages: string[]): Promise<FaithfulnessResult | null>;

package/dist/grader.d.ts

@@ -0,0 +1,3 @@
+export type RetrievalGrade = "good" | "weak" | "bad";
+export declare function gradeRetrieval(ai: any, model: string, query: string, passages: string[]): Promise<RetrievalGrade>;
+export declare function scoreJudge(ai: any, model: string, systemPrompt: string, userPrompt: string): Promise<number | null>;

package/dist/graph.d.ts

@@ -0,0 +1,13 @@
+import type { Env } from "./env";
+export declare function graphExpand(env: Env, u: {
+    term?: string | null;
+    defined_terms?: string[];
+    docidentifier?: string | null;
+} | null): Promise<string[] | undefined>;
+/** Edition registry note (documents table): when the query names a
+ *  publication, tell the model which editions are ACTIVE so superseded
+ *  passages are treated as such — derived status from successor edges,
+ *  not the fallible relaton status field. */
+export declare function editionNote(env: Env, u: {
+    doc_number?: string | null;
+} | null): Promise<string | undefined>;

package/dist/hybrid.d.ts

@@ -0,0 +1,7 @@
+import type { Hit } from "./pipeline";
+/** Rank all candidates by keyword overlap against the query. */
+export declare function keywordRank(query: string, hits: Hit[]): Hit[];
+/** Fuse two rankings with Reciprocal Rank Fusion.
+ *  score(d) = Σ 1/(k + rank_i(d)) — rank-agnostic, robust across
+ *  heterogeneous scorers (dense + sparse). */
+export declare function rrfFuse(dense: Hit[], keyword: Hit[], keep: number): Hit[];

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { setProfile } from "./profile.ts";
+import type { Env } from "./env";
+export type { Env };
+import { type Route } from "./lib/router";
+export declare const ROUTES: Route[];
+declare const _default: {
+    fetch(req: Request, env: Env, ctx: ExecutionContext): Promise<Response>;
+};
+export default _default;