@exellix/ai-skills 6.5.0 → 6.7.0

package/dist/catalox/skill-template-catalog-mutations.js

@@ -1,19 +1,15 @@
-import { copySkillOptimixerCatalogDataFields, skillOptimixerCatalogSpecToDataFields, } from "./skill-optimixer-catalog.js";
 import { AI_SKILLS_CATALOG_ID, computeSkillRowStatus } from "./ai-skills-catalog.js";
+import { AI_SUB_SKILLS_CATALOG_ID } from "./ai-sub-skills-catalog.js";
+import { buildAiSkillsBaseWriteRecord, buildAiSubSkillsWriteRecord, computeSubSkillOverrides, resolveBaseSkillFromRecord, readIndexedParentSkillKey, } from "./catalog-normalization.js";
+import { getNativeCatalogRecord, replaceNativeCatalogRecord, deleteNativeCatalogRecordByItemId } from "./catalog-native-store.js";
 import { CataloxSkillAlreadyExistsError, CataloxSkillNotFoundError } from "./catalox-skill-errors.js";
-import { catalogItemIdFromSkillKey } from "./skill-templates.js";
+import { defaultSkillOptimixerCatalogSpecForTests } from "./skill-optimixer-catalog.js";
+import { catalogItemIdFromSkillKey, resolveSkillRuntimeFromCatalogs, } from "./skill-templates.js";
 import { extractTemplateTokensFromTexts, extractTokenNamesFromStrings, normalizeForStorage, toPresentationMarkdown, } from "./skill-template-markdown.js";
-/** Stable role ids for template bodies (matches Catalox `*Text` fields). */
 export const SKILL_TEMPLATE_ROLES_ORDER = ["instructions", "prompt", "auditInstructions", "auditPrompt"];
 function isSkillTemplateRole(s) {
     return SKILL_TEMPLATE_ROLES_ORDER.includes(s);
 }
