glirastes 0.3.2 → 0.5.0

package/dist/cjs/contracts/revisions.js

@@ -0,0 +1,301 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeSyncBundleSchema = exports.RuntimeDeploymentBundleSchema = exports.SignedPromptBindingSchema = exports.RuntimeRevisionEnvelopeSchema = exports.ExecutionLeaseSchema = exports.SecurityRevocationSchema = exports.RuntimePolicyRevisionSchema = exports.RuntimeToolPolicySchema = exports.PlannerRevisionPayloadSchema = exports.AgentRevisionSchema = exports.ManifestRevisionSchema = exports.ManifestToolSchema = exports.ToolPresentationSchema = exports.LocalBindingReferenceSchema = exports.RevisionSignatureSchema = exports.ToolRiskClassSchema = void 0;
+const zod_1 = require("zod");
+const runtime_js_1 = require("./runtime.js");
+const content_boundary_js_1 = require("./content-boundary.js");
+const tool_policy_entry_js_1 = require("./tool-policy-entry.js");
+var tool_policy_entry_js_2 = require("./tool-policy-entry.js");
+Object.defineProperty(exports, "ToolRiskClassSchema", { enumerable: true, get: function () { return tool_policy_entry_js_2.ToolRiskClassSchema; } });
+const uuid = zod_1.z.uuid();
+const identifier = zod_1.z.string().trim().min(1).max(200);
+const digest = zod_1.z.string().regex(/^sha256:[A-Za-z0-9+/=_-]+$/);
+const publishedAt = zod_1.z.iso.datetime({ offset: true });
+exports.RevisionSignatureSchema = zod_1.z.object({
+    algorithm: zod_1.z.literal('Ed25519'),
+    keyId: identifier,
+    value: zod_1.z.string().trim().min(8).max(1_024),
+}).strict();
+exports.LocalBindingReferenceSchema = zod_1.z.object({
+    bindingId: identifier,
+    kind: zod_1.z.enum(['model', 'tool', 'prompt', 'store']),
+    providerAlias: identifier.optional(),
+}).strict();
+/**
+ * Curated, locale-specific labels for operator-facing surfaces. These values
+ * describe the operation; they never replace policy or execution checks.
+ */
+exports.ToolPresentationSchema = zod_1.z.object({
+    locale: zod_1.z.string().trim().min(2).max(35)
+        .regex(/^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$/),
+    singular: zod_1.z.string().trim().min(1).max(200),
+    plural: zod_1.z.string().trim().min(1).max(200),
+    approval: zod_1.z.string().trim().min(1).max(500),
+}).strict();
+const ManifestToolBaseSchema = zod_1.z.object({
+    toolId: uuid,
+    sourceFingerprint: digest,
+    name: identifier,
+    description: zod_1.z.string().trim().min(1).max(4_000),
+    modelName: zod_1.z.string().regex(/^[A-Za-z0-9_-]+$/).max(200).optional(),
+    module: identifier.optional(),
+    sharedWith: zod_1.z.array(identifier).max(50).optional(),
+    usageHints: zod_1.z.array(zod_1.z.string().trim().min(1).max(500)).min(1).max(20)
+        .optional(),
+    presentation: exports.ToolPresentationSchema.optional(),
+    riskClass: tool_policy_entry_js_1.ToolRiskClassSchema,
+    enabled: zod_1.z.boolean(),
+    tombstone: zod_1.z.boolean(),
+    inputSchemaDigest: digest,
+    outputSchemaDigest: digest,
+});
+const ManifestEndpointToolSchema = ManifestToolBaseSchema.extend({
+    executionKind: zod_1.z.literal('endpoint'),
+    method: zod_1.z.enum(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE']),
+    path: zod_1.z.string().startsWith('/').max(2_048),
+    authBindingRef: identifier,
+}).strict();
+const ManifestUiToolSchema = ManifestToolBaseSchema.extend({
+    executionKind: zod_1.z.literal('ui'),
+    actionBindingRef: identifier,
+}).strict();
+exports.ManifestToolSchema = zod_1.z.discriminatedUnion('executionKind', [
+    ManifestEndpointToolSchema,
+    ManifestUiToolSchema,
+]).superRefine((tool, context) => {
+    if (tool.tombstone && tool.enabled) {
+        context.addIssue({
+            code: 'custom',
+            message: 'A tombstoned tool cannot remain enabled',
+            path: ['enabled'],
+        });
+    }
+});
+exports.ManifestRevisionSchema = zod_1.z.object({
+    revisionId: uuid,
+    revision: zod_1.z.number().int().positive(),
+    tenantId: uuid,
+    targetAppId: uuid,
+    environmentId: uuid,
+    sourceDigest: digest,
+    tools: zod_1.z.array(exports.ManifestToolSchema),
+    publishedAt,
+    signature: exports.RevisionSignatureSchema,
+}).strict();
+exports.AgentRevisionSchema = zod_1.z.object({
+    revisionId: uuid,
+    revision: zod_1.z.number().int().positive(),
+    agentId: uuid,
+    tenantId: uuid,
+    name: zod_1.z.string().trim().min(1).max(200),
+    objective: zod_1.z.string().trim().min(1).max(4_000),
+    modelAlias: identifier,
+    promptBindingRef: identifier,
+    toolAllowlist: zod_1.z.array(uuid),
+    budget: runtime_js_1.ExecutionBudgetSchema,
+    publishedAt,
+    signature: exports.RevisionSignatureSchema,
+}).strict();
+/**
+ * The v2 app-scoped planner payload the Platform publishes from a setup run.
+ * It references a budget profile instead of carrying a concrete budget; the
+ * concrete budget is pinned by the policy revision of the same deployment.
+ */
+exports.PlannerRevisionPayloadSchema = zod_1.z.object({
+    schemaVersion: zod_1.z.literal(1),
+    plannerId: identifier,
+    modelBindingRef: identifier,
+    promptBindingRef: identifier,
+    budgetProfileRef: identifier,
+    toolAllowlist: zod_1.z.array(uuid),
+}).strict();
+exports.RuntimeToolPolicySchema = zod_1.z.object({
+    toolId: uuid,
+    enabled: zod_1.z.boolean(),
+    riskClass: tool_policy_entry_js_1.ToolRiskClassSchema,
+    requiresApproval: zod_1.z.boolean(),
+    allowedRoles: zod_1.z.array(identifier).max(100),
+}).strict();
+exports.RuntimePolicyRevisionSchema = zod_1.z.object({
+    revisionId: uuid,
+    revision: zod_1.z.number().int().positive(),
+    tenantId: uuid,
+    environmentId: uuid,
+    budget: runtime_js_1.ExecutionBudgetSchema,
+    toolPolicies: zod_1.z.array(exports.RuntimeToolPolicySchema),
+    /**
+     * Signed Platform decisions as deltas (P08b shared contract item 2): only
+     * fields an operator decided, one entry per tool. Absent on revisions
+     * without decisions, which therefore keep their bytes.
+     */
+    toolOverrides: zod_1.z.array(tool_policy_entry_js_1.ToolOverrideDeltaSchema).max(5_000).default([])
+        .superRefine((deltas, context) => {
+        const seen = new Set();
+        deltas.forEach((delta, index) => {
+            if (seen.has(delta.toolId)) {
+                context.addIssue({
+                    code: 'custom',
+                    message: 'A tool has more than one Platform decision',
+                    path: [index, 'toolId'],
+                });
+            }
+            seen.add(delta.toolId);
+        });
+    }),
+    publishedAt,
+    signature: exports.RevisionSignatureSchema,
+}).strict();
+exports.SecurityRevocationSchema = zod_1.z.object({
+    revocationId: uuid,
+    environmentId: uuid,
+    effectiveAt: publishedAt,
+    reasonCode: identifier,
+    toolIds: zod_1.z.array(uuid).default([]),
+    agentRevisionIds: zod_1.z.array(uuid).default([]),
+    policyRevisionIds: zod_1.z.array(uuid).default([]),
+    signature: exports.RevisionSignatureSchema,
+}).strict();
+exports.ExecutionLeaseSchema = zod_1.z.object({
+    schemaVersion: zod_1.z.literal(1),
+    leaseId: uuid,
+    tenantId: uuid,
+    targetAppId: uuid,
+    environmentId: uuid,
+    runnerId: uuid,
+    deploymentId: uuid,
+    agentRevisionId: uuid,
+    triggerId: identifier,
+    allowedRiskClasses: zod_1.z.array(tool_policy_entry_js_1.ToolRiskClassSchema).min(1),
+    budget: runtime_js_1.ExecutionBudgetSchema,
+    issuedAt: publishedAt,
+    expiresAt: publishedAt,
+    signature: exports.RevisionSignatureSchema,
+}).strict().superRefine((lease, context) => {
+    if (Date.parse(lease.expiresAt) <= Date.parse(lease.issuedAt)) {
+        context.addIssue({
+            code: 'custom',
+            message: 'Execution lease must expire after it is issued',
+            path: ['expiresAt'],
+        });
+    }
+});
+exports.RuntimeRevisionEnvelopeSchema = zod_1.z.object({
+    schemaVersion: zod_1.z.literal(1),
+    revisionId: uuid,
+    revisionType: zod_1.z.enum(['tool', 'manifest', 'agent', 'policy', 'config']),
+    revision: zod_1.z.number().int().positive(),
+    tenantId: uuid,
+    targetAppId: uuid,
+    environmentId: uuid.optional(),
+    subjectId: uuid.optional(),
+    contentHash: digest,
+    payload: zod_1.z.unknown(),
+    publishedAt,
+    signature: exports.RevisionSignatureSchema,
+}).strict().superRefine((revisionEnvelope, context) => {
+    if (['manifest', 'policy'].includes(revisionEnvelope.revisionType)
+        && !revisionEnvelope.environmentId) {
+        context.addIssue({
+            code: 'custom',
+            message: 'Environment-scoped revisions require environmentId',
+            path: ['environmentId'],
+        });
+    }
+    if (['tool', 'agent'].includes(revisionEnvelope.revisionType)
+        && !revisionEnvelope.subjectId) {
+        context.addIssue({
+            code: 'custom',
+            message: 'Subject-scoped revisions require subjectId',
+            path: ['subjectId'],
+        });
+    }
+    const forbiddenPath = (0, content_boundary_js_1.findForbiddenContentPath)(revisionEnvelope.payload, ['payload']);
+    if (forbiddenPath) {
+        context.addIssue({
+            code: 'custom',
+            message: 'Runtime revision payload contains raw content or credentials',
+            path: forbiddenPath,
+        });
+    }
+});
+/**
+ * Signed desired-state pin for one prompt bundle. The Platform signs the
+ * binding; the bundle contents stay in the customer-controlled registry and are
+ * proven by the content digest. Defined here (not in prompt-bundle.ts) because
+ * the deployment bundle below carries it and prompt-bundle already imports from
+ * this module.
+ */
+exports.SignedPromptBindingSchema = zod_1.z.object({
+    schemaVersion: zod_1.z.literal(1),
+    appId: uuid,
+    revisionId: uuid,
+    revision: zod_1.z.number().int().positive(),
+    bundleDigest: digest,
+    artifactRef: zod_1.z.string().trim().min(1).max(2_048),
+    activatedAt: publishedAt,
+    signature: exports.RevisionSignatureSchema,
+}).strict();
+const DEPLOYMENT_BINDING_FIELDS = [
+    'configRevision',
+    'runtimeDigest',
+    'promptDigest',
+    'promptBinding',
+];
+exports.RuntimeDeploymentBundleSchema = zod_1.z.object({
+    deploymentId: uuid,
+    environmentId: uuid,
+    status: zod_1.z.enum(['pending', 'active']),
+    rolloutMode: zod_1.z.enum(['stable', 'canary']),
+    targetPercentage: zod_1.z.number().int().min(1).max(100),
+    pinned: zod_1.z.boolean(),
+    healthStatus: zod_1.z.enum(['unknown', 'healthy', 'degraded', 'unhealthy']),
+    agentRevision: exports.RuntimeRevisionEnvelopeSchema.refine((revision) => revision.revisionType === 'agent', 'Expected agent revision'),
+    manifestRevision: exports.RuntimeRevisionEnvelopeSchema.refine((revision) => revision.revisionType === 'manifest', 'Expected manifest revision'),
+    policyRevision: exports.RuntimeRevisionEnvelopeSchema.refine((revision) => revision.revisionType === 'policy', 'Expected policy revision'),
+    // Artifact bindings: present on every deployment created since the Platform
+    // binds runtime and prompt artifacts; absent on the transitional shape.
+    configRevision: exports.RuntimeRevisionEnvelopeSchema.refine((revision) => revision.revisionType === 'config', 'Expected config revision').optional(),
+    runtimeDigest: digest.optional(),
+    promptDigest: digest.optional(),
+    promptBinding: exports.SignedPromptBindingSchema.optional(),
+    updatedAt: publishedAt,
+}).strict().superRefine((deployment, context) => {
+    // The server emits all four binding fields or none. A partial set means
+    // something was stripped or tampered with and must not pass as either shape.
+    const bindingsPresent = DEPLOYMENT_BINDING_FIELDS
+        .filter((field) => deployment[field] !== undefined);
+    if (bindingsPresent.length > 0
+        && bindingsPresent.length < DEPLOYMENT_BINDING_FIELDS.length) {
+        for (const field of DEPLOYMENT_BINDING_FIELDS) {
+            if (deployment[field] === undefined) {
+                context.addIssue({
+                    code: 'custom',
+                    message: 'Deployment artifact bindings are all-or-nothing',
+                    path: [field],
+                });
+            }
+        }
+    }
+    if (deployment.rolloutMode === 'stable'
+        && deployment.targetPercentage !== 100) {
+        context.addIssue({
+            code: 'custom',
+            message: 'Stable rollout must target 100 percent',
+            path: ['targetPercentage'],
+        });
+    }
+    if (deployment.rolloutMode === 'canary'
+        && deployment.targetPercentage >= 100) {
+        context.addIssue({
+            code: 'custom',
+            message: 'Canary rollout must target less than 100 percent',
+            path: ['targetPercentage'],
+        });
+    }
+});
+exports.RuntimeSyncBundleSchema = zod_1.z.object({
+    cursor: publishedAt,
+    activeSnapshotComplete: zod_1.z.literal(true),
+    deployments: zod_1.z.array(exports.RuntimeDeploymentBundleSchema),
+    revocations: zod_1.z.array(exports.SecurityRevocationSchema),
+}).strict();

package/dist/cjs/contracts/runtime.d.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+export declare const RuntimeEnvironmentNameSchema: z.ZodString;
+export declare const RuntimeEnvironmentSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    tenantId: z.ZodUUID;
+    targetAppId: z.ZodUUID;
+    name: z.ZodString;
+    status: z.ZodEnum<{
+        disconnected: "disconnected";
+        connecting: "connecting";
+        connected: "connected";
+        degraded: "degraded";
+        disabled: "disabled";
+    }>;
+}, z.core.$strict>;
+export declare const PrincipalSchema: z.ZodObject<{
+    subjectId: z.ZodString;
+    tenantId: z.ZodString;
+    roles: z.ZodArray<z.ZodString>;
+    attributes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+/**
+ * Immutable prompt-revision identity pinned for the lifetime of one turn.
+ */
+export declare const PromptPinSchema: z.ZodObject<{
+    revisionId: z.ZodUUID;
+    revision: z.ZodNumber;
+    bundleDigest: z.ZodString;
+}, z.core.$strict>;
+export declare const DelegationBudgetSchema: z.ZodObject<{
+    maxDepth: z.ZodNumber;
+    maxBreadth: z.ZodNumber;
+    sharedBudget: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const ExecutionBudgetSchema: z.ZodObject<{
+    maxModelSteps: z.ZodNumber;
+    maxToolCalls: z.ZodNumber;
+    totalTimeoutMs: z.ZodNumber;
+    toolTimeoutMs: z.ZodNumber;
+    maxInputTokens: z.ZodNumber;
+    maxOutputTokens: z.ZodNumber;
+    maxEstimatedCostUsd: z.ZodNumber;
+    maxRepeatedFingerprint: z.ZodNumber;
+    maxConsecutiveErrors: z.ZodNumber;
+    delegation: z.ZodObject<{
+        maxDepth: z.ZodNumber;
+        maxBreadth: z.ZodNumber;
+        sharedBudget: z.ZodBoolean;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type RuntimeEnvironment = z.infer<typeof RuntimeEnvironmentSchema>;
+export type Principal = z.infer<typeof PrincipalSchema>;
+export type DelegationBudget = z.infer<typeof DelegationBudgetSchema>;
+export type ExecutionBudget = z.infer<typeof ExecutionBudgetSchema>;
+export type PromptPin = z.infer<typeof PromptPinSchema>;

package/dist/cjs/contracts/runtime.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutionBudgetSchema = exports.DelegationBudgetSchema = exports.PromptPinSchema = exports.PrincipalSchema = exports.RuntimeEnvironmentSchema = exports.RuntimeEnvironmentNameSchema = void 0;
+const zod_1 = require("zod");
+const content_boundary_js_1 = require("./content-boundary.js");
+const identifier = zod_1.z.string().trim().min(1).max(200);
+const uuid = zod_1.z.uuid();
+exports.RuntimeEnvironmentNameSchema = zod_1.z.string()
+    .trim()
+    .min(1)
+    .max(64)
+    .regex(/^[a-z][a-z0-9-]*$/);
+exports.RuntimeEnvironmentSchema = zod_1.z.object({
+    id: uuid,
+    tenantId: uuid,
+    targetAppId: uuid,
+    name: exports.RuntimeEnvironmentNameSchema,
+    status: zod_1.z.enum(['disconnected', 'connecting', 'connected', 'degraded', 'disabled']),
+}).strict();
+exports.PrincipalSchema = zod_1.z.object({
+    subjectId: identifier,
+    tenantId: identifier,
+    roles: zod_1.z.array(identifier).max(100),
+    attributes: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).default({}),
+}).strict().superRefine((principal, context) => {
+    const path = (0, content_boundary_js_1.findForbiddenContentPath)(principal.attributes, ['attributes']);
+    if (path) {
+        context.addIssue({
+            code: 'custom',
+            message: 'Principal attributes must not contain raw credentials',
+            path,
+        });
+    }
+});
+/**
+ * Immutable prompt-revision identity pinned for the lifetime of one turn.
+ */
+exports.PromptPinSchema = zod_1.z.object({
+    revisionId: uuid,
+    revision: zod_1.z.number().int().positive(),
+    bundleDigest: zod_1.z.string().regex(/^sha256:(?:[A-Za-z0-9_-]{43}|[A-Za-z0-9+/]{43}=)$/),
+}).strict();
+exports.DelegationBudgetSchema = zod_1.z.object({
+    maxDepth: zod_1.z.number().int().min(0).max(32),
+    maxBreadth: zod_1.z.number().int().min(0).max(128),
+    sharedBudget: zod_1.z.boolean(),
+}).strict();
+exports.ExecutionBudgetSchema = zod_1.z.object({
+    maxModelSteps: zod_1.z.number().int().positive(),
+    maxToolCalls: zod_1.z.number().int().positive(),
+    totalTimeoutMs: zod_1.z.number().int().positive(),
+    toolTimeoutMs: zod_1.z.number().int().positive(),
+    maxInputTokens: zod_1.z.number().int().positive(),
+    maxOutputTokens: zod_1.z.number().int().positive(),
+    maxEstimatedCostUsd: zod_1.z.number().finite().nonnegative(),
+    maxRepeatedFingerprint: zod_1.z.number().int().positive(),
+    maxConsecutiveErrors: zod_1.z.number().int().positive(),
+    delegation: exports.DelegationBudgetSchema,
+}).strict().superRefine((budget, context) => {
+    if (budget.toolTimeoutMs > budget.totalTimeoutMs) {
+        context.addIssue({
+            code: 'custom',
+            message: 'Tool timeout cannot exceed total timeout',
+            path: ['toolTimeoutMs'],
+        });
+    }
+});

package/dist/cjs/contracts/semantic-change.d.ts

@@ -0,0 +1,27 @@
+import { type ToolPresentation, type ToolRiskClass } from './revisions.js';
+export type SemanticChangeClassification = 'unchanged' | 'added' | 'hardening' | 'neutral' | 'loosening';
+export interface ToolSemanticState {
+    toolId: string;
+    enabled: boolean;
+    requiresApproval: boolean;
+    riskClass: ToolRiskClass;
+    allowedRoles?: ReadonlyArray<string>;
+    description?: string;
+    modelName?: string;
+    module?: string;
+    sharedWith?: ReadonlyArray<string>;
+    usageHints?: ReadonlyArray<string>;
+    presentation?: ToolPresentation;
+}
+export interface SemanticChange {
+    toolId: string;
+    classification: SemanticChangeClassification;
+    fields: string[];
+    requiresConfirmation: boolean;
+}
+/**
+ * Compares only the explicit curated and authorization-bearing semantic
+ * fields. Loosening dominates a mixed change so confirmation can never be
+ * hidden by simultaneous hardening or copy changes.
+ */
+export declare function classifyToolSemanticChange(before: ToolSemanticState, after: ToolSemanticState): SemanticChange;

package/dist/cjs/contracts/semantic-change.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyToolSemanticChange = classifyToolSemanticChange;
+const revisions_js_1 = require("./revisions.js");
+const index_js_1 = require("../diagnostics/index.js");
+const tool_policy_js_1 = require("./tool-policy.js");
+function incomparable(toolId) {
+    throw new index_js_1.FoundationDiagnosticError({
+        code: 'E-SEMANTICS-003',
+        operation: 'setup.semantic-change',
+        message: 'A semantic change cannot be classified safely.',
+        remediation: 'review-semantic-change',
+        identifier: toolId,
+    });
+}
+function compareRisk(before, after, toolId) {
+    if (before === after)
+        return 'unchanged';
+    // An out-of-enum label cannot be ranked; never guess a direction.
+    if (!revisions_js_1.ToolRiskClassSchema.safeParse(before).success
+        || !revisions_js_1.ToolRiskClassSchema.safeParse(after).success) {
+        return incomparable(toolId);
+    }
+    const beforeTier = (0, tool_policy_js_1.riskTier)(before);
+    const afterTier = (0, tool_policy_js_1.riskTier)(after);
+    // Equal-tier relabels (the unassessed 'unknown' counts as tier 3) change
+    // no protection, so they never need confirmation.
+    if (beforeTier === afterTier)
+        return 'neutral';
+    return afterTier > beforeTier ? 'hardening' : 'loosening';
+}
+function normalizedSet(values) {
+    return [...new Set(values ?? [])].sort();
+}
+function compareRoles(beforeValue, afterValue, toolId) {
+    const before = normalizedSet(beforeValue);
+    const after = normalizedSet(afterValue);
+    if (before.length === after.length && before.every((role, i) => role === after[i])) {
+        return 'unchanged';
+    }
+    // An empty role list means no additional role restriction at authorization.
+    if (before.length === 0)
+        return 'hardening';
+    if (after.length === 0)
+        return 'loosening';
+    const afterNarrowsBefore = after.every((role) => before.includes(role));
+    const afterWidensBefore = before.every((role) => after.includes(role));
+    if (afterNarrowsBefore)
+        return 'hardening';
+    if (afterWidensBefore)
+        return 'loosening';
+    return incomparable(toolId);
+}
+function equalValue(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+/**
+ * Compares only the explicit curated and authorization-bearing semantic
+ * fields. Loosening dominates a mixed change so confirmation can never be
+ * hidden by simultaneous hardening or copy changes.
+ */
+function classifyToolSemanticChange(before, after) {
+    if (before.toolId !== after.toolId)
+        return incomparable(after.toolId);
+    const changes = [];
+    const add = (field, classification) => {
+        if (classification !== 'unchanged')
+            changes.push({ field, classification });
+    };
+    if (before.enabled !== after.enabled) {
+        add('enabled', after.enabled ? 'loosening' : 'hardening');
+    }
+    if (before.requiresApproval !== after.requiresApproval) {
+        add('requiresApproval', after.requiresApproval ? 'hardening' : 'loosening');
+    }
+    add('riskClass', compareRisk(before.riskClass, after.riskClass, after.toolId));
+    add('allowedRoles', compareRoles(before.allowedRoles, after.allowedRoles, after.toolId));
+    const neutralFields = [
+        'description',
+        'modelName',
+        'module',
+        'sharedWith',
+        'usageHints',
+        'presentation',
+    ];
+    for (const field of neutralFields) {
+        if (!equalValue(before[field], after[field]))
+            add(field, 'neutral');
+    }
+    const classification = changes.some((change) => change.classification === 'loosening')
+        ? 'loosening'
+        : changes.some((change) => change.classification === 'hardening')
+            ? 'hardening'
+            : changes.length > 0
+                ? 'neutral'
+                : 'unchanged';
+    return {
+        toolId: after.toolId,
+        classification,
+        fields: changes.map((change) => change.field),
+        requiresConfirmation: classification === 'loosening',
+    };
+}

package/dist/cjs/contracts/tool-exclude-pattern.d.ts

@@ -0,0 +1,12 @@
+export interface ExcludePattern {
+    /** Absent for `*` and for a pattern without a method: any method. */
+    method: string | undefined;
+    /** Path segments; `*` is one segment, `**` any number of segments. */
+    segments: string[];
+}
+/**
+ * The grammar of `.glirastes/tool-policy.json` `exclude[].match`:
+ * `[METHOD|*] /path/glob`, upper-case methods only. Undefined for anything
+ * else, because such a pattern would exclude nothing and say so to nobody.
+ */
+export declare function parseExcludePattern(pattern: string): ExcludePattern | undefined;

package/dist/cjs/contracts/tool-exclude-pattern.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseExcludePattern = parseExcludePattern;
+// PAGE matches app pages (navigation destinations and filtered views).
+const EXCLUDE_PATTERN = /^(?:(GET|POST|PUT|PATCH|DELETE|HEAD|PAGE|\*)\s+)?(\/\S*)$/;
+function isValidSegment(segment) {
+    if (segment === '*' || segment === '**')
+        return true;
+    // Route paths carry `:id` and `*slug`, never the Next.js file-system spelling.
+    if (/^\[.*\]$/.test(segment) || /^\(.*\)$/.test(segment))
+        return false;
+    // `*slug` is a catch-all stable-key segment and matches literally; any other `*` is a partial glob.
+    return !segment.includes('*') || /^\*[^*]+$/.test(segment);
+}
+/**
+ * The grammar of `.glirastes/tool-policy.json` `exclude[].match`:
+ * `[METHOD|*] /path/glob`, upper-case methods only. Undefined for anything
+ * else, because such a pattern would exclude nothing and say so to nobody.
+ */
+function parseExcludePattern(pattern) {
+    const match = EXCLUDE_PATTERN.exec(pattern.trim());
+    if (!match)
+        return undefined;
+    const [, method, path] = match;
+    const segments = path.split('/').filter(Boolean);
+    if (!segments.every(isValidSegment))
+        return undefined;
+    return { method: method === '*' ? undefined : method, segments };
+}