@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.21

package/dist/platform/ops/themes.ops.d.ts

@@ -0,0 +1,14 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { ThemesService } from "../../themes/themes.service.js";
+import { PlatformOperations } from "../registry.js";
+/**
+ * Theme operations of the `Platform` tool (themes spec §9): the org's theme listing. Setting a
+ * theme goes through the settings operations (`platform.set-preferences`, `org-settings.update`,
+ * `admin.update-settings`).
+ */
+export declare class ThemesOperations implements OnModuleInit {
+    private readonly registry;
+    private readonly themes;
+    constructor(registry: PlatformOperations, themes: ThemesService);
+    onModuleInit(): void;
+}

package/dist/platform/ops/themes.ops.js

@@ -0,0 +1,47 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { z } from "zod";
+import { ThemesService } from "../../themes/themes.service.js";
+import { defineOperation } from "../operation.js";
+import { PlatformOperations } from "../registry.js";
+/**
+ * Theme operations of the `Platform` tool (themes spec §9): the org's theme listing. Setting a
+ * theme goes through the settings operations (`platform.set-preferences`, `org-settings.update`,
+ * `admin.update-settings`).
+ */
+let ThemesOperations = class ThemesOperations {
+    registry;
+    themes;
+    constructor(registry, themes) {
+        this.registry = registry;
+        this.themes = themes;
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "themes.list",
+                description: "List the themes on in this org (id, version, name, schemes, logo and the bg / panel / ink / accent swatches per scheme), the theme in effect for you here (resolved; null is the built-in theme) and the org's setting (its default theme id, null following the platform, and whether personal picks are allowed or locked). Use a theme id with platform.set-preferences to change your own theme, or with org-settings.update to change the org's default.",
+                input: z.object({}).strict(),
+                example: {},
+                authz: { orgAction: "org.read" },
+                mirrors: ["GET /api/v1/orgs/:orgId/themes"],
+                confirm: "read",
+                run: async (_input, ctx) => this.themes.forOrg(ctx.orgId, ctx.actorAccountId),
+            }),
+        ]);
+    }
+};
+ThemesOperations = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations)),
+    __param(1, Inject(ThemesService))
+], ThemesOperations);
+export { ThemesOperations };

package/dist/platform/ops/ui.ops.d.ts

@@ -0,0 +1,8 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { PlatformOperations } from "../registry.js";
+/** UI operations of the `Platform` tool (UI slots spec §3): the slot catalog. */
+export declare class UiOperations implements OnModuleInit {
+    private readonly registry;
+    constructor(registry: PlatformOperations);
+    onModuleInit(): void;
+}

package/dist/platform/ops/ui.ops.js

@@ -0,0 +1,41 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { UI_SLOTS } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { z } from "zod";
+import { defineOperation } from "../operation.js";
+import { PlatformOperations } from "../registry.js";
+/** UI operations of the `Platform` tool (UI slots spec §3): the slot catalog. */
+let UiOperations = class UiOperations {
+    registry;
+    constructor(registry) {
+        this.registry = registry;
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "ui.slots",
+                description: "List the UI slots an extension can contribute to (id, version, where it is, scope and args, accepted kinds view / embed / component, cardinality list or single, minimum role, anchors). Use a slot id as a ui contribution's `slot` in a plugin manifest.",
+                input: z.object({}).strict(),
+                example: {},
+                // any signed-in person may call the route; every run's actor is a member of this org
+                authz: { orgAction: "agents.use" },
+                mirrors: ["GET /api/v1/ui/slots"],
+                confirm: "read",
+                run: async () => ({ slots: UI_SLOTS }),
+            }),
+        ]);
+    }
+};
+UiOperations = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations))
+], UiOperations);
+export { UiOperations };

package/dist/platform/ops/unavailable.d.ts

