@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

package/dist/inbox/org-notices.js

@@ -0,0 +1,91 @@
+// Org notices (`org_notices`, plugin scope phase 3, spec §14, ruling P3-22): what an org's admins
+// are told about shared items and uploads, until one of them dismisses it. The writers run in the
+// caller's transaction, so a notice exists exactly when its change does.
+import { randomUUID } from "node:crypto";
+import { orgsUsing, ownerOf, ownersOf } from "../catalog/ownership.js";
+/** An owned ref's display name: a plugin's (skills and agent templates have none). */
+const refDisplayName = (db, ref) => ref.kind === "plugin" ? itemDisplayName(db, ref.id) : Promise.resolve(null);
+/** A catalog item's display name for an upload notice (null without one, or for an unknown id). */
+export async function itemDisplayName(db, itemId) {
+    const row = await db
+        .selectFrom("catalog_items")
+        .select("display_name")
+        .where("id", "=", itemId)
+        .executeTakeFirst();
+    return row?.display_name ?? null;
+}
+/** Writes an org notice in the caller's transaction. */
+export async function addOrgNotice(db, orgId, kind, detail) {
+    await db
+        .insertInto("org_notices")
+        .values({ id: randomUUID(), org_id: orgId, kind, detail: JSON.stringify(detail) })
+        .execute();
+}
+const OWNER_TABLE = {
+    plugin: "catalog_items",
+    skill: "platform_skills",
+    agent_template: "platform_agent_templates",
+};
+/**
+ * Tells the owner org that its item was shared (`item_shared`): with each org of `orgs` (the owner
+ * itself is skipped), or with `all_orgs`. A platform-owned item writes nothing.
+ */
+export async function notifyItemShared(db, ownerOrgId, ref, name, orgs) {
+    if (ownerOrgId === null)
+        return;
+    const displayName = await refDisplayName(db, ref);
+    if (orgs === "all_orgs") {
+        await addOrgNotice(db, ownerOrgId, "item_shared", {
+            ref,
+            name,
+            displayName,
+            org: "all_orgs",
+        });
+        return;
+    }
+    const targets = [...new Set(orgs)].filter((o) => o !== ownerOrgId);
+    if (targets.length === 0)
+        return;
+    const rows = await db
+        .selectFrom("orgs")
+        .select(["id", "name"])
+        .where("id", "in", targets)
+        .execute();
+    const names = new Map(rows.map((r) => [r.id, r.name]));
+    for (const id of targets) {
+        await addOrgNotice(db, ownerOrgId, "item_shared", {
+            ref,
+            name,
+            displayName,
+            org: { id, name: names.get(id) ?? id },
+        });
+    }
+}
+/**
+ * Tells every live org the org-owned item is on in, except its owner (P3-18, {@link orgsUsing}),
+ * that it changed version (`shared_item_updated`); returns how many orgs were told. A platform-owned
+ * or missing item tells nobody.
+ */
+export async function notifySharedUpdate(db, ref, change) {
+    const row = await db
+        .selectFrom(OWNER_TABLE[ref.kind])
+        .select("owner_org_id")
+        .where("id", "=", ref.id)
+        .executeTakeFirst();
+    if (!row || row.owner_org_id === null)
+        return 0;
+    const owner = ownerOf(row.owner_org_id, await ownersOf(db, [row.owner_org_id]));
+    const using = await orgsUsing(db, ref, { except: row.owner_org_id });
+    const displayName = await refDisplayName(db, ref);
+    for (const o of using) {
+        await addOrgNotice(db, o.id, "shared_item_updated", {
+            ref,
+            name: change.name,
+            displayName,
+            from: change.from,
+            to: change.to,
+            owner,
+        });
+    }
+    return using.length;
+}

package/dist/inbox/platform-inbox.controller.d.ts

