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

package/dist/skills/usable.d.ts

@@ -0,0 +1,81 @@
+import type { Logger, ObjectStore } from "@capybara-hq/plugin-sdk";
+import type { KernelSchemaDb, SkillManifest, SourceFormat } from "../db/kernel-schema.js";
+/** The `source` prefix of a platform skill version in a snapshot or an invocation record. */
+export declare const PLATFORM_SOURCE = "platform:";
+/** The snapshot `source` of a platform skill version stored at `prefix` (in `deployment/`). */
+export declare const platformSource: (prefix: string) => string;
+/**
+ * Where the files of a skill version with snapshot `source` live: `deployment/` for a platform
+ * version (`platform:<prefix>`), else the org's `kernel/<orgId>/`; `prefix` is the key prefix in
+ * that store.
+ */
+export declare function skillFileStore(storage: {
+    kernel(orgId: string): ObjectStore;
+    deployment(): ObjectStore;
+}, orgId: string, source: string): {
+    store: ObjectStore;
+    prefix: string;
+};
+/** A skill the org can use: one of its own, or a platform skill that is on in the org. */
+export interface UsableSkill {
+    id: string;
+    name: string;
+    description: string;
+    version: number;
+    /** The object prefix of the version (`platform:<prefix>` for a platform version). */
+    source: string;
+    /** The plugin it came from (a platform skill's plugin, an org skill's provenance). */
+    plugin: string | null;
+    origin: "org" | "platform";
+    /** The platform skill whose content this is (a platform skill, or a linked org copy). */
+    platformSkillId?: string;
+}
+/** A usable or selected skill with what the resolvers need beyond {@link UsableSkill}. */
+export interface SkillVersionRow extends UsableSkill {
+    /** `agent`: an agent's own skill (never in the org library). Platform skills are `org`. */
+    scope: "org" | "agent";
+    agentId: string | null;
+    manifest: SkillManifest;
+    format: SourceFormat;
+}
+/**
+ * The ids among `ids` of the platform skills on in the org (see {@link platformOn}), whatever the
+ * org's own skills are named: a skill of the org with the same name would clash with them.
+ */
+export declare function platformSkillsOn(db: KernelSchemaDb, orgId: string, ids: readonly string[]): Promise<Set<string>>;
+/**
+ * The ids among `ids` (platform skills that org copies are pinned to) whose pinned copies the org
+ * may use (ruling P2-18): the platform skill is on in the org ({@link platformSkillsOn}), or it was
+ * removed by a plugin update (soft-deleted, ruling P2-7: a pinned copy then keeps its own version
+ * as the org's).
+ */
+export declare function pinnedSkillLinksServed(db: KernelSchemaDb, orgId: string, ids: readonly string[]): Promise<Set<string>>;
+/**
+ * The org's live skills by id (`ids`; ids that are no usable skill are missing from the map): an
+ * agent's own skill or an org skill with its current version; an org copy linked to a platform
+ * skill without a pin (ruling B2) as that platform skill's current version under the copy's id,
+ * while the platform skill is on in the org; a pinned copy as its own version, while its platform
+ * skill is on in the org (ruling P2-18); a platform skill id while it is on in the org.
+ */
+export declare function skillVersionsById(db: KernelSchemaDb, orgId: string, ids: readonly string[], log?: Pick<Logger, "warn">): Promise<Map<string, SkillVersionRow>>;
+/**
+ * The skills an agent selects, sorted by id: its own skills (`scope = 'agent'`) and the ids of
+ * `orgSkills` that resolve ({@link skillVersionsById}: org skills, linked copies, platform skills
+ * on in the org). Not deduplicated by name.
+ */
+export declare function selectedSkills(db: KernelSchemaDb, a: {
+    orgId: string;
+    agentId: string;
+    orgSkills: readonly string[];
+}, log?: Pick<Logger, "warn">): Promise<SkillVersionRow[]>;
+/**
+ * The org's usable skills, sorted by name: its own live org skills (`scope = 'org'`, unlinked, or
+ * pinned while their platform skill is on in the org, ruling P2-18) and the platform skills on in
+ * the org (see {@link platformOn}). An org copy linked
+ * without a pin is not listed: its platform skill is; except the org's own skill it promoted
+ * (ruling P3-3), listed once under its own id instead of the platform skill.
+ * `log` receives the name-clash warnings.
+ */
+export declare function usableSkills(db: KernelSchemaDb, orgId: string, log?: Pick<Logger, "warn">): Promise<UsableSkill[]>;
+/** {@link usableSkills} with each skill's manifest and format. */
+export declare function usableSkillVersions(db: KernelSchemaDb, orgId: string, log?: Pick<Logger, "warn">): Promise<SkillVersionRow[]>;