@@ -0,0 +1,23 @@
+import type { PluginUnavailableReason } from "../../catalog/catalog-content.js";
+import type { KernelSchemaDb } from "../../db/kernel-schema.js";
+import { type ErrorRole } from "../errors.js";
+import type { OperationContext, OperationErrorNext } from "../operation.js";
+/** The next step for an unavailable plugin or extension, keyed by role. */
+export declare function unavailableNext(reason: PluginUnavailableReason, name: string): OperationErrorNext;
+/** Why it cannot be used: "The extension of plugin "X" is not running on the platform: … (reason)." */
+export declare function unavailableMessage(reason: PluginUnavailableReason, name: string): string;
+/** The fields an unavailable list row or detail adds: the reason and the role's next step. */
+export declare function unavailableFields(reason: PluginUnavailableReason | undefined, name: string, role: ErrorRole): {
+    reason?: PluginUnavailableReason;
+    next?: string;
+};
+/**
+ * The actor's role for next steps: the one the tool derived from this call's actor facts
+ * (`ctx.errorRole`), else read now with {@link errorRoleFor} (a context no tool call is behind).
+ */
+export declare function roleFor(db: KernelSchemaDb, ctx: OperationContext): Promise<ErrorRole>;
+/**
+ * The actor's role for next steps, read now (the super admin first, then an org admin): the
+ * fallback of {@link roleFor}, the same rule as `errorRoleOf` over `PlatformActor` facts.
+ */
+export declare function errorRoleFor(db: KernelSchemaDb, orgId: string, accountId: string): Promise<ErrorRole>;

package/dist/platform/ops/unavailable.js

@@ -0,0 +1,118 @@
+import { errorRoleOf, resolveNext } from "../errors.js";
+/**
+ * What an unavailable plugin or extension tells the model (Platform tool spec §14.2 problems 1
+ * and 3): what is missing, and the next step for the actor's role. Only the super admin gets the
+ * admin console path; nothing names a config field or carries a value.
+ */
+/** What is missing, per reason (model-visible English, completes "…is not running on the platform: "). */
+const MISSING = {
+    plugin_disabled: "the super admin stopped the plugin on the platform",
+    not_deployed: "its extension is not installed on the platform",
+    needs_deployment_config: "it is installed, but its deployment config is missing or invalid",
+    pending_approval: "it is installed, but its permissions wait for the super admin's approval",
+    pending_migration: "the platform is still preparing it (database migration)",
+    loading: "the platform is still loading it",
+    dependency: "it requires an extension point that no running extension provides",
+    conflict: "it provides an extension point only one extension may provide, and another running extension already provides it",
+    failed: "it failed to load on the platform",
+    deployment_disabled: "the super admin disabled it on the platform",
+};
+/** No request operation reaches the super admin for these (requests.create: enable / access only). */
+const TELL_SUPER_ADMIN = "There is no request operation for this (requests.create covers enabling and access only), so tell the super admin directly.";
+/** The member's step: inside the org, never the admin console. */
+const memberNext = (name) => `Ask an org admin: the super admin must set up ${name} on the platform before anyone in the org can use it.`;
+/** The next step for an unavailable plugin or extension, keyed by role. */
+export function unavailableNext(reason, name) {
+    const adminPath = `Open the admin console → Extensions → ${name}`;
+    switch (reason) {
+        case "loading":
+        case "pending_migration":
+            return `The platform is still bringing ${name} up; wait a minute and check again with plugins.get or extensions.list.`;
+        case "plugin_disabled":
+            return {
+                superAdmin: "The plugin is stopped on the platform: turn it back on in the admin console under Plugins, then call again.",
+                orgAdmin: "The super admin stopped this plugin on the platform; ask them.",
+                member: "The super admin stopped this plugin on the platform; nothing can switch it on here.",
+            };
+        case "needs_deployment_config":
+            return {
+                superAdmin: `${adminPath} → fill in the deployment config; once it loads, switch the plugin on again.`,
+                orgAdmin: `Only the super admin can fill in the deployment config of ${name}. ${TELL_SUPER_ADMIN}`,
+                member: memberNext(name),
+            };
+        case "pending_approval":
+            return {
+                superAdmin: `${adminPath} → review and approve its permissions; once it loads, switch the plugin on again.`,
+                orgAdmin: `Only the super admin can approve the permissions of ${name}. ${TELL_SUPER_ADMIN}`,
+                member: memberNext(name),
+            };
+        case "dependency":
+            return {
+                superAdmin: `${adminPath} to see the extension point it requires, then install or enable an extension that provides it.`,
+                orgAdmin: `Only the super admin can provide what ${name} requires. ${TELL_SUPER_ADMIN}`,
+                member: memberNext(name),
+            };
+        case "conflict":
+            return {
+                superAdmin: `${adminPath} to see which extension already provides the same extension point; disable that one (or uninstall it) and ${name} loads, no restart.`,
+                orgAdmin: `Only the super admin can resolve the conflict of ${name} with another extension. ${TELL_SUPER_ADMIN}`,
+                member: memberNext(name),
+            };
+        case "failed":
+            return {
+                superAdmin: `${adminPath} to see why it failed to load; fix its deployment config or reinstall it.`,
+                orgAdmin: `Only the super admin can fix ${name}, which failed to load. ${TELL_SUPER_ADMIN}`,
+                member: memberNext(name),
+            };
+        case "deployment_disabled":
+            return {
+                superAdmin: `${adminPath} → enable it; once it loads, switch the plugin on again.`,
+                orgAdmin: `Only the super admin can enable ${name} on the platform. ${TELL_SUPER_ADMIN}`,
+                member: memberNext(name),
+            };
+        case "not_deployed":
+            return {
+                superAdmin: `Install the extension of ${name}: admin console → Extensions (or update the plugin in the admin console under Plugins), then switch it on again.`,
+                orgAdmin: `Only the super admin can install the extension of ${name}. ${TELL_SUPER_ADMIN}`,
+                member: memberNext(name),
+            };
+    }
+}
+/** Why it cannot be used: "The extension of plugin "X" is not running on the platform: … (reason)." */
+export function unavailableMessage(reason, name) {
+    if (reason === "plugin_disabled")
+        return `Plugin "${name}" is unavailable: ${MISSING[reason]}.`;
+    return `The extension of "${name}" is not running on the platform: ${MISSING[reason]} (${reason}).`;
+}
+/** The fields an unavailable list row or detail adds: the reason and the role's next step. */
+export function unavailableFields(reason, name, role) {
+    if (reason === undefined)
+        return {};
+    const next = resolveNext(unavailableNext(reason, name), role);
+    return { reason, ...(next !== undefined && { next }) };
+}
+/**
+ * The actor's role for next steps: the one the tool derived from this call's actor facts
+ * (`ctx.errorRole`), else read now with {@link errorRoleFor} (a context no tool call is behind).
+ */
+export function roleFor(db, ctx) {
+    return ctx.errorRole !== undefined
+        ? Promise.resolve(ctx.errorRole)
+        : errorRoleFor(db, ctx.orgId, ctx.actorAccountId);
+}
+/**
+ * The actor's role for next steps, read now (the super admin first, then an org admin): the
+ * fallback of {@link roleFor}, the same rule as `errorRoleOf` over `PlatformActor` facts.
+ */
+export async function errorRoleFor(db, orgId, accountId) {
+    const row = await db
+        .selectFrom("accounts")
+        .leftJoin("memberships", (j) => j.onRef("memberships.account_id", "=", "accounts.id").on("memberships.org_id", "=", orgId))
+        .select(["accounts.is_super_admin", "accounts.status", "memberships.role"])
+        .where("accounts.id", "=", accountId)
+        .executeTakeFirst();
+    return errorRoleOf({
+        role: row?.role ?? null,
+        isSuperAdmin: row?.is_super_admin === true && row.status === "active",
+    });
+}

