Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🧱 feat: Add Skill Lifecycle Persistence Primitives (#17040)

Dustin Healy887f3ea0c909
diff --git a/packages/data-provider/src/config.spec.ts b/packages/data-provider/src/config.spec.ts
index 6e06d485ea..3340ca6471 100644
--- a/packages/data-provider/src/config.spec.ts
+++ b/packages/data-provider/src/config.spec.ts
@@ -69,6 +69,41 @@ describe('host-side file edit limits', () => {
});
});
+describe('skill deletion worker config', () => {
+ it('defaults and accepts deployment-specific sweep timing', () => {
+ expect(configSchema.parse({ version: '1.0' }).skillDeletion).toEqual({
+ finalizationEnabled: false,
+ sweepIntervalMs: 60_000,
+ claimLeaseMs: 120_000,
+ batchSize: 100,
+ recheckIntervalMs: 3_600_000,
+ });
+ expect(
+ configSchema.parse({ version: '1.0', skillDeletion: { claimLeaseMs: 180_000 } })
+ .skillDeletion,
+ ).toEqual({
+ finalizationEnabled: false,
+ sweepIntervalMs: 60_000,
+ claimLeaseMs: 180_000,
+ batchSize: 100,
+ recheckIntervalMs: 3_600_000,
+ });
+ expect(
+ configSchema.parse({ version: '1.0', skillDeletion: { finalizationEnabled: true } })
+ .skillDeletion.finalizationEnabled,
+ ).toBe(true);
+ });
+
+ it('rejects invalid sweep timing', () => {
+ expect(
+ configSchema.safeParse({ version: '1.0', skillDeletion: { sweepIntervalMs: 999 } }).success,
+ ).toBe(false);
+ expect(
+ configSchema.safeParse({ version: '1.0', skillDeletion: { recheckIntervalMs: 999 } }).success,
+ ).toBe(false);
+ });
+});
+
describe('stream keepalive interval', () => {
it('defaults to 25 seconds and accepts 0 to disable', () => {
expect(agentsEndpointSchema.parse({}).streamKeepaliveIntervalMs).toBe(25_000);
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index 9b8f8fcb8e..f75d81fc37 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -4080,6 +4080,23 @@ export const configSchema = z.object({
memory: memorySchema.optional(),
summarization: summarizationConfigSchema.optional(),
skillSync: skillSyncConfigSchema,
+ skillDeletion: z
+ .object({
+ /** Enable only after every server that can write Skill files uses upload intents. */
+ finalizationEnabled: z.boolean().default(false),
+ sweepIntervalMs: z.number().int().min(1_000).default(60_000),
+ claimLeaseMs: z.number().int().min(1_000).default(120_000),
+ batchSize: z.number().int().min(1).max(1_000).default(100),
+ recheckIntervalMs: z.number().int().min(60_000).default(3_600_000),
+ })
+ .strict()
+ .default(() => ({
+ finalizationEnabled: false,
+ sweepIntervalMs: 60_000,
+ claimLeaseMs: 120_000,
+ batchSize: 100,
+ recheckIntervalMs: 3_600_000,
+ })),
secureImageLinks: z.boolean().optional(),
imageOutputType: z.nativeEnum(EImageOutputType).default(EImageOutputType.PNG),
conversationList: conversationListConfigSchema.default(() =>
diff --git a/packages/data-provider/src/file-config.spec.ts b/packages/data-provider/src/file-config.spec.ts
index 3acee7e7d8..311d8e9fd9 100644
--- a/packages/data-provider/src/file-config.spec.ts
+++ b/packages/data-provider/src/file-config.spec.ts
@@ -979,6 +979,15 @@ describe('getEndpointFileConfig', () => {
expect(merged.skills?.fileSizeLimit).toBe(50 * 1024 * 1024);
});
+ it('defaults whole-Skill deletion concurrency and preserves configured overrides', () => {
+ expect(mergeFileConfig(undefined).skills?.deletionCleanupConcurrency).toBe(8);
+ const parsed = fileConfigSchema.parse({ skills: { deletionCleanupConcurrency: 3 } });
+ expect(mergeFileConfig(parsed).skills?.deletionCleanupConcurrency).toBe(3);
+ expect(
+ fileConfigSchema.safeParse({ skills: { deletionCleanupConcurrency: 0 } }).success,
+ ).toBe(false);
+ });
+
it.each([0, -1, 1.5])('rejects invalid rollback concurrency %s', (concurrency) => {
expect(
fileConfigSchema.safeParse({ skills: { importCleanupConcurrency: concurrency } }).success,
diff --git a/packages/data-provider/src/file-config.ts b/packages/data-provider/src/file-config.ts
index fadeb3352a..3ac2c521d3 100644
--- a/packages/data-provider/src/file-config.ts
+++ b/packages/data-provider/src/file-config.ts
@@ -7,6 +7,8 @@ import { normalizeEndpointName } from './utils';
/** Parallel storage deletions during rollback of a failed skill archive import. */
export const DEFAULT_SKILL_IMPORT_CLEANUP_CONCURRENCY = 8;
+/** Parallel provider deletions during a whole-Skill cleanup pass. */
+export const DEFAULT_SKILL_DELETION_CLEANUP_CONCURRENCY = 8;
export const supportsFiles = {
[EModelEndpoint.openAI]: true,
@@ -586,6 +588,7 @@ export const fileConfig = {
skills: {
fileSizeLimit: defaultSkillImportSizeLimit,
importCleanupConcurrency: DEFAULT_SKILL_IMPORT_CLEANUP_CONCURRENCY,
+ deletionCleanupConcurrency: DEFAULT_SKILL_DELETION_CLEANUP_CONCURRENCY,
},
serverFileSizeLimit: defaultSizeLimit,
avatarSizeLimit: mbToBytes(2),
@@ -652,6 +655,7 @@ export const endpointFileConfigSchema = z.object({
const skillFileConfigSchema = z.object({
fileSizeLimit: z.number().min(0).optional(),
importCleanupConcurrency: z.number().int().positive().optional(),
+ deletionCleanupConcurrency: z.number().int().positive().optional(),
});
export const fileConfigSchema = z.object({
@@ -1305,6 +1309,13 @@ function buildMergedFileConfig(dynamic: DynamicFileConfig | undefined): FileConf
};
}
+ if (dynamic.skills?.deletionCleanupConcurrency !== undefined) {
+ mergedConfig.skills = {
+ ...mergedConfig.skills,
+ deletionCleanupConcurrency: dynamic.skills.deletionCleanupConcurrency,
+ };
+ }
+
if (dynamic.skills?.fileSizeLimit !== undefined) {
mergedConfig.skills = {
...mergedConfig.skills,
diff --git a/packages/data-provider/src/types/files.ts b/packages/data-provider/src/types/files.ts
index 50c6e4dbe9..39650f3fa5 100644
--- a/packages/data-provider/src/types/files.ts
+++ b/packages/data-provider/src/types/files.ts
@@ -64,6 +64,8 @@ export type FileConfig = {
skills?: {
/** Maximum concurrent blob deletions during failed archive import cleanup. */
importCleanupConcurrency?: number;
+ /** Maximum concurrent blob deletions during whole-Skill cleanup. */
+ deletionCleanupConcurrency?: number;
fileSizeLimit?: number;
};
fileTokenLimit?: number;
@@ -105,6 +107,8 @@ export type FileConfigInput = {
skills?: {
/** Maximum concurrent blob deletions during failed archive import cleanup. */
importCleanupConcurrency?: number;
+ /** Maximum concurrent blob deletions during whole-Skill cleanup. */
+ deletionCleanupConcurrency?: number;
fileSizeLimit?: number;
};
serverFileSizeLimit?: number;
diff --git a/packages/data-provider/src/types/skills.ts b/packages/data-provider/src/types/skills.ts
index 8f1e732ebd..1923bb9f1a 100644
--- a/packages/data-provider/src/types/skills.ts
+++ b/packages/data-provider/src/types/skills.ts
@@ -399,7 +399,7 @@ export type TSkillImportFailedResponse = {
export type TDeleteSkillResponse = {
id: string;
deleted: true;
- /** False when the Skill row is gone but a dependent cleanup step needs repair. */
+ /** False while provider cleanup or final removal is still pending. */
cleanupComplete: boolean;
};
diff --git a/packages/data-schemas/src/app/service.spec.ts b/packages/data-schemas/src/app/service.spec.ts
index 92d59a5aa7..e052e5065b 100644
--- a/packages/data-schemas/src/app/service.spec.ts
+++ b/packages/data-schemas/src/app/service.spec.ts
@@ -221,6 +221,31 @@ describe('loadFiltersConfig', () => {
});
describe('AppService assistants config', () => {
+ it('exposes default Skill deletion worker settings when the block is omitted', async () => {
+ const result = await AppService({ config: {} });
+ expect(result.skillDeletion).toEqual({
+ finalizationEnabled: false,
+ sweepIntervalMs: 60_000,
+ claimLeaseMs: 120_000,
+ batchSize: 100,
+ recheckIntervalMs: 3_600_000,
+ });
+ });
+
+ it('fills omitted Skill deletion settings around an explicit override', async () => {
+ const config = {
+ skillDeletion: { claimLeaseMs: 180_000 },
+ } as unknown as DeepPartial<TCustomConfig>;
+ const result = await AppService({ config });
+ expect(result.skillDeletion).toEqual({
+ finalizationEnabled: false,
+ sweepIntervalMs: 60_000,
+ claimLeaseMs: 180_000,
+ batchSize: 100,
+ recheckIntervalMs: 3_600_000,
+ });
+ });
+
it('preserves configured Assistants API versions', async () => {
const config = {
endpoints: {
diff --git a/packages/data-schemas/src/app/service.ts b/packages/data-schemas/src/app/service.ts
index d34a6e8063..85e11a3467 100644
--- a/packages/data-schemas/src/app/service.ts
+++ b/packages/data-schemas/src/app/service.ts
@@ -2,6 +2,7 @@ import {
AgentCapabilities,
EModelEndpoint,
chatProjectsConfigSchema,
+ configSchema,
filtersConfigSchema,
conversationListConfigSchema,
toolCallPreviewsConfigSchema,
@@ -167,6 +168,7 @@ export const AppService = async (params?: {
const memory = loadMemoryConfig(config.memory);
const summarization = loadSummarizationConfig(config);
const skillSync = loadSkillSyncConfig(config);
+ const skillDeletion = configSchema.shape.skillDeletion.parse(config.skillDeletion);
const filteredTools = config.filteredTools;
const includedTools = config.includedTools;
const fileStrategy = (config.fileStrategy ?? configDefaults.fileStrategy) as
@@ -210,6 +212,7 @@ export const AppService = async (params?: {
actions,
balance,
skillSync,
+ skillDeletion,
webSearch,
githubCompare: config.githubCompare,
mcpSettings,
diff --git a/packages/data-schemas/src/index.ts b/packages/data-schemas/src/index.ts
index 6afad13b80..560d21ebdb 100644
--- a/packages/data-schemas/src/index.ts
+++ b/packages/data-schemas/src/index.ts
@@ -7,6 +7,7 @@ export * from './utils';
export { createModels } from './models';
export {
createMethods,
+ createSkillDeletionPersistenceAdapter,
AGENT_OWNER_CONTACT_RESOLVED_FIELD,
AgentSortCursorError,
CLIENT_MESSAGE_SELECT,
@@ -26,6 +27,7 @@ export {
validateSkillBody,
validateRelativePath,
inferSkillFileCategory,
+ filterExistingSkillIds,
validateSkillFrontmatter,
getCanonicalSkillFrontmatterKey,
normalizeSkillFrontmatterKeys,
diff --git a/packages/data-schemas/src/methods/index.ts b/packages/data-schemas/src/methods/index.ts
index 8be120e86d..0af1e815b2 100644
--- a/packages/data-schemas/src/methods/index.ts
+++ b/packages/data-schemas/src/methods/index.ts
@@ -146,6 +146,7 @@ import {
validateSkillDescription,
deriveStructuredFrontmatterFields,
inferSkillFileCategory,
+ filterExistingSkillIds,
type SkillMethods,
type SkillDeps,
type CreateSkillInput,
@@ -178,6 +179,7 @@ import {
type AgentEventActorReceiptStorageMetrics,
} from './triggerDelivery';
import { createSkillSyncMethods, type SkillSyncMethods } from './skillSync';
+import { createSkillLifecycleMethods, type SkillLifecycleMethods } from './skillLifecycle';
import type {
SkillSyncStatusInput,
SkillSyncCredentialSummary,
@@ -238,12 +240,19 @@ export {
validateSkillDescription,
deriveStructuredFrontmatterFields,
inferSkillFileCategory,
+ filterExistingSkillIds,
};
export { AUDIT_SCHEMA_VERSION, MAX_AUDIT_EXPORT_ROWS, MAX_AUDIT_LOG_LIMIT, MAX_AUDIT_VERIFY_ROWS };
export { MAX_TOOL_FAVORITES };
export { AgentTriggerDeliveryConflictError };
export type { PromptGroupListParams };
export { AGENT_OWNER_CONTACT_RESOLVED_FIELD, AgentSortCursorError } from './agent';
+export { createSkillDeletionPersistenceAdapter } from './skillDeletionAdapter';
+export type {
+ SkillDeletionRecord,
+ SkillUploadIntentRecord,
+ SkillDeletionFileRecord,
+} from './skillDeletionAdapter';
export {
AgentQueuedTurnCapacityError,
AgentQueuedTurnConflictError,
@@ -292,6 +301,7 @@ export type AllMethods = ToolApprovalGrantStorage &
PromptMethods &
SkillMethods &
SkillSyncMethods &
+ SkillLifecycleMethods &
AgentTriggerDeliveryMethods &
AgentQueuedTurnMethods &
ScheduleMCPConsentStorage &
@@ -537,6 +547,7 @@ export function createMethods(
...promptMethods,
...skillMethods,
...createSkillSyncMethods(mongoose),
+ ...createSkillLifecycleMethods(mongoose),
...agentTriggerDeliveryMethods,
...agentQueuedTurnMethods,
...createScheduleMethods(mongoose),
@@ -629,6 +640,7 @@ export type {
SkillSyncCredentialSummary,
UpsertSkillSyncCredentialInput,
SkillSyncMethods,
+ SkillLifecycleMethods,
AgentTriggerDeliveryMethods,
AgentQueuedTurnMethods,
AgentTriggerProducerLeaseStatus,
diff --git a/packages/data-schemas/src/methods/skillDeletionAdapter.spec.ts b/packages/data-schemas/src/methods/skillDeletionAdapter.spec.ts
new file mode 100644
index 0000000000..0e719d42a1
--- /dev/null
+++ b/packages/data-schemas/src/methods/skillDeletionAdapter.spec.ts
@@ -0,0 +1,65 @@
+import { Types } from 'mongoose';
+import { createSkillDeletionPersistenceAdapter } from './skillDeletionAdapter';
+
+it('projects deletion persistence records into plain string-ID API records', async () => {
+ const skillId = new Types.ObjectId();
+ const author = new Types.ObjectId();
+ const source = {
+ beginSkillDeletion: async () => ({ skillId, author, startedAt: new Date() }),
+ getSkillDeletion: async () => ({ skillId, author, startedAt: new Date() }),
+ listSkillDeletionTombstones: async () => [{ skillId, author, startedAt: new Date() }],
+ listSkillUploadIntents: async () => [
+ {
+ skillId,
+ author,
+ fileId: 'file-1',
+ source: 'local',
+ storageKey: '/uploads/file-1',
+ writerId: 'writer',
+ state: 'committed' as const,
+ },
+ ],
+ listAbandonedSkillUploadIntents: async () => [
+ {
+ skillId,
+ author,
+ fileId: 'file-2',
+ source: 'local',
+ storageKey: '/uploads/file-2',
+ writerId: 'writer',
+ state: 'abandoned' as const,
+ },
+ ],
+ listSkillFiles: async () => [
+ {
+ skillId,
+ author,
+ file_id: 'file-1',
+ filepath: '/uploads/file-1',
+ source: 'local',
+ },
+ ],
+ };
+ const adapter = createSkillDeletionPersistenceAdapter(source);
+
+ expect(await adapter.beginSkillDeletion(skillId.toString())).toEqual({
+ skillId: skillId.toString(),
+ completedAt: undefined,
+ });
+ expect((await adapter.listSkillDeletionTombstones(1))[0].skillId).toBe(skillId.toString());
+ expect((await adapter.listSkillUploadIntents(skillId.toString()))[0]).toMatchObject({
+ skillId: skillId.toString(),
+ author: author.toString(),
+ fileId: 'file-1',
+ });
+ expect((await adapter.listAbandonedSkillUploadIntents(1))[0].author).toBe(author.toString());
+ expect((await adapter.listSkillFiles(skillId.toString()))[0]).toEqual({
+ file_id: 'file-1',
+ filepath: '/uploads/file-1',
+ source: 'local',
+ storageKey: undefined,
+ storageRegion: undefined,
+ author: author.toString(),
+ tenantId: undefined,
+ });
+});
diff --git a/packages/data-schemas/src/methods/skillDeletionAdapter.ts b/packages/data-schemas/src/methods/skillDeletionAdapter.ts
new file mode 100644
index 0000000000..913e074026
--- /dev/null
+++ b/packages/data-schemas/src/methods/skillDeletionAdapter.ts
@@ -0,0 +1,150 @@
+import type { ISkillDeletion, ISkillUploadIntent } from '~/types/skillDeletion';
+import type { ISkillFile } from '~/types/skill';
+
+export interface SkillDeletionRecord {
+ skillId: string;
+ completedAt?: Date;
+}
+
+export interface SkillUploadIntentRecord {
+ skillId: string;
+ author: string;
+ fileId: string;
+ source: string;
+ storageKey: string;
+ tenantId?: string;
+ state: 'uploading' | 'committing' | 'committed' | 'abandoned';
+ cleanedAt?: Date;
+}
+
+export interface SkillDeletionFileRecord {
+ file_id: string;
+ filepath: string;
+ source: string;
+ storageKey?: string;
+ storageRegion?: string;
+ author: string;
+ tenantId?: string;
+}
+
+type Source = {
+ beginSkillDeletion: (
+ id: string,
+ ) => Promise<Pick<ISkillDeletion, 'skillId' | 'completedAt'> | null>;
+ getSkillDeletion: (id: string) => Promise<Pick<ISkillDeletion, 'skillId' | 'completedAt'> | null>;
+ listSkillDeletionTombstones: (
+ limit: number,
+ ) => Promise<Array<Pick<ISkillDeletion, 'skillId' | 'completedAt'>>>;
+ listSkillUploadIntents: (
+ id: string,
+ ) => Promise<
+ Array<
+ Pick<
+ ISkillUploadIntent,
+ | 'skillId'
+ | 'author'
+ | 'fileId'
+ | 'source'
+ | 'storageKey'
+ | 'tenantId'
+ | 'state'
+ | 'cleanedAt'
+ >
+ >
+ >;
+ listAbandonedSkillUploadIntents: (
+ limit: number,
+ ) => Promise<
+ Array<
+ Pick<
+ ISkillUploadIntent,
+ | 'skillId'
+ | 'author'
+ | 'fileId'
+ | 'source'
+ | 'storageKey'
+ | 'tenantId'
+ | 'state'
+ | 'cleanedAt'
+ >
+ >
+ >;
+ listSkillFiles: (
+ id: string,
+ ) => Promise<
+ Array<
+ Pick<
+ ISkillFile,
+ 'file_id' | 'filepath' | 'source' | 'storageKey' | 'storageRegion' | 'author' | 'tenantId'
+ >
+ >
+ >;
+};
+
+function journal(row: Pick<ISkillDeletion, 'skillId' | 'completedAt'>): SkillDeletionRecord {
+ return { skillId: row.skillId.toString(), completedAt: row.completedAt };
+}
+
+function intent(
+ row: Pick<
+ ISkillUploadIntent,
+ 'skillId' | 'author' | 'fileId' | 'source' | 'storageKey' | 'tenantId' | 'state' | 'cleanedAt'
+ >,
+): SkillUploadIntentRecord {
+ return {
+ skillId: row.skillId.toString(),
+ author: row.author.toString(),
+ fileId: row.fileId,
+ source: row.source,
+ storageKey: row.storageKey,
+ tenantId: row.tenantId,
+ state: row.state,
+ cleanedAt: row.cleanedAt,
+ };
+}
+
+function file(
+ row: Pick<
+ ISkillFile,
+ 'file_id' | 'filepath' | 'source' | 'storageKey' | 'storageRegion' | 'author' | 'tenantId'
+ >,
+): SkillDeletionFileRecord {
+ return {
+ file_id: row.file_id,
+ filepath: row.filepath,
+ source: row.source,
+ storageKey: row.storageKey,
+ storageRegion: row.storageRegion,
+ author: row.author.toString(),
+ tenantId: row.tenantId,
+ };
+}
+
+/** Project database records once, before they cross into the storage-independent API service. */
+export function createSkillDeletionPersistenceAdapter(source: Source): {
+ beginSkillDeletion: (id: string) => Promise<SkillDeletionRecord | null>;
+ getSkillDeletion: (id: string) => Promise<SkillDeletionRecord | null>;
+ listSkillDeletionTombstones: (limit: number) => Promise<SkillDeletionRecord[]>;
+ listSkillUploadIntents: (id: string) => Promise<SkillUploadIntentRecord[]>;
+ listAbandonedSkillUploadIntents: (limit: number) => Promise<SkillUploadIntentRecord[]>;
+ listSkillFiles: (id: string) => Promise<SkillDeletionFileRecord[]>;
+} {
+ return {
+ beginSkillDeletion: async (id: string): Promise<SkillDeletionRecord | null> => {
+ const row = await source.beginSkillDeletion(id);
+ return row ? journal(row) : null;
+ },
+ getSkillDeletion: async (id: string): Promise<SkillDeletionRecord | null> => {
+ const row = await source.getSkillDeletion(id);
+ return row ? journal(row) : null;
+ },
+ listSkillDeletionTombstones: async (limit: number): Promise<SkillDeletionRecord[]> =>
+ (await source.listSkillDeletionTombstones(limit)).map(journal),
+ listSkillUploadIntents: async (id: string): Promise<SkillUploadIntentRecord[]> =>
+ (await source.listSkillUploadIntents(id)).map(intent),
+ listAbandonedSkillUploadIntents: async (limit: number): Promise<SkillUploadIntentRecord[]> =>
+ (await source.listAbandonedSkillUploadIntents(limit)).map(intent),
+ listSkillFiles: async (id: string): Promise<SkillDeletionFileRecord[]> =>
+ (await source.listSkillFiles(id)).map(file),
+ };
+}
diff --git a/packages/data-schemas/src/methods/skillLifecycle.spec.ts b/packages/data-schemas/src/methods/skillLifecycle.spec.ts
new file mode 100644
index 0000000000..5a4495a469
--- /dev/null
+++ b/packages/data-schemas/src/methods/skillLifecycle.spec.ts
@@ -0,0 +1,745 @@
+import mongoose from 'mongoose';
+import { MongoMemoryServer } from 'mongodb-memory-server';
+import { runAsSystem, tenantStorage } from '~/config/tenantContext';
+import { createSkillLifecycleMethods } from './skillLifecycle';
+import { createModels } from '../models';
+
+jest.mock('~/config/winston', () => ({
+ __esModule: true,
+ default: { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn() },
+}));
+jest.mock('~/config/meiliLogger', () => ({
+ __esModule: true,
+ default: { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn() },
+}));
+
+let mongoServer: MongoMemoryServer;
+let lifecycle: ReturnType<typeof createSkillLifecycleMethods>;
+
+beforeAll(async () => {
+ mongoServer = await MongoMemoryServer.create();
+ await mongoose.connect(mongoServer.getUri());
+ createModels(mongoose);
+ lifecycle = createSkillLifecycleMethods(mongoose);
+});
+
+afterAll(async () => {
+ await mongoose.disconnect();
+ await mongoServer.stop();
+});
+
+beforeEach(async () => {
+ await mongoose.models.Skill.deleteMany({});
+ await mongoose.models.SkillDeletion.deleteMany({});
+ await mongoose.models.SkillUploadIntent.deleteMany({});
+ await mongoose.models.SkillFile.deleteMany({});
+});
+
+async function makeSkill() {
+ const author = new mongoose.Types.ObjectId();
+ const skill = await mongoose.models.Skill.create({
+ name: 'example',
+ description: 'Example skill for lifecycle tests',
+ body: '',
+ author,
+ authorName: 'Example',
+ tenantId: 'tenant-a',
+ });
+ return { skill, author };
+}
+
+async function completeWithClaim(skillId: mongoose.Types.ObjectId) {
+ expect(await lifecycle.claimSkillDeletion(skillId, 'test-worker', 60_000)).toBe(true);
+ expect(await lifecycle.completeSkillDeletion(skillId, 'test-worker')).toBe(true);
+ await lifecycle.releaseSkillDeletionClaim(skillId, 'test-worker');
+}
+
+describe('Skill deletion journal', () => {
+ it('indexes only marked Skills for startup and periodic deletion discovery', () => {
+ expect(mongoose.models.Skill.schema.indexes()).toContainEqual([
+ { deletionNeedsJournal: 1, deletionJournalAttemptAt: 1, deletingAt: 1 },
+ expect.objectContaining({ sparse: true }),
+ ]);
+ });
+
+ it('marks a skill before recording its retryable tombstone', async () => {
+ const { skill } = await makeSkill();
+ const result = await lifecycle.beginSkillDeletion(skill.id);
+ expect(result).toMatchObject({ skillId: skill._id, tenantId: 'tenant-a' });
+ const stored = (await mongoose.models.Skill.findById(skill.id).lean()) as {
+ deletingAt?: Date;
+ } | null;
+ expect(stored?.deletingAt).toBeInstanceOf(Date);
+ expect(await lifecycle.discoverUnjournaledDeletions()).toBe(0);
+ await lifecycle.beginSkillDeletion(skill.id);
+ expect(await mongoose.models.SkillDeletion.countDocuments({ skillId: skill._id })).toBe(1);
+ });
+
+ it('scopes lifecycle journals and upload intents to the active tenant', async () => {
+ const { skill, author } = await makeSkill();
+ await lifecycle.beginSkillDeletion(skill.id);
+ await expect(
+ lifecycle.reserveSkillUploadIntent({
+ skillId: skill.id,
+ fileId: 'tenant-a-intent',
+ source: 'local',
+ storageKey: `/uploads/${author}/tenant-a-intent`,
+ author: author.toString(),
+ tenantId: 'tenant-a',
+ writerId: 'tenant-a-writer',
+ }),
+ ).rejects.toMatchObject({ code: 'SKILL_DELETING' });
+
+ await tenantStorage.run({ tenantId: 'tenant-b' }, async () => {
+ expect(await lifecycle.beginSkillDeletion(skill.id)).toBeNull();
+ expect(await lifecycle.getSkillDeletion(skill.id)).toBeNull();
+ expect(await lifecycle.getSkillUploadIntent('tenant-a-intent')).toBeNull();
+ expect(await lifecycle.listPendingSkillDeletions()).toEqual([]);
+ expect(await lifecycle.listAbandonedSkillUploadIntents()).toEqual([]);
+ expect(
+ await lifecycle.transitionSkillUploadIntent(
+ 'tenant-a-intent',
+ 'tenant-a-writer',
+ 'abandoned',
+ 'committed',
+ ),
+ ).toBe(false);
+ });
+
+ expect(await runAsSystem(() => lifecycle.getSkillDeletion(skill.id))).not.toBeNull();
+ expect(
+ await runAsSystem(() => lifecycle.getSkillUploadIntent('tenant-a-intent')),
+ ).not.toBeNull();
+ });
+
+ it('releases the public name at the deletion mark without dropping the unique index', async () => {
+ const { skill, author } = await makeSkill();
+ await mongoose.models.Skill.init();
+
+ await lifecycle.beginSkillDeletion(skill.id);
+ expect(
+ ((await mongoose.models.Skill.findById(skill.id).lean()) as { name: string } | null)?.name,
+ ).toBe(`__deleted__${skill.id}`);
+ const replacement = await mongoose.models.Skill.create({
+ name: 'example',
+ description: 'Replacement',
+ body: '',
+ author,
+ authorName: 'Example',
+ tenantId: 'tenant-a',
+ });
+ expect(replacement.name).toBe('example');
+ await lifecycle.beginSkillDeletion(skill.id);
+ expect(
+ ((await mongoose.models.Skill.findById(skill.id).lean()) as { name: string } | null)?.name,
+ ).toBe(`__deleted__${skill.id}`);
+ });
+
+ it('repairs a crash between the Skill mark and tombstone insert', async () => {
+ const { skill } = await makeSkill();
+ await mongoose.models.Skill.updateOne(
+ { _id: skill._id },
+ { $set: { deletingAt: new Date(), deletionNeedsJournal: true } },
+ );
+ expect(await mongoose.models.SkillDeletion.countDocuments({})).toBe(0);
+ expect(await lifecycle.discoverUnjournaledDeletions()).toBe(1);
+ expect(await lifecycle.discoverUnjournaledDeletions()).toBe(0);
+ expect(await mongoose.models.SkillDeletion.countDocuments({ skillId: skill._id })).toBe(1);
+ });
+
+ it('bounds discovery and rotates a failed backfill behind other marked Skills', async () => {
+ const first = await makeSkill();
+ const second = await makeSkill();
+ const third = await makeSkill();
+ for (const [index, item] of [first, second, third].entries()) {
+ await mongoose.models.Skill.updateOne(
+ { _id: item.skill._id },
+ {
+ $set: {
+ deletingAt: new Date(Date.now() - (3 - index) * 1_000),
+ deletionNeedsJournal: true,
+ },
+ },
+ );
+ }
+ await mongoose.models.SkillFile.create({
+ skillId: first.skill._id,
+ file_id: 'failed-backfill',
+ relativePath: 'references/failed.md',
+ filename: 'failed.md',
+ filepath: `/uploads/${first.author}/failed-backfill`,
+ source: 'local',
+ mimeType: 'text/markdown',
+ bytes: 4,
+ author: first.author,
+ tenantId: 'tenant-a',
+ });
+ const write = jest
+ .spyOn(mongoose.models.SkillUploadIntent, 'bulkWrite')
+ .mockRejectedValueOnce(new Error('temporary database failure'));
+ try {
+ expect(await lifecycle.discoverUnjournaledDeletions(1)).toBe(0);
+ } finally {
+ write.mockRestore();
+ }
+ expect(await lifecycle.discoverUnjournaledDeletions(1)).toBe(1);
+ expect(await mongoose.models.SkillDeletion.exists({ skillId: second.skill._id })).toBeTruthy();
+ expect(await lifecycle.discoverUnjournaledDeletions(1)).toBe(1);
+ expect(await mongoose.models.SkillDeletion.exists({ skillId: third.skill._id })).toBeTruthy();
+ expect(await lifecycle.discoverUnjournaledDeletions(1)).toBe(1);
+ expect(await mongoose.models.SkillDeletion.exists({ skillId: first.skill._id })).toBeTruthy();
+ expect(await lifecycle.discoverUnjournaledDeletions(1)).toBe(0);
+ });
+
+ it('retries a partially backfilled deletion without rescanning it after success', async () => {
+ const { skill, author } = await makeSkill();
+ await mongoose.models.SkillFile.create({
+ skillId: skill._id,
+ file_id: 'legacy-file',
+ relativePath: 'references/legacy.md',
+ filename: 'legacy.md',
+ filepath: `/uploads/${author}/legacy-file`,
+ source: 'local',
+ mimeType: 'text/markdown',
+ bytes: 4,
+ author,
+ tenantId: 'tenant-a',
+ });
+ const write = jest
+ .spyOn(mongoose.models.SkillUploadIntent, 'bulkWrite')
+ .mockRejectedValueOnce(new Error('database unavailable'));
+ try {
+ await expect(lifecycle.beginSkillDeletion(skill.id)).rejects.toThrow('database unavailable');
+ } finally {
+ write.mockRestore();
+ }
+ expect(await mongoose.models.SkillDeletion.countDocuments({ skillId: skill._id })).toBe(1);
+ expect(await lifecycle.discoverUnjournaledDeletions()).toBe(1);
+ expect(await lifecycle.listSkillUploadIntents(skill._id)).toMatchObject([
+ { fileId: 'legacy-file', state: 'committed' },
+ ]);
+ expect(await lifecycle.discoverUnjournaledDeletions()).toBe(0);
+ });
+
+ it('backfills many legacy file references in bounded batches before clearing the marker', async () => {
+ const { skill, author } = await makeSkill();
+ await mongoose.models.SkillFile.insertMany(
+ Array.from({ length: 205 }, (_, index) => ({
+ skillId: skill._id,
+ file_id: `legacy-file-${index}`,
+ relativePath: `references/${index}.md`,
+ filename: `${index}.md`,
+ filepath: `/uploads/${author}/legacy-file-${index}`,
+ source: 'local',
+ mimeType: 'text/markdown',
+ bytes: 4,
+ author,
+ tenantId: 'tenant-a',
+ })),
+ );
+ const write = jest.spyOn(mongoose.models.SkillUploadIntent, 'bulkWrite');
+ try {
+ await lifecycle.beginSkillDeletion(skill.id);
+ expect(write.mock.calls.map(([operations]) => operations.length)).toEqual([100, 100, 5]);
+ } finally {
+ write.mockRestore();
+ }
+ expect(await mongoose.models.SkillUploadIntent.countDocuments({ skillId: skill._id })).toBe(
+ 205,
+ );
+ expect(
+ await mongoose.models.SkillUploadIntent.countDocuments({
+ skillId: skill._id,
+ tenantId: 'tenant-a',
+ }),
+ ).toBe(205);
+ expect(
+ (
+ (await mongoose.models.Skill.findById(skill.id).lean()) as {
+ deletionNeedsJournal?: boolean;
+ }
+ )?.deletionNeedsJournal,
+ ).toBeUndefined();
+ });
+
+ it('resumes after a later backfill batch fails without losing acknowledged references', async () => {
+ const { skill, author } = await makeSkill();
+ await mongoose.models.SkillFile.insertMany(
+ Array.from({ length: 101 }, (_, index) => ({
+ skillId: skill._id,
+ file_id: `resume-file-${index}`,
+ relativePath: `references/${index}.md`,
+ filename: `${index}.md`,
+ filepath: `/uploads/${author}/resume-file-${index}`,
+ source: 'local',
+ mimeType: 'text/markdown',
+ bytes: 4,
+ author,
+ tenantId: 'tenant-a',
+ })),
+ );
+ const intentModel = mongoose.models.SkillUploadIntent;
+ const originalWrite = intentModel.bulkWrite.bind(intentModel);
+ const write = jest
+ .spyOn(intentModel, 'bulkWrite')
+ .mockImplementationOnce((...args) => originalWrite(...args))
+ .mockRejectedValueOnce(new Error('second batch failed'));
+ try {
+ await expect(lifecycle.beginSkillDeletion(skill.id)).rejects.toThrow('second batch failed');
+ } finally {
+ write.mockRestore();
+ }
+ expect(await intentModel.countDocuments({ skillId: skill._id })).toBe(100);
+ expect(
+ (
+ (await mongoose.models.Skill.findById(skill.id).lean()) as {
+ deletionNeedsJournal?: boolean;
+ }
+ )?.deletionNeedsJournal,
+ ).toBe(true);
+ expect(await lifecycle.discoverUnjournaledDeletions()).toBe(1);
+ expect(await intentModel.countDocuments({ skillId: skill._id })).toBe(101);
+ expect(await lifecycle.discoverUnjournaledDeletions()).toBe(0);
+ });
+
+ it('retains completed tombstones for late file reconciliation', async () => {
+ const { skill } = await makeSkill();
+ await lifecycle.beginSkillDeletion(skill.id);
+ await completeWithClaim(skill._id);
+ expect(await lifecycle.listPendingSkillDeletions()).toHaveLength(0);
+ expect(await lifecycle.listSkillDeletionTombstones()).toHaveLength(1);
+ await lifecycle.reopenSkillDeletion(skill._id);
+ expect(await lifecycle.listPendingSkillDeletions()).toHaveLength(1);
+ });
+
+ it('rediscovers a late upload intent after completion and method reconstruction', async () => {
+ const { skill, author } = await makeSkill();
+ await lifecycle.beginSkillDeletion(skill.id);
+ await completeWithClaim(skill._id);
+ // An upload that passed the initial Skill check before deletion may commit
+ // its intent after an earlier clean sweep. The tombstone must survive it.
+ await mongoose.models.SkillUploadIntent.create({
+ skillId: skill._id,
+ author,
+ tenantId: 'tenant-a',
+ fileId: 'late-file',
+ source: 'local',
+ storageKey: `/uploads/${author}/late-file`,
+ writerId: 'stale-writer',
+ state: 'abandoned',
+ });
+ const restarted = createSkillLifecycleMethods(mongoose);
+ expect(await restarted.listSkillDeletionTombstones()).toHaveLength(1);
+ expect(await restarted.listSkillUploadIntents(skill._id)).toMatchObject([
+ { fileId: 'late-file', state: 'abandoned' },
+ ]);
+ });
+});
+
+describe('Skill upload intents', () => {
+ it('requires an active Skill and fences state changes by the writer id', async () => {
+ const { skill, author } = await makeSkill();
+ await lifecycle.reserveSkillUploadIntent({
+ skillId: skill.id,
+ fileId: 'file-1',
+ source: 'local',
+ storageKey: 'uploads/author/file-1',
+ author: author.toString(),
+ tenantId: 'tenant-a',
+ writerId: 'worker-1',
+ });
+ expect(
+ await lifecycle.transitionSkillUploadIntent('file-1', 'worker-2', 'uploading', 'committing'),
+ ).toBe(false);
+ expect(
+ await lifecycle.transitionSkillUploadIntent('file-1', 'worker-1', 'uploading', 'committing'),
+ ).toBe(true);
+ expect(
+ await lifecycle.transitionSkillUploadIntent('file-1', 'worker-1', 'uploading', 'committing'),
+ ).toBe(true);
+ expect(
+ await lifecycle.transitionSkillUploadIntent('file-1', 'worker-1', 'committing', 'committed'),
+ ).toBe(true);
+ expect(
+ await lifecycle.transitionSkillUploadIntent('file-1', 'worker-1', 'committing', 'committed'),
+ ).toBe(true);
+ await lifecycle.beginSkillDeletion(skill.id);
+ await expect(
+ lifecycle.reserveSkillUploadIntent({
+ skillId: skill.id,
+ fileId: 'file-2',
+ source: 'local',
+ storageKey: 'uploads/author/file-2',
+ author: author.toString(),
+ tenantId: 'tenant-a',
+ writerId: 'worker-1',
+ }),
+ ).rejects.toMatchObject({ code: 'SKILL_DELETING' });
+ expect((await lifecycle.getSkillUploadIntent('file-2'))?.state).toBe('abandoned');
+ });
+
+ it('makes an in-flight reservation visible before deletion marks the Skill', async () => {
+ const { skill, author } = await makeSkill();
+ const model = mongoose.models.Skill;
+ const findOne = jest.spyOn(model, 'findOne').mockImplementationOnce(
+ () =>
+ ({
+ select: () => ({
+ lean: async () => {
+ expect((await lifecycle.getSkillUploadIntent('racing-file'))?.state).toBe(
+ 'uploading',
+ );
+ await lifecycle.beginSkillDeletion(skill.id);
+ return null;
+ },
+ }),
+ }) as never,
+ );
+ try {
+ await expect(
+ lifecycle.reserveSkillUploadIntent({
+ skillId: skill.id,
+ fileId: 'racing-file',
+ source: 'local',
+ storageKey: `/uploads/${author}/racing-file`,
+ author: author.toString(),
+ writerId: 'racing-writer',
+ }),
+ ).rejects.toMatchObject({ code: 'SKILL_DELETING' });
+ expect((await lifecycle.getSkillUploadIntent('racing-file'))?.state).toBe('abandoned');
+ expect(await lifecycle.getSkillDeletion(skill.id)).not.toBeNull();
+ } finally {
+ findOne.mockRestore();
+ }
+ });
+
+ it('abandons a persisted reservation when its insert acknowledgement is lost', async () => {
+ const { skill, author } = await makeSkill();
+ const model = mongoose.models.SkillUploadIntent;
+ const create = model.create.bind(model);
+ const spy = jest.spyOn(model, 'create').mockImplementationOnce(async (input) => {
+ await create(input);
+ throw new Error('insert acknowledgement lost');
+ });
+ try {
+ await expect(
+ lifecycle.reserveSkillUploadIntent({
+ skillId: skill.id,
+ fileId: 'unacknowledged-file',
+ source: 'local',
+ storageKey: `/uploads/${author}/unacknowledged-file`,
+ author: author.toString(),
+ writerId: 'unacknowledged-writer',
+ }),
+ ).rejects.toThrow('insert acknowledgement lost');
+ expect((await lifecycle.getSkillUploadIntent('unacknowledged-file'))?.state).toBe(
+ 'abandoned',
+ );
+ } finally {
+ spy.mockRestore();
+ }
+ });
+
+ it('backfills a pre-existing blob before its Skill row can be finalized', async () => {
+ const { skill, author } = await makeSkill();
+ await mongoose.models.SkillFile.create({
+ skillId: skill._id,
+ file_id: 'legacy-file',
+ relativePath: 'references/legacy.md',
+ filename: 'legacy.md',
+ filepath: `/uploads/${author}/legacy-file`,
+ source: 'local',
+ mimeType: 'text/markdown',
+ bytes: 4,
+ author,
+ tenantId: 'tenant-a',
+ });
+ await lifecycle.beginSkillDeletion(skill.id);
+ const [intent] = await lifecycle.listSkillUploadIntents(skill._id);
+ expect(intent).toMatchObject({
+ fileId: 'legacy-file',
+ source: 'local',
+ storageKey: `/uploads/${author}/legacy-file`,
+ state: 'committed',
+ });
+ await mongoose.models.SkillFile.deleteMany({ skillId: skill._id });
+ expect(await lifecycle.listSkillUploadIntents(skill._id)).toHaveLength(1);
+ await lifecycle.markSkillUploadIntentCleaned('legacy-file');
+ expect((await lifecycle.listSkillUploadIntents(skill._id))[0].cleanedAt).toBeInstanceOf(Date);
+ });
+
+ it('backfills the canonical storage key instead of a public file URL', async () => {
+ const { skill, author } = await makeSkill();
+ await mongoose.models.SkillFile.create({
+ skillId: skill._id,
+ file_id: 'remote-legacy-file',
+ relativePath: 'references/remote.md',
+ filename: 'remote.md',
+ filepath: 'https://cdn.example.test/temporary-signed-url',
+ storageKey: `skills/${author}/remote-legacy-file`,
+ source: 's3',
+ mimeType: 'text/markdown',
+ bytes: 4,
+ author,
+ tenantId: 'tenant-a',
+ });
+
+ await lifecycle.beginSkillDeletion(skill.id);
+ expect(await lifecycle.getSkillUploadIntent('remote-legacy-file')).toMatchObject({
+ storageKey: `skills/${author}/remote-legacy-file`,
+ tenantId: 'tenant-a',
+ });
+ });
+
+ it('queues a committed rolled-back upload for retry and records successful cleanup', async () => {
+ const { skill, author } = await makeSkill();
+ await mongoose.models.SkillUploadIntent.create({
+ skillId: skill._id,
+ fileId: 'rolled-back-file',
+ source: 'local',
+ storageKey: `/uploads/${author}/rolled-back-file`,
+ author,
+ tenantId: 'tenant-a',
+ writerId: 'sync-writer',
+ state: 'committed',
+ });
+ await lifecycle.queueCommittedSkillUploadCleanup('rolled-back-file');
+ expect(
+ (await lifecycle.listAbandonedSkillUploadIntents()).map((intent) => intent.fileId),
+ ).toContain('rolled-back-file');
+ await lifecycle.markSkillUploadIntentCleaned('rolled-back-file');
+ expect((await lifecycle.getSkillUploadIntent('rolled-back-file'))?.cleanedAt).toBeInstanceOf(
+ Date,
+ );
+ });
+
+ it('serializes sweep claims and permits retry after expiry', async () => {
+ const { skill } = await makeSkill();
+ await lifecycle.beginSkillDeletion(skill.id);
+ expect(await lifecycle.claimSkillDeletion(skill._id, 'worker-a', 60_000)).toBe(true);
+ expect(await lifecycle.listSkillDeletionTombstones()).toHaveLength(0);
+ expect(await lifecycle.claimSkillDeletion(skill._id, 'worker-b', 60_000)).toBe(false);
+ await lifecycle.releaseSkillDeletionClaim(skill._id, 'worker-a');
+ expect(await lifecycle.claimSkillDeletion(skill._id, 'worker-b', 60_000)).toBe(true);
+ });
+
+ it('does not complete a deletion after its claim expires or transfers', async () => {
+ const { skill } = await makeSkill();
+ await lifecycle.beginSkillDeletion(skill.id);
+ expect(await lifecycle.claimSkillDeletion(skill._id, 'worker-a', 60_000)).toBe(true);
+ await mongoose.models.SkillDeletion.updateOne(
+ { skillId: skill._id },
+ { $set: { claimExpiresAt: new Date(Date.now() - 1) } },
+ );
+ expect(await lifecycle.completeSkillDeletion(skill._id, 'worker-a')).toBe(false);
+ expect(await lifecycle.claimSkillDeletion(skill._id, 'worker-b', 60_000)).toBe(true);
+ expect(await lifecycle.completeSkillDeletion(skill._id, 'worker-a')).toBe(false);
+ expect((await lifecycle.getSkillDeletion(skill.id))?.completedAt).toBeUndefined();
+ expect(await lifecycle.completeSkillDeletion(skill._id, 'worker-b')).toBe(true);
+ expect((await lifecycle.getSkillDeletion(skill.id))?.completedAt).toBeInstanceOf(Date);
+ });
+
+ it('retains a lease when a refresh matches without changing its expiry', async () => {
+ const { skill, author } = await makeSkill();
+ await lifecycle.beginSkillDeletion(skill.id);
+ await mongoose.models.SkillUploadIntent.create({
+ skillId: skill._id,
+ fileId: 'abandoned-refresh',
+ source: 'local',
+ storageKey: `/uploads/${author}/abandoned-refresh`,
+ author,
+ writerId: 'stopped',
+ state: 'abandoned',
+ });
+ const deletionWrite = jest
+ .spyOn(mongoose.models.SkillDeletion, 'updateOne')
+ .mockResolvedValueOnce({
+ acknowledged: true,
+ matchedCount: 1,
+ modifiedCount: 0,
+ upsertedCount: 0,
+ upsertedId: null,
+ });
+ const intentWrite = jest
+ .spyOn(mongoose.models.SkillUploadIntent, 'updateOne')
+ .mockResolvedValueOnce({
+ acknowledged: true,
+ matchedCount: 1,
+ modifiedCount: 0,
+ upsertedCount: 0,
+ upsertedId: null,
+ });
+ try {
+ expect(await lifecycle.refreshSkillDeletionClaim(skill._id, 'worker-a', 60_000)).toBe(true);
+ expect(
+ await lifecycle.refreshAbandonedSkillUploadIntentClaim(
+ 'abandoned-refresh',
+ 'worker-a',
+ 60_000,
+ ),
+ ).toBe(true);
+ } finally {
+ deletionWrite.mockRestore();
+ intentWrite.mockRestore();
+ }
+ });
+
+ it('defers clean tombstones but admits them after the recheck deadline', async () => {
+ const { skill } = await makeSkill();
+ await lifecycle.beginSkillDeletion(skill.id);
+ await completeWithClaim(skill._id);
+ expect(await lifecycle.claimSkillDeletion(skill._id, 'worker-a', 60_000)).toBe(true);
+ expect(await lifecycle.scheduleSkillDeletionRecheck(skill._id, 'worker-b', 3_600_000)).toBe(
+ false,
+ );
+ expect(await lifecycle.scheduleSkillDeletionRecheck(skill._id, 'worker-a', 3_600_000)).toBe(
+ true,
+ );
+ await lifecycle.releaseSkillDeletionClaim(skill._id, 'worker-a');
+ expect(await lifecycle.listSkillDeletionTombstones()).toHaveLength(0);
+ expect(await lifecycle.claimSkillDeletion(skill._id, 'worker-b', 60_000)).toBe(false);
+ await mongoose.models.SkillDeletion.updateOne(
+ { skillId: skill._id },
+ { $set: { nextCheckAt: new Date(Date.now() - 1) } },
+ );
+ expect(await lifecycle.listSkillDeletionTombstones()).toHaveLength(1);
+ expect(await lifecycle.claimSkillDeletion(skill._id, 'worker-b', 60_000)).toBe(true);
+ await lifecycle.reopenSkillDeletion(skill._id);
+ const reopened = await lifecycle.getSkillDeletion(skill.id);
+ expect(reopened?.completedAt).toBeUndefined();
+ expect(reopened?.nextCheckAt).toBeUndefined();
+ });
+
+ it('recovers a verified-stopped writer without deleting a persisted file', async () => {
+ const { skill, author } = await makeSkill();
+ await lifecycle.reserveSkillUploadIntent({
+ skillId: skill.id,
+ fileId: 'orphan-file',
+ source: 'local',
+ storageKey: `/uploads/${author}/orphan-file`,
+ author: author.toString(),
+ writerId: 'stopped-writer',
+ });
+ expect(await lifecycle.recoverStoppedSkillUploadIntent('orphan-file', 'wrong-writer')).toEqual({
+ status: 'changed',
+ });
+ expect(
+ await lifecycle.recoverStoppedSkillUploadIntent('orphan-file', 'stopped-writer'),
+ ).toEqual({
+ status: 'recovered',
+ state: 'abandoned',
+ });
+ expect((await lifecycle.getSkillUploadIntent('orphan-file'))?.state).toBe('abandoned');
+
+ await lifecycle.reserveSkillUploadIntent({
+ skillId: skill.id,
+ fileId: 'persisted-file',
+ source: 'local',
+ storageKey: `/uploads/${author}/persisted-file`,
+ author: author.toString(),
+ writerId: 'stopped-writer',
+ });
+ await lifecycle.transitionSkillUploadIntent(
+ 'persisted-file',
+ 'stopped-writer',
+ 'uploading',
+ 'committing',
+ );
+ await mongoose.models.SkillFile.create({
+ skillId: skill._id,
+ file_id: 'persisted-file',
+ relativePath: 'references/persisted.md',
+ filename: 'persisted.md',
+ filepath: `/uploads/${author}/persisted-file`,
+ source: 'local',
+ mimeType: 'text/markdown',
+ bytes: 4,
+ author,
+ });
+ expect(
+ await lifecycle.recoverStoppedSkillUploadIntent('persisted-file', 'stopped-writer'),
+ ).toEqual({
+ status: 'recovered',
+ state: 'committed',
+ });
+ expect(await lifecycle.listAbandonedSkillUploadIntents()).toHaveLength(1);
+ expect(await lifecycle.claimAbandonedSkillUploadIntent('orphan-file', 'worker-a', 60_000)).toBe(
+ true,
+ );
+ expect(await lifecycle.listAbandonedSkillUploadIntents()).toHaveLength(0);
+ expect(await lifecycle.claimAbandonedSkillUploadIntent('orphan-file', 'worker-b', 60_000)).toBe(
+ false,
+ );
+ await lifecycle.noteAbandonedSkillUploadIntentAttempt('orphan-file');
+ await lifecycle.releaseAbandonedSkillUploadIntentClaim('orphan-file', 'worker-a');
+ expect(
+ (await lifecycle.getSkillUploadIntent('orphan-file'))?.lastCleanupAttemptAt,
+ ).toBeInstanceOf(Date);
+ });
+
+ it('keeps cleaned abandoned intents as deferred late-upload sentinels', async () => {
+ const { skill, author } = await makeSkill();
+ await lifecycle.reserveSkillUploadIntent({
+ skillId: skill.id,
+ fileId: 'late-blob',
+ source: 'local',
+ storageKey: `/uploads/${author}/late-blob`,
+ author: author.toString(),
+ writerId: 'writer-a',
+ });
+ await lifecycle.transitionSkillUploadIntent('late-blob', 'writer-a', 'uploading', 'abandoned');
+ expect(await lifecycle.claimAbandonedSkillUploadIntent('late-blob', 'worker-a', 60_000)).toBe(
+ true,
+ );
+ await lifecycle.markSkillUploadIntentCleaned('late-blob');
+ expect(
+ await lifecycle.scheduleAbandonedSkillUploadIntentRecheck('late-blob', 'worker-b', 3_600_000),
+ ).toBe(false);
+ expect(
+ await lifecycle.scheduleAbandonedSkillUploadIntentRecheck('late-blob', 'worker-a', 3_600_000),
+ ).toBe(true);
+ await lifecycle.releaseAbandonedSkillUploadIntentClaim('late-blob', 'worker-a');
+ expect(await lifecycle.listAbandonedSkillUploadIntents()).toHaveLength(0);
+ expect(await lifecycle.claimAbandonedSkillUploadIntent('late-blob', 'worker-b', 60_000)).toBe(
+ false,
+ );
+ await mongoose.models.SkillUploadIntent.updateOne(
+ { fileId: 'late-blob' },
+ { $set: { nextCheckAt: new Date(Date.now() - 1) } },
+ );
+ expect(await lifecycle.listAbandonedSkillUploadIntents()).toHaveLength(1);
+ expect(await lifecycle.claimAbandonedSkillUploadIntent('late-blob', 'worker-b', 60_000)).toBe(
+ true,
+ );
+ });
+
+ it('can defer an uncleaned abandoned intent while its Skill tombstone owns cleanup', async () => {
+ const { skill, author } = await makeSkill();
+ await mongoose.models.SkillUploadIntent.create({
+ skillId: skill._id,
+ fileId: 'tombstone-owned',
+ source: 'local',
+ storageKey: `/uploads/${author}/tombstone-owned`,
+ author,
+ writerId: 'stopped',
+ state: 'abandoned',
+ });
+ expect(
+ await lifecycle.claimAbandonedSkillUploadIntent('tombstone-owned', 'worker-a', 60_000),
+ ).toBe(true);
+ expect(
+ await lifecycle.scheduleAbandonedSkillUploadIntentRecheck(
+ 'tombstone-owned',
+ 'worker-a',
+ 3_600_000,
+ ),
+ ).toBe(true);
+ await lifecycle.releaseAbandonedSkillUploadIntentClaim('tombstone-owned', 'worker-a');
+ expect(await lifecycle.listAbandonedSkillUploadIntents()).toHaveLength(0);
+ await mongoose.models.SkillUploadIntent.updateOne(
+ { fileId: 'tombstone-owned' },
+ { $set: { nextCheckAt: new Date(Date.now() - 1) } },
+ );
+ expect(await lifecycle.listAbandonedSkillUploadIntents()).toHaveLength(1);
+ });
+});
diff --git a/packages/data-schemas/src/methods/skillLifecycle.ts b/packages/data-schemas/src/methods/skillLifecycle.ts
new file mode 100644
index 0000000000..803d2cbaf8
--- /dev/null
+++ b/packages/data-schemas/src/methods/skillLifecycle.ts
@@ -0,0 +1,522 @@
+import type { AnyBulkWriteOperation, Model, Types } from 'mongoose';
+import type {
+ ISkillDeletion,
+ ISkillDeletionDocument,
+ ISkillUploadIntent,
+ ISkillUploadIntentDocument,
+} from '~/types/skillDeletion';
+import type { ISkillFileDocument } from '~/types/skill';
+import type { ISkillDocument } from '~/types/skill';
+import { tenantSafeBulkWrite } from '~/utils/tenantBulkWrite';
+import { runAsSystem } from '~/config/tenantContext';
+import logger from '~/config/winston';
+
+type SkillRow = ISkillDocument & { _id: Types.ObjectId };
+const LEGACY_BACKFILL_BATCH_SIZE = 100;
+type IntentInput = {
+ skillId: string;
+ author: string;
+ fileId: string;
+ source: string;
+ storageKey: string;
+ tenantId?: string;
+ writerId: string;
+};
+
+export type StoppedSkillUploadRecovery =
+ | { status: 'missing' | 'changed' }
+ | { status: 'recovered'; state: 'committed' | 'abandoned' };
+
+export interface SkillLifecycleMethods {
+ beginSkillDeletion: (id: string) => Promise<ISkillDeletion | null>;
+ getSkillDeletion: (id: string) => Promise<ISkillDeletion | null>;
+ discoverUnjournaledDeletions: (limit?: number) => Promise<number>;
+ listPendingSkillDeletions: (limit?: number) => Promise<ISkillDeletion[]>;
+ listSkillDeletionTombstones: (limit?: number) => Promise<ISkillDeletion[]>;
+ noteSkillDeletionAttempt: (skillId: string | Types.ObjectId) => Promise<void>;
+ claimSkillDeletion: (
+ skillId: string | Types.ObjectId,
+ owner: string,
+ leaseMs: number,
+ ) => Promise<boolean>;
+ refreshSkillDeletionClaim: (
+ skillId: string | Types.ObjectId,
+ owner: string,
+ leaseMs: number,
+ ) => Promise<boolean>;
+ releaseSkillDeletionClaim: (skillId: string | Types.ObjectId, owner: string) => Promise<void>;
+ completeSkillDeletion: (skillId: string | Types.ObjectId, owner: string) => Promise<boolean>;
+ reopenSkillDeletion: (skillId: string | Types.ObjectId) => Promise<void>;
+ scheduleSkillDeletionRecheck: (
+ skillId: string | Types.ObjectId,
+ owner: string,
+ delayMs: number,
+ ) => Promise<boolean>;
+ reserveSkillUploadIntent: (input: IntentInput) => Promise<ISkillUploadIntent>;
+ transitionSkillUploadIntent: (
+ fileId: string,
+ writerId: string,
+ from: ISkillUploadIntent['state'],
+ to: ISkillUploadIntent['state'],
+ ) => Promise<boolean>;
+ listSkillUploadIntents: (skillId: string | Types.ObjectId) => Promise<ISkillUploadIntent[]>;
+ getSkillUploadIntent: (fileId: string) => Promise<ISkillUploadIntent | null>;
+ recoverStoppedSkillUploadIntent: (
+ fileId: string,
+ expectedWriterId: string,
+ ) => Promise<StoppedSkillUploadRecovery>;
+ listAbandonedSkillUploadIntents: (limit?: number) => Promise<ISkillUploadIntent[]>;
+ claimAbandonedSkillUploadIntent: (
+ fileId: string,
+ owner: string,
+ leaseMs: number,
+ ) => Promise<boolean>;
+ refreshAbandonedSkillUploadIntentClaim: (
+ fileId: string,
+ owner: string,
+ leaseMs: number,
+ ) => Promise<boolean>;
+ noteAbandonedSkillUploadIntentAttempt: (fileId: string) => Promise<void>;
+ releaseAbandonedSkillUploadIntentClaim: (fileId: string, owner: string) => Promise<void>;
+ skillFileExistsForIntent: (skillId: string, fileId: string) => Promise<boolean>;
+ markSkillUploadIntentCleaned: (fileId: string) => Promise<void>;
+ queueCommittedSkillUploadCleanup: (fileId: string) => Promise<void>;
+ scheduleAbandonedSkillUploadIntentRecheck: (
+ fileId: string,
+ owner: string,
+ delayMs: number,
+ ) => Promise<boolean>;
+}
+
+/** Durable bookkeeping only. Provider effects are owned by the API-layer cleanup worker. */
+export function createSkillLifecycleMethods(
+ mongoose: typeof import('mongoose'),
+): SkillLifecycleMethods {
+ // createMethods may be constructed before createModels (for example in
+ // server bootstrap and tests). Resolve models at call time, not here.
+ const skillModel = () => mongoose.models.Skill as Model<ISkillDocument>;
+ const skillFileModel = () => mongoose.models.SkillFile as Model<ISkillFileDocument>;
+ const deletionModel = () => mongoose.models.SkillDeletion as Model<ISkillDeletionDocument>;
+ const intentModel = () => mongoose.models.SkillUploadIntent as Model<ISkillUploadIntentDocument>;
+
+ async function beginSkillDeletion(id: string): Promise<ISkillDeletion | null> {
+ const skillId = new mongoose.Types.ObjectId(id);
+ const skill = (await skillModel()
+ .findOneAndUpdate(
+ { _id: skillId, deletingAt: { $exists: false } },
+ // The reserved name cannot be created through Skill validation. Moving
+ // it in the same write as the deletion mark releases the public name
+ // under the existing unique index, without an index migration.
+ { $set: { name: `__deleted__${id}`, deletingAt: new Date(), deletionNeedsJournal: true } },
+ { new: true },
+ )
+ .lean()) as SkillRow | null;
+ const existing = skill ?? ((await skillModel().findById(skillId).lean()) as SkillRow | null);
+ if (!existing?.deletingAt) return null;
+ // The parent was resolved under the caller's tenant scope above. Preserve
+ // its tenant on the journal even when a legacy caller has no ALS context.
+ const journal = (await runAsSystem(async () =>
+ deletionModel()
+ .findOneAndUpdate(
+ { skillId },
+ {
+ $setOnInsert: {
+ skillId,
+ author: existing.author,
+ tenantId: existing.tenantId,
+ startedAt: existing.deletingAt,
+ },
+ },
+ { upsert: true, new: true },
+ )
+ .lean(),
+ )) as ISkillDeletion;
+ if (existing.deletionNeedsJournal) {
+ // The marker also covers crashes after the journal insert but before
+ // every legacy file has a durable blob reference.
+ let writes: AnyBulkWriteOperation[] = [];
+ for await (const file of skillFileModel().find({ skillId }).cursor()) {
+ writes.push({
+ updateOne: {
+ filter: {
+ fileId: file.file_id,
+ ...(file.tenantId ? { tenantId: file.tenantId } : {}),
+ },
+ update: {
+ $setOnInsert: {
+ skillId,
+ fileId: file.file_id,
+ source: file.source,
+ storageKey: file.storageKey ?? file.filepath,
+ author: file.author,
+ writerId: 'legacy-backfill',
+ state: 'committed',
+ },
+ },
+ upsert: true,
+ },
+ });
+ if (writes.length === LEGACY_BACKFILL_BATCH_SIZE) {
+ await tenantSafeBulkWrite(intentModel(), writes, { ordered: false });
+ writes = [];
+ }
+ }
+ if (writes.length > 0) {
+ await tenantSafeBulkWrite(intentModel(), writes, { ordered: false });
+ }
+ await skillModel().updateOne(
+ { _id: skillId, deletionNeedsJournal: true },
+ { $unset: { deletionNeedsJournal: '' } },
+ );
+ }
+ return journal;
+ }
+
+ async function getSkillDeletion(id: string): Promise<ISkillDeletion | null> {
+ return (await deletionModel()
+ .findOne({ skillId: new mongoose.Types.ObjectId(id) })
+ .lean()) as ISkillDeletion | null;
+ }
+
+ /** Repairs the mark/outbox crash gap without requiring a MongoDB transaction. */
+ async function discoverUnjournaledDeletions(limit = 100): Promise<number> {
+ let count = 0;
+ const pending = await skillModel()
+ .find({ deletionNeedsJournal: true })
+ .sort({ deletionJournalAttemptAt: 1, deletingAt: 1 })
+ .limit(limit)
+ .select('_id')
+ .lean();
+ for (const skill of pending) {
+ await skillModel().updateOne(
+ { _id: skill._id, deletionNeedsJournal: true },
+ { $set: { deletionJournalAttemptAt: new Date() } },
+ );
+ try {
+ await beginSkillDeletion(skill._id.toString());
+ count++;
+ } catch {
+ // Keep the marker and rotate this Skill behind other pending backfills.
+ logger.warn(`[skill deletion] Journal backfill deferred for ${skill._id}`);
+ }
+ }
+ return count;
+ }
+
+ async function listPendingSkillDeletions(limit = 100): Promise<ISkillDeletion[]> {
+ return (await deletionModel()
+ .find({ completedAt: { $exists: false } })
+ .sort({ updatedAt: 1 })
+ .limit(limit)
+ .lean()) as ISkillDeletion[];
+ }
+
+ async function listSkillDeletionTombstones(limit = 100): Promise<ISkillDeletion[]> {
+ const now = new Date();
+ return (await deletionModel()
+ .find({
+ $and: [
+ { $or: [{ claimExpiresAt: { $exists: false } }, { claimExpiresAt: { $lte: now } }] },
+ {
+ $or: [
+ { completedAt: { $exists: false } },
+ { nextCheckAt: { $exists: false } },
+ { nextCheckAt: { $lte: now } },
+ ],
+ },
+ ],
+ })
+ .sort({ lastAttemptAt: 1, startedAt: 1 })
+ .limit(limit)
+ .lean()) as ISkillDeletion[];
+ }
+
+ async function noteSkillDeletionAttempt(skillId: string | Types.ObjectId): Promise<void> {
+ await deletionModel().updateOne({ skillId }, { $set: { lastAttemptAt: new Date() } });
+ }
+
+ async function claimSkillDeletion(
+ skillId: string | Types.ObjectId,
+ owner: string,
+ leaseMs: number,
+ ): Promise<boolean> {
+ const now = new Date();
+ const result = await deletionModel().updateOne(
+ {
+ skillId,
+ $and: [
+ {
+ $or: [
+ { claimExpiresAt: { $exists: false } },
+ { claimExpiresAt: { $lte: now } },
+ { claimOwner: owner },
+ ],
+ },
+ {
+ $or: [
+ { completedAt: { $exists: false } },
+ { nextCheckAt: { $exists: false } },
+ { nextCheckAt: { $lte: now } },
+ ],
+ },
+ ],
+ },
+ { $set: { claimOwner: owner, claimExpiresAt: new Date(now.getTime() + leaseMs) } },
+ );
+ return result.matchedCount === 1;
+ }
+
+ async function refreshSkillDeletionClaim(
+ skillId: string | Types.ObjectId,
+ owner: string,
+ leaseMs: number,
+ ): Promise<boolean> {
+ const result = await deletionModel().updateOne(
+ { skillId, claimOwner: owner, claimExpiresAt: { $gt: new Date() } },
+ { $set: { claimExpiresAt: new Date(Date.now() + leaseMs) } },
+ );
+ return result.matchedCount === 1;
+ }
+
+ async function releaseSkillDeletionClaim(
+ skillId: string | Types.ObjectId,
+ owner: string,
+ ): Promise<void> {
+ await deletionModel().updateOne(
+ { skillId, claimOwner: owner },
+ { $unset: { claimOwner: '', claimExpiresAt: '' } },
+ );
+ }
+
+ async function completeSkillDeletion(
+ skillId: string | Types.ObjectId,
+ owner: string,
+ ): Promise<boolean> {
+ const result = await deletionModel().updateOne(
+ { skillId, claimOwner: owner, claimExpiresAt: { $gt: new Date() } },
+ { $set: { completedAt: new Date() } },
+ );
+ return result.matchedCount === 1;
+ }
+
+ async function reopenSkillDeletion(skillId: string | Types.ObjectId): Promise<void> {
+ await deletionModel().updateOne({ skillId }, { $unset: { completedAt: '', nextCheckAt: '' } });
+ }
+
+ async function scheduleSkillDeletionRecheck(
+ skillId: string | Types.ObjectId,
+ owner: string,
+ delayMs: number,
+ ): Promise<boolean> {
+ const now = new Date();
+ const result = await deletionModel().updateOne(
+ { skillId, claimOwner: owner, claimExpiresAt: { $gt: now }, completedAt: { $exists: true } },
+ { $set: { nextCheckAt: new Date(now.getTime() + delayMs) } },
+ );
+ return result.modifiedCount === 1;
+ }
+
+ async function reserveSkillUploadIntent(input: IntentInput): Promise<ISkillUploadIntent> {
+ // Publish the future blob reference before checking the parent. Deletion
+ // marks the parent first, then scans intents: it must either see this row
+ // or make the check below fail before any bytes are written.
+ try {
+ const intent = (await intentModel().create({ ...input, state: 'uploading' })).toObject();
+ const skill = await skillModel()
+ .findOne({ _id: input.skillId, deletingAt: { $exists: false } })
+ .select('_id')
+ .lean();
+ if (!skill) {
+ throw Object.assign(new Error('Skill is being deleted'), { code: 'SKILL_DELETING' });
+ }
+ return intent;
+ } catch (error) {
+ await intentModel().updateOne(
+ { fileId: input.fileId, writerId: input.writerId, state: 'uploading' },
+ { $set: { state: 'abandoned' } },
+ );
+ throw error;
+ }
+ }
+
+ async function transitionSkillUploadIntent(
+ fileId: string,
+ writerId: string,
+ from: ISkillUploadIntent['state'],
+ to: ISkillUploadIntent['state'],
+ ): Promise<boolean> {
+ const result = await intentModel().updateOne(
+ { fileId, writerId, state: from },
+ { $set: { state: to } },
+ );
+ if (result.modifiedCount === 1) return true;
+ return Boolean(await intentModel().exists({ fileId, writerId, state: to }));
+ }
+
+ async function listSkillUploadIntents(
+ skillId: string | Types.ObjectId,
+ ): Promise<ISkillUploadIntent[]> {
+ return (await intentModel().find({ skillId }).lean()) as ISkillUploadIntent[];
+ }
+
+ async function getSkillUploadIntent(fileId: string): Promise<ISkillUploadIntent | null> {
+ return (await intentModel().findOne({ fileId }).lean()) as ISkillUploadIntent | null;
+ }
+
+ /** Operator-only recovery: call only after independently confirming the writer has stopped. */
+ async function recoverStoppedSkillUploadIntent(
+ fileId: string,
+ expectedWriterId: string,
+ ): Promise<StoppedSkillUploadRecovery> {
+ const intent = await getSkillUploadIntent(fileId);
+ if (!intent) return { status: 'missing' };
+ if (
+ intent.writerId !== expectedWriterId ||
+ (intent.state !== 'uploading' && intent.state !== 'committing')
+ ) {
+ return { status: 'changed' };
+ }
+ const rowExists = await skillFileExistsForIntent(intent.skillId.toString(), fileId);
+ const state = rowExists ? 'committed' : 'abandoned';
+ const result = await intentModel().updateOne(
+ { fileId, writerId: expectedWriterId, state: intent.state },
+ { $set: { state } },
+ );
+ return result.modifiedCount === 1 ? { status: 'recovered', state } : { status: 'changed' };
+ }
+
+ async function listAbandonedSkillUploadIntents(limit = 100): Promise<ISkillUploadIntent[]> {
+ const now = new Date();
+ return (await intentModel()
+ .find({
+ state: 'abandoned',
+ $and: [
+ { $or: [{ claimExpiresAt: { $exists: false } }, { claimExpiresAt: { $lte: now } }] },
+ { $or: [{ nextCheckAt: { $exists: false } }, { nextCheckAt: { $lte: now } }] },
+ ],
+ })
+ .sort({ lastCleanupAttemptAt: 1, createdAt: 1 })
+ .limit(limit)
+ .lean()) as ISkillUploadIntent[];
+ }
+
+ async function claimAbandonedSkillUploadIntent(
+ fileId: string,
+ owner: string,
+ leaseMs: number,
+ ): Promise<boolean> {
+ const now = new Date();
+ const result = await intentModel().updateOne(
+ {
+ fileId,
+ state: 'abandoned',
+ $and: [
+ {
+ $or: [
+ { claimExpiresAt: { $exists: false } },
+ { claimExpiresAt: { $lte: now } },
+ { claimOwner: owner },
+ ],
+ },
+ { $or: [{ nextCheckAt: { $exists: false } }, { nextCheckAt: { $lte: now } }] },
+ ],
+ },
+ { $set: { claimOwner: owner, claimExpiresAt: new Date(now.getTime() + leaseMs) } },
+ );
+ return result.matchedCount === 1;
+ }
+
+ async function refreshAbandonedSkillUploadIntentClaim(
+ fileId: string,
+ owner: string,
+ leaseMs: number,
+ ): Promise<boolean> {
+ const result = await intentModel().updateOne(
+ { fileId, state: 'abandoned', claimOwner: owner, claimExpiresAt: { $gt: new Date() } },
+ { $set: { claimExpiresAt: new Date(Date.now() + leaseMs) } },
+ );
+ return result.matchedCount === 1;
+ }
+
+ async function noteAbandonedSkillUploadIntentAttempt(fileId: string): Promise<void> {
+ await intentModel().updateOne({ fileId }, { $set: { lastCleanupAttemptAt: new Date() } });
+ }
+
+ async function releaseAbandonedSkillUploadIntentClaim(
+ fileId: string,
+ owner: string,
+ ): Promise<void> {
+ await intentModel().updateOne(
+ { fileId, claimOwner: owner },
+ { $unset: { claimOwner: '', claimExpiresAt: '' } },
+ );
+ }
+
+ async function skillFileExistsForIntent(skillId: string, fileId: string): Promise<boolean> {
+ return Boolean(await skillFileModel().exists({ skillId, file_id: fileId }));
+ }
+
+ async function markSkillUploadIntentCleaned(fileId: string): Promise<void> {
+ await intentModel().updateOne({ fileId }, { $set: { cleanedAt: new Date() } });
+ }
+
+ /** A committed upload rolled back before publication must remain sweepable. */
+ async function queueCommittedSkillUploadCleanup(fileId: string): Promise<void> {
+ const result = await intentModel().updateOne(
+ { fileId, state: 'committed', cleanedAt: { $exists: false } },
+ { $set: { state: 'abandoned' }, $unset: { nextCheckAt: '' } },
+ );
+ if (result.matchedCount === 1) return;
+ const intent = await intentModel().findOne({ fileId }).lean();
+ if (intent?.state !== 'abandoned' && !intent?.cleanedAt) {
+ throw new Error(`Skill blob cleanup intent is missing or invalid: ${fileId}`);
+ }
+ }
+
+ async function scheduleAbandonedSkillUploadIntentRecheck(
+ fileId: string,
+ owner: string,
+ delayMs: number,
+ ): Promise<boolean> {
+ const now = new Date();
+ const result = await intentModel().updateOne(
+ {
+ fileId,
+ state: 'abandoned',
+ claimOwner: owner,
+ claimExpiresAt: { $gt: now },
+ },
+ { $set: { nextCheckAt: new Date(now.getTime() + delayMs) } },
+ );
+ return result.modifiedCount === 1;
+ }
+
+ return {
+ beginSkillDeletion,
+ getSkillDeletion,
+ discoverUnjournaledDeletions,
+ listPendingSkillDeletions,
+ listSkillDeletionTombstones,
+ noteSkillDeletionAttempt,
+ claimSkillDeletion,
+ refreshSkillDeletionClaim,
+ releaseSkillDeletionClaim,
+ completeSkillDeletion,
+ reopenSkillDeletion,
+ scheduleSkillDeletionRecheck,
+ reserveSkillUploadIntent,
+ transitionSkillUploadIntent,
+ listSkillUploadIntents,
+ getSkillUploadIntent,
+ recoverStoppedSkillUploadIntent,
+ listAbandonedSkillUploadIntents,
+ claimAbandonedSkillUploadIntent,
+ refreshAbandonedSkillUploadIntentClaim,
+ noteAbandonedSkillUploadIntentAttempt,
+ releaseAbandonedSkillUploadIntentClaim,
+ skillFileExistsForIntent,
+ markSkillUploadIntentCleaned,
+ queueCommittedSkillUploadCleanup,
+ scheduleAbandonedSkillUploadIntentRecheck,
+ };
+}
diff --git a/packages/data-schemas/src/models/index.ts b/packages/data-schemas/src/models/index.ts
index 1d999c870f..7cc7b1eb3b 100644
--- a/packages/data-schemas/src/models/index.ts
+++ b/packages/data-schemas/src/models/index.ts
@@ -8,9 +8,11 @@ import { createAgentTriggerUserPurgeModel } from './triggerUserPurge';
import { createRefreshTokenBridgeModel } from './refreshTokenBridge';
import { createAgentTriggerDeliveryModel } from './triggerDelivery';
import { createToolApprovalGrantModel } from './toolApprovalGrant';
+import { createSkillUploadIntentModel } from './skillUploadIntent';
import { createSkillSyncStatusModel } from './skillSyncStatus';
import { createConversationTagModel } from './conversationTag';
import { createCodeEnvironmentModel } from './codeEnvironment';
+import { createSkillDeletionModel } from './skillDeletion';
import { createAgentCategoryModel } from './agentCategory';
import { createResourceLockModel } from './resourceLock';
import { createChatProjectModel } from './chatProject';
@@ -80,6 +82,8 @@ export function createModels(mongoose: typeof import('mongoose')): {
PromptGroup: ReturnType<typeof createPromptGroupModel>;
Skill: ReturnType<typeof createSkillModel>;
SkillFile: ReturnType<typeof createSkillFileModel>;
+ SkillDeletion: ReturnType<typeof createSkillDeletionModel>;
+ SkillUploadIntent: ReturnType<typeof createSkillUploadIntentModel>;
SkillSyncCredential: ReturnType<typeof createSkillSyncCredentialModel>;
SkillSyncStatus: ReturnType<typeof createSkillSyncStatusModel>;
ConversationTag: ReturnType<typeof createConversationTagModel>;
@@ -132,6 +136,8 @@ export function createModels(mongoose: typeof import('mongoose')): {
PromptGroup: createPromptGroupModel(mongoose),
Skill: createSkillModel(mongoose),
SkillFile: createSkillFileModel(mongoose),
+ SkillDeletion: createSkillDeletionModel(mongoose),
+ SkillUploadIntent: createSkillUploadIntentModel(mongoose),
SkillSyncCredential: createSkillSyncCredentialModel(mongoose),
SkillSyncStatus: createSkillSyncStatusModel(mongoose),
ConversationTag: createConversationTagModel(mongoose),
diff --git a/packages/data-schemas/src/models/skillDeletion.ts b/packages/data-schemas/src/models/skillDeletion.ts
new file mode 100644
index 0000000000..d19bb8ccf4
--- /dev/null
+++ b/packages/data-schemas/src/models/skillDeletion.ts
@@ -0,0 +1,14 @@
+import type { Model } from 'mongoose';
+import type { ISkillDeletionDocument } from '~/types/skillDeletion';
+import { applyTenantIsolation } from '~/models/plugins/tenantIsolation';
+import skillDeletionSchema from '~/schema/skillDeletion';
+
+export function createSkillDeletionModel(
+ mongoose: typeof import('mongoose'),
+): Model<ISkillDeletionDocument> {
+ applyTenantIsolation(skillDeletionSchema);
+ return (
+ mongoose.models.SkillDeletion ||
+ mongoose.model<ISkillDeletionDocument>('SkillDeletion', skillDeletionSchema)
+ );
+}
diff --git a/packages/data-schemas/src/models/skillUploadIntent.ts b/packages/data-schemas/src/models/skillUploadIntent.ts
new file mode 100644
index 0000000000..65c2ab8dab
--- /dev/null
+++ b/packages/data-schemas/src/models/skillUploadIntent.ts
@@ -0,0 +1,14 @@
+import type { Model } from 'mongoose';
+import type { ISkillUploadIntentDocument } from '~/types/skillDeletion';
+import { applyTenantIsolation } from '~/models/plugins/tenantIsolation';
+import skillUploadIntentSchema from '~/schema/skillUploadIntent';
+
+export function createSkillUploadIntentModel(
+ mongoose: typeof import('mongoose'),
+): Model<ISkillUploadIntentDocument> {
+ applyTenantIsolation(skillUploadIntentSchema);
+ return (
+ mongoose.models.SkillUploadIntent ||
+ mongoose.model<ISkillUploadIntentDocument>('SkillUploadIntent', skillUploadIntentSchema)
+ );
+}
diff --git a/packages/data-schemas/src/schema/skill.ts b/packages/data-schemas/src/schema/skill.ts
index 35a1d779c5..7a18f369fe 100644
--- a/packages/data-schemas/src/schema/skill.ts
+++ b/packages/data-schemas/src/schema/skill.ts
@@ -202,6 +202,11 @@ const skillSchema: Schema<ISkillDocument> = new Schema(
default: 0,
min: 0,
},
+ /** Hidden immediately after deletion begins; retained until dependent cleanup completes. */
+ deletingAt: { type: Date, default: undefined },
+ /** Cleared only after the retryable deletion journal and legacy blob references are durable. */
+ deletionNeedsJournal: { type: Boolean, default: undefined },
+ deletionJournalAttemptAt: { type: Date, default: undefined },
/**
* When `true`, the skill's SKILL.md body is auto-primed into every turn
* without user `$` invocation or model discretion. Mirrors the
@@ -227,6 +232,10 @@ const skillSchema: Schema<ISkillDocument> = new Schema(
skillSchema.index({ author: 1, tenantId: 1 });
skillSchema.index({ category: 1, updatedAt: -1 });
skillSchema.index({ updatedAt: -1, _id: 1 });
+skillSchema.index(
+ { deletionNeedsJournal: 1, deletionJournalAttemptAt: 1, deletingAt: 1 },
+ { sparse: true },
+);
skillSchema.index({ name: 1, author: 1, tenantId: 1 }, { unique: true });
skillSchema.index({ source: 1, 'sourceMetadata.upstreamId': 1, tenantId: 1 });
skillSchema.index({ source: 1, 'sourceMetadata.sourceId': 1, tenantId: 1 });
diff --git a/packages/data-schemas/src/schema/skillDeletion.ts b/packages/data-schemas/src/schema/skillDeletion.ts
new file mode 100644
index 0000000000..a7e081f738
--- /dev/null
+++ b/packages/data-schemas/src/schema/skillDeletion.ts
@@ -0,0 +1,23 @@
+import { Schema } from 'mongoose';
+import type { ISkillDeletionDocument } from '~/types/skillDeletion';
+
+const skillDeletionSchema: Schema<ISkillDeletionDocument> = new Schema<ISkillDeletionDocument>(
+ {
+ skillId: { type: Schema.Types.ObjectId, required: true, unique: true, index: true },
+ author: { type: Schema.Types.ObjectId, required: true },
+ tenantId: { type: String, index: true },
+ startedAt: { type: Date, required: true },
+ lastAttemptAt: Date,
+ completedAt: Date,
+ nextCheckAt: Date,
+ claimOwner: String,
+ claimExpiresAt: Date,
+ },
+ { timestamps: true },
+);
+
+// The sweep rotates attempted rows and sorts by these fields before its batch limit.
+skillDeletionSchema.index({ lastAttemptAt: 1, startedAt: 1, claimExpiresAt: 1 });
+skillDeletionSchema.index({ completedAt: 1, nextCheckAt: 1 });
+
+export default skillDeletionSchema;
diff --git a/packages/data-schemas/src/schema/skillUploadIntent.ts b/packages/data-schemas/src/schema/skillUploadIntent.ts
new file mode 100644
index 0000000000..a96e8243ad
--- /dev/null
+++ b/packages/data-schemas/src/schema/skillUploadIntent.ts
@@ -0,0 +1,32 @@
+import { Schema } from 'mongoose';
+import type { ISkillUploadIntentDocument } from '~/types/skillDeletion';
+
+const skillUploadIntentSchema: Schema<ISkillUploadIntentDocument> =
+ new Schema<ISkillUploadIntentDocument>(
+ {
+ skillId: { type: Schema.Types.ObjectId, required: true, index: true },
+ fileId: { type: String, required: true, unique: true, index: true },
+ source: { type: String, required: true },
+ storageKey: { type: String, required: true },
+ author: { type: Schema.Types.ObjectId, required: true },
+ tenantId: { type: String, index: true },
+ writerId: { type: String, required: true },
+ state: {
+ type: String,
+ enum: ['uploading', 'committing', 'committed', 'abandoned'],
+ required: true,
+ },
+ cleanedAt: Date,
+ nextCheckAt: Date,
+ lastCleanupAttemptAt: Date,
+ claimOwner: String,
+ claimExpiresAt: Date,
+ },
+ { timestamps: true },
+ );
+
+skillUploadIntentSchema.index({ skillId: 1, state: 1 });
+skillUploadIntentSchema.index({ state: 1, lastCleanupAttemptAt: 1, createdAt: 1 });
+skillUploadIntentSchema.index({ state: 1, cleanedAt: 1, nextCheckAt: 1 });
+
+export default skillUploadIntentSchema;
diff --git a/packages/data-schemas/src/types/app.ts b/packages/data-schemas/src/types/app.ts
index 4394d1fbe5..fd63f71297 100644
--- a/packages/data-schemas/src/types/app.ts
+++ b/packages/data-schemas/src/types/app.ts
@@ -69,6 +69,13 @@ export interface AppConfig {
/** Web search configuration */
webSearch?: TCustomConfig['webSearch'];
githubCompare?: TCustomConfig['githubCompare'];
+ skillDeletion?: {
+ finalizationEnabled?: boolean;
+ sweepIntervalMs?: number;
+ claimLeaseMs?: number;
+ batchSize?: number;
+ recheckIntervalMs?: number;
+ };
/** Source-scoped content filter configuration */
filters?: FiltersConfig;
/** Message filter configuration (PII and future filter types) */
diff --git a/packages/data-schemas/src/types/index.ts b/packages/data-schemas/src/types/index.ts
index eba6570762..7bad06f82d 100644
--- a/packages/data-schemas/src/types/index.ts
+++ b/packages/data-schemas/src/types/index.ts
@@ -36,6 +36,7 @@ export * from './prompts';
/* Skills */
export * from './skill';
export * from './skillSync';
+export * from './skillDeletion';
export * from './triggerDelivery';
export * from './queuedTurn';
export * from './schedule';
diff --git a/packages/data-schemas/src/types/skill.ts b/packages/data-schemas/src/types/skill.ts
index d3cf701826..e834f116f5 100644
--- a/packages/data-schemas/src/types/skill.ts
+++ b/packages/data-schemas/src/types/skill.ts
@@ -82,6 +82,9 @@ export interface ISkill {
sourceMetadata?: Record<string, unknown>;
/** Denormalized count of associated `SkillFile` rows. Kept in sync by skill methods. */
fileCount: number;
+ deletingAt?: Date;
+ deletionNeedsJournal?: boolean;
+ deletionJournalAttemptAt?: Date;
/**
* When `true`, the skill is auto-primed into every turn — no user `$`
* invocation or model discretion required. Mirrors the `always-apply` YAML
diff --git a/packages/data-schemas/src/types/skillDeletion.ts b/packages/data-schemas/src/types/skillDeletion.ts
new file mode 100644
index 0000000000..7507ccb9ab
--- /dev/null
+++ b/packages/data-schemas/src/types/skillDeletion.ts
@@ -0,0 +1,39 @@
+import type { Document, Types } from 'mongoose';
+
+/** Retained repair record for an explicit or compensating Skill deletion. */
+export interface ISkillDeletion {
+ skillId: Types.ObjectId;
+ author: Types.ObjectId;
+ tenantId?: string;
+ startedAt: Date;
+ lastAttemptAt?: Date;
+ completedAt?: Date;
+ nextCheckAt?: Date;
+ claimOwner?: string;
+ claimExpiresAt?: Date;
+ createdAt?: Date;
+ updatedAt?: Date;
+}
+
+export interface ISkillDeletionDocument extends ISkillDeletion, Document {}
+
+/** A storage key is recorded before uploading bytes, not after the upload succeeds. */
+export interface ISkillUploadIntent {
+ skillId: Types.ObjectId;
+ fileId: string;
+ source: string;
+ storageKey: string;
+ author: Types.ObjectId;
+ tenantId?: string;
+ writerId: string;
+ state: 'uploading' | 'committing' | 'committed' | 'abandoned';
+ cleanedAt?: Date;
+ nextCheckAt?: Date;
+ lastCleanupAttemptAt?: Date;
+ claimOwner?: string;
+ claimExpiresAt?: Date;
+ createdAt?: Date;
+ updatedAt?: Date;
+}
+
+export interface ISkillUploadIntentDocument extends ISkillUploadIntent, Document {}