package/dist/skills/usable.js

@@ -0,0 +1,379 @@
+import { componentOn } from "../catalog/component-state.js";
+/** The `source` prefix of a platform skill version in a snapshot or an invocation record. */
+export const PLATFORM_SOURCE = "platform:";
+/** The snapshot `source` of a platform skill version stored at `prefix` (in `deployment/`). */
+export const platformSource = (prefix) => `${PLATFORM_SOURCE}${prefix}`;
+/**
+ * Where the files of a skill version with snapshot `source` live: `deployment/` for a platform
+ * version (`platform:<prefix>`), else the org's `kernel/<orgId>/`; `prefix` is the key prefix in
+ * that store.
+ */
+export function skillFileStore(storage, orgId, source) {
+    return source.startsWith(PLATFORM_SOURCE)
+        ? { store: storage.deployment(), prefix: source.slice(PLATFORM_SOURCE.length) }
+        : { store: storage.kernel(orgId), prefix: source };
+}
+/** Plugin install statuses that make a plugin on in the org (phase 1, org catalog state). */
+const LIVE_INSTALL = ["installing", "installed", "upgrading"];
+const byNameThenId = (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+/** The live platform skill rows on in the org (`ids`: only those), before any name clash. */
+async function platformRowsOn(db, orgId, ids) {
+    if (ids !== undefined && ids.length === 0)
+        return [];
+    let q = db
+        .selectFrom("platform_skills as p")
+        .innerJoin("platform_skill_versions as v", (j) => j.onRef("v.skill_id", "=", "p.id").onRef("v.version", "=", "p.current_version"))
+        .leftJoin("catalog_items as c", (j) => j.onRef("c.id", "=", "p.catalog_item_id").on("c.deleted_at", "is", null))
+        .select((eb) => [
+        "p.id",
+        "p.name",
+        "p.plugin_name",
+        "p.catalog_item_id",
+        "p.current_version",
+        "p.scope_mode",
+        "p.scope",
+        "v.manifest",
+        "v.object_prefix",
+        "v.source_format",
+        "c.id as item_id",
+        "c.disabled as item_disabled",
+        "c.builtin as item_builtin",
+        eb
+            .exists(eb
+            .selectFrom("plugin_installs as a")
+            .select("a.id")
+            .whereRef("a.item_id", "=", "p.catalog_item_id")
+            .where("a.org_id", "=", orgId)
+            .where("a.status", "in", [...LIVE_INSTALL]))
+            .as("installed"),
+        eb
+            .exists(eb
+            .selectFrom("component_scope_orgs as l")
+            .select("l.org_id")
+            .where("l.kind", "=", "skill")
+            .whereRef("l.component_id", "=", "p.id")
+            .where("l.org_id", "=", orgId))
+            .as("listed"),
+        eb
+            .selectFrom("component_org_switches as w")
+            .select("w.enabled")
+            .where("w.kind", "=", "skill")
+            .whereRef("w.component_id", "=", "p.id")
+            .where("w.org_id", "=", orgId)
+            .as("switch"),
+    ])
+        .where("p.deleted_at", "is", null)
+        .where("p.disabled", "=", false);
+    if (ids !== undefined)
+        q = q.where("p.id", "in", [...ids]);
+    // the predicate of component scope (catalog/component-state.ts); `disabled` is filtered above
+    return (await q.execute()).filter((r) => componentOn({ scopeMode: r.scope_mode, scope: r.scope, disabled: false, itemId: r.catalog_item_id }, r.catalog_item_id === null
+        ? null
+        : {
+            live: r.item_id !== null,
+            disabled: r.item_disabled === true,
+            builtin: r.item_builtin === true,
+            // the plugin's own scope and list do not decide whether a component is on
+            scope: "optional",
+            listed: false,
+            installed: Boolean(r.installed),
+        }, Boolean(r.listed), r.switch ?? null));
+}
+/**
+ * The ids among `ids` of the platform skills on in the org (see {@link platformOn}), whatever the
+ * org's own skills are named: a skill of the org with the same name would clash with them.
+ */
+export async function platformSkillsOn(db, orgId, ids) {
+    return new Set((await platformRowsOn(db, orgId, ids)).map((r) => r.id));
+}
+/**
+ * The ids among `ids` (platform skills that org copies are pinned to) whose pinned copies the org
+ * may use (ruling P2-18): the platform skill is on in the org ({@link platformSkillsOn}), or it was
+ * removed by a plugin update (soft-deleted, ruling P2-7: a pinned copy then keeps its own version
+ * as the org's).
+ */
+export async function pinnedSkillLinksServed(db, orgId, ids) {
+    if (ids.length === 0)
+        return new Set();
+    const removed = await db
+        .selectFrom("platform_skills")
+        .select("id")
+        .where("id", "in", [...ids])
+        .where("deleted_at", "is not", null)
+        .execute();
+    return new Set([...(await platformSkillsOn(db, orgId, ids)), ...removed.map((r) => r.id)]);
+}
+/**
+ * The platform skills on in the org (`ids`: only those), minus the ones whose name an org skill of
+ * its own already uses (rule 10: the org's wins; logged unless that skill is a copy of the same
+ * component: linked to it, or carrying the same plugin's provenance before the migration linked
+ * it). On in the org:
+ * - never when the skill or its plugin is disabled (or its plugin is deleted);
+ * - `follow`: its plugin is on in the org (a live install, or builtin) and no component switch of
+ *   the org says off;
+ * - `own`: `wantedOn` over the skill's own scope, the org's list membership and its switch.
+ * One query for the skills with their plugin and org state, one for the org's names.
+ */
+async function platformOn(db, orgId, ids, log) {
+    const rows = await platformRowsOn(db, orgId, ids);
+    if (rows.length === 0)
+        return [];
+    const own = await db
+        .selectFrom("skills")
+        .select(["id", "name", "platform_skill_id", "catalog_item_id"])
+        .where("org_id", "=", orgId)
+        .where("scope", "=", "org")
+        .where("deleted_at", "is", null)
+        .where((eb) => eb.or([eb("platform_skill_id", "is", null), eb("pinned_version", "is not", null)]))
+        .where("name", "in", [...new Set(rows.map((r) => r.name))])
+        .execute();
+    const ownByName = new Map(own.map((r) => [r.name, r]));
+    const out = [];
+    const taken = new Map();
+    rows.sort((a, b) => (a.plugin_name ?? "") < (b.plugin_name ?? "")
+        ? -1
+        : (a.plugin_name ?? "") > (b.plugin_name ?? "")
+            ? 1
+            : a.id < b.id
+                ? -1
+                : 1);
+    for (const r of rows) {
+        const o = ownByName.get(r.name);
+        if (o) {
+            const sameComponent = o.platform_skill_id === r.id ||
+                (o.catalog_item_id !== null && o.catalog_item_id === r.catalog_item_id);
+            if (!sameComponent) {
+                log?.warn("platform skill shadowed by an org skill of the same name", {
+                    orgId,
+                    name: r.name,
+                    platformSkillId: r.id,
+                    skillId: o.id,
+                });
+            }
+            continue;
+        }
+        const first = taken.get(r.name);
+        if (first !== undefined) {
+            log?.warn("platform skills share a name in one org", {
+                orgId,
+                name: r.name,
+                kept: first,
+                dropped: r.id,
+            });
+            continue;
+        }
+        taken.set(r.name, r.id);
+        out.push({
+            id: r.id,
+            name: r.name,
+            description: r.manifest.description,
+            version: r.current_version,
+            source: platformSource(r.object_prefix),
+            plugin: r.plugin_name,
+            origin: "platform",
+            platformSkillId: r.id,
+            scope: "org",
+            agentId: null,
+            manifest: r.manifest,
+            format: r.source_format,
+        });
+    }
+    return out;
+}
+/**
+ * The org's live skills by id (`ids`; ids that are no usable skill are missing from the map): an
+ * agent's own skill or an org skill with its current version; an org copy linked to a platform
+ * skill without a pin (ruling B2) as that platform skill's current version under the copy's id,
+ * while the platform skill is on in the org; a pinned copy as its own version, while its platform
+ * skill is on in the org (ruling P2-18); a platform skill id while it is on in the org.
+ */
+export async function skillVersionsById(db, orgId, ids, log) {
+    const unique = [...new Set(ids)];
+    const out = new Map();
+    if (unique.length === 0)
+        return out;
+    const rows = await db
+        .selectFrom("skills as s")
+        .innerJoin("skill_versions as v", (j) => j.onRef("v.skill_id", "=", "s.id").onRef("v.version", "=", "s.current_version"))
+        .leftJoin("catalog_items as c", "c.id", "s.catalog_item_id")
+        .select([
+        "s.id",
+        "s.scope",
+        "s.agent_id",
+        "s.name",
+        "s.current_version",
+        "s.platform_skill_id",
+        "s.pinned_version",
+        "v.manifest",
+        "v.object_prefix",
+        "v.source_format",
+        "c.name as item_name",
+    ])
+        .where("s.org_id", "=", orgId)
+        .where("s.deleted_at", "is", null)
+        .where("s.id", "in", unique)
+        .execute();
+    const linked = rows.filter((r) => r.scope === "org" && r.platform_skill_id !== null && r.pinned_version === null);
+    const pinned = rows.filter((r) => r.scope === "org" && r.platform_skill_id !== null && r.pinned_version !== null);
+    const known = new Set(rows.map((r) => r.id));
+    const platformIds = [
+        ...new Set([
+            ...unique.filter((id) => !known.has(id)),
+            ...linked.map((r) => r.platform_skill_id),
+        ]),
+    ];
+    const platform = new Map((await platformOn(db, orgId, platformIds, log)).map((p) => [p.id, p]));
+    const owned = await ownedPlatformIds(db, orgId, linked.map((r) => r.platform_skill_id));
+    // ruling P2-18: a pinned copy serves its own version while its platform skill is on in the org
+    const pinnedOn = await pinnedSkillLinksServed(db, orgId, pinned.map((r) => r.platform_skill_id));
+    for (const r of rows) {
+        if (linked.includes(r)) {
+            const p = platform.get(r.platform_skill_id);
+            if (!p)
+                continue;
+            if (!owned.has(p.id)) {
+                out.set(r.id, { ...p, id: r.id });
+                continue;
+            }
+            // the org's own skill, promoted (ruling P3-3): promotion copied its current version to the
+            // platform under the same number, so while that is still the platform's current version it
+            // serves its own stored version (its snapshot source stays); a newer platform version (the
+            // owner's later upload, ruling P3-4) serves under its id. Either way it is the org's own.
+            if (r.current_version !== p.version) {
+                out.set(r.id, { ...p, id: r.id, origin: "org", plugin: r.item_name });
+                continue;
+            }
+        }
+        if (pinned.includes(r) && !pinnedOn.has(r.platform_skill_id))
+            continue;
+        out.set(r.id, {
+            id: r.id,
+            name: r.name,
+            description: r.manifest.description,
+            version: r.current_version,
+            source: r.object_prefix,
+            plugin: r.item_name,
+            origin: "org",
+            ...(r.platform_skill_id !== null && { platformSkillId: r.platform_skill_id }),
+            scope: r.scope,
+            agentId: r.agent_id,
+            manifest: r.manifest,
+            format: r.source_format,
+        });
+    }
+    for (const id of unique) {
+        const p = platform.get(id);
+        if (p && !known.has(id))
+            out.set(id, p);
+    }
+    return out;
+}
+/**
+ * The ids among `platformIds` of the live platform skills owned by `orgId` (promoted from its own
+ * skills, ruling P3-3).
+ */
+async function ownedPlatformIds(db, orgId, platformIds) {
+    if (platformIds.length === 0)
+        return new Set();
+    const rows = await db
+        .selectFrom("platform_skills")
+        .select("id")
+        .where("id", "in", [...new Set(platformIds)])
+        .where("owner_org_id", "=", orgId)
+        .where("deleted_at", "is", null)
+        .execute();
+    return new Set(rows.map((r) => r.id));
+}
+/**
+ * The skills an agent selects, sorted by id: its own skills (`scope = 'agent'`) and the ids of
+ * `orgSkills` that resolve ({@link skillVersionsById}: org skills, linked copies, platform skills
+ * on in the org). Not deduplicated by name.
+ */
+export async function selectedSkills(db, a, log) {
+    const agentOwn = await db
+        .selectFrom("skills")
+        .select("id")
+        .where("org_id", "=", a.orgId)
+        .where("scope", "=", "agent")
+        .where("agent_id", "=", a.agentId)
+        .where("deleted_at", "is", null)
+        .execute();
+    const orgSkills = new Set(a.orgSkills);
+    const byId = await skillVersionsById(db, a.orgId, [...agentOwn.map((r) => r.id), ...orgSkills], log);
+    return [...byId.values()]
+        .filter((r) => (r.scope === "agent" ? r.agentId === a.agentId : orgSkills.has(r.id)))
+        .sort((x, y) => (x.id < y.id ? -1 : x.id > y.id ? 1 : 0));
+}
+/**
+ * The org's usable skills, sorted by name: its own live org skills (`scope = 'org'`, unlinked, or
+ * pinned while their platform skill is on in the org, ruling P2-18) and the platform skills on in
+ * the org (see {@link platformOn}). An org copy linked
+ * without a pin is not listed: its platform skill is; except the org's own skill it promoted
+ * (ruling P3-3), listed once under its own id instead of the platform skill.
+ * `log` receives the name-clash warnings.
+ */
+export async function usableSkills(db, orgId, log) {
+    return (await usableSkillVersions(db, orgId, log)).map(({ scope: _s, agentId: _a, manifest: _m, format: _f, ...u }) => u);
+}
+/** {@link usableSkills} with each skill's manifest and format. */
+export async function usableSkillVersions(db, orgId, log) {
+    const own = await db
+        .selectFrom("skills as s")
+        .innerJoin("skill_versions as v", (j) => j.onRef("v.skill_id", "=", "s.id").onRef("v.version", "=", "s.current_version"))
+        .leftJoin("catalog_items as c", "c.id", "s.catalog_item_id")
+        .select([
+        "s.id",
+        "s.name",
+        "s.current_version",
+        "s.platform_skill_id",
+        "v.manifest",
+        "v.object_prefix",
+        "v.source_format",
+        "c.name as item_name",
+    ])
+        .where("s.org_id", "=", orgId)
+        .where("s.scope", "=", "org")
+        .where("s.deleted_at", "is", null)
+        .where((eb) => eb.or([eb("s.platform_skill_id", "is", null), eb("s.pinned_version", "is not", null)]))
+        .execute();
+    // ruling P2-18: a pinned copy follows its platform skill's availability (the pin fixes the
+    // version only)
+    const pinnedOn = await pinnedSkillLinksServed(db, orgId, [
+        ...new Set(own.flatMap((r) => (r.platform_skill_id === null ? [] : [r.platform_skill_id]))),
+    ]);
+    const rows = own
+        .filter((r) => r.platform_skill_id === null || pinnedOn.has(r.platform_skill_id))
+        .map((r) => ({
+        id: r.id,
+        name: r.name,
+        description: r.manifest.description,
+        version: r.current_version,
+        source: r.object_prefix,
+        plugin: r.item_name,
+        origin: "org",
+        ...(r.platform_skill_id !== null && { platformSkillId: r.platform_skill_id }),
+        scope: "org",
+        agentId: null,
+        manifest: r.manifest,
+        format: r.source_format,
+    }));
+    // the org's own skills it promoted: under their own ids, instead of their platform skills
+    const promoted = await db
+        .selectFrom("skills as s")
+        .innerJoin("platform_skills as p", "p.id", "s.platform_skill_id")
+        .select(["s.id", "s.platform_skill_id"])
+        .where("s.org_id", "=", orgId)
+        .where("s.scope", "=", "org")
+        .where("s.deleted_at", "is", null)
+        .where("s.pinned_version", "is", null)
+        .where("p.owner_org_id", "=", orgId)
+        .where("p.deleted_at", "is", null)
+        .execute();
+    const promotedTo = new Set(promoted.map((r) => r.platform_skill_id));
+    if (promoted.length > 0) {
+        const served = await skillVersionsById(db, orgId, promoted.map((r) => r.id), log);
+        rows.push(...served.values());
+    }
+    rows.push(...(await platformOn(db, orgId, undefined, log)).filter((p) => !promotedTo.has(p.id)));
+    return rows.sort(byNameThenId);
+}

package/dist/storage/job-ids.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The maintenance job scheduler ids the storage purge had before becoming `@LockedCron` /
+ * `@LockedInterval` jobs (retired at worker start, `RETIRED_SCHEDULER_IDS`). A leaf module.
+ */
+/** The maintenance job scheduler id it had before it became a cron (retired at worker start). */
+export declare const STORAGE_PURGE_SCHEDULER_ID = "storage-org-purge-hourly";

package/dist/storage/job-ids.js

@@ -0,0 +1,6 @@
+/**
+ * The maintenance job scheduler ids the storage purge had before becoming `@LockedCron` /
+ * `@LockedInterval` jobs (retired at worker start, `RETIRED_SCHEDULER_IDS`). A leaf module.
+ */
+/** The maintenance job scheduler id it had before it became a cron (retired at worker start). */
+export const STORAGE_PURGE_SCHEDULER_ID = "storage-org-purge-hourly";

package/dist/storage/purge.d.ts

@@ -1,10 +1,12 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
-import type { KernelDb } from "../db/kernel-schema.js";
-import type { StorageService } from "./storage.service.js";
-/** 维护任务：清理已删除组织的对象存储（任务名与 scheduler id 不含 `:`）。 */
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { type PrefixedStorage, StorageService } from "./storage.service.js";
+/** 定时任务：清理已删除组织的对象存储（名字不含 `:`），每小时整点。 */
 export declare const STORAGE_PURGE_JOB = "storage-org-purge";
-export declare const STORAGE_PURGE_SCHEDULER_ID = "storage-org-purge-hourly";
-export declare const STORAGE_PURGE_EVERY_MS = 3600000;
 /**
  * 删除「软删除超过 `afterDays` 天、尚未清理存储」的组织的全部对象（`StorageService.deleteOrg`），
  * 成功后写 `orgs.storage_purged_at`，之后不再处理。返回本次清理的组织数。
@@ -20,8 +22,21 @@ export declare const STORAGE_PURGE_EVERY_MS = 3600000;
  * 3. 成功：写 `storage_purged_at` 并清空认领；失败：清空认领（下一次运行重试），本次运行不再碰它。
  */
 export declare function purgeDeletedOrgStorage(d: {
-    db: KernelDb;
-    storage: StorageService;
+    db: Pick<KernelSchemaDb, "updateTable" | "selectFrom">;
+    storage: PrefixedStorage;
     afterDays: number;
     log: Pick<Logger, "info" | "warn">;
 }): Promise<number>;
+/**
+ * The hourly `storage-org-purge` job (fixed period: `@LockedCron`, once per tick across replicas):
+ * {@link purgeDeletedOrgStorage} with `storage.purgeDeletedOrgsAfterDays`.
+ */
+export declare class StoragePurgeJob {
+    private readonly db;
+    private readonly storage;
+    private readonly config;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    constructor(db: KernelDb, storage: StorageService, config: KernelConfigService, lockService: LockService, log: KernelLogger);
+    run(): Promise<void>;
+}

package/dist/storage/purge.js

@@ -1,8 +1,22 @@
+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";
-/** 维护任务：清理已删除组织的对象存储（任务名与 scheduler id 不含 `:`）。 */
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { LockedCron } from "../infra/schedule/locked-cron.decorator.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { StorageService } from "./storage.service.js";
+/** 定时任务：清理已删除组织的对象存储（名字不含 `:`），每小时整点。 */
 export const STORAGE_PURGE_JOB = "storage-org-purge";
-export const STORAGE_PURGE_SCHEDULER_ID = "storage-org-purge-hourly";
-export const STORAGE_PURGE_EVERY_MS = 3_600_000;
 /** 每次运行最多处理的组织数（成功与失败合计）。 */
 const PURGE_BATCH = 100;
 /** 认领超过这么久仍未完成（运行中途退出）就可被重新认领。 */
@@ -73,3 +87,41 @@ export async function purgeDeletedOrgStorage(d) {
     }
     return purged;
 }