package/dist/platform/parity.d.ts

@@ -0,0 +1,33 @@
+import type { PlatformOperation } from "./operation.js";
+import type { RouteSchemas } from "./route-schemas.js";
+/** One difference between an operation's input and its mirrored route (spec §14.5 item 3). */
+export interface ParityFinding {
+    op: string;
+    route: string;
+    /** The operation field (or declaration entry) it is about; absent when about the whole route. */
+    field?: string;
+    message: string;
+}
+/** What {@link inputParity} reads of an operation. */
+export type ParityOperation = Pick<PlatformOperation, "id" | "input" | "mirrors"> & Partial<Pick<PlatformOperation, "omits" | "extras" | "renames" | "loosens">>;
+/**
+ * Compares an operation's input with one mirrored route's body + query + path params (spec
+ * §14.5 item 3), on their input JSON Schemas:
+ * - each input field is compared with the route field of the same name, or the route path its
+ *   `renames` entry names (`skillId` → `id`, `name` → `definition.name`): the same type (an
+ *   operation `integer` fits a route `number`), enum values a subset, bounds no looser
+ *   (`maxLength` / `maximum` / `maxItems` at most the route's, the lower bounds at least), the
+ *   same `pattern` and `format`, and required where the route requires it; nested objects,
+ *   arrays and records recursively (a nested optional route field the operation leaves out is
+ *   allowed, a required one is not);
+ * - a `loosens` entry names an input field allowed to accept more than the route (with the
+ *   reason); it is still compared by type, and an entry that loosens nothing is stale;
+ * - a top-level route field the input neither has nor renames into is listed in `omits`, an input
+ *   field with no route counterpart in `extras`; stale entries of either are findings.
+ */
+export declare function inputParity(op: ParityOperation, route: RouteSchemas): ParityFinding[];
+/**
+ * {@link inputParity} of every operation against each route it mirrors; a mirrored route whose
+ * schemas are not registered is a finding too (a removed route is `check:platform-ops`'s orphan).
+ */
+export declare function checkInputParity(ops: readonly ParityOperation[], routes: readonly RouteSchemas[]): ParityFinding[];

