glirastes 0.4.0 → 0.5.1

package/dist/cjs/runtime/prompt-bundle-store.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromptBundleStore = void 0;
+const index_js_1 = require("../contracts/index.js");
+const signature_verifier_js_1 = require("../sync/signature-verifier.js");
+const DEFAULT_MAX_BUNDLE_BYTES = 1_000_000;
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value)) {
+            deepFreeze(child);
+        }
+    }
+    return value;
+}
+/**
+ * Local, verified prompt-bundle activation.
+ *
+ * Runtime and prompt bundles are separate artifacts. Staging performs every
+ * network and cryptographic step outside interactive turns; activation is a
+ * single atomic reference swap. A running turn keeps the revision it started
+ * with, a new turn atomically sees the activated revision, and there is no
+ * unsigned, stale, or partially verified fallback.
+ */
+class PromptBundleStore {
+    options;
+    verifier;
+    maxBundleBytes;
+    active;
+    previous;
+    turnPins = new Map();
+    constructor(options) {
+        this.options = options;
+        this.verifier = new signature_verifier_js_1.RuntimeRevisionVerifier(options.keys);
+        this.maxBundleBytes = options.maxBundleBytes ?? DEFAULT_MAX_BUNDLE_BYTES;
+    }
+    async stage(binding) {
+        const pin = index_js_1.SignedPromptBindingSchema.parse(binding);
+        if (pin.appId !== this.options.appId) {
+            throw new Error('Prompt binding targets a different app');
+        }
+        await this.verifier.verifyPromptBinding(pin);
+        const raw = await this.options.registry.fetch(pin.artifactRef);
+        const size = Buffer.byteLength(JSON.stringify(raw ?? null), 'utf8');
+        if (size > this.maxBundleBytes) {
+            throw new Error('Prompt bundle artifact is too large to verify');
+        }
+        const bundle = index_js_1.PromptBundleSchema.parse(raw);
+        if (bundle.appId !== this.options.appId) {
+            throw new Error('Prompt bundle targets a different app');
+        }
+        await this.verifier.verifyPromptBundle(bundle);
+        if (bundle.revisionId !== pin.revisionId) {
+            throw new Error('Prompt binding revision identity does not match the bundle');
+        }
+        if (bundle.revision !== pin.revision) {
+            throw new Error('Prompt binding revision does not match the bundle revision');
+        }
+        if (bundle.bundleDigest !== pin.bundleDigest) {
+            throw new Error('Prompt binding digest does not match the bundle digest');
+        }
+        this.assertNotStale(bundle.revision);
+        return deepFreeze({
+            revisionId: bundle.revisionId,
+            revision: bundle.revision,
+            bundleDigest: bundle.bundleDigest,
+            sections: bundle.sections,
+        });
+    }
+    async activate(staged) {
+        this.assertNotStale(staged.revision);
+        const next = deepFreeze({
+            revisionId: staged.revisionId,
+            revision: staged.revision,
+            bundleDigest: staged.bundleDigest,
+            sections: staged.sections,
+        });
+        // Single atomic swap: a concurrent turn either sees the old or the new
+        // reference, never a partially applied bundle.
+        this.previous = this.active;
+        this.active = next;
+    }
+    current() {
+        if (!this.active) {
+            throw new Error('No verified prompt bundle is active');
+        }
+        return this.active;
+    }
+    pinForTurn(turnId) {
+        const existing = this.turnPins.get(turnId);
+        if (existing)
+            return existing;
+        const active = this.current();
+        const pinned = deepFreeze({ ...active, turnId });
+        this.turnPins.set(turnId, pinned);
+        return pinned;
+    }
+    releaseTurn(turnId) {
+        this.turnPins.delete(turnId);
+    }
+    /** Restores the previously verified pin without refetching or rebuilding. */
+    rollback() {
+        if (!this.previous) {
+            throw new Error('No previously verified prompt bundle to roll back to');
+        }
+        this.active = this.previous;
+        this.previous = undefined;
+    }
+    promptPin() {
+        const active = this.current();
+        return {
+            revisionId: active.revisionId,
+            revision: active.revision,
+            bundleDigest: active.bundleDigest,
+        };
+    }
+    assertNotStale(revision) {
+        if (this.active && revision <= this.active.revision) {
+            throw new Error('Prompt bundle revision is stale');
+        }
+    }
+}
+exports.PromptBundleStore = PromptBundleStore;