+/**
+ * The hourly `storage-org-purge` job (fixed period: `@LockedCron`, once per tick across replicas):
+ * {@link purgeDeletedOrgStorage} with `storage.purgeDeletedOrgsAfterDays`.
+ */
+let StoragePurgeJob = class StoragePurgeJob {
+    db;
+    storage;
+    config;
+    lockService;
+    log;
+    constructor(db, storage, config, lockService, log) {
+        this.db = db;
+        this.storage = storage;
+        this.config = config;
+        this.lockService = lockService;
+        this.log = log;
+    }
+    async run() {
+        await purgeDeletedOrgStorage({
+            db: this.db,
+            storage: this.storage,
+            afterDays: this.config.get().storage.purgeDeletedOrgsAfterDays,
+            log: this.log,
+        });
+    }
+};
+__decorate([
+    LockedCron("0 * * * *", { name: STORAGE_PURGE_JOB })
+], StoragePurgeJob.prototype, "run", null);
+StoragePurgeJob = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(StorageService)),
+    __param(2, Inject(KernelConfigService)),
+    __param(3, Inject(LockService)),
+    __param(4, Inject(KERNEL_LOGGER))
+], StoragePurgeJob);
+export { StoragePurgeJob };

package/dist/storage/storage.module.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Object storage (`object-store@1` with the kernel's key prefixes): the one {@link StorageService}
+ * (the hourly `storage-org-purge` job, `StoragePurgeJob`, is the worker role's: `WorkerModule`).
+ */
+export declare class StorageModule {
+}

package/dist/storage/storage.module.js

@@ -0,0 +1,23 @@
+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 { ExtensionRegistryModule } from "../extensions/registry.js";
+import { StorageService } from "./storage.service.js";
+/**
+ * Object storage (`object-store@1` with the kernel's key prefixes): the one {@link StorageService}
+ * (the hourly `storage-org-purge` job, `StoragePurgeJob`, is the worker role's: `WorkerModule`).
+ */
+let StorageModule = class StorageModule {
+};
+StorageModule = __decorate([
+    Module({
+        imports: [ExtensionRegistryModule],
+        providers: [StorageService],
+        exports: [StorageService],
+    })
+], StorageModule);
+export { StorageModule };

package/dist/storage/storage.service.d.ts

@@ -1,4 +1,6 @@
 import { ExtensionPointUnavailableError, type ExtensionStorage, type ObjectStore } from "@capybara-hq/plugin-sdk";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
 export { StorageKeyError } from "./prefix.js";
 /** 部署级对象的键前缀（见 {@link StorageService.deployment}）。 */
 export declare const DEPLOYMENT_PREFIX = "deployment/";
@@ -8,22 +10,25 @@ export declare const storageUnavailable: () => ExtensionPointUnavailableError;
 export declare const MAX_PRESIGN_TTL_SECONDS = 604800;
 /** 把预签名有效期取整并限制在 1..{@link MAX_PRESIGN_TTL_SECONDS}；不是有限数时抛 RangeError。 */
 export declare function clampPresignTtl(ttlSeconds: number): number;
-export interface StorageServiceDeps {
+/** Where a {@link PrefixedStorage} gets its object store and the extensions that may hold data. */
+export interface StorageSource {
     /** 当前的 `object-store@1` 提供方；每次调用时取（提供方在插件加载过程中才就绪）。 */
     provider: () => ObjectStore | undefined;
     /** 可能存过数据的插件名（删除组织数据时逐个删 `plugins/<插件>/<orgId>/`）。 */
     plugins: () => Promise<string[]>;
 }
 /**
- * 内核的对象存储服务（扩展模型 §5）：在 `object-store@1` 提供方之上加前缀隔离。
+ * 前缀隔离的对象存储（扩展模型 §5）：在 `object-store@1` 提供方之上加前缀隔离。A plain class over a
+ * {@link StorageSource}: the kernel's one instance is the {@link StorageService} provider; an
+ * extension's `ctx.storage` and the CLI build their own over their own source.
  * - 插件经 {@link forPlugin} 拿到 `ctx.storage`：键落在 `plugins/<插件>/<orgId>/` 下；
  * - 内核功能经 {@link kernel} 用 `kernel/<orgId>/`；
  * - 返回给调用方的键（`head` / `get` / `put` / `list`）都去掉前缀，列举结果只保留本前缀下的对象。
  * 没有提供方时各方法 reject `storage.unavailable`（{@link available} 为 false）。本身无状态，可多副本共用。
  */
-export declare class StorageService {
+export declare class PrefixedStorage {
     private readonly d;
-    constructor(d: StorageServiceDeps);
+    constructor(d: StorageSource);
     /** 是否有对象存储提供方。 */
     get available(): boolean;
     /** 依赖存储的 HTTP 功能在入口调用：没有提供方时抛 `ApiError("storage.unavailable")`（503）。 */
@@ -42,3 +47,12 @@ export declare class StorageService {
     deleteOrg(orgId: string): Promise<number>;
     private require;
 }
+/**
+ * The kernel's object storage (one provider): the object store is the first loaded `object-store@1`
+ * provider in the {@link ExtensionRegistry} (read per call: it is ready only after the extensions
+ * load); the extensions that may hold data are those ever approved (permission snapshots, including
+ * uninstalled ones) plus the loaded ones.
+ */
+export declare class StorageService extends PrefixedStorage {
+    constructor(registry: ExtensionRegistry, db: KernelDb);
+}