entroly-wasm 1.0.16 → 1.0.18

package/index.d.ts

@@ -0,0 +1,97 @@
+export * from "./pkg/entroly_wasm";
+
+export type EntrolyProvider = "openai" | "anthropic" | "gemini";
+
+export interface EntrolyAppSdkOptions {
+  budget?: number;
+  preserveLastN?: number;
+  provider?: EntrolyProvider;
+}
+
+export interface EntrolyAppDecision {
+  provider: EntrolyProvider;
+  action: "compress" | "observe";
+  tokensBefore: number;
+  tokensAfter: number;
+  requestFingerprint: string;
+}
+
+export interface EntrolyOptimizedParams<T = Record<string, unknown>> {
+  params: T;
+  decision: EntrolyAppDecision;
+}
+
+export function estimateTokens(value: unknown): number;
+export function stableStringify(value: unknown): string;
+export function optimizeMessages<T extends Array<Record<string, unknown>>>(
+  messages: T,
+  options?: EntrolyAppSdkOptions,
+): { messages: T; tokensBefore: number; tokensAfter: number };
+export function optimizeRequestParams<T extends Record<string, unknown>>(
+  params: T,
+  options?: EntrolyAppSdkOptions,
+): EntrolyOptimizedParams<T>;
+export function optimizeOpenAIParams<T extends Record<string, unknown>>(
+  params: T,
+  options?: EntrolyAppSdkOptions,
+): EntrolyOptimizedParams<T>;
+export function optimizeAnthropicParams<T extends Record<string, unknown>>(
+  params: T,
+  options?: EntrolyAppSdkOptions,
+): EntrolyOptimizedParams<T>;
+export function optimizeGeminiParams<T extends Record<string, unknown>>(
+  params: T,
+  options?: EntrolyAppSdkOptions,
+): EntrolyOptimizedParams<T>;
+
+export function createEntrolyMiddleware(options?: EntrolyAppSdkOptions): {
+  specificationVersion: "v3";
+  transformParams(args: { params: Record<string, unknown> }): Promise<Record<string, unknown>>;
+  wrapGenerate(args: { doGenerate: () => Promise<unknown> }): Promise<unknown>;
+  wrapStream(args: { doStream: () => Promise<unknown> }): Promise<unknown>;
+};
+
+export function wrapOpenAI<TClient>(client: TClient, options?: EntrolyAppSdkOptions): unknown;
+export function wrapAnthropic<TClient>(client: TClient, options?: EntrolyAppSdkOptions): unknown;
+export function wrapGemini<TClient>(client: TClient, options?: EntrolyAppSdkOptions): unknown;
+
+export interface ContextReceiptDocument {
+  source_path?: string;
+  source?: string;
+  path?: string;
+  text?: string;
+  content?: string;
+}
+
+export type ContextReceiptInput =
+  | Record<string, string>
+  | Array<[string, string] | ContextReceiptDocument | string>;
+
+export interface ContextReceiptOptions {
+  query?: string;
+  budget?: number;
+  tokenBudget?: number;
+  token_budget?: number;
+  chunkTokens?: number;
+  chunk_tokens?: number;
+  overlapTokens?: number;
+  overlap_tokens?: number;
+}
+
+export function ingestReceiptDocuments(
+  documents: ContextReceiptInput,
+  options?: ContextReceiptOptions,
+): Record<string, unknown>;
+
+export function selectReceiptContext(
+  index: Record<string, unknown>,
+  options: ContextReceiptOptions & { query: string },
+): Record<string, unknown>;
+
+export function createContextReceipt(
+  documents: ContextReceiptInput,
+  options: ContextReceiptOptions & { query: string },
+): Record<string, unknown>;
+
+export function renderContextReceipt(receipt: Record<string, unknown>): string;
+export function explainReceiptOmission(receipt: Record<string, unknown>, chunkId: string): string;

package/index.js