package/dist/cjs/runtime/runtime-mode.d.ts

@@ -0,0 +1,23 @@
+export type RuntimeMode = 'standalone' | 'managed';
+/** The hosted Glirastes Platform. Set `GLIRASTES_CONTROL_PLANE_URL` only to self-host or run it locally. */
+export declare const DEFAULT_CONTROL_PLANE_URL = "https://api.glirastes.io";
+/** The shape of a runtime key issued by `glirastes connect`. */
+export declare const RUNTIME_API_KEY_PATTERN: RegExp;
+/** What a connected runtime reads from its environment; the rest it asks the Platform. */
+export interface RuntimeConnectionConfig {
+    baseUrl: string;
+    apiKey: string;
+}
+/**
+ * The connection of this process, or undefined in Standalone. The switch is
+ * `GLIRASTES_API_KEY`: without it the runtime stays network-silent. A
+ * malformed key or a control plane URL that is not http(s) fails closed; the
+ * error names the variable, never its value.
+ */
+export declare function resolveRuntimeConnectionConfig(env: Record<string, string | undefined>): RuntimeConnectionConfig | undefined;
+/**
+ * Standalone is the default. Managed (Connected) is opted into by setting
+ * `GLIRASTES_API_KEY`. A malformed configuration fails closed — it never
+ * silently degrades into standalone.
+ */
+export declare function resolveRuntimeMode(env: Record<string, string | undefined>): RuntimeMode;

package/dist/cjs/runtime/runtime-mode.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNTIME_API_KEY_PATTERN = exports.DEFAULT_CONTROL_PLANE_URL = void 0;
+exports.resolveRuntimeConnectionConfig = resolveRuntimeConnectionConfig;
+exports.resolveRuntimeMode = resolveRuntimeMode;
+/** The hosted Glirastes Platform. Set `GLIRASTES_CONTROL_PLANE_URL` only to self-host or run it locally. */
+exports.DEFAULT_CONTROL_PLANE_URL = 'https://api.glirastes.io';
+/** The shape of a runtime key issued by `glirastes connect`. */
+exports.RUNTIME_API_KEY_PATTERN = /^gl_[A-Za-z0-9]{32,128}$/;
+function isHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:' || url.protocol === 'http:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The connection of this process, or undefined in Standalone. The switch is
+ * `GLIRASTES_API_KEY`: without it the runtime stays network-silent. A
+ * malformed key or a control plane URL that is not http(s) fails closed; the
+ * error names the variable, never its value.
+ */
+function resolveRuntimeConnectionConfig(env) {
+    const apiKey = env.GLIRASTES_API_KEY?.trim();
+    const configuredUrl = env.GLIRASTES_CONTROL_PLANE_URL?.trim();
+    if (configuredUrl && !isHttpUrl(configuredUrl)) {
+        throw new Error('GLIRASTES_CONTROL_PLANE_URL must be an http(s) URL.');
+    }
+    if (!apiKey)
+        return undefined;
+    if (!exports.RUNTIME_API_KEY_PATTERN.test(apiKey)) {
+        throw new Error('GLIRASTES_API_KEY is malformed. Refusing to fall back to standalone; '
+            + 'rerun `glirastes connect` or remove the variable.');
+    }
+    return { baseUrl: configuredUrl || exports.DEFAULT_CONTROL_PLANE_URL, apiKey };
+}
+/**
+ * Standalone is the default. Managed (Connected) is opted into by setting
+ * `GLIRASTES_API_KEY`. A malformed configuration fails closed — it never
+ * silently degrades into standalone.
+ */
+function resolveRuntimeMode(env) {
+    return resolveRuntimeConnectionConfig(env) ? 'managed' : 'standalone';
+}