@@ -0,0 +1,23 @@
+import type { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { PlatformInboxService, type PlatformInboxView } from "./platform-inbox.service.js";
+declare const NoticeParamsSchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The super admin's inbox (`GET /api/v1/admin/inbox`): the platform's requests, permission
+ * confirmations, scope sync failures and the migration run that needs a look, newest first, at
+ * most 100 (`truncated`: more, `total`: how many in all), and `GET /api/v1/admin/inbox/count`
+ * (`{ total }`, the sidebar's count). Super admins only (web session or personal token).
+ */
+export declare class PlatformInboxController {
+    private readonly inbox;
+    constructor(inbox: PlatformInboxService);
+    list(): Promise<PlatformInboxView>;
+    count(): Promise<{
+        total: number;
+    }>;
+    /** A super admin dismisses a platform notice (`ownership_transferred`) for every super admin. */
+    dismissNotice(principal: Principal, params: z.infer<typeof NoticeParamsSchema>): Promise<void>;
+}
+export {};

package/dist/inbox/platform-inbox.controller.js

@@ -0,0 +1,58 @@
+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 { Controller, Get, HttpCode, Inject, Post } from "@nestjs/common";
+import { CurrentPrincipal, requireUser, SuperAdmin, } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZParam } from "../infra/validation/zod-params.js";
+import { InboxNoticeParams } from "./inbox.schemas.js";
+import { PlatformInboxService } from "./platform-inbox.service.js";
+const NoticeParamsSchema = InboxNoticeParams;
+class NoticeParams extends createZodDto(NoticeParamsSchema, "PlatformInboxNoticeParams") {
+}
+/**
+ * The super admin's inbox (`GET /api/v1/admin/inbox`): the platform's requests, permission
+ * confirmations, scope sync failures and the migration run that needs a look, newest first, at
+ * most 100 (`truncated`: more, `total`: how many in all), and `GET /api/v1/admin/inbox/count`
+ * (`{ total }`, the sidebar's count). Super admins only (web session or personal token).
+ */
+let PlatformInboxController = class PlatformInboxController {
+    inbox;
+    constructor(inbox) {
+        this.inbox = inbox;
+    }
+    list() {
+        return this.inbox.list();
+    }
+    async count() {
+        return { total: await this.inbox.count() };
+    }
+    /** A super admin dismisses a platform notice (`ownership_transferred`) for every super admin. */
+    async dismissNotice(principal, params) {
+        await this.inbox.dismissNotice(requireUser(principal).account.id, params.id);
+    }
+};
+__decorate([
+    Get()
+], PlatformInboxController.prototype, "list", null);
+__decorate([
+    Get("count")
+], PlatformInboxController.prototype, "count", null);
+__decorate([
+    Post("notices/:id/dismiss"),
+    HttpCode(204),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZParam(NoticeParams))
+], PlatformInboxController.prototype, "dismissNotice", null);
+PlatformInboxController = __decorate([
+    Controller("api/v1/admin/inbox"),
+    SuperAdmin(),
+    __param(0, Inject(PlatformInboxService))
+], PlatformInboxController);
+export { PlatformInboxController };

package/dist/inbox/platform-inbox.service.d.ts