-function appendParentSkillKeyIfPresent(data, payload) {
-    const p = asString(data.parentSkillKey);
-    if (p.length > 0) {
-        payload.parentSkillKey = p;
-    }
-}
 function asSkillCatalogStatus(v) {
     if (v === "draft" || v === "published" || v === "planned")
         return v;
@@ -22,36 +18,27 @@ function asSkillCatalogStatus(v) {
 function asString(v) {
     return typeof v === "string" ? v : "";
 }
-/**
- * Loads skill template bodies from Catalox and returns markdown formatted for editors / presentation.
- * Requires Catalox read access for `appId` + catalog binding.
- */
 export async function getSkillTemplatesForPresentation(catalox, context, skillKey, options = {}) {
+    void catalox;
+    void context;
     const catalogItemId = catalogItemIdFromSkillKey(skillKey);
-    const res = await catalox.getCatalogItem(context, AI_SKILLS_CATALOG_ID, catalogItemId);
-    if (res.outcome === "not_found") {
-        throw new CataloxSkillNotFoundError(skillKey, catalogItemId);
-    }
-    if (res.outcome === "mapping_blocked") {
-        throw new Error(`[AI-SKILLS] Catalox mapping blocked for skill ${catalogItemId}`);
-    }
-    const data = (res.item.data ?? {});
-    const shortKey = asString(data.skillKey) || catalogItemId;
-    const ins = asString(data.instructionsText);
-    const pr = asString(data.promptText);
+    const resolved = await resolveSkillRuntimeFromCatalogs(skillKey);
+    const ins = resolved.instructionsText ?? "";
+    const pr = resolved.promptText ?? "";
     const out = {
-        skillKey: shortKey,
+        skillKey: resolved.subSkillKey ?? resolved.skillKey,
         catalogItemId,
-        status: asSkillCatalogStatus(data.status),
-        title: asString(data.title) || shortKey,
-        description: asString(data.description),
-        isLocal: data.isLocal === true,
+        status: resolved.status,
+        title: resolved.title || catalogItemId,
+        description: resolved.description,
+        isLocal: false,
         instructionsMarkdown: ins ? toPresentationMarkdown(ins) : "",
         promptMarkdown: pr ? toPresentationMarkdown(pr) : "",
+        ...(resolved.parentSkillKey ? { parentSkillKey: resolved.parentSkillKey } : {}),
     };
     if (options.includeAudit === true) {
-        const ains = asString(data.auditInstructionsText);
-        const apr = asString(data.auditPromptText);
+        const ains = resolved.auditInstructionsText ?? "";
+        const apr = resolved.auditPromptText ?? "";
         if (ains)
             out.auditInstructionsMarkdown = toPresentationMarkdown(ains);
         if (apr)
@@ -59,174 +46,173 @@ export async function getSkillTemplatesForPresentation(catalox, context, skillKe
     }
     return out;
 }
-async function loadAiSkillsItemDataOrThrow(catalox, context, skillKey) {
-    const catalogItemId = catalogItemIdFromSkillKey(skillKey);
-    const res = await catalox.getCatalogItem(context, AI_SKILLS_CATALOG_ID, catalogItemId);
-    if (res.outcome === "not_found") {
-        throw new CataloxSkillNotFoundError(skillKey, catalogItemId);
-    }
-    if (res.outcome === "mapping_blocked") {
-        throw new Error(`[AI-SKILLS] Catalox mapping blocked for skill ${catalogItemId}`);
-    }
-    return (res.item.data ?? {});
+async function isSubSkillItem(itemId) {
+    const sub = await getNativeCatalogRecord(AI_SUB_SKILLS_CATALOG_ID, itemId);
+    return sub != null;
+}
+/** Whether a catalog item id resolves to an ai-sub-skills row. */
+export async function isSubSkillCatalogItem(itemId) {
+    return isSubSkillItem(itemId);
+}
+async function writeBaseSkillRecord(input) {
+    const existing = await getNativeCatalogRecord(AI_SKILLS_CATALOG_ID, input.itemId);
+    const record = buildAiSkillsBaseWriteRecord({
+        itemId: input.itemId,
+        catalogId: AI_SKILLS_CATALOG_ID,
+        status: input.status,
+        title: input.title,
+        description: input.description,
+        instructionsText: input.instructionsText,
+        promptText: input.promptText,
+        auditInstructionsText: input.auditInstructionsText,
+        auditPromptText: input.auditPromptText,
+        optimixer: input.optimixer,
+        existing,
+    });
+    await replaceNativeCatalogRecord(AI_SKILLS_CATALOG_ID, record);
+}
+async function writeSubSkillRecord(input) {
+    const existing = await getNativeCatalogRecord(AI_SUB_SKILLS_CATALOG_ID, input.itemId);
+    const record = buildAiSubSkillsWriteRecord({
+        itemId: input.itemId,
+        catalogId: AI_SUB_SKILLS_CATALOG_ID,
+        parentSkillKey: input.parentSkillKey,
+        status: input.status,
+        overrides: input.overrides,
+        existing,
+    });
+    await replaceNativeCatalogRecord(AI_SUB_SKILLS_CATALOG_ID, record);
 }
-/**
- * Template bodies as `{ role, content }[]` (presentation markdown). Always four entries in stable order.
- */
 export async function getSkillContent(catalox, context, skillKey) {
-    const data = await loadAiSkillsItemDataOrThrow(catalox, context, skillKey);
+    void catalox;
+    void context;
+    const resolved = await resolveSkillRuntimeFromCatalogs(skillKey);
     return SKILL_TEMPLATE_ROLES_ORDER.map((role) => {
         const raw = role === "instructions"
-            ? asString(data.instructionsText)
+            ? resolved.instructionsText ?? ""
             : role === "prompt"
-                ? asString(data.promptText)
+                ? resolved.promptText ?? ""
                 : role === "auditInstructions"
-                    ? asString(data.auditInstructionsText)
-                    : asString(data.auditPromptText);
+                    ? resolved.auditInstructionsText ?? ""
+                    : resolved.auditPromptText ?? "";
         return { role, content: raw ? toPresentationMarkdown(raw) : "" };
     });
 }
-/**
- * Unique `{{token}}` names across all template bodies (same presentation strings as {@link getSkillContent}).
- */
 export async function getSkillTokens(catalox, context, skillKey) {
-    const data = await loadAiSkillsItemDataOrThrow(catalox, context, skillKey);
-    const contents = SKILL_TEMPLATE_ROLES_ORDER.map((role) => {
-        const raw = role === "instructions"
-            ? asString(data.instructionsText)
-            : role === "prompt"
-                ? asString(data.promptText)
-                : role === "auditInstructions"
-                    ? asString(data.auditInstructionsText)
-                    : asString(data.auditPromptText);
-        return raw ? toPresentationMarkdown(raw) : "";
-    });
+    void catalox;
+    void context;
+    const resolved = await resolveSkillRuntimeFromCatalogs(skillKey);
+    const contents = [
+        resolved.instructionsText ?? "",
+        resolved.promptText ?? "",
+        resolved.auditInstructionsText ?? "",
+        resolved.auditPromptText ?? "",
+    ].map((raw) => (raw ? toPresentationMarkdown(raw) : ""));
     return extractTokenNamesFromStrings(contents);
 }
-/**
- * Partial template update by role. Returns structured success/failure (including Catalox/not-found errors).
- */
 export async function modifySkillContent(catalox, context, skillKey, parts, options) {
     try {
         if (parts.length === 0) {
-            return {
-                success: false,
-                error: "[AI-SKILLS] modifySkillContent: parts must include at least one role.",
-            };
+            return { success: false, error: "[AI-SKILLS] modifySkillContent: parts must include at least one role." };
         }
         const seen = new Set();
         const patch = {};
         for (const p of parts) {
             if (!isSkillTemplateRole(p.role)) {
-                return {
-                    success: false,
-                    error: `[AI-SKILLS] modifySkillContent: unknown role "${String(p.role)}".`,
-                };
+                return { success: false, error: `[AI-SKILLS] modifySkillContent: unknown role "${String(p.role)}".` };
             }
             if (seen.has(p.role)) {
-                return {
-                    success: false,
-                    error: `[AI-SKILLS] modifySkillContent: duplicate role "${p.role}".`,
-                };
+                return { success: false, error: `[AI-SKILLS] modifySkillContent: duplicate role "${p.role}".` };
             }
             seen.add(p.role);
-            if (p.role === "instructions") {
+            if (p.role === "instructions")
                 patch.instructionsMarkdown = p.content;
-            }
-            else if (p.role === "prompt") {
+            else if (p.role === "prompt")
                 patch.promptMarkdown = p.content;
-            }
-            else if (p.role === "auditInstructions") {
+            else if (p.role === "auditInstructions")
                 patch.auditInstructionsMarkdown = p.content;
-            }
-            else {
+            else
                 patch.auditPromptMarkdown = p.content;
-            }
         }
         await updateSkillTemplatesFromPresentation(catalox, context, skillKey, patch, options);
         return { success: true };
     }
     catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        return { success: false, error: msg };
+        return { success: false, error: e instanceof Error ? e.message : String(e) };
     }
 }
-/**
- * Merges edited markdown into the native catalog item and upserts the full row.
- * Requires Catalox **write** access (e.g. god-mode or app binding with write).
- *
- * @throws CataloxSkillNotFoundError when the item does not exist.
- */
 export async function updateSkillTemplatesFromPresentation(catalox, context, skillKey, patch, options) {
+    void catalox;
+    void context;
     const keys = Object.keys(patch).filter((k) => patch[k] !== undefined);
     if (keys.length === 0) {
         throw new Error("[AI-SKILLS] updateSkillTemplatesFromPresentation: patch must include at least one field.");
     }
     const catalogItemId = catalogItemIdFromSkillKey(skillKey);
-    const res = await catalox.getCatalogItem(context, AI_SKILLS_CATALOG_ID, catalogItemId);
-    if (res.outcome === "not_found") {
-        throw new CataloxSkillNotFoundError(skillKey, catalogItemId);
-    }
-    if (res.outcome === "mapping_blocked") {
-        throw new Error(`[AI-SKILLS] Catalox mapping blocked for skill ${catalogItemId}`);
-    }
-    const data = (res.item.data ?? {});
-    let instructionsText = asString(data.instructionsText);
-    let promptText = asString(data.promptText);
-    let auditInstructionsText = asString(data.auditInstructionsText);
-    let auditPromptText = asString(data.auditPromptText);
-    if (patch.instructionsMarkdown !== undefined) {
+    const resolved = await resolveSkillRuntimeFromCatalogs(skillKey);
+    let instructionsText = resolved.instructionsText ?? "";
+    let promptText = resolved.promptText ?? "";
+    let auditInstructionsText = resolved.auditInstructionsText ?? "";
+    let auditPromptText = resolved.auditPromptText ?? "";
+    if (patch.instructionsMarkdown !== undefined)
         instructionsText = normalizeForStorage(patch.instructionsMarkdown);
-    }
-    if (patch.promptMarkdown !== undefined) {
+    if (patch.promptMarkdown !== undefined)
         promptText = normalizeForStorage(patch.promptMarkdown);
-    }
     if (patch.auditInstructionsMarkdown !== undefined) {
         auditInstructionsText = normalizeForStorage(patch.auditInstructionsMarkdown);
     }
-    if (patch.auditPromptMarkdown !== undefined) {
+    if (patch.auditPromptMarkdown !== undefined)
         auditPromptText = normalizeForStorage(patch.auditPromptMarkdown);
-    }
-    const prevStatus = asSkillCatalogStatus(data.status);
     const catalogReleaseStatus = options?.catalogReleaseStatus !== undefined
         ? options.catalogReleaseStatus
-        : prevStatus === "published"
+        : resolved.status === "published"
             ? "published"
             : undefined;
     const status = computeSkillRowStatus(instructionsText || undefined, promptText || undefined, catalogReleaseStatus);
-    const shortKey = asString(data.skillKey) || catalogItemId;
-    const payload = {
-        skillKey: shortKey,
-        title: asString(data.title) || shortKey,
-        description: asString(data.description),
-        isLocal: data.isLocal === true,
+    if (resolved.parentSkillKey) {
+        const parentRecord = await getNativeCatalogRecord(AI_SKILLS_CATALOG_ID, resolved.parentSkillKey);
+        if (!parentRecord) {
+            throw new CataloxSkillNotFoundError(skillKey, resolved.parentSkillKey);
+        }
+        const parent = resolveBaseSkillFromRecord(parentRecord, `skills/${resolved.parentSkillKey}`);
+        const nextRuntime = {
+            ...parent,
+            skillKey: catalogItemId,
+            subSkillKey: catalogItemId,
+            parentSkillKey: resolved.parentSkillKey,
+            status,
+            instructionsText,
+            promptText,
+            auditInstructionsText,
+            auditPromptText,
+        };
+        const overrides = computeSubSkillOverrides(parent, nextRuntime);
+        await writeSubSkillRecord({
+            itemId: catalogItemId,
+            parentSkillKey: resolved.parentSkillKey,
+            status,
+            overrides,
+        });
+        return;
+    }
+    await writeBaseSkillRecord({
+        itemId: catalogItemId,
         status,
+        title: resolved.title || catalogItemId,
+        description: resolved.description,
         instructionsText,
         promptText,
-    };
-    if (auditInstructionsText.length > 0 || patch.auditInstructionsMarkdown !== undefined) {
-        payload.auditInstructionsText = auditInstructionsText;
-    }
-    if (auditPromptText.length > 0 || patch.auditPromptMarkdown !== undefined) {
-        payload.auditPromptText = auditPromptText;
-    }
-    appendParentSkillKeyIfPresent(data, payload);
-    await catalox.batchUpsertNativeCatalogItems(context, AI_SKILLS_CATALOG_ID, [payload]);
+        auditInstructionsText,
+        auditPromptText,
+        optimixer: resolved.optimixer,
+    });
 }
-/**
- * Creates or updates a full skill catalog row (metadata + optional template markdown).
- * Uses read–merge–write when the item exists; otherwise writes a new row.
- * Requires Catalox **write** access.
- *
- * @throws CataloxSkillAlreadyExistsError when `options.ifNotExists` is true and the item exists.
- */
 export async function upsertSkillCatalogItem(catalox, context, input, options) {
+    void catalox;
+    void context;
     const catalogItemId = catalogItemIdFromSkillKey(input.skillKey);
-    const res = await catalox.getCatalogItem(context, AI_SKILLS_CATALOG_ID, catalogItemId);
-    if (res.outcome === "mapping_blocked") {
-        throw new Error(`[AI-SKILLS] Catalox mapping blocked for skill ${catalogItemId}`);
-    }
-    if (options?.ifNotExists === true && res.outcome === "found") {
+    const existing = await getNativeCatalogRecord(AI_SKILLS_CATALOG_ID, catalogItemId);
+    if (options?.ifNotExists === true && existing) {
         throw new CataloxSkillAlreadyExistsError(input.skillKey, catalogItemId);
     }
     let instructionsText = "";
@@ -234,248 +220,221 @@ export async function upsertSkillCatalogItem(catalox, context, input, options) {
     let auditInstructionsText = "";
     let auditPromptText = "";
     let prevStatus = "planned";
-    if (res.outcome === "found") {
-        const data = (res.item.data ?? {});
-        prevStatus = asSkillCatalogStatus(data.status);
-        instructionsText = asString(data.instructionsText);
-        promptText = asString(data.promptText);
-        auditInstructionsText = asString(data.auditInstructionsText);
-        auditPromptText = asString(data.auditPromptText);
-    }
-    if (input.instructionsMarkdown !== undefined) {
+    let optimixer = input.optimixer ?? defaultSkillOptimixerCatalogSpecForTests();
+    if (existing) {
+        const resolved = resolveBaseSkillFromRecord(existing, input.skillKey);
+        prevStatus = resolved.status;
+        instructionsText = resolved.instructionsText ?? "";
+        promptText = resolved.promptText ?? "";
+        auditInstructionsText = resolved.auditInstructionsText ?? "";
+        auditPromptText = resolved.auditPromptText ?? "";
+        if (input.optimixer === undefined)
+            optimixer = resolved.optimixer;
+    }
+    if (input.instructionsMarkdown !== undefined)
         instructionsText = normalizeForStorage(input.instructionsMarkdown);
-    }
-    if (input.promptMarkdown !== undefined) {
+    if (input.promptMarkdown !== undefined)
         promptText = normalizeForStorage(input.promptMarkdown);
-    }
     if (input.auditInstructionsMarkdown !== undefined) {
         auditInstructionsText = normalizeForStorage(input.auditInstructionsMarkdown);
     }
-    if (input.auditPromptMarkdown !== undefined) {
+    if (input.auditPromptMarkdown !== undefined)
         auditPromptText = normalizeForStorage(input.auditPromptMarkdown);
-    }
-    const shortKey = res.outcome === "found"
-        ? asString((res.item.data ?? {}).skillKey) || catalogItemId
-        : catalogItemId;
     const catalogReleaseStatus = input.catalogReleaseStatus !== undefined
         ? input.catalogReleaseStatus
         : prevStatus === "published"
             ? "published"
             : undefined;
     const status = computeSkillRowStatus(instructionsText || undefined, promptText || undefined, catalogReleaseStatus);
-    const payload = {
-        skillKey: shortKey,
-        title: input.title || shortKey,
-        description: input.description,
-        isLocal: input.isLocal,
+    await writeBaseSkillRecord({
+        itemId: catalogItemId,
         status,
+        title: input.title || catalogItemId,
+        description: input.description,
         instructionsText,
         promptText,
-    };
-    if (auditInstructionsText.length > 0 || input.auditInstructionsMarkdown !== undefined) {
-        payload.auditInstructionsText = auditInstructionsText;
-    }
-    if (auditPromptText.length > 0 || input.auditPromptMarkdown !== undefined) {
-        payload.auditPromptText = auditPromptText;
-    }
-    if (input.optimixer !== undefined) {
-        Object.assign(payload, skillOptimixerCatalogSpecToDataFields(input.optimixer));
-    }
-    else if (res.outcome === "found") {
-        copySkillOptimixerCatalogDataFields((res.item.data ?? {}), payload);
-    }
-    else {
-        throw new Error(`[AI-SKILLS] upsertSkillCatalogItem("${input.skillKey}") requires optimixer on new catalog rows (Optimixer v3 mandatory fields).`);
+        auditInstructionsText,
+        auditPromptText,
+        optimixer,
+    });
+}
+export async function updateSkillMetadata(catalox, context, input) {
+    void catalox;
+    void context;
+    const keys = ["title", "description", "optimixer", "catalogReleaseStatus"];
+    const hasPatch = keys.some((k) => input[k] !== undefined);
+    if (!hasPatch) {
+        throw new Error("[AI-SKILLS] updateSkillMetadata: patch must include at least one field.");
     }
-    if (res.outcome === "found") {
-        appendParentSkillKeyIfPresent((res.item.data ?? {}), payload);
+    const catalogItemId = catalogItemIdFromSkillKey(input.skillKey);
+    const resolved = await resolveSkillRuntimeFromCatalogs(input.skillKey);
+    const title = input.title !== undefined ? input.title : resolved.title || catalogItemId;
+    const description = input.description !== undefined ? input.description : resolved.description;
+    const optimixer = input.optimixer !== undefined ? input.optimixer : resolved.optimixer;
+    const catalogReleaseStatus = input.catalogReleaseStatus !== undefined
+        ? input.catalogReleaseStatus
+        : resolved.status === "published"
+            ? "published"
+            : undefined;
+    const status = computeSkillRowStatus(resolved.instructionsText || undefined, resolved.promptText || undefined, catalogReleaseStatus);
+    if (resolved.parentSkillKey) {
+        const parentRecord = await getNativeCatalogRecord(AI_SKILLS_CATALOG_ID, resolved.parentSkillKey);
+        if (!parentRecord) {
+            throw new CataloxSkillNotFoundError(input.skillKey, resolved.parentSkillKey);
+        }
+        const parent = resolveBaseSkillFromRecord(parentRecord, `skills/${resolved.parentSkillKey}`);
+        const nextRuntime = {
+            ...parent,
+            skillKey: catalogItemId,
+            subSkillKey: catalogItemId,
+            parentSkillKey: resolved.parentSkillKey,
+            status,
+            title,
+            description,
+            instructionsText: resolved.instructionsText,
+            promptText: resolved.promptText,
+            auditInstructionsText: resolved.auditInstructionsText,
+            auditPromptText: resolved.auditPromptText,
+            optimixer,
+        };
+        const overrides = computeSubSkillOverrides(parent, nextRuntime);
+        await writeSubSkillRecord({
+            itemId: catalogItemId,
+            parentSkillKey: resolved.parentSkillKey,
+            status,
+            overrides,
+        });
+        return;
     }
-    await catalox.batchUpsertNativeCatalogItems(context, AI_SKILLS_CATALOG_ID, [payload]);
+    await writeBaseSkillRecord({
+        itemId: catalogItemId,
+        status,
+        title,
+        description,
+        instructionsText: resolved.instructionsText ?? "",
+        promptText: resolved.promptText ?? "",
+        auditInstructionsText: resolved.auditInstructionsText ?? "",
+        auditPromptText: resolved.auditPromptText ?? "",
+        optimixer,
+    });
 }
-/**
- * Soft-deletes a skill: clears template bodies and audit fields and sets status to `planned`.
- * Requires Catalox **write** access.
- *
- * @throws CataloxSkillNotFoundError when the item does not exist.
- */
 export async function softDeleteSkillCatalogItem(catalox, context, skillKey) {
+    void catalox;
+    void context;
     const catalogItemId = catalogItemIdFromSkillKey(skillKey);
-    const res = await catalox.getCatalogItem(context, AI_SKILLS_CATALOG_ID, catalogItemId);
-    if (res.outcome === "not_found") {
+    if (await isSubSkillItem(catalogItemId)) {
+        const sub = await getNativeCatalogRecord(AI_SUB_SKILLS_CATALOG_ID, catalogItemId);
+        if (!sub)
+            throw new CataloxSkillNotFoundError(skillKey, catalogItemId);
+        const parentKey = readIndexedParentSkillKey(sub);
+        await writeSubSkillRecord({
+            itemId: catalogItemId,
+            parentSkillKey: parentKey,
+            status: "planned",
+            overrides: {},
+        });
+        return;
+    }
+    const existing = await getNativeCatalogRecord(AI_SKILLS_CATALOG_ID, catalogItemId);
+    if (!existing)
         throw new CataloxSkillNotFoundError(skillKey, catalogItemId);
-    }
-    if (res.outcome === "mapping_blocked") {
-        throw new Error(`[AI-SKILLS] Catalox mapping blocked for skill ${catalogItemId}`);
-    }
-    const data = (res.item.data ?? {});
-    const shortKey = asString(data.skillKey) || catalogItemId;
-    const title = asString(data.title) || shortKey;
-    const description = asString(data.description);
-    const isLocal = data.isLocal === true;
-    const instructionsText = "";
-    const promptText = "";
-    const status = computeSkillRowStatus(undefined, undefined, undefined);
-    const payload = {
-        skillKey: shortKey,
-        title,
-        description,
-        isLocal,
-        status,
-        instructionsText,
-        promptText,
+    const resolved = resolveBaseSkillFromRecord(existing, skillKey);
+    await writeBaseSkillRecord({
+        itemId: catalogItemId,
+        status: "planned",
+        title: resolved.title,
+        description: resolved.description,
+        instructionsText: "",
+        promptText: "",
         auditInstructionsText: "",
         auditPromptText: "",
-    };
-    appendParentSkillKeyIfPresent(data, payload);
-    await catalox.batchUpsertNativeCatalogItems(context, AI_SKILLS_CATALOG_ID, [payload]);
+        optimixer: resolved.optimixer,
+    });
 }
-/**
- * Duplicates a catalog skill into a new key, marking it with `parentSkillKey`. Structured success/failure.
- */
 export async function createSubSkill(catalox, context, input) {
+    void catalox;
+    void context;
     try {
         const sourceItemId = catalogItemIdFromSkillKey(input.sourceSkillKey);
         const newItemId = catalogItemIdFromSkillKey(input.newSkillKey);
         if (sourceItemId === newItemId) {
-            return {
-                success: false,
-                error: "[AI-SKILLS] createSubSkill: sourceSkillKey and newSkillKey must differ.",
-            };
-        }
-        const srcRes = await catalox.getCatalogItem(context, AI_SKILLS_CATALOG_ID, sourceItemId);
-        if (srcRes.outcome === "not_found") {
-            return {
-                success: false,
-                error: `[AI-SKILLS] createSubSkill: source skill not found (${input.sourceSkillKey}).`,
-            };
+            return { success: false, error: "[AI-SKILLS] createSubSkill: sourceSkillKey and newSkillKey must differ." };
         }
-        if (srcRes.outcome === "mapping_blocked") {
-            return {
-                success: false,
-                error: `[AI-SKILLS] Catalox mapping blocked for skill ${sourceItemId}`,
-            };
+        const parentRecord = await getNativeCatalogRecord(AI_SKILLS_CATALOG_ID, sourceItemId);
+        if (!parentRecord) {
+            return { success: false, error: `[AI-SKILLS] createSubSkill: source skill not found (${input.sourceSkillKey}).` };
         }
-        const tgtRes = await catalox.getCatalogItem(context, AI_SKILLS_CATALOG_ID, newItemId);
-        if (tgtRes.outcome === "mapping_blocked") {
-            return {
-                success: false,
-                error: `[AI-SKILLS] Catalox mapping blocked for skill ${newItemId}`,
-            };
+        const parent = resolveBaseSkillFromRecord(parentRecord, input.sourceSkillKey);
+        const existingSub = await getNativeCatalogRecord(AI_SUB_SKILLS_CATALOG_ID, newItemId);
+        if (existingSub) {
+            return { success: false, error: `[AI-SKILLS] createSubSkill: target skill already exists (${input.newSkillKey}).` };
         }
-        if (tgtRes.outcome === "found") {
-            return {
-                success: false,
-                error: `[AI-SKILLS] createSubSkill: target skill already exists (${input.newSkillKey}).`,
-            };
-        }
-        const sourceData = (srcRes.item.data ?? {});
-        const parentShortKey = asString(sourceData.skillKey) || sourceItemId;
         const ov = input.overrides ?? {};
-        let instructionsText = asString(sourceData.instructionsText);
-        let promptText = asString(sourceData.promptText);
-        let auditInstructionsText = asString(sourceData.auditInstructionsText);
-        let auditPromptText = asString(sourceData.auditPromptText);
-        if (ov.instructionsMarkdown !== undefined) {
-            instructionsText = normalizeForStorage(ov.instructionsMarkdown);
-        }
-        if (ov.promptMarkdown !== undefined) {
-            promptText = normalizeForStorage(ov.promptMarkdown);
-        }
-        if (ov.auditInstructionsMarkdown !== undefined) {
-            auditInstructionsText = normalizeForStorage(ov.auditInstructionsMarkdown);
-        }
-        if (ov.auditPromptMarkdown !== undefined) {
-            auditPromptText = normalizeForStorage(ov.auditPromptMarkdown);
-        }
-        const newShortKey = newItemId;
-        const title = ov.title !== undefined ? ov.title : asString(sourceData.title) || newShortKey;
-        const description = ov.description !== undefined ? ov.description : asString(sourceData.description);
-        const isLocal = ov.isLocal !== undefined ? ov.isLocal : sourceData.isLocal === true;
-        const prevStatus = asSkillCatalogStatus(sourceData.status);
+        const childRuntime = {
+            ...parent,
+            skillKey: newItemId,
+            subSkillKey: newItemId,
+            parentSkillKey: sourceItemId,
+            status: parent.status,
+            title: ov.title !== undefined ? ov.title : parent.title,
+            description: ov.description !== undefined ? ov.description : parent.description,
+            instructionsText: ov.instructionsMarkdown !== undefined
+                ? normalizeForStorage(ov.instructionsMarkdown)
+                : parent.instructionsText,
+            promptText: ov.promptMarkdown !== undefined ? normalizeForStorage(ov.promptMarkdown) : parent.promptText,
+            auditInstructionsText: ov.auditInstructionsMarkdown !== undefined
+                ? normalizeForStorage(ov.auditInstructionsMarkdown)
+                : parent.auditInstructionsText,
+            auditPromptText: ov.auditPromptMarkdown !== undefined
+                ? normalizeForStorage(ov.auditPromptMarkdown)
+                : parent.auditPromptText,
+            optimixer: ov.optimixer ?? parent.optimixer,
+        };
         const catalogReleaseStatus = ov.catalogReleaseStatus !== undefined
             ? ov.catalogReleaseStatus
-            : prevStatus === "published"
+            : parent.status === "published"
                 ? "published"
                 : undefined;
-        const status = computeSkillRowStatus(instructionsText || undefined, promptText || undefined, catalogReleaseStatus);
-        const payload = {
-            skillKey: newShortKey,
-            parentSkillKey: parentShortKey,
-            title: title || newShortKey,
-            description,
-            isLocal,
+        const status = computeSkillRowStatus(childRuntime.instructionsText, childRuntime.promptText, catalogReleaseStatus);
+        childRuntime.status = status;
+        const overrides = computeSubSkillOverrides(parent, childRuntime);
+        await writeSubSkillRecord({
+            itemId: newItemId,
+            parentSkillKey: sourceItemId,
             status,
-            instructionsText,
-            promptText,
-        };
-        if (auditInstructionsText.length > 0 || ov.auditInstructionsMarkdown !== undefined) {
-            payload.auditInstructionsText = auditInstructionsText;
-        }
-        if (auditPromptText.length > 0 || ov.auditPromptMarkdown !== undefined) {
-            payload.auditPromptText = auditPromptText;
-        }
-        copySkillOptimixerCatalogDataFields(sourceData, payload);
-        await catalox.batchUpsertNativeCatalogItems(context, AI_SKILLS_CATALOG_ID, [payload]);
+            overrides,
+        });
         return { success: true };
     }
     catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        return { success: false, error: msg };
+        return { success: false, error: e instanceof Error ? e.message : String(e) };
     }
 }
-/**
- * Deletes a native catalog row only when it is a sub-skill (`parentSkillKey` set).
- */
 export async function deleteSubSkill(catalox, context, subSkillKey) {
+    void catalox;
+    void context;
     try {
         const catalogItemId = catalogItemIdFromSkillKey(subSkillKey);
-        const res = await catalox.getCatalogItem(context, AI_SKILLS_CATALOG_ID, catalogItemId);
-        if (res.outcome === "not_found") {
-            return {
-                success: false,
-                error: `[AI-SKILLS] deleteSubSkill: skill not found (${subSkillKey}).`,
-            };
+        const sub = await getNativeCatalogRecord(AI_SUB_SKILLS_CATALOG_ID, catalogItemId);
+        if (!sub) {
+            return { success: false, error: `[AI-SKILLS] deleteSubSkill: skill not found (${subSkillKey}).` };
         }
-        if (res.outcome === "mapping_blocked") {
-            return {
-                success: false,
-                error: `[AI-SKILLS] Catalox mapping blocked for skill ${catalogItemId}`,
-            };
-        }
-        const data = (res.item.data ?? {});
-        const parent = asString(data.parentSkillKey);
-        if (parent.length === 0) {
-            return {
-                success: false,
-                error: "[AI-SKILLS] deleteSubSkill: only sub-skills (rows with parentSkillKey) can be deleted.",
-            };
-        }
-        await catalox.deleteNativeCatalogItem(context, AI_SKILLS_CATALOG_ID, catalogItemId);
+        await deleteNativeCatalogRecordByItemId(AI_SUB_SKILLS_CATALOG_ID, catalogItemId, sub);
         return { success: true };
     }
     catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        return { success: false, error: msg };
+        return { success: false, error: e instanceof Error ? e.message : String(e) };
     }
 }
-/**
- * Returns unique `{{token}}` names from raw Catalox template strings (before presentation transforms).
- */
 export async function getSkillTemplateInputs(catalox, context, skillKey) {
-    const catalogItemId = catalogItemIdFromSkillKey(skillKey);
-    const res = await catalox.getCatalogItem(context, AI_SKILLS_CATALOG_ID, catalogItemId);
-    if (res.outcome === "not_found") {
-        throw new CataloxSkillNotFoundError(skillKey, catalogItemId);
-    }
-    if (res.outcome === "mapping_blocked") {
-        throw new Error(`[AI-SKILLS] Catalox mapping blocked for skill ${catalogItemId}`);
-    }
-    const data = (res.item.data ?? {});
+    void catalox;
+    void context;
+    const resolved = await resolveSkillRuntimeFromCatalogs(skillKey);
     return extractTemplateTokensFromTexts({
-        instructionsText: asString(data.instructionsText) || undefined,
-        promptText: asString(data.promptText) || undefined,
-        auditInstructionsText: asString(data.auditInstructionsText) || undefined,
-        auditPromptText: asString(data.auditPromptText) || undefined,
+        instructionsText: resolved.instructionsText,
+        promptText: resolved.promptText,
+        auditInstructionsText: resolved.auditInstructionsText,
+        auditPromptText: resolved.auditPromptText,
     });
 }
 //# sourceMappingURL=skill-template-catalog-mutations.js.map