@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

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,39 @@
+import { AccountsOperations } from "./ops/accounts.ops.js";
+import { AdminOperations } from "./ops/admin.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 { EnvironmentsOperations } from "./ops/environments.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 { SkillsOperations } from "./ops/skills.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 EnvironmentsOperations, typeof AgentSkillsOperations];
+/**
+ * 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 {
+}

package/dist/platform/platform-ops.module.js

@@ -0,0 +1,122 @@
+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;
+};
+import { Module } from "@nestjs/common";
+import { AgentsModule } from "../agents/agents.module.js";
+import { BackgroundModule } from "../background/background.module.js";
+import { CatalogModule } from "../catalog/catalog.module.js";
+import { ChannelsModule } from "../channels/channels.module.js";
+import { ConversationsModule } from "../conversations/conversations.module.js";
+import { EnvironmentsModule } from "../environments/environments.module.js";
+import { EvalsModule } from "../evals/evals.module.js";
+import { ExtensionsModule } from "../extensions/extensions.module.js";
+import { FilesModule } from "../files/files.module.js";
+import { IdentityModule } from "../identity/identity.module.js";
+import { InboxModule } from "../inbox/inbox.module.js";
+import { ModelsModule } from "../models/models.module.js";
+import { OrgsModule } from "../orgs/orgs.module.js";
+import { ProvidersModule } from "../runtime/providers.js";
+import { SkillsModule } from "../skills/skills.module.js";
+import { ToolsModule } from "../tools/tools.module.js";
+import { AccountsOperations } from "./ops/accounts.ops.js";
+import { AdminOperations } from "./ops/admin.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 { EnvironmentsOperations } from "./ops/environments.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 { SkillsOperations } from "./ops/skills.ops.js";
+import { PlatformModule } from "./platform.module.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 const PLATFORM_OPERATION_PROVIDERS = [
+    PlatformOperationsProvider,
+    SkillsOperations,
+    AgentsOperations,
+    AgentTemplatesOperations,
+    PluginsOperations,
+    MarketplacesOperations,
+    RequestsOperations,
+    ConnectorsOperations,
+    ExtensionsOperations,
+    ConversationsOperations,
+    ComponentsOperations,
+    // Task 7: admin accounts and orgs
+    AccountsOperations,
+    OrgsOperations,
+    AdminOperations,
+    // Task 8: admin catalog, extensions, marketplaces, models, org uploads
+    CatalogAdminOperations,
+    OrgPluginsOperations,
+    ExtensionsAdminOperations,
+    ModelsOperations,
+    // Task 9: inbox and pending reads
+    InboxOperations,
+    ApprovalsOperations,
+    // Task 10: channels, org settings
+    ChannelsOperations,
+    OrgSettingsOperations,
+    // Task 11: evals, background tasks, file previewers
+    EvalsOperations,
+    BackgroundOperations,
+    PreviewersOperations,
+    // Task 11b: environments, agent skills
+    EnvironmentsOperations,
+    AgentSkillsOperations,
+];
+/**
+ * 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.
+ */
+let PlatformOpsModule = class PlatformOpsModule {
+};
+PlatformOpsModule = __decorate([
+    Module({
+        imports: [
+            PlatformModule,
+            SkillsModule,
+            AgentsModule,
+            OrgsModule,
+            CatalogModule,
+            ExtensionsModule,
+            ToolsModule,
+            ConversationsModule,
+            IdentityModule,
+            ModelsModule,
+            ProvidersModule,
+            InboxModule,
+            ChannelsModule,
+            EvalsModule,
+            EnvironmentsModule,
+            BackgroundModule,
+            FilesModule,
+        ],
+        providers: [...PLATFORM_OPERATION_PROVIDERS],
+    })
+], PlatformOpsModule);
+export { PlatformOpsModule };

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