@@ -0,0 +1,151 @@
+import type { LocalizedName } from "@capybara-hq/plugin-sdk";
+import { type CatalogItemView, CatalogService } from "../catalog/catalog.service.js";
+import { CatalogRequestsService, type CatalogRequestView } from "../catalog/requests.service.js";
+import type { ScopeSyncOp } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import type { PlatformNoticeDetails } from "./platform-notices.js";
+/** The most items one platform inbox read returns. */
+export declare const PLATFORM_INBOX_MAX_ITEMS = 100;
+/** The most open scope sync failures one read takes. */
+export declare const SCOPE_SYNC_FAILURES_LIST_MAX = 200;
+/**
+ * A platform components migration run unfinished this long after its start is stuck (its worker
+ * stopped mid-run; a run takes seconds, and the next one starts at the next worker start or day).
+ */
+export declare const MIGRATION_RUN_STUCK_MS: number;
+/**
+ * An open failure of the plugin scope sync: its last attempt to install the plugin in the org, to
+ * uninstall it, or to install the dependencies a platform update added (`dependencies`) failed,
+ * and the org still differs from the scope in that direction.
+ */
+export interface ScopeSyncFailureView {
+    item: {
+        id: string;
+        name: string;
+        displayName: LocalizedName | null;
+    };
+    org: {
+        id: string;
+        name: string;
+    };
+    op: ScopeSyncOp;
+    /** The error code (`internal` for an unexpected error) and its message. */
+    code: string;
+    message: string;
+    failedAt: string;
+}
+/**
+ * The latest platform components migration run (`platform_migration_runs`) when it needs a look:
+ * finished with catalog items whose components could not be written (`itemsFailed`,
+ * `<name>@<version>`), or `stuck` (unfinished {@link MIGRATION_RUN_STUCK_MS} after its start).
+ */
+export interface MigrationRunView {
+    id: string;
+    startedAt: string;
+    finishedAt: string | null;
+    stuck: boolean;
+    itemsFailed: string[];
+}
+/**
+ * One item of the super admin's inbox (by `type`). Nothing is decided in the inbox: each item is
+ * acted on where it lives (the web links to it).
+ * - `catalog_request`: an org's pending request to the platform (`access`: use a plugin shown to
+ *   it; `import`: bring in a marketplace entry), as `GET /admin/catalog/requests` lists them;
+ * - `permission_confirmation`: a platform plugin whose extension permissions wait for a super
+ *   admin's confirmation (`GET /admin/catalog/items?pending=true`), `id` = the item's;
+ * - `org_upload_pending`: an org-owned plugin whose uploaded version (with an extension) waits for
+ *   the super admin in 待确认 (ruling P3-22; confirmed or rejected there), `id` = the item's;
+ * - `scope_sync_failed`: an open scope sync failure, `id` = `<itemId>/<orgId>`;
+ * - `platform_migration`: the latest migration run, failed items or stuck, `id` = the run's;
+ * - `ownership_transferred`: a deleted org's shared item now belongs to the platform, until a
+ *   super admin dismisses it (`POST admin/inbox/notices/:id/dismiss`).
+ */
+export type PlatformInboxItem = {
+    type: "catalog_request";
+    id: string;
+    createdAt: string;
+    request: CatalogRequestView;
+} | {
+    type: "permission_confirmation";
+    id: string;
+    createdAt: string;
+    item: CatalogItemView;
+} | {
+    type: "org_upload_pending";
+    id: string;
+    createdAt: string;
+    item: CatalogItemView;
+} | {
+    type: "scope_sync_failed";
+    id: string;
+    createdAt: string;
+    failure: ScopeSyncFailureView;
+} | {
+    type: "platform_migration";
+    id: string;
+    createdAt: string;
+    run: MigrationRunView;
+} | {
+    type: "ownership_transferred";
+    id: string;
+    createdAt: string;
+    notice: PlatformNoticeView;
+};
+/** An open platform notice (`platform_notices`, kind `ownership_transferred`). */
+export interface PlatformNoticeView {
+    id: string;
+    kind: "ownership_transferred";
+    createdAt: string;
+    detail: PlatformNoticeDetails["ownership_transferred"];
+}
+/**
+ * `GET /admin/inbox`: newest first, at most {@link PLATFORM_INBOX_MAX_ITEMS}; `truncated`: more;
+ * `total`: how many items wait in all (also `GET /admin/inbox/count`).
+ */
+export interface PlatformInboxView {
+    items: PlatformInboxItem[];
+    truncated: boolean;
+    total: number;
+}
+/**
+ * The super admin's inbox (plugin scope spec §5.1 rule 5, §13.5): what waits on the platform,
+ * gathered from the sources the admin pages read (the 待确认 tab's requests and permission
+ * confirmations), plus the scope sync's open failures and the platform components migration's
+ * latest run. Stateless, read live from PG.
+ */
+export declare class PlatformInboxService {
+    private readonly requests;
+    private readonly catalog;
+    private readonly kdb;
+    constructor(requests: Pick<CatalogRequestsService, "listDeployment" | "countPendingDeployment">, catalog: Pick<CatalogService, "list">, kdb: KernelDb);
+    list(): Promise<PlatformInboxView>;
+    /**
+     * How many items wait (the sidebar's count): the same sources, counted where they can be (the
+     * requests and the failures; the permission confirmations are the catalog's pending list).
+     */
+    count(): Promise<number>;
+    private countNotices;
+    /** The open platform notices, newest first, at most {@link PLATFORM_INBOX_MAX_ITEMS}. */
+    private notices;
+    /**
+     * A super admin dismisses a platform notice (for every super admin). Dismissing one already
+     * dismissed is fine; no notice with that id -> `inbox.notice_not_found`.
+     */
+    dismissNotice(accountId: string, id: string): Promise<void>;
+    /**
+     * The open failures still worth a look, joined to their item and org: of a live item and org,
+     * and the pair still differs in the failed direction (a person may have converged it meanwhile):
+     * an install failure while the org has no live install of the item; an uninstall or dependencies
+     * failure while it has one.
+     */
+    private failureRows;
+    private countScopeSyncFailures;
+    /** The open scope sync failures ({@link failureRows}), newest first. */
+    private scopeSyncFailures;
+    /**
+     * The latest migration run when it needs a look (see {@link MigrationRunView}); null when it
+     * finished without failed items, is still running, or there was none. An earlier run's failure
+     * is not shown: each run tries every unwritten item again.
+     */
+    private migrationRun;
+}