@@ -65,6 +65,25 @@ const { ValueTracker, EVOLUTION_TAX_RATE, estimateCost } = require('./js/value_t
 const { exportPromoted: exportAgentSkills } = require('./js/agentskills_export');
 const { TelegramGateway, DiscordGateway, SlackGateway } = require('./js/gateways');
 const { VaultObserver } = require('./js/vault_observer');
+const {
+  createContextReceipt,
+  explainReceiptOmission,
+  ingestReceiptDocuments,
+  renderContextReceipt,
+  selectReceiptContext,
+} = require('./js/context_receipts');
+const {
+  createEntrolyMiddleware,
+  optimizeAnthropicParams,
+  optimizeGeminiParams,
+  optimizeMessages,
+  optimizeOpenAIParams,
+  optimizeRequestParams,
+  stableStringify,
+  wrapAnthropic,
+  wrapGemini,
+  wrapOpenAI,
+} = require('./js/app_sdk');
 
 function classifyQueryTransition(...args) {
   if (!classifyQueryTransitionRust) {
@@ -141,4 +160,23 @@ module.exports = {
   // Observe the shared vault — works with skills promoted by the
   // Python daemon OR any node-side orchestrator. No daemon required.
   VaultObserver,
+
+  // App SDK: middleware shape plus native provider wrappers.
+  createEntrolyMiddleware,
+  optimizeAnthropicParams,
+  optimizeGeminiParams,
+  optimizeMessages,
+  optimizeOpenAIParams,
+  optimizeRequestParams,
+  stableStringify,
+  wrapAnthropic,
+  wrapGemini,
+  wrapOpenAI,
+
+  // Context Receipts: auditable context selection receipts for JS users.
+  ingestReceiptDocuments,
+  selectReceiptContext,
+  createContextReceipt,
+  renderContextReceipt,
+  explainReceiptOmission,
 };

package/js/app_sdk.js

@@ -0,0 +1,241 @@
+// App-level SDK helpers for JavaScript/TypeScript applications.
+//
+// These helpers are dependency-free. They do not import provider SDKs or the
+// Vercel AI SDK; instead they expose plain middleware/wrapper shapes that those
+// libraries can consume. All transforms are local and preserve provider-owned
+// controls such as model, temperature, tools, tool_choice, safetySettings, and
+// thinking fields.
+
+function estimateTokens(value) {
+  if (value == null) return 0;
+  if (typeof value === 'string') return Math.ceil(value.length / 4);
+  if (Array.isArray(value)) return value.reduce((n, item) => n + estimateTokens(item), 0);
+  if (typeof value === 'object') {
+    if (typeof value.text === 'string') return estimateTokens(value.text);
+    if (typeof value.content === 'string' || Array.isArray(value.content)) {
+      return estimateTokens(value.content);
+    }
+    if (Array.isArray(value.parts)) return estimateTokens(value.parts);
+  }
+  return 0;
+}
+
+function cloneJson(value) {
+  if (value == null) return value;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map(k => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function fingerprint(value) {
+  const crypto = require('crypto');
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex').slice(0, 12);
+}
+
+function compactText(text, tokenBudget) {
+  if (typeof text !== 'string' || tokenBudget <= 0 || estimateTokens(text) <= tokenBudget) {
+    return text;
+  }
+  const maxChars = Math.max(16, tokenBudget * 4);
+  const marker = '\n...[entroly: middle omitted; request stayed local]...\n';
+  if (maxChars <= marker.length + 8) return text.slice(0, maxChars);
+  const headChars = Math.floor((maxChars - marker.length) * 0.62);
+  const tailChars = Math.max(0, maxChars - marker.length - headChars);
+  return `${text.slice(0, headChars).trimEnd()}${marker}${text.slice(-tailChars).trimStart()}`;
+}
+
+function transformContent(content, tokenBudget) {
+  if (typeof content === 'string') return compactText(content, tokenBudget);
+  if (Array.isArray(content)) {
+    return content.map(part => transformContent(part, tokenBudget));
+  }
+  if (content && typeof content === 'object') {
+    const out = { ...content };
+    if (typeof out.text === 'string') out.text = compactText(out.text, tokenBudget);
+    else if (typeof out.content === 'string' || Array.isArray(out.content)) {
+      out.content = transformContent(out.content, tokenBudget);
+    } else if (Array.isArray(out.parts)) {
+      out.parts = out.parts.map(part => transformContent(part, tokenBudget));
+    }
+    return out;
+  }
+  return content;
+}
+
+function optimizeMessages(messages, options) {
+  if (!Array.isArray(messages)) return { messages, tokensBefore: 0, tokensAfter: 0 };
+  const budget = Math.max(1, Number(options.budget || 32000));
+  const preserveLastN = Math.max(1, Number(options.preserveLastN || 4));
+  const out = cloneJson(messages);
+  let tokensBefore = estimateTokens(out);
+  if (tokensBefore <= budget) return { messages: out, tokensBefore, tokensAfter: tokensBefore };
+
+  const targetOlderTokens = Math.max(1, budget - estimateTokens(out.slice(-preserveLastN)));
+  const older = Math.max(1, out.length - preserveLastN);
+  const perOldMessageBudget = Math.max(16, Math.floor(targetOlderTokens / older));
+  for (let i = 0; i < out.length - preserveLastN; i += 1) {
+    out[i].content = transformContent(out[i].content, perOldMessageBudget);
+  }
+  return { messages: out, tokensBefore, tokensAfter: estimateTokens(out) };
+}
+
+function optimizeOpenAIParams(params, options = {}) {
+  const out = { ...params };
+  const before = estimateTokens(out.messages || out.input || out.prompt);
+  let after = before;
+  if (Array.isArray(out.messages)) {
+    const result = optimizeMessages(out.messages, options);
+    out.messages = result.messages;
+    after = result.tokensAfter;
+  } else if (typeof out.input === 'string') {
+    out.input = compactText(out.input, Number(options.budget || 32000));
+    after = estimateTokens(out.input);
+  } else if (typeof out.prompt === 'string') {
+    out.prompt = compactText(out.prompt, Number(options.budget || 32000));
+    after = estimateTokens(out.prompt);
+  }
+  return {
+    params: out,
+    decision: {
+      provider: 'openai',
+      action: after < before ? 'compress' : 'observe',
+      tokensBefore: before,
+      tokensAfter: after,
+      requestFingerprint: fingerprint(out),
+    },
+  };
+}
+
+function optimizeAnthropicParams(params, options = {}) {
+  const out = { ...params };
+  const before = estimateTokens(out.messages || out.system);
+  let after = before;
+  if (Array.isArray(out.messages)) {
+    const result = optimizeMessages(out.messages, options);
+    out.messages = result.messages;
+    after = result.tokensAfter + estimateTokens(out.system);
+  }
+  return {
+    params: out,
+    decision: {
+      provider: 'anthropic',
+      action: after < before ? 'compress' : 'observe',
+      tokensBefore: before,
+      tokensAfter: after,
+      requestFingerprint: fingerprint(out),
+    },
+  };
+}
+
+function optimizeGeminiParams(params, options = {}) {
+  const out = { ...params };
+  const contents = Array.isArray(out.contents) ? cloneJson(out.contents) : out.contents;
+  const before = estimateTokens(contents);
+  let after = before;
+  if (Array.isArray(contents)) {
+    const asMessages = contents.map(item => ({
+      role: item.role || 'user',
+      content: Array.isArray(item.parts) ? item.parts : item,
+    }));
+    const result = optimizeMessages(asMessages, options);
+    out.contents = result.messages.map(item => ({
+      role: item.role,
+      parts: Array.isArray(item.content) ? item.content : [{ text: String(item.content || '') }],
+    }));
+    after = estimateTokens(out.contents);
+  }
+  return {
+    params: out,
+    decision: {
+      provider: 'gemini',
+      action: after < before ? 'compress' : 'observe',
+      tokensBefore: before,
+      tokensAfter: after,
+      requestFingerprint: fingerprint(out),
+    },
+  };
+}
+
+function optimizeRequestParams(params, options = {}) {
+  const provider = (options.provider || '').toLowerCase();
+  if (provider === 'anthropic' || (params && Array.isArray(params.messages) && typeof params.system === 'string')) {
+    return optimizeAnthropicParams(params, options);
+  }
+  if (provider === 'gemini' || Array.isArray(params && params.contents)) {
+    return optimizeGeminiParams(params, options);
+  }
+  return optimizeOpenAIParams(params, options);
+}
+
+function createEntrolyMiddleware(options = {}) {
+  return {
+    specificationVersion: 'v3',
+    transformParams: async ({ params }) => optimizeRequestParams(params, options).params,
+    wrapGenerate: async ({ doGenerate }) => doGenerate(),
+    wrapStream: async ({ doStream }) => doStream(),
+  };
+}
+
+function wrapOpenAI(client, options = {}) {
+  return {
+    raw: client,
+    chat: {
+      completions: {
+        create: (params, ...rest) => client.chat.completions.create(
+          optimizeOpenAIParams(params, options).params,
+          ...rest,
+        ),
+      },
+    },
+    responses: client.responses ? {
+      create: (params, ...rest) => client.responses.create(
+        optimizeOpenAIParams(params, options).params,
+        ...rest,
+      ),
+    } : undefined,
+  };
+}
+
+function wrapAnthropic(client, options = {}) {
+  return {
+    raw: client,
+    messages: {
+      create: (params, ...rest) => client.messages.create(
+        optimizeAnthropicParams(params, options).params,
+        ...rest,
+      ),
+    },
+  };
+}
+
+function wrapGemini(client, options = {}) {
+  return {
+    raw: client,
+    models: {
+      generateContent: (params, ...rest) => client.models.generateContent(
+        optimizeGeminiParams(params, options).params,
+        ...rest,
+      ),
+    },
+  };
+}
+
+module.exports = {
+  createEntrolyMiddleware,
+  estimateTokens,
+  optimizeAnthropicParams,
+  optimizeGeminiParams,
+  optimizeMessages,
+  optimizeOpenAIParams,
+  optimizeRequestParams,
+  stableStringify,
+  wrapAnthropic,
+  wrapGemini,
+  wrapOpenAI,
+};

package/js/context_receipts.js

@@ -0,0 +1,443 @@
+const crypto = require('crypto');
+
+const SCHEMA_VERSION = 'context-receipt.v1';
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(String(value).replace(/\r\n/g, '\n').replace(/\r/g, '\n')).digest('hex');
+}
+
+function fingerprint(text) {
+  return `sha256:${sha256(text)}`;
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === 'object') {
+    return Object.keys(value).sort().reduce((out, key) => {
+      out[key] = stableValue(value[key]);
+      return out;
+    }, {});
+  }
+  return value;
+}
+
+function stableHash(value) {
+  return sha256(JSON.stringify(stableValue(value)));
+}
+
+function tokenize(text) {
+  return String(text)
+    .replace(/-/g, ' ')
+    .toLowerCase()
+    .match(/[a-z0-9][a-z0-9_']*/g) || [];
+}
+
+function estimateTokens(text) {
+  return Math.max(1, tokenize(text).length);
+}
+
+function titleForPath(sourcePath) {
+  const name = String(sourcePath).split(/[\\/]/).pop() || sourcePath;
+  return name.replace(/\.[^.]+$/, '').replace(/[_-]/g, ' ');
+}
+
+function normalizeDocs(documents) {
+  if (!documents) return [];
+  if (!Array.isArray(documents) && typeof documents === 'object') {
+    return Object.entries(documents).map(([sourcePath, text]) => [String(sourcePath), String(text)]);
+  }
+  return documents.map((item, idx) => {
+    if (Array.isArray(item)) return [String(item[0]), String(item[1] || '')];
+    if (item && typeof item === 'object') {
+      return [
+        String(item.source_path || item.source || item.path || `document_${idx}.txt`),
+        String(Object.prototype.hasOwnProperty.call(item, 'text') ? item.text : item.content || ''),
+      ];
+    }
+    return [`document_${idx}.txt`, String(item || '')];
+  });
+}
+
+function isHeading(line) {
+  const trimmed = line.trim();
+  return /^#{1,6}\s+/.test(trimmed)
+    || /^(section|article|clause|exhibit|schedule|addendum)\s+[A-Za-z0-9.-]+/i.test(trimmed)
+    || /^\d+(\.\d+)*\s+\S+/.test(trimmed);
+}
+
+function paragraphBlocks(text) {
+  const blocks = [];
+  let offset = 0;
+  let start = null;
+  let current = [];
+  let heading = null;
+  let page = null;
+  const flush = (end) => {
+    if (start !== null && current.length) {
+      const raw = current.join('').trim();
+      if (raw) blocks.push({ text: raw, start, end, heading, page });
+    }
+    start = null;
+    current = [];
+  };
+  for (const line of String(text).match(/[^\n]*\n|[^\n]+$/g) || []) {
+    const trimmed = line.trim();
+    const pageMatch = trimmed.match(/\bpage\s+(\d+)\b/i);
+    if (pageMatch) page = Number(pageMatch[1]);
+    if (trimmed && isHeading(trimmed)) {
+      flush(offset);
+      heading = trimmed.replace(/^#+\s*/, '');
+    }
+    if (!trimmed) {
+      flush(offset);
+    } else {
+      if (start === null) start = offset;
+      current.push(line);
+    }
+    offset += line.length;
+  }
+  flush(String(text).length);
+  return blocks;
+}
+
+function chunkDocument(sourcePath, text, documentId, docFingerprint, chunkTokens = 360) {
+  const raw = [];
+  let pending = [];
+  let start = null;
+  let end = 0;
+  let heading = null;
+  let page = null;
+  let tokens = 0;
+  const flush = () => {
+    if (start !== null && pending.length) {
+      raw.push({ text: pending.join('\n\n').trim(), start, end, heading, page });
+    }
+    pending = [];
+    start = null;
+    tokens = 0;
+  };
+  for (const block of paragraphBlocks(text)) {
+    const count = estimateTokens(block.text);
+    if (pending.length && tokens + count > chunkTokens) flush();
+    if (start === null) {
+      start = block.start;
+      heading = block.heading;
+      page = block.page;
+    }
+    pending.push(block.text);
+    end = block.end;
+    tokens += count;
+  }
+  flush();
+
+  let running = 0;
+  return raw.map((chunk, idx) => {
+    const count = estimateTokens(chunk.text);
+    const fp = fingerprint(`${docFingerprint}\n${chunk.start}:${chunk.end}\n${chunk.text}`);
+    const chunkId = `chk_${stableHash({ doc: documentId, start: chunk.start, end: chunk.end, fp }).slice(0, 12)}`;
+    const out = {
+      chunk_id: chunkId,
+      document_id: documentId,
+      source_path: sourcePath,
+      title: titleForPath(sourcePath),
+      section_heading: chunk.heading,
+      page_number: chunk.page,
+      chunk_index: idx,
+      byte_start: chunk.start,
+      byte_end: chunk.end,
+      token_start: running,
+      token_end: running + count,
+      token_count: count,
+      fingerprint: fp,
+      text: chunk.text,
+    };
+    running += count;
+    return out;
+  });
+}
+
+function ingestReceiptDocuments(documents, options = {}) {
+  const chunkTokens = Math.max(40, Number(options.chunkTokens || options.chunk_tokens || 360));
+  const normalized = normalizeDocs(documents).sort((a, b) => a[0].localeCompare(b[0]));
+  const records = [];
+  const chunks = [];
+  const sourceFingerprints = {};
+  for (const [sourcePath, text] of normalized) {
+    const docFp = fingerprint(text);
+    const documentId = `doc_${stableHash({ sourcePath, docFp }).slice(0, 12)}`;
+    const docChunks = chunkDocument(sourcePath, text, documentId, docFp, chunkTokens);
+    sourceFingerprints[sourcePath] = docFp;
+    records.push({
+      document_id: documentId,
+      source_path: sourcePath,
+      title: titleForPath(sourcePath),
+      fingerprint: docFp,
+      token_count: estimateTokens(text),
+      byte_count: Buffer.byteLength(text),
+      chunk_ids: docChunks.map((c) => c.chunk_id),
+    });
+    chunks.push(...docChunks);
+  }
+  return {
+    schema_version: SCHEMA_VERSION,
+    documents: records,
+    chunks,
+    chunk_token_limit: chunkTokens,
+    chunk_overlap: Number(options.overlapTokens || options.overlap_tokens || 32),
+    source_fingerprints: sourceFingerprints,
+  };
+}
+
+function rankChunks(index, query) {
+  const queryTerms = Array.from(new Set(tokenize(query).filter((t) => t.length > 1)));
+  const docs = index.chunks.map((chunk) => ({ chunk, terms: tokenize(chunk.text) }));
+  const df = {};
+  for (const doc of docs) {
+    for (const term of new Set(doc.terms)) df[term] = (df[term] || 0) + 1;
+  }
+  const docCount = Math.max(1, docs.length);
+  const avgLen = docs.reduce((sum, doc) => sum + doc.terms.length, 0) / docCount || 1;
+  return docs.map(({ chunk, terms }) => {
+    const tf = {};
+    for (const term of terms) tf[term] = (tf[term] || 0) + 1;
+    let lexical = 0;
+    const matched = new Set();
+    const heading = String(chunk.section_heading || '').toLowerCase();
+    const sourcePath = String(chunk.source_path || '').toLowerCase();
+    for (const term of queryTerms) {
+      const freq = tf[term] || 0;
+      const inHeading = heading.includes(term);
+      const inPath = sourcePath.includes(term);
+      if (freq || inHeading || inPath) matched.add(term);
+      const idf = Math.log((docCount - (df[term] || 0) + 0.5) / ((df[term] || 0) + 0.5) + 1);
+      if (freq) lexical += idf * ((freq * 2.2) / (freq + 1.2 * (1 - 0.75 + 0.75 * terms.length / Math.max(1, avgLen))));
+      if (inHeading) lexical += idf * 2.5;
+      if (inPath) lexical += idf * 1.5;
+    }
+    lexical *= 1 + matched.size / Math.max(1, queryTerms.length);
+    const reasons = matched.size ? [`lexical match: ${Array.from(matched).slice(0, 8).join(', ')}`] : ['low lexical overlap; retained as lower-ranked candidate'];
+    if (/(as defined in|subject to|pursuant to|see section)/i.test(chunk.text)) reasons.push('contains explicit dependency/reference language');
+    return {
+      chunk_id: chunk.chunk_id,
+      lexical_score: Number(lexical.toFixed(6)),
+      semantic_score: 0,
+      rerank_score: 0,
+      final_score: Number(lexical.toFixed(6)),
+      reasons,
+    };
+  }).sort((a, b) => b.final_score - a.final_score || a.chunk_id.localeCompare(b.chunk_id));
+}
+
+function norm(value) {
+  return String(value).toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+
+function detectDependencies(index) {
+  const termDefs = new Map();
+  for (const chunk of index.chunks) {
+    for (const match of chunk.text.matchAll(/"([^"]{2,80})"\s+(means|shall mean|is defined as|refers to)\b/gi)) {
+      const term = norm(match[1]);
+      if (!termDefs.has(term)) termDefs.set(term, []);
+      termDefs.get(term).push(chunk);
+    }
+  }
+  const links = [];
+  const seen = new Set();
+  const add = (source, target, relationType, evidence) => {
+    const key = `${source.chunk_id}:${target ? target.chunk_id : ''}:${relationType}:${evidence}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    links.push({
+      source_chunk_id: source.chunk_id,
+      target_chunk_id: target ? target.chunk_id : null,
+      relation_type: relationType,
+      evidence,
+      source_document_id: source.document_id,
+      target_document_id: target ? target.document_id : null,
+      resolved: Boolean(target),
+      warning: target ? null : `Unresolved reference: ${evidence}`,
+    });
+  };
+  const resolve = (source, label) => {
+    const target = norm(label);
+    return index.chunks.find((chunk) => chunk.chunk_id !== source.chunk_id && (
+      norm(chunk.section_heading || '').includes(target)
+      || norm(chunk.source_path).includes(target)
+      || norm(chunk.text.slice(0, 300)).includes(target)
+    ));
+  };
+  for (const chunk of index.chunks) {
+    const lower = norm(chunk.text);
+    for (const [term, defs] of termDefs.entries()) {
+      if (lower.includes(term) && defs.every((def) => def.chunk_id !== chunk.chunk_id)) add(chunk, defs[0], 'defined_term', term);
+    }
+    const patterns = [
+      ['defined_in', /\bas defined in\s+((section|clause|article|exhibit|schedule|addendum)\s+[A-Za-z0-9.-]+)/gi],
+      ['subject_to', /\bsubject to\s+((section|clause|article|exhibit|schedule|addendum)\s+[A-Za-z0-9.-]+)/gi],
+      ['pursuant_to', /\bpursuant to\s+((section|clause|article|exhibit|schedule|addendum)\s+[A-Za-z0-9.-]+)/gi],
+      ['see_reference', /\bsee\s+((section|clause|article|exhibit|schedule|addendum)\s+[A-Za-z0-9.-]+)/gi],
+    ];
+    for (const [relationType, re] of patterns) {
+      for (const match of chunk.text.matchAll(re)) add(chunk, resolve(chunk, match[1]), relationType, match[1]);
+    }
+  }
+  return links;
+}
+
+function selectReceiptContext(index, options = {}) {
+  const query = options.query || '';
+  const tokenBudget = Number(options.tokenBudget || options.token_budget || options.budget || 8000);
+  const ranked = rankChunks(index, query);
+  const deps = detectDependencies(index);
+  const chunksById = Object.fromEntries(index.chunks.map((chunk) => [chunk.chunk_id, chunk]));
+  const selectedIds = [];
+  let selectedTokens = 0;
+  const warnings = [];
+  const add = (chunkId) => {
+    const chunk = chunksById[chunkId];
+    if (!chunk || selectedIds.includes(chunkId) || selectedTokens + chunk.token_count > tokenBudget) return false;
+    selectedIds.push(chunkId);
+    selectedTokens += chunk.token_count;
+    return true;
+  };
+  for (const rank of ranked) {
+    if (!add(rank.chunk_id)) continue;
+    for (const dep of deps.filter((d) => d.source_chunk_id === rank.chunk_id)) {
+      if (dep.target_chunk_id && !selectedIds.includes(dep.target_chunk_id) && !add(dep.target_chunk_id)) {
+        warnings.push(`Dependency not included due to budget: ${rank.chunk_id} -> ${dep.target_chunk_id} (${dep.relation_type})`);
+      } else if (!dep.resolved && dep.warning) {
+        warnings.push(dep.warning);
+      }
+    }
+  }
+  const rankById = Object.fromEntries(ranked.map((rank) => [rank.chunk_id, rank]));
+  const selected_context = selectedIds.map((chunkId) => {
+    const chunk = chunksById[chunkId];
+    const sourceDeps = deps.filter((d) => d.source_chunk_id === chunkId);
+    return {
+      chunk_id: chunk.chunk_id,
+      source_path: chunk.source_path,
+      section_heading: chunk.section_heading || null,
+      page_number: chunk.page_number || null,
+      byte_start: chunk.byte_start,
+      byte_end: chunk.byte_end,
+      token_start: chunk.token_start,
+      token_end: chunk.token_end,
+      token_count: chunk.token_count,
+      score: rankById[chunkId] ? rankById[chunkId].final_score : 0,
+      reasons: rankById[chunkId] ? rankById[chunkId].reasons : ['included as dependency'],
+      dependencies_included: sourceDeps.map((d) => d.target_chunk_id).filter((id) => id && selectedIds.includes(id)),
+      dependencies_missing: sourceDeps.map((d) => d.target_chunk_id || d.evidence).filter((id) => !selectedIds.includes(id)),
+      fingerprint: chunk.fingerprint,
+      text: chunk.text,
+    };
+  });
+  const omitted_context = ranked.filter((rank) => !selectedIds.includes(rank.chunk_id)).slice(0, 20).map((rank) => {
+    const chunk = chunksById[rank.chunk_id];
+    return {
+      chunk_id: chunk.chunk_id,
+      source_path: chunk.source_path,
+      section_heading: chunk.section_heading || null,
+      page_number: chunk.page_number || null,
+      token_count: chunk.token_count,
+      score: rank.final_score,
+      reasons: rank.reasons,
+      omission_reason: selectedTokens + chunk.token_count > tokenBudget ? 'budget_limit' : 'lower ranked than selected context under token budget',
+      fingerprint: chunk.fingerprint,
+      text_preview: chunk.text.replace(/\s+/g, ' ').slice(0, 240),
+    };
+  });
+  const sourceTokens = index.chunks.reduce((sum, chunk) => sum + chunk.token_count, 0);
+  const selectedToSource = selectedTokens / Math.max(1, sourceTokens);
+  const relevantOmitted = omitted_context.filter((item) => item.score > 0).length;
+  if (relevantOmitted) warnings.push(`${relevantOmitted} relevant chunk(s) were omitted; inspect omitted_context.`);
+  const unresolved = deps.filter((dep) => !dep.resolved).length;
+  if (unresolved) warnings.push(`${unresolved} dependency reference(s) could not be resolved to an ingested chunk.`);
+  const ranking_reasons = Object.fromEntries(ranked.map((rank) => [rank.chunk_id, rank.reasons]));
+  const source_fingerprints = {
+    documents: Object.fromEntries(index.documents.map((doc) => [doc.source_path, doc.fingerprint])),
+    chunks: Object.fromEntries(index.chunks.map((chunk) => [chunk.chunk_id, chunk.fingerprint])),
+  };
+  const risk_summary = {
+    coverage_score: Number((0.45 * selectedToSource + 0.35 * (selected_context.length / Math.max(1, index.chunks.length)) + 0.2 * (1 - unresolved / Math.max(1, deps.length))).toFixed(6)),
+    review_level: relevantOmitted || unresolved ? 'medium' : 'low',
+    selected_chunks: selected_context.length,
+    total_chunks: index.chunks.length,
+    omitted_relevant_chunks: relevantOmitted,
+    unresolved_dependency_count: unresolved,
+    controls: {
+      dependency_closure: unresolved ? 'partial' : 'complete',
+      omitted_evidence_pressure: relevantOmitted ? 'medium' : 'low',
+      replayable_fingerprints: true,
+      local_no_llm_judgment: true,
+    },
+  };
+  const payload = {
+    schema_version: SCHEMA_VERSION,
+    query,
+    token_budget: tokenBudget,
+    selected_context,
+    omitted_context,
+    dependency_links: deps,
+    ranking_reasons,
+    compression_ratio: {
+      source_tokens: sourceTokens,
+      selected_tokens: selectedTokens,
+      tokens_saved: Math.max(0, sourceTokens - selectedTokens),
+      selected_to_source_ratio: Number(selectedToSource.toFixed(6)),
+      source_to_selected_ratio: Number((sourceTokens / Math.max(1, selectedTokens)).toFixed(6)),
+      reduction_pct: Number(((1 - selectedToSource) * 100).toFixed(3)),
+    },
+    source_fingerprints,
+    risk_summary,
+    warnings: Array.from(new Set(warnings)),
+    outcome_links: [],
+  };
+  const reproducibility_hash = stableHash(payload);
+  return { receipt_id: `cr_${reproducibility_hash.slice(0, 12)}`, ...payload, reproducibility_hash };
+}
+
+function createContextReceipt(documents, options = {}) {
+  return selectReceiptContext(ingestReceiptDocuments(documents, options), options);
+}
+
+function renderContextReceipt(receipt) {
+  const lines = [
+    `# Context Receipt ${receipt.receipt_id}`,
+    '',
+    `Query: \`${receipt.query}\``,
+    '',
+    '## Coverage And Risk Controls',
+    '',
+    `- Coverage score: ${receipt.risk_summary.coverage_score}`,
+    `- Review level: ${receipt.risk_summary.review_level}`,
+    `- Dependency closure: ${receipt.risk_summary.controls.dependency_closure}`,
+    '',
+    '## Included Context',
+    '',
+  ];
+  for (const item of receipt.selected_context || []) {
+    lines.push(`### ${item.chunk_id}`, `- Source: \`${item.source_path}\``, `- Why: ${item.reasons.join('; ')}`, '');
+  }
+  lines.push('## Omitted Context', '');
+  for (const item of receipt.omitted_context || []) {
+    lines.push(`### ${item.chunk_id}`, `- Why omitted: ${item.omission_reason}`, `- Preview: ${item.text_preview}`, '');
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function explainReceiptOmission(receipt, chunkId) {
+  const omitted = (receipt.omitted_context || []).find((item) => item.chunk_id === chunkId);
+  if (omitted) return `${chunkId} was omitted from ${omitted.source_path}: ${omitted.omission_reason}.`;
+  if ((receipt.selected_context || []).some((item) => item.chunk_id === chunkId)) return `${chunkId} was not omitted; it is present in selected_context.`;
+  return `${chunkId} is not present in this receipt.`;
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  ingestReceiptDocuments,
+  selectReceiptContext,
+  createContextReceipt,
+  renderContextReceipt,
+  explainReceiptOmission,
+};

package/js/server.js

@@ -89,11 +89,10 @@ class EntrolyMCPServer {
     this.flowOrchestrator = new FlowOrchestrator(this.vault, this.epistemicRouter, this.beliefCompiler, this.verifier, this.changePipe, this.sourceDir);
     this.workspaceListener = new WorkspaceChangeListener(this.vault, this.beliefCompiler, this.verifier, this.changePipe, this.sourceDir);
 
-    // Try loading persistent index
-    if (loadIndex(this.engine, this.indexPath)) {
-      const n = this.engine.fragment_count();
-      this._log(`Loaded persistent index: ${n} fragments`);
-    }
+    // Persistent index loads LAZILY (first tool use / deferred warm-up) so
+    // construction and the MCP handshake stay instant — never block the client's
+    // ~5-10s connect window on a cold index read. npm twin of the pip/MCP fix.
+    this._indexLoaded = false;
 
     this._buffer = '';
     this._initialized = false;
@@ -101,6 +100,55 @@ class EntrolyMCPServer {
 
   _log(msg) { process.stderr.write(`${new Date().toISOString()} [entroly] ${msg}\n`); }
 
+  // Lazily perform the full one-time warm-up (persisted index load + auto-index
+  // + background daemons) on the calling thread. Idempotent: the FIRST tool call
+  // pays this cost; every later call is an instant no-op.
+  //
+  // Crucially this is NEVER called from the MCP handshake (initialize /
+  // tools/list) and NEVER from a timer — only from handleTool. autoIndex is a
+  // synchronous repo scan, so a setImmediate/setTimeout defer would still block
+  // the single-threaded event loop and stall the handshake (a timer can even
+  // fire before the first request arrives). Triggering strictly on the first
+  // tools/call guarantees an instant handshake for every client regardless of
+  // message ordering, with no race — the npm twin of the pip/MCP instant-start
+  // fix ("first request pays"). Node is single-threaded, so there is also no
+  // borrow race (unlike the pip background path).
+  _ensureWarm() {
+    if (this._indexLoaded) return;
+    this._indexLoaded = true; // set before work so a throw cannot cause re-entry
+
+    // 1) Restore the persisted index BEFORE auto-index — auto-index skips when
+    //    the engine already has fragments, and a later load would otherwise
+    //    overwrite freshly ingested state.
+    try {
+      if (loadIndex(this.engine, this.indexPath)) {
+        this._log(`Loaded persistent index: ${this.engine.fragment_count()} fragments`);
+      }
+    } catch (e) {
+      this._log(`Index load failed (non-fatal): ${e.message}`);
+    }
+
+    // 2) Auto-index the project (internally skips when already warm) and start
+    //    the incremental file watcher.
+    try {
+      const result = autoIndex(this.engine);
+      if (result.status === 'indexed') {
+        this._log(`Auto-indexed ${result.files_indexed} files (${result.total_tokens.toLocaleString()} tokens) in ${result.duration_s}s`);
+      }
+      startIncrementalWatcher(this.engine);
+    } catch (e) {
+      this._log(`Auto-index failed (non-fatal): ${e.message}`);
+    }
+
+    // 3) Start the autotune daemon — hot-reloads weights from tuning_config.json.
+    try {
+      const tid = startAutotuneDaemon(this.engine);
+      if (tid) this._log('Autotune daemon started (hot-reload every 30s)');
+    } catch (e) {
+      this._log(`Autotune: failed to start daemon: ${e.message}`);
+    }
+  }
+
   _projectDir(candidate = '') {
     const resolved = resolveProjectDirectory(this.sourceDir, candidate || '.');
     if (!resolved) throw new Error(`Path must remain within project root: ${candidate}`);
@@ -166,6 +214,7 @@ class EntrolyMCPServer {
 
   // ── Tool Handlers (36 tools) ──
   handleTool(name, args) {
+    this._ensureWarm(); // lazy one-time index load; instant no-op once warm
     switch (name) {
       // ── Core Engine Tools ──
       case 'remember_fragment':
@@ -482,33 +531,15 @@ class EntrolyMCPServer {
   async run() {
     this._log(`Starting Entroly MCP server v${this.config.serverVersion} (Wasm engine)`);
 
-    // Auto-index on startup
-    try {
-      const result = autoIndex(this.engine);
-      if (result.status === 'indexed') {
-        this._log(`Auto-indexed ${result.files_indexed} files (${result.total_tokens.toLocaleString()} tokens) in ${result.duration_s}s`);
-      }
-      startIncrementalWatcher(this.engine);
-    } catch (e) {
-      this._log(`Auto-index failed (non-fatal): ${e.message}`);
-    }
-
-    // Start autotune daemon — reads tuning_config.json, hot-reloads weights
-    try {
-      const tid = startAutotuneDaemon(this.engine);
-      if (tid) this._log('Autotune daemon started (hot-reload every 30s)');
-    } catch (e) {
-      this._log(`Autotune: failed to start daemon: ${e.message}`);
-    }
-
-    // Graceful shutdown
-    process.on('SIGTERM', () => {
-      this._log('Shutdown — persisting state...');
-      try { persistIndex(this.engine, this.indexPath); } catch {}
-      process.exit(0);
-    });
-
-    // Read JSONRPC from stdin
+    // Attach the stdio transport and DO NOT warm up here. The MCP handshake
+    // (initialize / tools/list) is answered immediately; the heavy one-time
+    // warm-up (index load + auto-index + daemons) is deferred to the first
+    // actual tool call (handleTool -> _ensureWarm). autoIndex is a synchronous
+    // repo scan, so warming on a timer would still block the single-threaded
+    // event loop and stall the handshake (the timer can even fire before the
+    // first request arrives). Triggering strictly on the first tools/call gives
+    // an instant handshake for every client with no race — the npm twin of the
+    // pip/MCP instant-start fix (cold start ~6.5s → instant handshake).
     process.stdin.setEncoding('utf-8');
     process.stdin.on('data', (chunk) => {
       this._buffer += chunk;
@@ -516,7 +547,15 @@ class EntrolyMCPServer {
     });
     process.stdin.on('end', () => {
       this._log('stdin closed — shutting down');
-      try { persistIndex(this.engine, this.indexPath); } catch {}
+      if (this._indexLoaded) { try { persistIndex(this.engine, this.indexPath); } catch {} }
+    });
+
+    // Graceful shutdown — only persist if we actually warmed (loaded) the index,
+    // otherwise an early shutdown would overwrite the good index with empty state.
+    process.on('SIGTERM', () => {
+      this._log('Shutdown — persisting state...');
+      if (this._indexLoaded) { try { persistIndex(this.engine, this.indexPath); } catch {} }
+      process.exit(0);
     });
   }
 

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "entroly-wasm",
-  "version": "1.0.16",
-  "description": "Local proxy that cuts your Claude / OpenAI / Gemini bill 70%+. Drop-in for Cursor, Claude Code, Codex, Aider — 30 seconds, no code changes. Pure WebAssembly, no Python dependency.",
+  "version": "1.0.18",
+  "description": "Auditable context control plane for AI agents: context receipts, local optimization, MCP, and app SDK helpers. Pure WebAssembly, no Python dependency.",
   "main": "index.js",
-  "types": "pkg/entroly_wasm.d.ts",
+  "types": "index.d.ts",
   "bin": {
     "entroly-wasm": "./bin/entroly-wasm.js"
   },
@@ -11,6 +11,7 @@
     "LICENSE",
     "NOTICE",
     "index.js",
+    "index.d.ts",
     "data/tuning_defaults.json",
     "pkg/entroly_wasm_bg.wasm",
     "pkg/entroly_wasm.js",
@@ -29,6 +30,8 @@
     "js/skills.js",
     "js/multimodal.js",
     "js/value_tracker.js",
+    "js/app_sdk.js",
+    "js/context_receipts.js",
     "js/agentskills_export.js",
     "js/gateways.js",
     "js/vault_observer.js",
@@ -49,6 +52,8 @@
   },
   "keywords": [
     "entroly",
+    "context-receipts",
+    "context-control-plane",
     "context-optimization",
     "mcp",
     "mcp-server",