@@ -0,0 +1,8 @@
+/**
+ * The `Platform` tool's core (Platform tool spec §3, §6, §7): the operation registry, the actor
+ * facts and the agent docs. It imports no domain module (ruling P2), so `ToolsModule` can import it without a
+ * cycle; domain providers register their operations into `PlatformOperations` from
+ * `onModuleInit`.
+ */
+export declare class PlatformModule {
+}

package/dist/platform/platform.module.js

@@ -0,0 +1,25 @@
+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;
+};
+import { Module } from "@nestjs/common";
+import { PlatformActor } from "./actor.js";
+import { AgentDocs } from "./agent-docs.js";
+import { PlatformOperations } from "./registry.js";
+/**
+ * The `Platform` tool's core (Platform tool spec §3, §6, §7): the operation registry, the actor
+ * facts and the agent docs. It imports no domain module (ruling P2), so `ToolsModule` can import it without a
+ * cycle; domain providers register their operations into `PlatformOperations` from
+ * `onModuleInit`.
+ */
+let PlatformModule = class PlatformModule {
+};
+PlatformModule = __decorate([
+    Module({
+        providers: [PlatformOperations, PlatformActor, AgentDocs],
+        exports: [PlatformOperations, PlatformActor, AgentDocs],
+    })
+], PlatformModule);
+export { PlatformModule };

package/dist/platform/registry.d.ts

@@ -0,0 +1,30 @@
+import { type PlatformOperation } from "./operation.js";
+/**
+ * The `Platform` tool's operations (spec §7). Domain providers add theirs with {@link register}
+ * from `onModuleInit` (ruling P2: this module imports no domain module); a bad batch throws and
+ * registers nothing, so a mistake fails the kernel's start.
+ */
+export declare class PlatformOperations {
+    private readonly ops;
+    /**
+     * Adds `ops`. Throws on an id not shaped `<domain>.<verb>`, a domain outside
+     * {@link PLATFORM_DOMAINS}, a duplicate id (in the batch or already registered), or a write
+     * (`confirm` other than `read`) without `summary`.
+     */
+    register(ops: readonly PlatformOperation[]): void;
+    domains(): readonly {
+        id: string;
+        description: string;
+    }[];
+    /** The domain's operations, sorted by id. */
+    inDomain(domain: string): PlatformOperation[];
+    get(id: string): PlatformOperation | null;
+    /** Every operation, sorted by id. */
+    all(): PlatformOperation[];
+    /**
+     * Keyword search (deterministic, like ToolSearch's): per distinct query term,
+     * `idf × (ID_WEIGHT if in the id + 1 if in the description)`; a term also matches a word it is a
+     * prefix of. Zero scores are dropped; ties go by id.
+     */
+    search(query: string, limit: number): PlatformOperation[];
+}

package/dist/platform/registry.js