package/dist/inbox/platform-inbox.service.js

@@ -0,0 +1,263 @@
+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 { sql } from "kysely";
+import { CatalogService } from "../catalog/catalog.service.js";
+import { CatalogRequestsService } from "../catalog/requests.service.js";
+import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+/** The most items one platform inbox read returns. */
+export const PLATFORM_INBOX_MAX_ITEMS = 100;
+/** The most open scope sync failures one read takes. */
+export const SCOPE_SYNC_FAILURES_LIST_MAX = 200;
+/**
+ * A platform components migration run unfinished this long after its start is stuck (its worker
+ * stopped mid-run; a run takes seconds, and the next one starts at the next worker start or day).
+ */
+export const MIGRATION_RUN_STUCK_MS = 60 * 60_000;
+/** Plugin install statuses of a plugin that is on in the org. */
+const LIVE_INSTALL = ["installing", "installed", "upgrading"];
+/**
+ * The super admin's inbox (plugin scope spec §5.1 rule 5, §13.5): what waits on the platform,
+ * gathered from the sources the admin pages read (the 待确认 tab's requests and permission
+ * confirmations), plus the scope sync's open failures and the platform components migration's
+ * latest run. Stateless, read live from PG.
+ */
+let PlatformInboxService = class PlatformInboxService {
+    requests;
+    catalog;
+    kdb;
+    constructor(requests, catalog, kdb) {
+        this.requests = requests;
+        this.catalog = catalog;
+        this.kdb = kdb;
+    }
+    async list() {
+        const [requests, requestCount, pending, failures, failureCount, run, notices, noticeCount] = await Promise.all([
+            this.requests.listDeployment(),
+            this.requests.countPendingDeployment(),
+            this.catalog.list({ pending: true }),
+            this.scopeSyncFailures(),
+            this.countScopeSyncFailures(),
+            this.migrationRun(),
+            this.notices(),
+            this.countNotices(),
+        ]);
+        const all = [
+            ...requests.map((r) => ({
+                type: "catalog_request",
+                id: r.id,
+                createdAt: r.createdAt,
+                request: r,
+            })),
+            ...pending.map((i) => ({
+                type: i.owner.kind === "org" ? "org_upload_pending" : "permission_confirmation",
+                id: i.id,
+                createdAt: i.updatedAt,
+                item: i,
+            })),
+            ...failures.map((f) => ({
+                type: "scope_sync_failed",
+                id: `${f.item.id}/${f.org.id}`,
+                createdAt: f.failedAt,
+                failure: f,
+            })),
+            ...notices.map((n) => ({
+                type: "ownership_transferred",
+                id: n.id,
+                createdAt: n.createdAt,
+                notice: n,
+            })),
+            ...(run === null
+                ? []
+                : [
+                    {
+                        type: "platform_migration",
+                        id: run.id,
+                        createdAt: run.finishedAt ?? run.startedAt,
+                        run,
+                    },
+                ]),
+        ];
+        // newest first; equal times by id (a stable order)
+        all.sort((a, b) => a.createdAt !== b.createdAt
+            ? a.createdAt < b.createdAt
+                ? 1
+                : -1
+            : a.id < b.id
+                ? -1
+                : a.id > b.id
+                    ? 1
+                    : 0);
+        const total = requestCount + pending.length + failureCount + (run === null ? 0 : 1) + noticeCount;
+        const items = all.slice(0, PLATFORM_INBOX_MAX_ITEMS);
+        return { items, truncated: total > items.length, total };
+    }
+    /**
+     * How many items wait (the sidebar's count): the same sources, counted where they can be (the
+     * requests and the failures; the permission confirmations are the catalog's pending list).
+     */
+    async count() {
+        const [requests, pending, failures, run, notices] = await Promise.all([
+            this.requests.countPendingDeployment(),
+            this.catalog.list({ pending: true }),
+            this.countScopeSyncFailures(),
+            this.migrationRun(),
+            this.countNotices(),
+        ]);
+        return requests + pending.length + failures + (run === null ? 0 : 1) + notices;
+    }
+    async countNotices() {
+        const r = await this.kdb.db
+            .selectFrom("platform_notices")
+            .select(sql `count(*)`.as("n"))
+            .where("dismissed_at", "is", null)
+            .executeTakeFirstOrThrow();
+        return Number(r.n);
+    }
+    /** The open platform notices, newest first, at most {@link PLATFORM_INBOX_MAX_ITEMS}. */
+    async notices() {
+        const rows = await this.kdb.db
+            .selectFrom("platform_notices")
+            .select(["id", "kind", "detail", "created_at"])
+            .where("dismissed_at", "is", null)
+            .orderBy("created_at", "desc")
+            .orderBy("id")
+            .limit(PLATFORM_INBOX_MAX_ITEMS)
+            .execute();
+        return rows.map((r) => ({
+            id: r.id,
+            kind: r.kind,
+            createdAt: r.created_at.toISOString(),
+            detail: r.detail,
+        }));
+    }
+    /**
+     * A super admin dismisses a platform notice (for every super admin). Dismissing one already
+     * dismissed is fine; no notice with that id -> `inbox.notice_not_found`.
+     */
+    async dismissNotice(accountId, id) {
+        if (!UUID_RE.test(id))
+            throw new ApiError("inbox.notice_not_found", "Notice not found");
+        const r = await this.kdb.db
+            .updateTable("platform_notices")
+            .set({ dismissed_at: sql `now()`, dismissed_by: accountId })
+            .where("id", "=", id)
+            .where("dismissed_at", "is", null)
+            .executeTakeFirst();
+        if (r.numUpdatedRows > 0n)
+            return;
+        const exists = await this.kdb.db
+            .selectFrom("platform_notices")
+            .select("id")
+            .where("id", "=", id)
+            .executeTakeFirst();
+        if (!exists)
+            throw new ApiError("inbox.notice_not_found", "Notice not found");
+    }
+    /**
+     * The open failures still worth a look, joined to their item and org: of a live item and org,
+     * and the pair still differs in the failed direction (a person may have converged it meanwhile):
+     * an install failure while the org has no live install of the item; an uninstall or dependencies
+     * failure while it has one.
+     */
+    failureRows() {
+        return this.kdb.db
+            .selectFrom("plugin_scope_sync_failures as f")
+            .innerJoin("catalog_items as i", "i.id", "f.item_id")
+            .innerJoin("orgs as o", "o.id", "f.org_id")
+            .where("i.deleted_at", "is", null)
+            .where("o.deleted_at", "is", null)
+            .where((eb) => {
+            const live = eb.exists(eb
+                .selectFrom("plugin_installs as p")
+                .select("p.id")
+                .whereRef("p.org_id", "=", "f.org_id")
+                .whereRef("p.item_id", "=", "f.item_id")
+                .where("p.status", "in", [...LIVE_INSTALL]));
+            return eb.or([
+                eb.and([eb("f.op", "=", "install"), eb.not(live)]),
+                eb.and([eb("f.op", "in", ["uninstall", "dependencies"]), live]),
+            ]);
+        });
+    }
+    async countScopeSyncFailures() {
+        const r = await this.failureRows()
+            .select(sql `count(*)`.as("n"))
+            .executeTakeFirstOrThrow();
+        return Number(r.n);
+    }
+    /** The open scope sync failures ({@link failureRows}), newest first. */
+    async scopeSyncFailures() {
+        const rows = await this.failureRows()
+            .select([
+            "f.item_id",
+            "i.name as item_name",
+            "i.display_name",
+            "f.org_id",
+            "o.name as org_name",
+            "f.op",
+            "f.code",
+            "f.message",
+            "f.failed_at",
+        ])
+            .orderBy("f.failed_at", "desc")
+            .orderBy("f.item_id")
+            .orderBy("f.org_id")
+            .limit(SCOPE_SYNC_FAILURES_LIST_MAX)
+            .execute();
+        return rows.map((r) => ({
+            item: { id: r.item_id, name: r.item_name, displayName: r.display_name },
+            org: { id: r.org_id, name: r.org_name },
+            op: r.op,
+            code: r.code,
+            message: r.message,
+            failedAt: r.failed_at.toISOString(),
+        }));
+    }
+    /**
+     * The latest migration run when it needs a look (see {@link MigrationRunView}); null when it
+     * finished without failed items, is still running, or there was none. An earlier run's failure
+     * is not shown: each run tries every unwritten item again.
+     */
+    async migrationRun() {
+        const run = await this.kdb.db
+            .selectFrom("platform_migration_runs")
+            .select(["id", "started_at", "finished_at", "stats"])
+            .orderBy("started_at", "desc")
+            .orderBy("id", "desc")
+            .limit(1)
+            .executeTakeFirst();
+        if (run === undefined)
+            return null;
+        const failed = run.stats.itemsFailed;
+        const itemsFailed = Array.isArray(failed)
+            ? failed.filter((x) => typeof x === "string")
+            : [];
+        const stuck = run.finished_at === null && run.started_at.getTime() < Date.now() - MIGRATION_RUN_STUCK_MS;
+        if (!stuck && (run.finished_at === null || itemsFailed.length === 0))
+            return null;
+        return {
+            id: run.id,
+            startedAt: run.started_at.toISOString(),
+            finishedAt: run.finished_at?.toISOString() ?? null,
+            stuck,
+            itemsFailed,
+        };
+    }
+};
+PlatformInboxService = __decorate([
+    Injectable(),
+    __param(0, Inject(CatalogRequestsService)),
+    __param(1, Inject(CatalogService)),
+    __param(2, Inject(KernelDb))
+], PlatformInboxService);
+export { PlatformInboxService };
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