package/dist/platform/parity.js

@@ -0,0 +1,272 @@
+import { z } from "zod";
+/** `:orgId` is the conversation's org: never an operation field, so never compared. */
+const IMPLICIT = new Set(["orgId"]);
+/** Bounds an operation may tighten but never loosen: the upper ones, then the lower ones. */
+const UPPER = ["maxLength", "maximum", "exclusiveMaximum", "maxItems", "maxProperties"];
+const LOWER = ["minLength", "minimum", "exclusiveMinimum", "minItems", "minProperties"];
+const toJson = (s) => z.toJSONSchema(s, { io: "input", unrepresentable: "any" });
+/** A schema's alternatives: the branches of `anyOf` / `oneOf` (flattened), else itself. */
+function alternatives(s) {
+    const branches = (s.anyOf ?? s.oneOf);
+    return branches ? branches.flatMap(alternatives) : [s];
+}
+const propsOf = (s) => s.properties;
+const requiredOf = (s) => new Set((s.required ?? []));
+/**
+ * The top-level fields of an object schema; of a union, each branch's fields (a field that
+ * differs between branches is the `anyOf` of its branch schemas, required only when every
+ * branch requires it).
+ */
+function fieldsOf(s) {
+    const branches = alternatives(s);
+    const out = new Map();
+    for (const branch of branches) {
+        const req = requiredOf(branch);
+        for (const [k, v] of Object.entries(propsOf(branch) ?? {})) {
+            const f = out.get(k) ?? { schemas: [], requiredIn: 0 };
+            f.schemas.push(v);
+            if (req.has(k))
+                f.requiredIn += 1;
+            out.set(k, f);
+        }
+    }
+    return new Map([...out].map(([k, f]) => {
+        const distinct = [...new Map(f.schemas.map((v) => [JSON.stringify(v), v])).values()];
+        const schema = distinct.length === 1 ? distinct[0] : { anyOf: distinct };
+        return [k, { schema, required: f.requiredIn === branches.length }];
+    }));
+}
+/** The route field at a dotted path (`definition.name`): required only when every step is. */
+function fieldAt(fields, path) {
+    const [head, ...rest] = path.split(".");
+    let f = fields.get(head);
+    for (const seg of rest) {
+        if (f === undefined)
+            return undefined;
+        const holder = alternatives(f.schema).find((a) => propsOf(a)?.[seg] !== undefined);
+        const next = holder && propsOf(holder)?.[seg];
+        if (!holder || !next)
+            return undefined;
+        f = { schema: next, required: f.required && requiredOf(holder).has(seg) };
+    }
+    return f;
+}
+const jsonType = (v) => v === null ? "null" : Array.isArray(v) ? "array" : typeof v;
+/** The JSON types a schema accepts; `undefined` when it accepts anything. */
+function typesOf(s) {
+    if (s.type !== undefined)
+        return new Set(Array.isArray(s.type) ? s.type : [s.type]);
+    if ("const" in s)
+        return new Set([jsonType(s.const)]);
+    if (Array.isArray(s.enum))
+        return new Set(s.enum.map(jsonType));
+    return undefined;
+}
+/** `integer` is a `number`; every other type only itself. */
+const typeFits = (t, allowed) => allowed.has(t) || (t === "integer" && allowed.has("number"));
+const describeTypes = (t) => t === undefined ? "any" : [...t].sort().join(" | ");
+const valuesOf = (s) => "const" in s ? [s.const] : Array.isArray(s.enum) ? s.enum : undefined;
+/**
+ * Why one operation alternative accepts more than one route alternative, or null when it accepts
+ * no more (spec §14.5 item 3). Objects, arrays and records are compared recursively: every
+ * operation property is a route property, every property the route requires the operation
+ * requires, a closed route object is closed in the operation, items and values fit.
+ */
+function misfit(op, route, path, top) {
+    /** The reason, prefixed by the path inside the compared field (none at the field itself). */
+    const at = (p, why) => (p === top ? why : `${p}: ${why}`);
+    const want = typesOf(route);
+    const got = typesOf(op);
+    if (want !== undefined && (got === undefined || [...got].some((t) => !typeFits(t, want)))) {
+        return at(path, `type ${describeTypes(got)} in the operation, ${describeTypes(want)} in the route`);
+    }
+    const allowed = valuesOf(route);
+    if (allowed !== undefined) {
+        const vs = valuesOf(op);
+        const keys = new Set(allowed.map((v) => JSON.stringify(v)));
+        if (vs === undefined || vs.some((v) => !keys.has(JSON.stringify(v)))) {
+            return at(path, `values ${vs === undefined ? "any" : JSON.stringify(vs)} are looser than the route's ${JSON.stringify(allowed)}`);
+        }
+    }
+    for (const k of UPPER) {
+        const r = route[k];
+        const o = op[k];
+        if (r !== undefined && (o === undefined || o > r)) {
+            return at(path, `${k} ${o ?? "unbounded"} is looser than the route's ${r}`);
+        }
+    }
+    for (const k of LOWER) {
+        const r = route[k];
+        const o = op[k];
+        if (r !== undefined && (o === undefined || o < r)) {
+            return at(path, `${k} ${o ?? "unbounded"} is looser than the route's ${r}`);
+        }
+    }
+    for (const k of ["pattern", "format"]) {
+        if (route[k] !== undefined && op[k] !== route[k]) {
+            return at(path, `${k} ${op[k] === undefined ? "none" : JSON.stringify(op[k])} differs from the route's ${JSON.stringify(route[k])}`);
+        }
+    }
+    const sub = (k) => `${path}.${k}`;
+    const rp = propsOf(route);
+    if (rp !== undefined) {
+        const opProps = propsOf(op) ?? {};
+        const opReq = requiredOf(op);
+        for (const k of requiredOf(route)) {
+            if (!opReq.has(k))
+                return at(sub(k), "required by the route, optional or missing here");
+        }
+        for (const [k, v] of Object.entries(opProps)) {
+            const r = rp[k];
+            if (r === undefined)
+                return at(sub(k), "no field of the route");
+            const why = fieldMismatch(v, r, sub(k), top);
+            if (why !== null)
+                return why;
+        }
+    }
+    if (route.additionalProperties === false && op.additionalProperties !== false) {
+        return at(path, "accepts unknown keys, the route does not");
+    }
+    // a record's values: an operation closed to unknown keys accepts none, else its values must fit
+    if (typeof route.additionalProperties === "object" && op.additionalProperties !== false) {
+        const why = fieldMismatch((op.additionalProperties ?? {}), route.additionalProperties, sub("*"), top);
+        if (why !== null)
+            return why;
+    }
+    if (typeof route.propertyNames === "object") {
+        const why = fieldMismatch((op.propertyNames ?? {}), route.propertyNames, sub("<key>"), top);
+        if (why !== null)
+            return why;
+    }
+    if (typeof route.items === "object" && route.items !== null) {
+        const why = fieldMismatch((op.items ?? {}), route.items, sub("[]"), top);
+        if (why !== null)
+            return why;
+    }
+    return null;
+}
+/** Why the operation's schema accepts more than the route's, or null: each op alternative fits one. */
+function fieldMismatch(op, route, path, top) {
+    const routeAlts = alternatives(route);
+    for (const a of alternatives(op)) {
+        const reasons = routeAlts.map((b) => misfit(a, b, path, top));
+        if (!reasons.includes(null))
+            return reasons[0];
+    }
+    return null;
+}
+/**
+ * Compares an operation's input with one mirrored route's body + query + path params (spec
+ * §14.5 item 3), on their input JSON Schemas:
+ * - each input field is compared with the route field of the same name, or the route path its
+ *   `renames` entry names (`skillId` → `id`, `name` → `definition.name`): the same type (an
+ *   operation `integer` fits a route `number`), enum values a subset, bounds no looser
+ *   (`maxLength` / `maximum` / `maxItems` at most the route's, the lower bounds at least), the
+ *   same `pattern` and `format`, and required where the route requires it; nested objects,
+ *   arrays and records recursively (a nested optional route field the operation leaves out is
+ *   allowed, a required one is not);
+ * - a `loosens` entry names an input field allowed to accept more than the route (with the
+ *   reason); it is still compared by type, and an entry that loosens nothing is stale;
+ * - a top-level route field the input neither has nor renames into is listed in `omits`, an input
+ *   field with no route counterpart in `extras`; stale entries of either are findings.
+ */
+export function inputParity(op, route) {
+    const out = [];
+    const add = (field, message) => out.push({ op: op.id, route: route.route, field, message: `${op.id}: ${message}` });
+    const opFields = fieldsOf(toJson(op.input));
+    const routeFields = new Map();
+    for (const part of [route.params, route.query, route.body]) {
+        if (part === undefined)
+            continue;
+        for (const [k, v] of fieldsOf(toJson(part)))
+            if (!IMPLICIT.has(k))
+                routeFields.set(k, v);
+    }
+    const omits = new Set(op.omits ?? []);
+    const extras = new Set(op.extras ?? []);
+    const renames = new Map(Object.entries(op.renames ?? {}));
+    const loosens = new Map(Object.entries(op.loosens ?? {}));
+    const r = `\`${route.route}\``;
+    /** Top-level route fields an input field covers (by name or by a rename into it). */
+    const covered = new Set();
+    for (const [k, opField] of opFields) {
+        const target = renames.get(k) ?? k;
+        const routeField = fieldAt(routeFields, target);
+        if (routeField === undefined) {
+            if (renames.has(k))
+                add(k, `\`renames\` maps \`${k}\` to \`${target}\`, no field of ${r}`);
+            else if (!extras.has(k))
+                add(k, `\`${k}\` is no field of ${r} and not in \`extras\``);
+            continue;
+        }
+        covered.add(target.split(".")[0]);
+        if (extras.has(k))
+            add(k, `\`extras\` names \`${k}\`, which ${r} has as \`${target}\``);
+        const reason = loosens.get(k);
+        const name = target === k ? `\`${k}\`` : `\`${k}\` (\`${target}\`)`;
+        if (reason !== undefined) {
+            if (reason.trim() === "")
+                add(k, `\`loosens\` names \`${k}\` without a reason`);
+            const want = typesOf(routeField.schema);
+            const got = typesOf(opField.schema);
+            if (want !== undefined && (got === undefined || [...got].some((t) => !typeFits(t, want)))) {
+                add(k, `${name}: type ${describeTypes(got)} in the operation, ${describeTypes(want)} in the route (${r}; \`loosens\` excuses bounds, never the type)`);
+            }
+            const looser = (routeField.required && !opField.required) ||
+                fieldMismatch(opField.schema, routeField.schema, target, target) !== null;
+            if (!looser)
+                add(k, `\`loosens\` names ${name}, which is no looser than ${r}`);
+            continue;
+        }
+        if (routeField.required && !opField.required) {
+            add(k, `${name} is required by ${r} but optional here (declare it in \`loosens\` if meant)`);
+        }
+        const why = fieldMismatch(opField.schema, routeField.schema, target, target);
+        if (why !== null)
+            add(k, `${name}: ${why} (${r})`);
+    }
+    for (const k of routeFields.keys()) {
+        if (!covered.has(k) && !omits.has(k)) {
+            add(k, `\`${k}\` of ${r} is missing from the input and not in \`omits\``);
+        }
+    }
+    for (const k of omits) {
+        if (!routeFields.has(k))
+            add(k, `\`omits\` names \`${k}\`, no field of ${r}`);
+        else if (covered.has(k))
+            add(k, `\`omits\` names \`${k}\`, but the input has it`);
+    }
+    for (const k of extras) {
+        if (!opFields.has(k))
+            add(k, `\`extras\` names \`${k}\`, which the input lacks`);
+    }
+    for (const k of renames.keys()) {
+        if (!opFields.has(k))
+            add(k, `\`renames\` names \`${k}\`, which the input lacks`);
+    }
+    for (const k of loosens.keys()) {
+        if (!opFields.has(k))
+            add(k, `\`loosens\` names \`${k}\`, which the input lacks`);
+    }
+    return out;
+}
+/**
+ * {@link inputParity} of every operation against each route it mirrors; a mirrored route whose
+ * schemas are not registered is a finding too (a removed route is `check:platform-ops`'s orphan).
+ */
+export function checkInputParity(ops, routes) {
+    const byRoute = new Map(routes.map((r) => [r.route, r]));
+    return ops.flatMap((op) => op.mirrors.flatMap((m) => {
+        const r = byRoute.get(m);
+        return r !== undefined
+            ? inputParity(op, r)
+            : [
+                {
+                    op: op.id,
+                    route: m,
+                    message: `${op.id} mirrors \`${m}\`, whose schemas are not in ROUTE_SCHEMAS: export them from the controller's <domain>.schemas.ts and list them there`,
+                },
+            ];
+    }));
+}

