@torknetwork/governance-contract 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tork Network Pty Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cache/exact-key.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Tenant-scoped cache identities keep answer content private and invalidate
+ * when sources or generation settings change. Role-dependent answers bypass
+ * caching; embedding identities preserve the exact text sent to the model.
+ */
+import type { Surface } from '../receipt';
+export declare const EXACT_CACHE_KEY_VERSION = "v1";
+export interface SourceVersion {
+    document_id: string;
+    version: string;
+}
+export interface ExactCacheKeyInput {
+    org_id: string;
+    product: string;
+    surface: Surface;
+    question: string;
+    model: string;
+    prompt_version: string;
+    config_version: string;
+    /** The documents (and their versions) the answer was built from. */
+    source_versions: readonly SourceVersion[];
+    /** True when the answer depends on the asker's role or clearance — never cached. */
+    role_dependent: boolean;
+    locale?: string;
+}
+export declare function normaliseQuestion(q: string): string;
+export declare function buildExactCacheKey(input: ExactCacheKeyInput): Promise<string | null>;
+export declare function buildEmbeddingCacheKey(input: {
+    org_id: string;
+    model: string;
+    content: string;
+}): Promise<string>;
+//# sourceMappingURL=exact-key.d.ts.map

package/dist/cache/exact-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exact-key.d.ts","sourceRoot":"","sources":["../../src/cache/exact-key.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C,MAAM,WAAW,aAAa;IAAG,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AAEvE,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,eAAe,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,oFAAoF;IACpF,cAAc,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD;AAUD,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA0B1F;AAED,wBAAsB,sBAAsB,CAAC,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAOvH"}