package/dist/inbox/platform-notices.d.ts

@@ -0,0 +1,19 @@
+import type { OwnedRef } from "../catalog/ownership.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+export type PlatformNoticeKind = "ownership_transferred";
+/** The `detail` of each platform notice kind. */
+export interface PlatformNoticeDetails {
+    /** A deleted org's (or owner's) shared item now belongs to the platform. */
+    ownership_transferred: {
+        ref: OwnedRef;
+        name: string;
+        fromOrg: {
+            id: string;
+            name: string;
+        };
+        reason: "owner_deleted" | "org_deleted";
+        /** How many other orgs use it. */
+        usedBy: number;
+    };
+}
+export declare function addPlatformNotice<K extends PlatformNoticeKind>(db: KernelSchemaDb, kind: K, detail: PlatformNoticeDetails[K]): Promise<void>;

package/dist/inbox/platform-notices.js

@@ -0,0 +1,9 @@
+// Platform notices (`platform_notices`, plugin scope phase 3, ruling P3-22): what the super admins
+// are told, until any one of them dismisses it. Written in the caller's transaction.
+import { randomUUID } from "node:crypto";
+export async function addPlatformNotice(db, kind, detail) {
+    await db
+        .insertInto("platform_notices")
+        .values({ id: randomUUID(), kind, detail: JSON.stringify(detail) })
+        .execute();
+}