package/dist/cjs/runtime/sdk-version.d.ts

@@ -0,0 +1,2 @@
+/** Kept equal to package.json#version by a test; bump both on release. */
+export declare const SDK_VERSION = "0.5.1";

package/dist/cjs/runtime/sdk-version.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_VERSION = void 0;
+/** Kept equal to package.json#version by a test; bump both on release. */
+exports.SDK_VERSION = '0.5.1';

package/dist/cjs/runtime/tool-discovery.d.ts

@@ -0,0 +1,51 @@
+import type { ToolPresentation } from '../contracts/index.js';
+import type { ToolRegistry } from '../types.js';
+import type { TurnSnapshot } from './turn-snapshot.js';
+export interface ToolDiscoveryResult {
+    readonly name: string;
+    readonly description: string;
+    readonly module?: string;
+    readonly usageHints?: ReadonlyArray<string>;
+    readonly presentation?: Readonly<ToolPresentation>;
+}
+export interface TurnToolDiscovery {
+    readonly turnId: string;
+    readonly eligibleNames: ReadonlyArray<string>;
+    search(query: string, limit?: number): ReadonlyArray<ToolDiscoveryResult>;
+}
+export interface TurnToolDiscoveryOptions {
+    maxQueryLength?: number;
+    maxResults?: number;
+    maxDescriptionLength?: number;
+    maxHintLength?: number;
+}
+/**
+ * Search-only enrichment keyed by the model-facing tool name. Synonyms are
+ * indexed but never returned and never make a tool eligible.
+ */
+export interface ToolSearchSemantics {
+    readonly synonyms?: ReadonlyArray<string>;
+}
+export type ToolSearchSemanticsMap = Readonly<Record<string, ToolSearchSemantics>>;
+/**
+ * Builds a content-bounded search index from the immutable turn snapshot and
+ * the already materialized local registry. Discovery neither grants access
+ * nor holds an executor or schema reference.
+ */
+export declare function createTurnToolDiscovery(input: {
+    snapshot: TurnSnapshot;
+    registry: ToolRegistry;
+    revokedToolIds?: ReadonlyArray<string>;
+    semantics?: ToolSearchSemanticsMap;
+}, options?: TurnToolDiscoveryOptions): TurnToolDiscovery;
+/**
+ * Discovery for apps without a managed or standalone runtime source. The
+ * per-request registry is the deployed, app-authorized tool set; names in
+ * `excludeNames` (SDK built-ins) are never indexed.
+ */
+export declare function createRegistryToolDiscovery(input: {
+    turnId: string;
+    registry: ToolRegistry;
+    excludeNames?: ReadonlyArray<string>;
+    semantics?: ToolSearchSemanticsMap;
+}, options?: TurnToolDiscoveryOptions): TurnToolDiscovery;

