glirastes 0.3.2 → 0.5.0

package/dist/cjs/runtime/metrics/sink.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRuntimeMetricsSink = createRuntimeMetricsSink;
+exports.createRuntimeMetricsSinkFromEnv = createRuntimeMetricsSinkFromEnv;
+const url_js_1 = require("../../contracts/url.js");
+const node_crypto_1 = require("node:crypto");
+const zod_1 = require("zod");
+const index_js_1 = require("../../contracts/index.js");
+const runtime_mode_js_1 = require("../runtime-mode.js");
+const label = zod_1.z.string().regex(index_js_1.RUNTIME_METRIC_LABEL_PATTERN);
+const SinkConfigSchema = zod_1.z.object({
+    controlPlaneUrl: index_js_1.PlatformConnectionDescriptorSchema.shape.baseUrl,
+    apiKey: zod_1.z.string().regex(/^\S{8,512}$/),
+    appId: zod_1.z.uuid(),
+    environmentId: zod_1.z.uuid(),
+    buildId: label.nullable(),
+    instanceId: label,
+    maxBatchSize: zod_1.z.number().int().min(1).max(index_js_1.RUNTIME_METRIC_MAX_BATCH),
+    maxQueueSize: zod_1.z.number().int().min(1).max(100_000),
+    flushIntervalMs: zod_1.z.number().int().min(100).max(3_600_000),
+    requestTimeoutMs: zod_1.z.number().int().min(10).max(60_000),
+});
+/**
+ * Batches turn events and delivers them to the Platform off the turn path.
+ * `record` validates and queues synchronously and never throws; delivery
+ * runs on an unref'd interval or when a batch is full. A failed, rejected or
+ * timed-out request drops its batch: metrics never retry, never block a turn
+ * and never hold the process open.
+ */
+function createRuntimeMetricsSink(options) {
+    const parsed = SinkConfigSchema.safeParse({
+        controlPlaneUrl: options.controlPlaneUrl,
+        apiKey: options.apiKey,
+        appId: options.appId,
+        environmentId: options.environmentId,
+        buildId: options.buildId ?? null,
+        instanceId: options.instanceId ?? (0, node_crypto_1.randomUUID)(),
+        maxBatchSize: options.maxBatchSize ?? index_js_1.RUNTIME_METRIC_MAX_BATCH,
+        maxQueueSize: options.maxQueueSize ?? 1_000,
+        flushIntervalMs: options.flushIntervalMs ?? 5_000,
+        requestTimeoutMs: options.requestTimeoutMs ?? 5_000,
+    });
+    if (!parsed.success) {
+        const paths = parsed.error.issues.map((issue) => issue.path.join('.'));
+        throw new RangeError(`Invalid runtime metrics sink options: ${[...new Set(paths)].join(', ')}`);
+    }
+    const config = parsed.data;
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const endpoint = `${(0, url_js_1.trimTrailingSlashes)(config.controlPlaneUrl)}/v1/runtime/apps/`
+        + `${config.appId}/environments/${config.environmentId}/metrics/events`;
+    const identity = Object.freeze({
+        appId: config.appId,
+        environmentId: config.environmentId,
+        buildId: config.buildId,
+        instanceId: config.instanceId,
+    });
+    // One queue per event type: a batch never mixes types, so a Platform that
+    // does not know `tool_contract_rejected` yet refuses only those batches.
+    // Turns are listed first, so they are sent first whatever arrives first.
+    const queues = new Map([['turn.finished', []]]);
+    const queued = () => [...queues.values()].reduce((sum, events) => sum + events.length, 0);
+    let timer;
+    let inFlight;
+    let flushScheduled = false;
+    let closed = false;
+    const drop = (reason, count) => {
+        try {
+            options.onDrop?.({ reason, count });
+        }
+        catch {
+            // Diagnostics must not reach the turn either.
+        }
+    };
+    const send = async (events) => {
+        try {
+            const body = {
+                schemaVersion: index_js_1.RUNTIME_METRIC_EVENT_SCHEMA_VERSION,
+                events,
+            };
+            const response = await fetchImpl(endpoint, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${config.apiKey}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(config.requestTimeoutMs),
+            });
+            try {
+                await response.body?.cancel();
+            }
+            catch {
+                // The answer carries nothing the runtime needs.
+            }
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    };
+    const flush = () => {
+        if (inFlight)
+            return inFlight;
+        if (queued() === 0)
+            return Promise.resolve();
+        inFlight = (async () => {
+            try {
+                // An event recorded while another type is on the wire may land in a
+                // queue that was already drained: go round again until all are empty.
+                while (queued() > 0) {
+                    for (const queue of queues.values()) {
+                        while (queue.length > 0) {
+                            const batch = queue.splice(0, config.maxBatchSize);
+                            if (!await send(batch))
+                                drop('send-failed', batch.length);
+                        }
+                    }
+                }
+            }
+            finally {
+                inFlight = undefined;
+            }
+        })();
+        return inFlight;
+    };
+    const ensureTimer = () => {
+        if (timer || closed)
+            return;
+        timer = setInterval(() => {
+            void flush();
+        }, config.flushIntervalMs);
+        timer.unref?.();
+    };
+    const scheduleFlush = () => {
+        if (flushScheduled)
+            return;
+        flushScheduled = true;
+        queueMicrotask(() => {
+            flushScheduled = false;
+            void flush();
+        });
+    };
+    return {
+        identity,
+        get pending() {
+            return queued();
+        },
+        record(event) {
+            try {
+                if (closed) {
+                    drop('closed', 1);
+                    return;
+                }
+                const checked = index_js_1.RuntimeMetricEventSchema.safeParse(event);
+                if (!checked.success
+                    || checked.data.appId !== identity.appId
+                    || checked.data.environmentId !== identity.environmentId) {
+                    drop('invalid', 1);
+                    return;
+                }
+                if (queued() >= config.maxQueueSize) {
+                    drop('queue-full', 1);
+                    return;
+                }
+                const queue = queues.get(checked.data.eventType) ?? [];
+                queues.set(checked.data.eventType, queue);
+                queue.push(checked.data);
+                ensureTimer();
+                if (queue.length >= config.maxBatchSize)
+                    scheduleFlush();
+            }
+            catch {
+                // Recording is best effort and must never fail a turn.
+            }
+        },
+        flush,
+        async close() {
+            closed = true;
+            if (timer) {
+                clearInterval(timer);
+                timer = undefined;
+            }
+            await flush();
+        },
+    };
+}
+/**
+ * The sink of a connected app, or undefined. The key (and the optional
+ * self-hosting URL) come from the environment; the app and environment come
+ * from the connection the runtime looked up (`lookupRuntimeConnection`), so
+ * the sink exists only once that lookup resolved. Standalone apps (no
+ * `GLIRASTES_API_KEY`) get no sink and stay network-silent; an invalid
+ * connection also yields none, because metrics must never stop a chat from
+ * starting. `GLIRASTES_BUILD_ID` (optional) names the deployed build.
+ */
+function createRuntimeMetricsSinkFromEnv(env = process.env, options = {}) {
+    const { connection, ...sinkOptions } = options;
+    if (!connection)
+        return undefined;
+    const buildId = env.GLIRASTES_BUILD_ID?.trim();
+    try {
+        const config = (0, runtime_mode_js_1.resolveRuntimeConnectionConfig)(env);
+        if (!config)
+            return undefined;
+        return createRuntimeMetricsSink({
+            ...sinkOptions,
+            controlPlaneUrl: config.baseUrl,
+            apiKey: config.apiKey,
+            appId: connection.appId,
+            environmentId: connection.environmentId,
+            buildId: buildId && index_js_1.RUNTIME_METRIC_LABEL_PATTERN.test(buildId) ? buildId : null,
+        });
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/cjs/runtime/metrics/turn-recorder.d.ts

@@ -0,0 +1,62 @@
+import { type RuntimeMetricEvent, type RuntimeTurnCost, type RuntimeTurnErrorCode, type RuntimeTurnStatus, type TechnicalRuntimeEventV2, type ToolContractRejectedEvent } from '../../contracts/index.js';
+import type { TurnSnapshot } from '../turn-snapshot.js';
+/** Who reports: fixed per sink, attached to every event. */
+export interface RuntimeMetricsIdentity {
+    readonly appId: string;
+    readonly environmentId: string;
+    readonly buildId: string | null;
+    readonly instanceId: string;
+}
+/**
+ * Receives finished turns and contract rejections. `record` must return
+ * immediately and never throw: delivery happens later, off the turn, and is
+ * dropped on failure.
+ */
+export interface RuntimeMetricsSink {
+    readonly identity: RuntimeMetricsIdentity;
+    record(event: RuntimeMetricEvent): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+/** One model step, already reduced to content-free numbers and tool names. */
+export interface TurnMetricsStep {
+    model: string | null;
+    inputTokens: number;
+    outputTokens: number;
+    cost: RuntimeTurnCost;
+    /** Model-facing names of every tool call in the step (one entry per call). */
+    toolNames: ReadonlyArray<string>;
+    /** Model-facing names of the calls that failed (one entry per failure). */
+    failedToolNames: ReadonlyArray<string>;
+}
+export interface TurnMetricsOutcome {
+    status: RuntimeTurnStatus;
+    errorCode: RuntimeTurnErrorCode | null;
+}
+export interface TurnMetricsRecorder {
+    /** The first streamed chunk of the turn; later calls do nothing. */
+    markFirstChunk(): void;
+    recordStep(step: TurnMetricsStep): void;
+    /**
+     * Builds the turn's event and hands it to the sink exactly once. Returns
+     * the event, or undefined when the turn was already finished. Never throws.
+     */
+    finish(outcome: TurnMetricsOutcome): TechnicalRuntimeEventV2 | undefined;
+    /**
+     * An endpoint refused a call its tool schema accepted (spec 4.7). Hands a
+     * content-free `tool_contract_rejected` event to the sink right away and
+     * returns it; undefined for a tool outside the pinned snapshot. The name is
+     * the manifest name or its model-facing encoding. Never throws.
+     */
+    recordToolContractRejected(toolName: string, httpStatus: 400 | 422): ToolContractRejectedEvent | undefined;
+}
+export interface TurnMetricsRecorderOptions {
+    sink: RuntimeMetricsSink;
+    /** Pinned snapshot: names the revision and maps tool names to tool ids. */
+    snapshot?: TurnSnapshot;
+    /** Turn start (request start), in the clock of `now`. */
+    startedAtMs: number;
+    now?: () => number;
+    createEventId?: () => string;
+}
+export declare function createTurnMetricsRecorder(options: TurnMetricsRecorderOptions): TurnMetricsRecorder;

package/dist/cjs/runtime/metrics/turn-recorder.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTurnMetricsRecorder = createTurnMetricsRecorder;
+const node_crypto_1 = require("node:crypto");
+const index_js_1 = require("../../contracts/index.js");
+const local_tool_bindings_js_1 = require("../local-tool-bindings.js");
+const cost_js_1 = require("./cost.js");
+const MAX_DURATION_MS = 86_400_000;
+const MAX_CALLS = 10_000;
+function bounded(value, max) {
+    return Number.isFinite(value) ? Math.min(max, Math.max(0, Math.round(value))) : 0;
+}
+function technicalLabel(value) {
+    return value !== null && index_js_1.RUNTIME_METRIC_LABEL_PATTERN.test(value) ? value : null;
+}
+function createTurnMetricsRecorder(options) {
+    const now = options.now ?? Date.now;
+    const createEventId = options.createEventId ?? node_crypto_1.randomUUID;
+    const manifestTools = options.snapshot?.manifestRevision.tools ?? [];
+    const toolIdByName = new Map(manifestTools.map((tool) => [
+        (0, local_tool_bindings_js_1.modelFacingToolName)(tool.name),
+        tool.toolId,
+    ]));
+    const schemaDigestByName = new Map(manifestTools.map((tool) => [
+        (0, local_tool_bindings_js_1.modelFacingToolName)(tool.name),
+        tool.inputSchemaDigest,
+    ]));
+    const costs = [];
+    const usage = new Map();
+    let firstChunkAtMs;
+    let model = null;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let toolCallCount = 0;
+    let toolErrorCount = 0;
+    let finished = false;
+    const usageOf = (toolName) => {
+        const toolId = toolIdByName.get(toolName);
+        if (!toolId)
+            return undefined;
+        let entry = usage.get(toolId);
+        if (!entry) {
+            entry = { calls: 0, errors: 0 };
+            usage.set(toolId, entry);
+        }
+        return entry;
+    };
+    const listedTools = () => [...usage.entries()]
+        .map(([toolId, entry]) => ({
+        toolId,
+        calls: Math.min(MAX_CALLS, entry.calls),
+        errors: Math.min(MAX_CALLS, entry.errors, entry.calls),
+    }))
+        .filter((tool) => tool.calls > 0)
+        .sort((left, right) => right.calls - left.calls
+        || left.toolId.localeCompare(right.toolId))
+        .slice(0, index_js_1.RUNTIME_METRIC_MAX_TOOLS)
+        .sort((left, right) => left.toolId.localeCompare(right.toolId));
+    const build = (outcome) => {
+        const endedAtMs = now();
+        const totalMs = bounded(endedAtMs - options.startedAtMs, MAX_DURATION_MS);
+        const firstTokenMs = firstChunkAtMs === undefined
+            ? null
+            : Math.min(totalMs, bounded(firstChunkAtMs - options.startedAtMs, MAX_DURATION_MS));
+        const calls = Math.min(MAX_CALLS, toolCallCount);
+        const parsed = index_js_1.TechnicalRuntimeEventV2Schema.safeParse({
+            schemaVersion: 2,
+            eventId: createEventId(),
+            eventType: 'turn.finished',
+            occurredAt: new Date(endedAtMs).toISOString(),
+            appId: options.sink.identity.appId,
+            environmentId: options.sink.identity.environmentId,
+            buildId: options.sink.identity.buildId,
+            instanceId: options.sink.identity.instanceId,
+            revisionId: options.snapshot?.agentRevision.revisionId ?? null,
+            model,
+            status: outcome.status,
+            errorCode: outcome.errorCode,
+            inputTokens: bounded(inputTokens, index_js_1.RUNTIME_METRIC_MAX_COUNT),
+            outputTokens: bounded(outputTokens, index_js_1.RUNTIME_METRIC_MAX_COUNT),
+            cost: (0, cost_js_1.combineTurnCost)(costs),
+            latency: { firstTokenMs, totalMs },
+            toolCallCount: calls,
+            toolErrorCount: Math.min(calls, toolErrorCount),
+            tools: listedTools(),
+        });
+        return parsed.success ? parsed.data : undefined;
+    };
+    return {
+        markFirstChunk() {
+            firstChunkAtMs ??= now();
+        },
+        recordStep(step) {
+            if (finished)
+                return;
+            model = technicalLabel(step.model) ?? model;
+            inputTokens += Number.isFinite(step.inputTokens) ? step.inputTokens : 0;
+            outputTokens += Number.isFinite(step.outputTokens) ? step.outputTokens : 0;
+            costs.push(step.cost);
+            toolCallCount += step.toolNames.length;
+            toolErrorCount += step.failedToolNames.length;
+            for (const name of step.toolNames) {
+                const entry = usageOf(name);
+                if (entry)
+                    entry.calls += 1;
+            }
+            for (const name of step.failedToolNames) {
+                const entry = usageOf(name);
+                if (entry)
+                    entry.errors += 1;
+            }
+        },
+        recordToolContractRejected(toolName, httpStatus) {
+            try {
+                // Endpoint tools may carry the dotted definitionId as `toolName`; the
+                // maps are keyed by the model-facing encoding (idempotent for names
+                // that are already encoded).
+                const modelName = (0, local_tool_bindings_js_1.modelFacingToolName)(toolName);
+                const toolId = toolIdByName.get(modelName);
+                const inputSchemaDigest = schemaDigestByName.get(modelName);
+                if (!toolId || !inputSchemaDigest)
+                    return undefined;
+                const parsed = index_js_1.ToolContractRejectedEventSchema.safeParse({
+                    schemaVersion: 2,
+                    eventId: createEventId(),
+                    eventType: 'tool_contract_rejected',
+                    occurredAt: new Date(now()).toISOString(),
+                    appId: options.sink.identity.appId,
+                    environmentId: options.sink.identity.environmentId,
+                    buildId: options.sink.identity.buildId,
+                    instanceId: options.sink.identity.instanceId,
+                    revisionId: options.snapshot?.agentRevision.revisionId ?? null,
+                    toolId,
+                    inputSchemaDigest,
+                    httpStatus,
+                });
+                if (!parsed.success)
+                    return undefined;
+                try {
+                    options.sink.record(parsed.data);
+                }
+                catch {
+                    // A sink must never fail a tool call.
+                }
+                return parsed.data;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        finish(outcome) {
+            if (finished)
+                return undefined;
+            finished = true;
+            try {
+                const event = build(outcome);
+                if (!event)
+                    return undefined;
+                try {
+                    options.sink.record(event);
+                }
+                catch {
+                    // A sink must never fail a turn.
+                }
+                return event;
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
+}

package/dist/cjs/runtime/offline-execution-lease.d.ts

@@ -0,0 +1,27 @@
+import { type ExecutionBudget, type ExecutionLease, type ToolRiskClass } from '../contracts/index.js';
+import { type RuntimePublicKeyProvider } from '../sync/signature-verifier.js';
+export interface OfflineExecutionLeaseScope {
+    tenantId: string;
+    targetAppId: string;
+    environmentId: string;
+    runnerId: string;
+    deploymentId: string;
+    agentRevisionId: string;
+    triggerId: string;
+}
+export interface OfflineExecutionLeaseAuthorization {
+    leaseId: string;
+    budget: ExecutionBudget;
+}
+export declare class OfflineExecutionLeaseAuthorizer {
+    private readonly verifier;
+    constructor(keys: RuntimePublicKeyProvider);
+    authorize(input: {
+        lease: ExecutionLease;
+        scope: OfflineExecutionLeaseScope;
+        riskClass: ToolRiskClass;
+        requiresApproval: boolean;
+        at?: Date;
+    }): Promise<OfflineExecutionLeaseAuthorization>;
+    private assertScope;
+}

package/dist/cjs/runtime/offline-execution-lease.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OfflineExecutionLeaseAuthorizer = void 0;
+const index_js_1 = require("../contracts/index.js");
+const signature_verifier_js_1 = require("../sync/signature-verifier.js");
+class OfflineExecutionLeaseAuthorizer {
+    verifier;
+    constructor(keys) {
+        this.verifier = new signature_verifier_js_1.RuntimeRevisionVerifier(keys);
+    }
+    async authorize(input) {
+        const lease = index_js_1.ExecutionLeaseSchema.parse(input.lease);
+        await this.verifier.verifyExecutionLease(lease);
+        this.assertScope(lease, input.scope);
+        const now = (input.at ?? new Date()).getTime();
+        if (now < Date.parse(lease.issuedAt)) {
+            throw new Error('Offline execution lease is not active yet');
+        }
+        if (now >= Date.parse(lease.expiresAt)) {
+            throw new Error('Offline execution lease has expired');
+        }
+        if (input.requiresApproval) {
+            throw new Error('Approval-required tools cannot execute offline');
+        }
+        if (input.riskClass !== 'safe-read') {
+            throw new Error('Offline execution is restricted to safe-read tools');
+        }
+        if (!lease.allowedRiskClasses.includes(input.riskClass)) {
+            throw new Error('Tool risk class is outside the offline execution lease');
+        }
+        return {
+            leaseId: lease.leaseId,
+            budget: structuredClone(lease.budget),
+        };
+    }
+    assertScope(lease, scope) {
+        const matches = (lease.tenantId === scope.tenantId
+            && lease.targetAppId === scope.targetAppId
+            && lease.environmentId === scope.environmentId
+            && lease.runnerId === scope.runnerId
+            && lease.deploymentId === scope.deploymentId
+            && lease.agentRevisionId === scope.agentRevisionId
+            && lease.triggerId === scope.triggerId);
+        if (!matches) {
+            throw new Error('Offline execution lease scope does not match the run');
+        }
+    }
+}
+exports.OfflineExecutionLeaseAuthorizer = OfflineExecutionLeaseAuthorizer;

package/dist/cjs/runtime/policy-overlay.d.ts

@@ -0,0 +1,86 @@
+import { type ExecutionBudget, type RuntimePolicyRevision, type RuntimeToolPolicy } from '../contracts/index.js';
+import { type ConfirmationRelaxationOutcome, type ToolPolicyEntry } from '../contracts/tool-policy.js';
+/** One Platform delta for one tool the deployed code owns. */
+export type PolicyOverlayEntry = {
+    toolId: string;
+} & ToolPolicyEntry;
+export interface PolicyOverlayIgnoredEntry {
+    toolId: string;
+    reason: 'platform-tool-not-in-code';
+}
+/**
+ * What became of a Platform relaxation of confirmation for a tool that asks
+ * before it runs. `locked-locally`: the local code report does not open this
+ * confirmation to the Platform (tool-policy.json decided it, the report names
+ * no origin, the local class is tier 3, or the caller passed no report).
+ * `duplicate-decisions`: the overlay holds more than one decision for the
+ * tool, which a signed revision never does. The rest come from the shared
+ * rule `confirmationRelaxationOutcome`.
+ */
+export type PolicyOverlayRelaxationOutcome = 'applied' | 'locked-locally' | 'duplicate-decisions' | Exclude<ConfirmationRelaxationOutcome, 'applies'>;
+/** Content-free: a tool id and a code, never a value. */
+export interface PolicyOverlayRelaxation {
+    toolId: string;
+    outcome: PolicyOverlayRelaxationOutcome;
+}
+export interface PolicyOverlayResult {
+    policies: RuntimeToolPolicy[];
+    ignored: PolicyOverlayIgnoredEntry[];
+    /** One entry per asking tool a Platform decision tried to relax, in local order. */
+    relaxations: PolicyOverlayRelaxation[];
+}
+export interface PolicyOverlayOptions {
+    /**
+     * Tools whose confirmation a signed Platform decision may switch off:
+     * `relaxableToolIds(setupArtifact)` of the running code. Every other tool
+     * keeps its local confirmation; without this set nothing relaxes.
+     */
+    relaxableToolIds?: ReadonlySet<string>;
+}
+/**
+ * A Platform policy overlay whose signature the sync layer already verified.
+ * The runtime reads the last accepted value; it never fetches one per turn.
+ */
+export interface VerifiedPolicyOverlay {
+    /** Platform policy revision id; revocations of it keep matching. */
+    revisionId: string;
+    revision: number;
+    entries: PolicyOverlayEntry[];
+    /** Optional Platform budget; it can only tighten the local limits. */
+    budget?: ExecutionBudget;
+}
+/**
+ * Composes the local effective policies with a verified Platform overlay
+ * (spec 4.9, resolveToolPolicy semantics). The overlay restricts: disable,
+ * raise the risk class, narrow roles, require confirmation; `enabled: true`
+ * and a lower risk class are no-ops. Its one relaxation is D16 (spec 4.5 as
+ * amended 2026-10-05): a signed `requiresApproval: false` switches a tool's
+ * confirmation off where `confirmationRelaxationOutcome` applies at the
+ * effective risk class (pinned to this tool, at most tier 2, lapsing once
+ * the risk rises above the pin; tier 3 and `unknown` never) and only for
+ * tools in `relaxableToolIds`, so a local lock in tool-policy.json always
+ * wins. Overlay ids without a local policy are ignored and reported.
+ */
+export declare function applyPolicyOverlay(local: RuntimeToolPolicy[], overlay: PolicyOverlayEntry[], options?: PolicyOverlayOptions): PolicyOverlayResult;
+/**
+ * The tools of the running code whose confirmation a signed Platform decision
+ * may switch off (D16): those the committed setup artifact (the code report)
+ * attributes to the code default, up to tier 2 (`platformMayRelaxConfirmation`).
+ * An explicit `requiresApproval: true` or a risk raise in tool-policy.json and
+ * an artifact without provenance are local locks.
+ */
+export declare function relaxableToolIds(setupArtifact: unknown): Set<string>;
+/**
+ * Platform descriptions for tools the deployed code has (spec 4.5: Platform >
+ * local > code for prose). The last delta for a tool wins, like the policy
+ * layers; deltas for tools the code does not have are ignored.
+ */
+export declare function overlayDescriptions(localToolIds: ReadonlySet<string>, overlay: ReadonlyArray<PolicyOverlayEntry>): Map<string, string>;
+/**
+ * Reads a Platform policy revision the sync manager already verified as an
+ * overlay. The entries are the signed `toolOverrides` deltas (P08b shared
+ * contract item 2), never the reported `toolPolicies`: those repeat what the
+ * code reported and would freeze an old local value, and a relaxation there
+ * is no decision. The revision id keeps Platform revocations matching.
+ */
+export declare function policyOverlayFromRevision(revision: RuntimePolicyRevision): VerifiedPolicyOverlay;