@capybara-hq/kernel 0.1.0-rc.3 → 0.1.0-rc.5

package/dist/catalog/platform-migration.d.ts

@@ -0,0 +1,115 @@
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { PlatformComponents } from "./platform-components.js";
+/** The job's name (`@LockedInterval`, run lock `cron:platform-components-migrate`). */
+export declare const PLATFORM_MIGRATION_JOB = "platform-components-migrate";
+/** The audit action and inbox notice of a renamed skill. */
+export declare const SKILL_RENAMED = "skill_renamed";
+/** What one run changed (also stored in `platform_migration_runs.stats`). */
+export interface PlatformMigrationStats {
+    /** Catalog items whose platform rows were written (`<name>@<version>`). */
+    itemsSynced: string[];
+    /** Catalog items whose sync failed (logged; tried again by the next run). */
+    itemsFailed: string[];
+    /** Org skill copies linked to their platform skill, and how many of them were pinned. */
+    skillsLinked: number;
+    skillsPinned: number;
+    /** Org skills renamed because a platform skill of the same name is on in their org. */
+    skillsRenamed: number;
+    /** Org template copies linked to their platform template, and how many of them were pinned. */
+    templatesLinked: number;
+    templatesPinned: number;
+    /** Connectors linked to the platform connector template they were made from. */
+    connectorsLinked: number;
+}
+/**
+ * The name a renamed skill gets: `<name>-org`, then `-org-2`, `-org-3`, … (the base shortened
+ * when the result would be longer than a skill name may be), the first one not in `taken`.
+ */
+export declare function renamedSkillName(name: string, taken: ReadonlySet<string>): string;
+/**
+ * The platform components migration (spec §6, §13.5), a worker job (`platform-components-migrate`,
+ * `@LockedInterval` with `runOnStart`: once across replicas at every worker start, then daily).
+ * Steps, each on the rows that still need it:
+ * 1. every live catalog item never synced (`platform_synced_version` null) gets its platform rows
+ *    (`syncFromVersion`, which records the version) at the highest
+ *    version installed in an org (spec §6: "the plugin's version becomes the highest installed
+ *    one"), else its latest version;
+ * 2. an org skill copy with plugin provenance (on the skill and its current version) links to the
+ *    platform skill of its plugin and name; it is pinned to its own current version when its files
+ *    differ from the platform version's. A copy whose platform skill is not on in its org is left
+ *    unlinked (it keeps serving what it served) until a later run finds it on: a linked copy,
+ *    pinned or not, follows its platform skill's availability (ruling P2-18);
+ * 3. one-shot (spec §5 rule 10, ruling P2-5: nothing is renamed outside the migration): only while
+ *    no run has finished (the first run's own execution), an org skill of the org's own (no
+ *    provenance) whose name a platform skill on in its org has stays the org's: it is renamed (`<name>-org`, `-org-2`, …), the org admins get an inbox notice
+ *    (`skill_renamed`) and that platform skill is switched off in the org (a switch the org already
+ *    has is kept). Agents select skills by id, so they keep it; the name changes in new runs. Once a
+ *    run has finished, a clash is only logged as a warning and left alone (the org's skill wins);
+ * 4. an org agent template links to the platform template of its plugin and name, pinned like
+ *    skills (definitions compared as canonical JSON). Templates are never renamed: an org template
+ *    always has its plugin's type, which is the platform template's;
+ * 5. a connector made from a connector template (the install ledger's `template_id`) links to that
+ *    platform connector template (ruling E2).
+ * Plugin switches exist since phase 1 and new platform rows follow the plugin's scope, so nothing
+ * else is written. Writes run per org under its row lock and re-check each row; nothing is deleted
+ * or overwritten except the renamed skill's name. Each run is recorded in `platform_migration_runs`
+ * (rows older than 30 days are pruned, except the first finished run: it marks the renames done).
+ */
+export declare class PlatformMigration {
+    private readonly kdb;
+    private readonly orgLock;
+    private readonly platform;
+    readonly txHost: TransactionHost;
+    readonly config: KernelConfigService;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    constructor(kdb: KernelDb, orgLock: OrgLock, platform: PlatformComponents, txHost: TransactionHost, config: KernelConfigService, lockService: LockService, log: KernelLogger);
+    private get db();
+    /** The scheduled run (see the class). */
+    migrate(signal?: AbortSignal): Promise<void>;
+    /**
+     * One run of every step; returns what it changed. `signal` (the stop, or a lost run lock) is
+     * read between items and orgs: an aborted run stops there and its row is deleted (every step is
+     * idempotent, so the next run carries on; an unfinished run never counts as the first one).
+     */
+    runOnce(signal?: AbortSignal): Promise<PlatformMigrationStats>;
+    /** Deletes finished runs older than {@link RUNS_KEPT_MS}, never the first one (`first`). */
+    private pruneRuns;
+    /**
+     * Step 1: the live catalog items whose platform components were never written
+     * (`platform_synced_version` null; `syncFromVersion` sets it). An item whose components were
+     * removed since is not synced again.
+     */
+    private syncItems;
+    /** The highest version of the item installed in an org (and still stored), else `latest`. */
+    private platformVersion;
+    /** Step 2: org skill copies with plugin provenance, not linked yet. */
+    private linkSkills;
+    /** Links `links` of one org under its row lock (each only while it is still as read). */
+    private linkSkillsIn;
+    /**
+     * Step 3 (one-shot): org skills of the org's own whose name a platform skill on in their org has,
+     * renamed only in the first run (`rename`: no run has finished yet); later ones are only logged.
+     */
+    private renameClashes;
+    /**
+     * Renames the clashing skills of one org under its row lock (each only while it still has the
+     * name and no provenance), switches the clashing platform skills off in the org (unless the org
+     * has a switch for them already), and writes one inbox notice and one audit event per skill.
+     */
+    private renameIn;
+    /** Step 4: org agent templates not linked yet, by plugin and name. */
+    private linkTemplates;
+    /** Links `links` of one org under its row lock (each only while it is still as read). */
+    private linkTemplatesIn;
+    /**
+     * Step 5: connectors not linked yet whose install ledger row names the connector template they
+     * were made from; one statement (a connector only gains a link, nothing else changes).
+     */
+    private linkConnectors;
+}