package/dist/cjs/runtime/tool-discovery.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTurnToolDiscovery = createTurnToolDiscovery;
+exports.createRegistryToolDiscovery = createRegistryToolDiscovery;
+const tool_policy_js_1 = require("../contracts/tool-policy.js");
+const authorization_js_1 = require("./authorization.js");
+const local_tool_bindings_js_1 = require("./local-tool-bindings.js");
+const tool_search_js_1 = require("./tool-search.js");
+const DEFAULT_MAX_QUERY_LENGTH = 200;
+const DEFAULT_MAX_RESULTS = 8;
+const HARD_MAX_RESULTS = 20;
+const DEFAULT_MAX_DESCRIPTION_LENGTH = 500;
+const DEFAULT_MAX_HINT_LENGTH = 300;
+const MAX_SYNONYMS = 20;
+const MAX_SYNONYM_LENGTH = 100;
+function bounded(value, maxLength) {
+    return value.slice(0, maxLength);
+}
+function freezeResult(result) {
+    if (result.usageHints)
+        Object.freeze(result.usageHints);
+    if (result.presentation)
+        Object.freeze(result.presentation);
+    return Object.freeze(result);
+}
+function boundedSynonyms(semantics, name) {
+    const entry = semantics && Object.hasOwn(semantics, name)
+        ? semantics[name]
+        : undefined;
+    return (entry?.synonyms ?? [])
+        .filter((synonym) => typeof synonym === 'string')
+        .slice(0, MAX_SYNONYMS)
+        .map((synonym) => bounded(synonym, MAX_SYNONYM_LENGTH));
+}
+function resolveLimits(options) {
+    return {
+        maxQueryLength: Math.min(Math.max(options.maxQueryLength ?? DEFAULT_MAX_QUERY_LENGTH, 1), DEFAULT_MAX_QUERY_LENGTH),
+        maxResults: Math.min(Math.max(options.maxResults ?? DEFAULT_MAX_RESULTS, 1), HARD_MAX_RESULTS),
+        maxDescriptionLength: Math.min(Math.max(options.maxDescriptionLength ?? DEFAULT_MAX_DESCRIPTION_LENGTH, 1), DEFAULT_MAX_DESCRIPTION_LENGTH),
+        maxHintLength: Math.min(Math.max(options.maxHintLength ?? DEFAULT_MAX_HINT_LENGTH, 1), DEFAULT_MAX_HINT_LENGTH),
+    };
+}
+function createDiscovery(turnId, unsortedEntries, limits) {
+    const entries = [...unsortedEntries].sort((left, right) => left.result.name.localeCompare(right.result.name));
+    Object.freeze(entries);
+    const byName = new Map(entries.map((entry) => [entry.result.name, entry.result]));
+    const eligibleNames = Object.freeze(entries.map((entry) => entry.result.name));
+    const index = (0, tool_search_js_1.createToolSearchIndex)(entries.map((entry) => ({
+        name: entry.result.name,
+        description: entry.result.description,
+        ...(entry.result.module ? { module: entry.result.module } : {}),
+        sharedWith: entry.sharedWith,
+        ...(entry.result.usageHints ? { usageHints: entry.result.usageHints } : {}),
+        synonyms: entry.synonyms,
+    })));
+    return Object.freeze({
+        turnId,
+        eligibleNames,
+        search(query, limit = limits.maxResults) {
+            if (query.length > limits.maxQueryLength) {
+                throw new Error('Tool discovery query exceeds the configured limit.');
+            }
+            const boundedLimit = Math.min(Math.max(Math.trunc(limit), 1), limits.maxResults);
+            return Object.freeze(index.search(query, boundedLimit)
+                .map((name) => byName.get(name))
+                .filter((result) => result !== undefined));
+        },
+    });
+}
+/**
+ * Builds a content-bounded search index from the immutable turn snapshot and
+ * the already materialized local registry. Discovery neither grants access
+ * nor holds an executor or schema reference.
+ */
+function createTurnToolDiscovery(input, options = {}) {
+    const limits = resolveLimits(options);
+    const { maxDescriptionLength, maxHintLength } = limits;
+    const revoked = new Set(input.revokedToolIds ?? []);
+    const policies = new Map(input.snapshot.policyRevision.toolPolicies.map((policy) => [policy.toolId, policy]));
+    const entries = [];
+    for (const manifestTool of input.snapshot.manifestRevision.tools) {
+        const name = (0, local_tool_bindings_js_1.modelFacingToolName)(manifestTool.name);
+        const binding = input.registry[name];
+        const policy = policies.get(manifestTool.toolId);
+        const authorization = (0, authorization_js_1.authorizeToolCall)({
+            principal: input.snapshot.principal,
+            agentRevision: input.snapshot.agentRevision,
+            manifestRevision: input.snapshot.manifestRevision,
+            policyRevision: input.snapshot.policyRevision,
+            toolId: manifestTool.toolId,
+        });
+        if (revoked.has(manifestTool.toolId)
+            || !binding
+            || binding.id !== manifestTool.toolId
+            || !policy
+            || (0, tool_policy_js_1.riskTier)(policy.riskClass) < (0, tool_policy_js_1.riskTier)(manifestTool.riskClass)
+            || !authorization.allowed) {
+            continue;
+        }
+        const description = bounded(manifestTool.description, maxDescriptionLength);
+        const usageHints = manifestTool.usageHints?.map((hint) => bounded(hint, maxHintLength));
+        const result = freezeResult({
+            name,
+            description,
+            ...(manifestTool.module ? { module: manifestTool.module } : {}),
+            ...(usageHints ? { usageHints } : {}),
+            ...(manifestTool.presentation
+                ? { presentation: { ...manifestTool.presentation } }
+                : {}),
+        });
+        entries.push({
+            result,
+            synonyms: boundedSynonyms(input.semantics, name),
+            sharedWith: manifestTool.sharedWith ?? [],
+        });
+    }
+    return createDiscovery(input.snapshot.turnId, entries, limits);
+}
+/**
+ * Discovery for apps without a managed or standalone runtime source. The
+ * per-request registry is the deployed, app-authorized tool set; names in
+ * `excludeNames` (SDK built-ins) are never indexed.
+ */
+function createRegistryToolDiscovery(input, options = {}) {
+    const limits = resolveLimits(options);
+    const excluded = new Set(input.excludeNames ?? []);
+    const entries = [];
+    for (const [name, tool] of Object.entries(input.registry)) {
+        if (excluded.has(name) || typeof tool?.description !== 'string')
+            continue;
+        entries.push({
+            result: freezeResult({
+                name,
+                description: bounded(tool.description, limits.maxDescriptionLength),
+            }),
+            synonyms: boundedSynonyms(input.semantics, name),
+            sharedWith: [],
+        });
+    }
+    return createDiscovery(input.turnId, entries, limits);
+}