package/dist/cache/exact-key.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Tenant-scoped cache identities keep answer content private and invalidate
+ * when sources or generation settings change. Role-dependent answers bypass
+ * caching; embedding identities preserve the exact text sent to the model.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXACT_CACHE_KEY_VERSION = void 0;
+exports.normaliseQuestion = normaliseQuestion;
+exports.buildExactCacheKey = buildExactCacheKey;
+exports.buildEmbeddingCacheKey = buildEmbeddingCacheKey;
+const canonical_1 = require("../canonical");
+exports.EXACT_CACHE_KEY_VERSION = 'v1';
+const ORG_ID = /^[A-Za-z0-9_-]{1,64}$/;
+function normaliseQuestion(q) {
+    return q.normalize('NFKC').trim().replace(/\s+/g, ' ').toLowerCase().replace(/[?!.\s]+$/g, '');
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function compare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+async function buildExactCacheKey(input) {
+    try {
+        if (input.role_dependent || !ORG_ID.test(input.org_id))
+            return null;
+        const q = normaliseQuestion(input.question);
+        if (!q || ![input.product, input.model, input.prompt_version, input.config_version].every(nonEmpty))
+            return null;
+        const sources = [];
+        const seen = new Set();
+        for (const source of input.source_versions) {
+            if (!nonEmpty(source.document_id) || !nonEmpty(source.version))
+                return null;
+            const pair = [source.document_id, source.version];
+            const identity = (0, canonical_1.canonicalJson)(pair);
+            if (!seen.has(identity)) {
+                seen.add(identity);
+                sources.push(pair);
+            }
+        }
+        sources.sort((a, b) => compare(a[0], b[0]) || compare(a[1], b[1]));
+        const hash = await (0, canonical_1.sha256Hex)((0, canonical_1.canonicalJson)({
+            product: input.product, surface: input.surface, q, model: input.model,
+            prompt_version: input.prompt_version, config_version: input.config_version,
+            locale: input.locale ?? null, sources,
+        }));
+        return `tork:xc:${exports.EXACT_CACHE_KEY_VERSION}:${input.org_id}:${hash}`;
+    }
+    catch {
+        return null; // Invalid input or unavailable hashing makes caching a miss.
+    }
+}
+async function buildEmbeddingCacheKey(input) {
+    if (!ORG_ID.test(input.org_id) || !nonEmpty(input.model)) {
+        throw new TypeError('Embedding cache requires a valid org_id and non-empty model');
+    }
+    const modelHash = await (0, canonical_1.sha256Hex)(input.model);
+    const contentHash = await (0, canonical_1.sha256Hex)(input.content);
+    return `tork:emb:${exports.EXACT_CACHE_KEY_VERSION}:${input.org_id}:${modelHash.slice(0, 16)}:${contentHash}`;
+}
+//# sourceMappingURL=exact-key.js.map

package/dist/cache/exact-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exact-key.js","sourceRoot":"","sources":["../../src/cache/exact-key.ts"],"names":[],"mappings":"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"}

package/dist/cache/exact.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Exact-match answer cache and embedding cache, on any Redis-like store
+ * (Upstash Redis in production: `new Redis({...})` satisfies CacheStore).
+ *
+ * Rules enforced here, not left to the caller:
+ *  - keys are scoped per tenant and include the source-document versions the
+ *    answer used, so publishing a new version invalidates by construction
+ *    (see exact-key.ts);
+ *  - an answer that depends on the asker's role or clearance is NEVER cached
+ *    (the key builder returns null and nothing is read or written);
+ *  - the tenant's `exact_cache` switch gates every read and write;
+ *  - a cache hit still produces a receipt: `cachedAnswer` calls `onReceipt`
+ *    on hits and misses alike, with `cache_hit` set on hits.
+ *
+ * Flow: retrieve first (cheap), then look up with the retrieved documents'
+ * versions, and only generate on a miss.
+ */
+import type { TenantSettings } from '../switches';
+import type { CacheHit } from '../receipt';
+import { type ExactCacheKeyInput } from './exact-key';
+export interface CacheStore {
+    get(key: string): Promise<unknown>;
+    set(key: string, value: string, opts?: {
+        ex?: number;
+    }): Promise<unknown>;
+}
+export interface CachedAnswerResult<T> {
+    value: T;
+    cache_hit: CacheHit | null;
+}
+export declare function cachedAnswer<T>(opts: {
+    store: CacheStore | null | undefined;
+    settings: TenantSettings;
+    key: ExactCacheKeyInput;
+    compute: () => Promise<T>;
+    /** Always called — on a hit with cache_hit 'exact', on a miss with null. */
+    onReceipt: (r: {
+        cache_hit: CacheHit | null;
+    }) => Promise<void> | void;
+    ttlSeconds?: number;
+}): Promise<CachedAnswerResult<T>>;
+/** Embeddings cached by content hash, per tenant and per model. */
+export declare function cachedEmbedding(opts: {
+    store: CacheStore | null | undefined;
+    settings: TenantSettings;
+    model: string;
+    content: string;
+    embed: (content: string) => Promise<number[]>;
+    ttlSeconds?: number;
+}): Promise<{
+    embedding: number[];
+    cache_hit: boolean;
+}>;
+//# sourceMappingURL=exact.d.ts.map

package/dist/cache/exact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exact.d.ts","sourceRoot":"","sources":["../../src/cache/exact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAA8C,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAElG,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3E;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,KAAK,EAAE,CAAC,CAAC;IACT,SAAS,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC5B;AAiBD,wBAAsB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE;IAC1C,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC;IACrC,QAAQ,EAAE,cAAc,CAAC;IACzB,GAAG,EAAE,kBAAkB,CAAC;IACxB,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IAC1B,4EAA4E;IAC5E,SAAS,EAAE,CAAC,CAAC,EAAE;QAAE,SAAS,EAAE,QAAQ,GAAG,IAAI,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CA2BjC;AAED,mEAAmE;AACnE,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC;IACrC,QAAQ,EAAE,cAAc,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAAC,CAwBvD"}

package/dist/cache/exact.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * Exact-match answer cache and embedding cache, on any Redis-like store
+ * (Upstash Redis in production: `new Redis({...})` satisfies CacheStore).
+ *
+ * Rules enforced here, not left to the caller:
+ *  - keys are scoped per tenant and include the source-document versions the
+ *    answer used, so publishing a new version invalidates by construction
+ *    (see exact-key.ts);
+ *  - an answer that depends on the asker's role or clearance is NEVER cached
+ *    (the key builder returns null and nothing is read or written);
+ *  - the tenant's `exact_cache` switch gates every read and write;
+ *  - a cache hit still produces a receipt: `cachedAnswer` calls `onReceipt`
+ *    on hits and misses alike, with `cache_hit` set on hits.
+ *
+ * Flow: retrieve first (cheap), then look up with the retrieved documents'
+ * versions, and only generate on a miss.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cachedAnswer = cachedAnswer;
+exports.cachedEmbedding = cachedEmbedding;
+const exact_key_1 = require("./exact-key");
+const DEFAULT_TTL_SECONDS = 24 * 60 * 60;
+function decode(raw) {
+    if (raw === null || raw === undefined)
+        return undefined;
+    // Upstash auto-deserialises JSON; other clients return the string.
+    if (typeof raw === 'string') {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return raw;
+}
+async function cachedAnswer(opts) {
+    const enabled = opts.settings.switches.exact_cache && !!opts.store;
+    const key = enabled ? await (0, exact_key_1.buildExactCacheKey)(opts.key) : null;
+    if (key && opts.store) {
+        let hit;
+        try {
+            hit = decode(await opts.store.get(key));
+        }
+        catch {
+            hit = undefined; // a cache outage is a miss, never an error
+        }
+        if (hit !== undefined) {
+            await opts.onReceipt({ cache_hit: 'exact' });
+            return { value: hit, cache_hit: 'exact' };
+        }
+    }
+    const value = await opts.compute();
+    if (key && opts.store) {
+        try {
+            await opts.store.set(key, JSON.stringify(value), { ex: opts.ttlSeconds ?? DEFAULT_TTL_SECONDS });
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    await opts.onReceipt({ cache_hit: null });
+    return { value, cache_hit: null };
+}
+/** Embeddings cached by content hash, per tenant and per model. */
+async function cachedEmbedding(opts) {
+    if (!opts.store || !opts.settings.switches.exact_cache) {
+        return { embedding: await opts.embed(opts.content), cache_hit: false };
+    }
+    let key;
+    try {
+        key = await (0, exact_key_1.buildEmbeddingCacheKey)({ org_id: opts.settings.org_id, model: opts.model, content: opts.content });
+    }
+    catch {
+        // An org id the key builder will not scope is never cached, never an error.
+        return { embedding: await opts.embed(opts.content), cache_hit: false };
+    }
+    try {
+        const hit = decode(await opts.store.get(key));
+        if (Array.isArray(hit))
+            return { embedding: hit, cache_hit: true };
+    }
+    catch {
+        /* miss */
+    }
+    const embedding = await opts.embed(opts.content);
+    try {
+        await opts.store.set(key, JSON.stringify(embedding), { ex: opts.ttlSeconds ?? 7 * DEFAULT_TTL_SECONDS });
+    }
+    catch {
+        /* best effort */
+    }
+    return { embedding, cache_hit: false };
+}
+//# sourceMappingURL=exact.js.map

package/dist/cache/exact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exact.js","sourceRoot":"","sources":["../../src/cache/exact.ts"],"names":[],"mappings":"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"}

package/dist/cache/gateway.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Vercel AI Gateway prompt caching.
+ *
+ * `providerOptions.gateway.caching = 'auto'` asks the Gateway to apply each
+ * provider's own prompt-caching strategy (Vercel docs, "Automatic caching",
+ * read 9 Oct 2026). `x-session-affinity` carries a stable value per
+ * conversation so turns of one conversation land where the cached prefix is.
+ *
+ * The affinity value is a SHA-256 of (org_id, conversation_id), never the raw
+ * conversation id: it leaves Tork's boundary in a request header.
+ */
+import type { TenantSettings } from '../switches';
+export interface GatewayCallOptions {
+    providerOptions?: {
+        gateway: {
+            caching: 'auto';
+        };
+    };
+    headers?: Record<string, string>;
+}
+export declare function sessionAffinity(org_id: string, conversation_id: string): Promise<string>;
+/**
+ * Options to spread into an AI SDK call through the Gateway. Returns `{}`
+ * when the tenant's `gateway_caching` switch is off.
+ */
+export declare function gatewayCallOptions(settings: TenantSettings, conversation_id: string | null | undefined): Promise<GatewayCallOptions>;
+//# sourceMappingURL=gateway.d.ts.map

package/dist/cache/gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../src/cache/gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,MAAM,WAAW,kBAAkB;IACjC,eAAe,CAAC,EAAE;QAAE,OAAO,EAAE;YAAE,OAAO,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE9F;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAK1I"}

package/dist/cache/gateway.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Vercel AI Gateway prompt caching.
+ *
+ * `providerOptions.gateway.caching = 'auto'` asks the Gateway to apply each
+ * provider's own prompt-caching strategy (Vercel docs, "Automatic caching",
+ * read 9 Oct 2026). `x-session-affinity` carries a stable value per
+ * conversation so turns of one conversation land where the cached prefix is.
+ *
+ * The affinity value is a SHA-256 of (org_id, conversation_id), never the raw
+ * conversation id: it leaves Tork's boundary in a request header.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionAffinity = sessionAffinity;
+exports.gatewayCallOptions = gatewayCallOptions;
+const canonical_1 = require("../canonical");
+async function sessionAffinity(org_id, conversation_id) {
+    return (await (0, canonical_1.sha256Hex)(`tork-affinity:v1:${org_id}:${conversation_id}`)).slice(0, 32);
+}
+/**
+ * Options to spread into an AI SDK call through the Gateway. Returns `{}`
+ * when the tenant's `gateway_caching` switch is off.
+ */
+async function gatewayCallOptions(settings, conversation_id) {
+    if (!settings.switches.gateway_caching)
+        return {};
+    const out = { providerOptions: { gateway: { caching: 'auto' } } };
+    if (conversation_id)
+        out.headers = { 'x-session-affinity': await sessionAffinity(settings.org_id, conversation_id) };
+    return out;
+}
+//# sourceMappingURL=gateway.js.map

package/dist/cache/gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.js","sourceRoot":"","sources":["../../src/cache/gateway.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;AAUH,0CAEC;AAMD,gDAKC;AArBD,4CAAyC;AAQlC,KAAK,UAAU,eAAe,CAAC,MAAc,EAAE,eAAuB;IAC3E,OAAO,CAAC,MAAM,IAAA,qBAAS,EAAC,oBAAoB,MAAM,IAAI,eAAe,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACzF,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,kBAAkB,CAAC,QAAwB,EAAE,eAA0C;IAC3G,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,eAAe;QAAE,OAAO,EAAE,CAAC;IAClD,MAAM,GAAG,GAAuB,EAAE,eAAe,EAAE,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACtF,IAAI,eAAe;QAAE,GAAG,CAAC,OAAO,GAAG,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC,EAAE,CAAC;IACrH,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/cache/semantic.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Semantic cache slot (Upstash `@upstash/semantic-cache`). OFF by default.
+ *
+ * Allowed only when ALL hold:
+ *  - the tenant's `semantic_cache` switch is on;
+ *  - the surface is `website_widget` (public content, same answer for every
+ *    visitor) — never a product panel, voice or API surface;
+ *  - the answer is not role- or clearance-dependent;
+ *  - the similarity threshold is at least 0.95.
+ *
+ * The package is not a dependency: the product constructs
+ * `new SemanticCache({ index, minProximity, namespace })` and passes it in as
+ * a SemanticCacheStore. `semanticCacheNamespace` gives the per-tenant
+ * namespace to construct it with.
+ */
+import type { TenantSettings } from '../switches';
+import type { Surface } from '../receipt';
+export declare const MIN_SEMANTIC_THRESHOLD = 0.95;
+export interface SemanticCacheStore {
+    get(question: string): Promise<string | undefined | null>;
+    set(question: string, answer: string): Promise<unknown>;
+}
+export declare class SemanticCacheRefused extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export declare function semanticCacheNamespace(org_id: string, source_versions_digest: string): string;
+/** Why the semantic cache may not be used, or null when it may. */
+export declare function semanticCacheRefusal(opts: {
+    settings: TenantSettings;
+    surface: Surface;
+    role_dependent: boolean;
+    threshold: number;
+}): string | null;
+export declare class GuardedSemanticCache {
+    private readonly store;
+    private readonly opts;
+    constructor(store: SemanticCacheStore, opts: {
+        settings: TenantSettings;
+        surface: Surface;
+        threshold: number;
+    });
+    get(question: string, role_dependent: boolean): Promise<string | null>;
+    set(question: string, answer: string, role_dependent: boolean): Promise<boolean>;
+}
+//# sourceMappingURL=semantic.d.ts.map

package/dist/cache/semantic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../src/cache/semantic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC;IAC1D,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzD;AAED,qBAAa,oBAAqB,SAAQ,KAAK;aACjB,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAI3C;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,sBAAsB,EAAE,MAAM,GAAG,MAAM,CAE7F;AAED,mEAAmE;AACnE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,GAAG,IAAI,CAMhB;AAED,qBAAa,oBAAoB;IAE7B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBADJ,KAAK,EAAE,kBAAkB,EACzB,IAAI,EAAE;QAAE,QAAQ,EAAE,cAAc,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;IAQpF,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAStE,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;CASvF"}

package/dist/cache/semantic.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Semantic cache slot (Upstash `@upstash/semantic-cache`). OFF by default.
+ *
+ * Allowed only when ALL hold:
+ *  - the tenant's `semantic_cache` switch is on;
+ *  - the surface is `website_widget` (public content, same answer for every
+ *    visitor) — never a product panel, voice or API surface;
+ *  - the answer is not role- or clearance-dependent;
+ *  - the similarity threshold is at least 0.95.
+ *
+ * The package is not a dependency: the product constructs
+ * `new SemanticCache({ index, minProximity, namespace })` and passes it in as
+ * a SemanticCacheStore. `semanticCacheNamespace` gives the per-tenant
+ * namespace to construct it with.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GuardedSemanticCache = exports.SemanticCacheRefused = exports.MIN_SEMANTIC_THRESHOLD = void 0;
+exports.semanticCacheNamespace = semanticCacheNamespace;
+exports.semanticCacheRefusal = semanticCacheRefusal;
+exports.MIN_SEMANTIC_THRESHOLD = 0.95;
+class SemanticCacheRefused extends Error {
+    constructor(reason) {
+        super(`semantic cache refused: ${reason}`);
+        this.reason = reason;
+        this.name = 'SemanticCacheRefused';
+    }
+}
+exports.SemanticCacheRefused = SemanticCacheRefused;
+function semanticCacheNamespace(org_id, source_versions_digest) {
+    return `tork:sc:v1:${org_id}:${source_versions_digest}`;
+}
+/** Why the semantic cache may not be used, or null when it may. */
+function semanticCacheRefusal(opts) {
+    if (!opts.settings.switches.semantic_cache)
+        return 'semantic_cache switch is off';
+    if (opts.surface !== 'website_widget')
+        return `surface ${opts.surface} is not a public website surface`;
+    if (opts.role_dependent)
+        return 'answer depends on the asker role or clearance';
+    if (!(opts.threshold >= exports.MIN_SEMANTIC_THRESHOLD))
+        return `threshold ${opts.threshold} is below ${exports.MIN_SEMANTIC_THRESHOLD}`;
+    return null;
+}
+class GuardedSemanticCache {
+    constructor(store, opts) {
+        this.store = store;
+        this.opts = opts;
+        // Fail at construction for the static conditions, so a mis-wired cache
+        // is a startup error rather than a silent leak.
+        const r = semanticCacheRefusal({ ...opts, role_dependent: false });
+        if (r)
+            throw new SemanticCacheRefused(r);
+    }
+    async get(question, role_dependent) {
+        if (semanticCacheRefusal({ ...this.opts, role_dependent }))
+            return null;
+        try {
+            return (await this.store.get(question)) ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async set(question, answer, role_dependent) {
+        if (semanticCacheRefusal({ ...this.opts, role_dependent }))
+            return false;
+        try {
+            await this.store.set(question, answer);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.GuardedSemanticCache = GuardedSemanticCache;
+//# sourceMappingURL=semantic.js.map

package/dist/cache/semantic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.js","sourceRoot":"","sources":["../../src/cache/semantic.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAmBH,wDAEC;AAGD,oDAWC;AA9BY,QAAA,sBAAsB,GAAG,IAAI,CAAC;AAO3C,MAAa,oBAAqB,SAAQ,KAAK;IAC7C,YAA4B,MAAc;QACxC,KAAK,CAAC,2BAA2B,MAAM,EAAE,CAAC,CAAC;QADjB,WAAM,GAAN,MAAM,CAAQ;QAExC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AALD,oDAKC;AAED,SAAgB,sBAAsB,CAAC,MAAc,EAAE,sBAA8B;IACnF,OAAO,cAAc,MAAM,IAAI,sBAAsB,EAAE,CAAC;AAC1D,CAAC;AAED,mEAAmE;AACnE,SAAgB,oBAAoB,CAAC,IAKpC;IACC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,cAAc;QAAE,OAAO,8BAA8B,CAAC;IAClF,IAAI,IAAI,CAAC,OAAO,KAAK,gBAAgB;QAAE,OAAO,WAAW,IAAI,CAAC,OAAO,kCAAkC,CAAC;IACxG,IAAI,IAAI,CAAC,cAAc;QAAE,OAAO,+CAA+C,CAAC;IAChF,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,IAAI,8BAAsB,CAAC;QAAE,OAAO,aAAa,IAAI,CAAC,SAAS,aAAa,8BAAsB,EAAE,CAAC;IACzH,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAa,oBAAoB;IAC/B,YACmB,KAAyB,EACzB,IAAuE;QADvE,UAAK,GAAL,KAAK,CAAoB;QACzB,SAAI,GAAJ,IAAI,CAAmE;QAExF,uEAAuE;QACvE,gDAAgD;QAChD,MAAM,CAAC,GAAG,oBAAoB,CAAC,EAAE,GAAG,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC;QACnE,IAAI,CAAC;YAAE,MAAM,IAAI,oBAAoB,CAAC,CAAC,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,QAAgB,EAAE,cAAuB;QACjD,IAAI,oBAAoB,CAAC,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC;QACxE,IAAI,CAAC;YACH,OAAO,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,IAAI,CAAC;QAClD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,QAAgB,EAAE,MAAc,EAAE,cAAuB;QACjE,IAAI,oBAAoB,CAAC,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,CAAC;YAAE,OAAO,KAAK,CAAC;QACzE,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YACvC,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF;AA7BD,oDA6BC"}

package/dist/canonical.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Canonical serialisation and hashing used by every hash in the contract.
+ *
+ * Same rule as Tork Tower's canonicalJson (tork-tower-t2
+ * src/lib/crypto/canonical-json.ts): object keys sorted at every depth, arrays
+ * kept in order, `undefined` dropped. Two parties that agree on this function
+ * agree on the exact bytes a hash covers without agreeing on JSON key order.
+ *
+ * Pure: no I/O, no keys. Uses Web Crypto so it runs unchanged in Node 18+,
+ * the Vercel Edge runtime, and browsers.
+ */
+export declare function canonicalJson(value: unknown): string;
+/** SHA-256 over UTF-8, lowercase hex. */
+export declare function sha256Hex(text: string): Promise<string>;
+/** SHA-256 of the canonical JSON of `value`. */
+export declare function hashCanonical(value: unknown): Promise<string>;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD;AAqDD,yCAAyC;AACzC,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK7D;AAED,gDAAgD;AAChD,wBAAsB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAEnE"}

package/dist/canonical.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Canonical serialisation and hashing used by every hash in the contract.
+ *
+ * Same rule as Tork Tower's canonicalJson (tork-tower-t2
+ * src/lib/crypto/canonical-json.ts): object keys sorted at every depth, arrays
+ * kept in order, `undefined` dropped. Two parties that agree on this function
+ * agree on the exact bytes a hash covers without agreeing on JSON key order.
+ *
+ * Pure: no I/O, no keys. Uses Web Crypto so it runs unchanged in Node 18+,
+ * the Vercel Edge runtime, and browsers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalJson = canonicalJson;
+exports.sha256Hex = sha256Hex;
+exports.hashCanonical = hashCanonical;
+function canonicalJson(value) {
+    return emit(value);
+}
+/** Code-point order — what Python's sorted() and Rust's String ordering use. */
+function compareCodePoints(a, b) {
+    const ia = a[Symbol.iterator]();
+    const ib = b[Symbol.iterator]();
+    for (;;) {
+        const x = ia.next();
+        const y = ib.next();
+        if (x.done || y.done)
+            return x.done === y.done ? 0 : x.done ? -1 : 1;
+        const cx = x.value.codePointAt(0);
+        const cy = y.value.codePointAt(0);
+        if (cx !== cy)
+            return cx - cy;
+    }
+}
+/**
+ * Built by hand rather than by sorting into an object and calling
+ * JSON.stringify: a JS object always enumerates integer-like keys ("2",
+ * "10") first and numerically, which would make {"2":…,"10":…} hash
+ * differently here than in the Python and Rust SDKs. (Tower's canonicaliser
+ * has that quirk; contract blocks never carry integer-like keys, so the two
+ * agree on every contract hash — tool-argument hashes are SDK-side only.)
+ */
+function emit(value) {
+    if (value === null)
+        return 'null';
+    switch (typeof value) {
+        case 'number':
+            // JSON.stringify turns NaN/Infinity into null silently; refuse instead,
+            // so a hash never covers a value that did not round-trip.
+            if (!Number.isFinite(value))
+                throw new TypeError('canonicalJson: non-finite number');
+            return JSON.stringify(value);
+        case 'string':
+        case 'boolean':
+            return JSON.stringify(value);
+        case 'object': {
+            // Array.from visits holes (map skips them): a hole emits null, as JSON.stringify does.
+            if (Array.isArray(value))
+                return `[${Array.from(value, (v) => (v === undefined ? 'null' : emit(v))).join(',')}]`;
+            const obj = value;
+            const keys = Object.keys(obj).filter((k) => obj[k] !== undefined).sort(compareCodePoints);
+            return `{${keys.map((k) => `${JSON.stringify(k)}:${emit(obj[k])}`).join(',')}}`;
+        }
+        default:
+            throw new TypeError(`canonicalJson: unsupported type ${typeof value}`);
+    }
+}
+function getSubtle() {
+    const c = globalThis.crypto;
+    if (!c?.subtle)
+        throw new Error('Web Crypto (crypto.subtle) is not available in this runtime');
+    return c.subtle;
+}
+/** SHA-256 over UTF-8, lowercase hex. */
+async function sha256Hex(text) {
+    const buf = await getSubtle().digest('SHA-256', new TextEncoder().encode(text));
+    let out = '';
+    for (const b of new Uint8Array(buf))
+        out += b.toString(16).padStart(2, '0');
+    return out;
+}
+/** SHA-256 of the canonical JSON of `value`. */
+async function hashCanonical(value) {
+    return sha256Hex(canonicalJson(value));
+}
+//# sourceMappingURL=canonical.js.map

package/dist/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"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"}