package/dist/platform/platform-ops.module.d.ts

@@ -0,0 +1,43 @@
+import { AccountsOperations } from "./ops/accounts.ops.js";
+import { AdminOperations } from "./ops/admin.ops.js";
+import { AdminItemsOperations } from "./ops/admin-items.ops.js";
+import { AgentSkillsOperations } from "./ops/agent-skills.ops.js";
+import { AgentTemplatesOperations } from "./ops/agent-templates.ops.js";
+import { AgentsOperations } from "./ops/agents.ops.js";
+import { ApprovalsOperations } from "./ops/approvals.ops.js";
+import { BackgroundOperations } from "./ops/background.ops.js";
+import { CatalogAdminOperations } from "./ops/catalog-admin.ops.js";
+import { ChannelsOperations } from "./ops/channels.ops.js";
+import { ComponentsOperations } from "./ops/components.ops.js";
+import { ConnectorsOperations } from "./ops/connectors.ops.js";
+import { ConversationsOperations } from "./ops/conversations.ops.js";
+import { DevicesOperations } from "./ops/devices.ops.js";
+import { EvalsOperations } from "./ops/evals.ops.js";
+import { ExtensionsOperations } from "./ops/extensions.ops.js";
+import { ExtensionsAdminOperations } from "./ops/extensions-admin.ops.js";
+import { InboxOperations } from "./ops/inbox.ops.js";
+import { MarketplacesOperations } from "./ops/marketplaces.ops.js";
+import { ModelsOperations } from "./ops/models.ops.js";
+import { OrgPluginsOperations } from "./ops/org-plugins.ops.js";
+import { OrgSettingsOperations } from "./ops/org-settings.ops.js";
+import { OrgsOperations } from "./ops/orgs.ops.js";
+import { PlatformOperationsProvider } from "./ops/platform.ops.js";
+import { PluginsOperations } from "./ops/plugins.ops.js";
+import { PreviewersOperations } from "./ops/previewers.ops.js";
+import { RequestsOperations } from "./ops/requests.ops.js";
+import { SetupOperations } from "./ops/setup.ops.js";
+import { SkillsOperations } from "./ops/skills.ops.js";
+import { ThemesOperations } from "./ops/themes.ops.js";
+import { UiOperations } from "./ops/ui.ops.js";
+/**
+ * One provider per domain, each taking `PlatformOperations` as its first constructor argument:
+ * the parity test in `tools/checks` builds the operations from it without a Nest app.
+ */
+export declare const PLATFORM_OPERATION_PROVIDERS: readonly [typeof PlatformOperationsProvider, typeof SkillsOperations, typeof AgentsOperations, typeof AgentTemplatesOperations, typeof PluginsOperations, typeof MarketplacesOperations, typeof RequestsOperations, typeof ConnectorsOperations, typeof ExtensionsOperations, typeof ConversationsOperations, typeof ComponentsOperations, typeof AccountsOperations, typeof OrgsOperations, typeof AdminOperations, typeof CatalogAdminOperations, typeof OrgPluginsOperations, typeof ExtensionsAdminOperations, typeof ModelsOperations, typeof InboxOperations, typeof ApprovalsOperations, typeof ChannelsOperations, typeof OrgSettingsOperations, typeof EvalsOperations, typeof BackgroundOperations, typeof PreviewersOperations, typeof DevicesOperations, typeof AgentSkillsOperations, typeof ThemesOperations, typeof SetupOperations, typeof UiOperations, typeof AdminItemsOperations];
+/**
+ * The `Platform` tool's operations (ruling P2): one provider per domain, each registering its
+ * operations into `PlatformOperations` from `onModuleInit`. It imports the domain modules, which
+ * `PlatformModule` itself must not.
+ */
+export declare class PlatformOpsModule {
+}