package/dist/cjs/runtime/tool-search.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Searchable, content-bounded tool facts. Discovery builds these from the
+ * pinned manifest or the deployed registry; nothing here grants access.
+ */
+export interface ToolSearchDocument {
+    readonly name: string;
+    readonly description: string;
+    readonly module?: string;
+    readonly sharedWith?: ReadonlyArray<string>;
+    readonly usageHints?: ReadonlyArray<string>;
+    readonly synonyms?: ReadonlyArray<string>;
+}
+export interface ToolSearchIndex {
+    /** Document names ordered by relevance; empty when no query term matches. */
+    search(query: string, limit: number): ReadonlyArray<string>;
+}
+/**
+ * Unicode-aware tokens: camelCase and snake/dot names split, letters and
+ * digits of every script kept, German/English diacritics folded, function
+ * words dropped.
+ */
+export declare function searchTokens(text: string): string[];
+/** Each query token with its German and English Snowball stems. */
+export declare function searchTermVariants(text: string): ReadonlyArray<ReadonlyArray<string>>;
+/**
+ * Builds a deterministic relevance index. Ranking: exact name, then the sum
+ * over query terms of the best field hit (name > synonyms > description >
+ * module > hints) weighted by inverse document frequency, then name.
+ * No embeddings, network or model call.
+ */
+export declare function createToolSearchIndex(documents: ReadonlyArray<ToolSearchDocument>): ToolSearchIndex;