@@ -0,0 +1,111 @@
+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;
+};
+import { Injectable } from "@nestjs/common";
+import { tokenize } from "../tools/builtins/tool-search.js";
+import { OPERATION_ID, operationDomain, PLATFORM_DOMAINS, } from "./operation.js";
+/** A word of an operation id weighs more than a word of its description (like ToolSearch). */
+const ID_WEIGHT = 2;
+/** The shortest query term that also matches as a word's prefix (`skill` → `skills`). */
+const MIN_PREFIX = 3;
+const DOMAIN_IDS = new Set(PLATFORM_DOMAINS.map((d) => d.id));
+const byId = (a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+/** A query term matches a word when equal, or as its prefix when long enough. */
+const matches = (words, term) => {
+    if (words.has(term))
+        return true;
+    if (term.length < MIN_PREFIX)
+        return false;
+    for (const w of words)
+        if (w.startsWith(term))
+            return true;
+    return false;
+};
+/**
+ * The `Platform` tool's operations (spec §7). Domain providers add theirs with {@link register}
+ * from `onModuleInit` (ruling P2: this module imports no domain module); a bad batch throws and
+ * registers nothing, so a mistake fails the kernel's start.
+ */
+let PlatformOperations = class PlatformOperations {
+    ops = new Map();
+    /**
+     * Adds `ops`. Throws on an id not shaped `<domain>.<verb>`, a domain outside
+     * {@link PLATFORM_DOMAINS}, a duplicate id (in the batch or already registered), or a write
+     * (`confirm` other than `read`) without `summary`.
+     */
+    register(ops) {
+        const seen = new Set();
+        for (const op of ops) {
+            if (!OPERATION_ID.test(op.id)) {
+                throw new Error(`Platform operation id "${op.id}" is not shaped <domain>.<verb>`);
+            }
+            if (!DOMAIN_IDS.has(operationDomain(op.id))) {
+                throw new Error(`Platform operation "${op.id}" names an unknown domain`);
+            }
+            if (seen.has(op.id) || this.ops.has(op.id)) {
+                throw new Error(`duplicate Platform operation "${op.id}"`);
+            }
+            if (op.confirm !== "read" && op.summary === undefined) {
+                throw new Error(`Platform operation "${op.id}" is a write without a summary`);
+            }
+            seen.add(op.id);
+        }
+        for (const op of ops)
+            this.ops.set(op.id, op);
+    }
+    domains() {
+        return PLATFORM_DOMAINS;
+    }
+    /** The domain's operations, sorted by id. */
+    inDomain(domain) {
+        return this.all().filter((op) => operationDomain(op.id) === domain);
+    }
+    get(id) {
+        return this.ops.get(id) ?? null;
+    }
+    /** Every operation, sorted by id. */
+    all() {
+        return [...this.ops.values()].sort(byId);
+    }
+    /**
+     * Keyword search (deterministic, like ToolSearch's): per distinct query term,
+     * `idf × (ID_WEIGHT if in the id + 1 if in the description)`; a term also matches a word it is a
+     * prefix of. Zero scores are dropped; ties go by id.
+     */
+    search(query, limit) {
+        const terms = [...new Set(tokenize(query))];
+        if (terms.length === 0)
+            return [];
+        const docs = this.all().map((op) => ({
+            op,
+            id: new Set(tokenize(op.id)),
+            desc: new Set(tokenize(op.description)),
+        }));
+        const n = docs.length;
+        const idf = new Map();
+        for (const term of terms) {
+            const df = docs.filter((d) => matches(d.id, term) || matches(d.desc, term)).length;
+            idf.set(term, df === 0 ? 0 : Math.log(1 + n / df));
+        }
+        return docs
+            .map((d) => {
+            let score = 0;
+            for (const term of terms) {
+                const w = (matches(d.id, term) ? ID_WEIGHT : 0) + (matches(d.desc, term) ? 1 : 0);
+                score += w * (idf.get(term) ?? 0);
+            }
+            return { op: d.op, score };
+        })
+            .filter((x) => x.score > 0)
+            .sort((a, b) => (b.score !== a.score ? b.score - a.score : byId(a.op, b.op)))
+            .slice(0, limit)
+            .map((x) => x.op);
+    }
+};
+PlatformOperations = __decorate([
+    Injectable()
+], PlatformOperations);
+export { PlatformOperations };

package/dist/platform/route-schemas.d.ts

@@ -0,0 +1,18 @@
+import type { z } from "zod";
+/**
+ * The zod schemas one HTTP route validates (spec §14.5 item 3), as its controller uses them:
+ * `route` is the `check:platform-ops` key (`POST /api/v1/orgs/:orgId/skills`), `params` its path
+ * params but `:orgId` (the conversation's org, never an operation field).
+ */
+export interface RouteSchemas {
+    route: string;
+    body?: z.ZodType;
+    query?: z.ZodType;
+    params?: z.ZodType;
+}
+/**
+ * Every route a Platform operation mirrors, from the exported `<domain>.schemas.ts` next to each
+ * controller. An operation builds its input from these (`pick` / `omit` / `extend`); the parity
+ * test in `tools/checks` compares the two. A route mirrored by a new operation adds its entry here.
+ */
+export declare const ROUTE_SCHEMAS: readonly RouteSchemas[];