package/dist/cjs/runtime/tool-search.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchTokens = searchTokens;
+exports.searchTermVariants = searchTermVariants;
+exports.createToolSearchIndex = createToolSearchIndex;
+const snowball_stemmers_1 = require("snowball-stemmers");
+const STEMMERS = [
+    (0, snowball_stemmers_1.newStemmer)('german'),
+    (0, snowball_stemmers_1.newStemmer)('english'),
+];
+/** Folded (lower-case, no diacritics, ß → ss) German and English function words. */
+const STOP_WORDS = new Set([
+    'a', 'all', 'an', 'and', 'any', 'are', 'as', 'at', 'be', 'by', 'can',
+    'could', 'do', 'does', 'for', 'from', 'get', 'give', 'how', 'in', 'into',
+    'is', 'it', 'me', 'my', 'of', 'on', 'or', 'our', 'please', 'show', 'some',
+    'that', 'the', 'these', 'this', 'those', 'to', 'we', 'what', 'which',
+    'who', 'with', 'would', 'you', 'your',
+    'alle', 'allen', 'als', 'am', 'auch', 'auf', 'aus', 'bei', 'bitte', 'das',
+    'dass', 'dem', 'den', 'der', 'des', 'die', 'dies', 'diese', 'diesem',
+    'diesen', 'dieser', 'dieses', 'du', 'ein', 'eine', 'einem', 'einen',
+    'einer', 'eines', 'es', 'fur', 'gib', 'habe', 'haben', 'hat', 'ich',
+    'ihr', 'im', 'ist', 'kann', 'kannst', 'mal', 'man', 'mein', 'meine',
+    'meinem', 'meinen', 'meiner', 'meines', 'mich', 'mir', 'mit', 'nach',
+    'noch', 'oder', 'sind', 'uber', 'und', 'uns', 'unser', 'unsere', 'vom',
+    'von', 'was', 'welche', 'welcher', 'welches', 'wer', 'wie', 'wir', 'wo',
+    'zu', 'zum', 'zur',
+]);
+const MIN_TOKEN_LENGTH = 2;
+const MIN_PREFIX_LENGTH = 5;
+const FIELD_WEIGHTS = {
+    name: 8,
+    synonyms: 6,
+    description: 4,
+    module: 3,
+    hints: 2,
+};
+const SEARCH_FIELDS = Object.keys(FIELD_WEIGHTS);
+/**
+ * Unicode-aware tokens: camelCase and snake/dot names split, letters and
+ * digits of every script kept, German/English diacritics folded, function
+ * words dropped.
+ */
+function searchTokens(text) {
+    return text
+        .normalize('NFKC')
+        .replace(/(\p{Ll}|\p{N})(\p{Lu})/gu, '$1 $2')
+        .toLowerCase()
+        .replace(/ß/g, 'ss')
+        .normalize('NFKD')
+        .replace(/\p{M}+/gu, '')
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter((token) => token.length >= MIN_TOKEN_LENGTH && !STOP_WORDS.has(token));
+}
+function termVariants(token) {
+    const variants = new Set([token]);
+    for (const stemmer of STEMMERS) {
+        const stem = stemmer.stem(token);
+        if (stem.length >= MIN_TOKEN_LENGTH)
+            variants.add(stem);
+    }
+    return [...variants];
+}
+/** Each query token with its German and English Snowball stems. */
+function searchTermVariants(text) {
+    return searchTokens(text).map(termVariants);
+}
+function fieldVariants(text) {
+    const variants = new Set();
+    for (const term of searchTermVariants(text)) {
+        for (const variant of term)
+            variants.add(variant);
+    }
+    return variants;
+}
+/** 1 for an exact token/stem hit, 0.5 for a compound prefix, else 0. */
+function matchStrength(term, field) {
+    for (const variant of term)
+        if (field.has(variant))
+            return 1;
+    for (const variant of term) {
+        if (variant.length < MIN_PREFIX_LENGTH)
+            continue;
+        for (const candidate of field) {
+            if (candidate.length < MIN_PREFIX_LENGTH)
+                continue;
+            if (candidate.startsWith(variant) || variant.startsWith(candidate)) {
+                return 0.5;
+            }
+        }
+    }
+    return 0;
+}
+function indexDocument(document) {
+    return {
+        name: document.name,
+        normalizedName: searchTokens(document.name).join(' '),
+        fields: {
+            name: fieldVariants(document.name),
+            synonyms: fieldVariants((document.synonyms ?? []).join(' ')),
+            description: fieldVariants(document.description),
+            module: fieldVariants([document.module, ...(document.sharedWith ?? [])]
+                .filter((value) => Boolean(value))
+                .join(' ')),
+            hints: fieldVariants((document.usageHints ?? []).join(' ')),
+        },
+    };
+}
+/**
+ * Builds a deterministic relevance index. Ranking: exact name, then the sum
+ * over query terms of the best field hit (name > synonyms > description >
+ * module > hints) weighted by inverse document frequency, then name.
+ * No embeddings, network or model call.
+ */
+function createToolSearchIndex(documents) {
+    const indexed = documents.map(indexDocument);
+    const documentFrequency = (term) => indexed.filter((document) => SEARCH_FIELDS.some((field) => matchStrength(term, document.fields[field]) > 0)).length;
+    return Object.freeze({
+        search(query, limit) {
+            const terms = searchTermVariants(query);
+            if (terms.length === 0 || indexed.length === 0)
+                return Object.freeze([]);
+            const inverseFrequency = terms.map((term) => Math.log(1 + indexed.length / Math.max(1, documentFrequency(term))));
+            const normalizedQuery = searchTokens(query).join(' ');
+            const ranked = indexed
+                .map((document) => {
+                let score = 0;
+                terms.forEach((term, index) => {
+                    let best = 0;
+                    for (const field of SEARCH_FIELDS) {
+                        best = Math.max(best, matchStrength(term, document.fields[field]) * FIELD_WEIGHTS[field]);
+                    }
+                    score += best * inverseFrequency[index];
+                });
+                return {
+                    name: document.name,
+                    exact: normalizedQuery === document.normalizedName ? 1 : 0,
+                    score,
+                };
+            })
+                .filter((candidate) => candidate.score > 0)
+                .sort((left, right) => right.exact - left.exact
+                || right.score - left.score
+                || left.name.localeCompare(right.name))
+                .slice(0, Math.max(0, Math.trunc(limit)))
+                .map((candidate) => candidate.name);
+            return Object.freeze(ranked);
+        },
+    });
+}

package/dist/cjs/runtime/turn-snapshot.d.ts

@@ -0,0 +1,44 @@
+import type { AgentRevision, ExecutionBudget, ManifestRevision, Principal, PromptPin, RuntimePolicyRevision, SecurityRevocation } from '../contracts/index.js';
+export interface TurnSnapshot {
+    readonly turnId: string;
+    readonly startedAt: string;
+    readonly principal: Principal;
+    readonly agentRevision: AgentRevision;
+    readonly manifestRevision: ManifestRevision;
+    /**
+     * The pinned policy revision. Its `toolPolicies` are the effective ones:
+     * the signed values composed with the revision's own signed `toolOverrides`
+     * deltas (restrictions, plus the D16 relaxations the local code report
+     * allows), so every consumer of the snapshot obeys Platform decisions,
+     * whichever path built it.
+     */
+    readonly policyRevision: RuntimePolicyRevision;
+    readonly budget: ExecutionBudget;
+    /**
+     * Prompt revision the turn started with. Prompt bundles hot-swap
+     * independently of the runtime bundle, so a running turn stays on this pin.
+     */
+    readonly promptPin?: PromptPin;
+}
+export declare function createTurnSnapshot(options: {
+    turnId: string;
+    agentRevision: AgentRevision;
+    manifestRevision: ManifestRevision;
+    policyRevision: RuntimePolicyRevision;
+    principal: Principal;
+    localLimits: ExecutionBudget;
+    promptPin?: PromptPin;
+    startedAt?: string;
+    /**
+     * D16: the tools whose confirmation a signed Platform decision may switch
+     * off, `relaxableToolIds(setupArtifact)` of the running code. Without it a
+     * snapshot built straight from a Platform deployment relaxes nothing.
+     */
+    relaxableToolIds?: ReadonlySet<string>;
+}): TurnSnapshot;
+/**
+ * Resuming a turn must never silently change its prompt revision. A turn that
+ * pinned a prompt bundle can only resume on the identical revision and digest.
+ */
+export declare function assertPromptPinForResume(snapshot: TurnSnapshot, pin: PromptPin | undefined): void;
+export declare function isToolRevoked(snapshot: TurnSnapshot, toolId: string, revocations: ReadonlyArray<SecurityRevocation>, at?: Date): boolean;