@duckcodeailabs/dql-agent 1.6.34 → 1.7.0

package/dist/metadata/catalog.js

@@ -22,6 +22,7 @@ import { retrieveScopedHints } from '../hints/retrieval.js';
 import { buildFtsMatch, sanitizeFtsQuery } from '../memory/fts-query.js';
 import { envEmbeddingProvider } from '../embeddings/provider.js';
 import { matchExampleParaphrase } from './example-match.js';
+import { loadSkills, selectRelevantSkills } from '../skills/loader.js';
 const require = createRequire(import.meta.url);
 let databaseCtor = null;
 function loadDatabase() {
@@ -96,7 +97,8 @@ export async function ensureMetadataCatalogFresh(projectRoot, options = {}) {
         ? options.semanticLayer ?? undefined
         : loadAgentSemanticLayer(projectRoot);
     const manifest = options.manifest ?? loadAgentManifest(projectRoot);
-    const snapshot = buildMetadataSnapshot(projectRoot, manifest, semanticLayer);
+    const skills = options.skills ?? loadSkills(projectRoot).skills;
+    const snapshot = buildMetadataSnapshot(projectRoot, manifest, semanticLayer, skills);
     const catalog = openMetadataCatalog(projectRoot);
     try {
         const existing = catalog.state('fingerprint');
@@ -150,7 +152,18 @@ export function upsertMetadataSnapshot(projectRoot, snapshot) {
     }
 }
 export async function buildLocalContextPack(projectRoot, request) {
-    await ensureMetadataCatalogFresh(projectRoot);
+    let prepared = false;
+    if (request.preparedMetadataFingerprint) {
+        const catalog = openMetadataCatalog(projectRoot);
+        try {
+            prepared = catalog.state('fingerprint') === request.preparedMetadataFingerprint;
+        }
+        finally {
+            catalog.close();
+        }
+    }
+    if (!prepared)
+        await ensureMetadataCatalogFresh(projectRoot);
     const catalog = openMetadataCatalog(projectRoot);
     try {
         const mode = request.mode ?? 'question';
@@ -163,7 +176,7 @@ export async function buildLocalContextPack(projectRoot, request) {
         // candidates only; a SHIFT ignores it. A metadata fingerprint mismatch
         // always disqualifies reuse.
         const reusePolicy = request.reusePolicy ?? 'seed';
-        const priorPack = reusePolicy !== 'off'
+        const priorPack = !request.domainContext && reusePolicy !== 'off'
             && request.priorContextPackId
             && request.conversationTopicRelation
             && request.conversationTopicRelation !== 'shift'
@@ -211,18 +224,24 @@ export async function buildLocalContextPack(projectRoot, request) {
             buildFollowUpSearchQuery(request.question, followUp),
             ...questionPlan.searchQueries,
         ]);
-        const searchRows = mergeObjects(searchQueries.flatMap((query) => catalog.searchObjects({
+        const scopeObjects = (rows) => filterMetadataObjectsByDomainContext(rows, request.domainContext);
+        // Skill guidance is injected only through selectContextPackSkills below.
+        // Leaving it in generic FTS results would bypass status/domain/area/exclusion
+        // eligibility simply because a word in its body matched the question.
+        const retrievalObjects = (rows) => scopeObjects(rows).filter((row) => row.objectType !== 'skill');
+        const searchRows = retrievalObjects(mergeObjects(searchQueries.flatMap((query) => catalog.searchObjects({
             query,
             objectTypes: request.objectTypes,
             limit: Math.max(request.limit ?? 80, 20),
-        })));
+        }))));
         const schemaShapeCandidates = schemaShapeCandidateObjects(catalog, questionPlan, request, mergeObjects([...runtimeObjects, ...runtimeValueObjects]));
         const schemaShapeObjects = schemaShapeCandidates.map((candidate) => candidate.object);
-        const exact = request.focusObjectKey ? catalog.getObject(request.focusObjectKey) : null;
+        const exactCandidate = request.focusObjectKey ? catalog.getObject(request.focusObjectKey) : null;
+        const exact = exactCandidate && retrievalObjects([exactCandidate]).length > 0 ? exactCandidate : null;
         const ranked = rankMetadataObjects({
-            rows: mergeObjects(exact
+            rows: retrievalObjects(mergeObjects(exact
                 ? [exact, ...followUpSourceObjects, ...followUpObjects, ...searchRows, ...schemaShapeObjects, ...runtimeObjects, ...runtimeValueObjects, ...selectedObjects, ...priorSeedObjects]
-                : [...followUpSourceObjects, ...followUpObjects, ...searchRows, ...schemaShapeObjects, ...runtimeObjects, ...runtimeValueObjects, ...selectedObjects, ...priorSeedObjects]),
+                : [...followUpSourceObjects, ...followUpObjects, ...searchRows, ...schemaShapeObjects, ...runtimeObjects, ...runtimeValueObjects, ...selectedObjects, ...priorSeedObjects])),
             question: searchQueries.join(' '),
             questionPlan,
             limit: request.limit ?? 80,
@@ -236,9 +255,9 @@ export async function buildLocalContextPack(projectRoot, request) {
         const focusObjectKey = request.focusObjectKey ?? selected[0]?.objectKey ?? null;
         const edgeWalk = catalog.edgesForKeys(selected.map((row) => row.objectKey), 3);
         const edgeObjectKeys = Array.from(new Set(edgeWalk.flatMap((edge) => [edge.fromKey, edge.toKey])));
-        const graphObjects = catalog.getObjectsByKeys(edgeObjectKeys);
+        const graphObjects = retrievalObjects(catalog.getObjectsByKeys(edgeObjectKeys));
         const rankedObjects = rankMetadataObjects({
-            rows: mergeObjects([...followUpSourceObjects, ...followUpObjects, ...selected, ...graphObjects, ...schemaShapeObjects, ...runtimeObjects, ...runtimeValueObjects, ...selectedObjects]),
+            rows: retrievalObjects(mergeObjects([...followUpSourceObjects, ...followUpObjects, ...selected, ...graphObjects, ...schemaShapeObjects, ...runtimeObjects, ...runtimeValueObjects, ...selectedObjects])),
             question: searchQueries.join(' '),
             questionPlan,
             limit: request.limit ?? 120,
@@ -248,17 +267,23 @@ export async function buildLocalContextPack(projectRoot, request) {
         // entire relation set ("send everything, let the agent decide"). Only when the
         // whole catalog fits comfortably in context — otherwise we keep ranked selection.
         const fullCatalogObjects = request.strictness === 'exploratory'
-            ? collectFullCatalogObjects(catalog)
+            ? retrievalObjects(collectFullCatalogObjects(catalog) ?? [])
             : undefined;
         const usedFullCatalog = Boolean(fullCatalogObjects);
+        // Skills are selected from the catalog snapshot with the same hard domain,
+        // area, status, and exclusion gates as the loader. They are not left to FTS
+        // chance or re-read from disk after the snapshot has been fingerprinted.
+        const selectedSkills = selectContextPackSkills(catalog.listObjects({ objectTypes: ['skill'], limit: 500 }), request.question, request.domainContext);
+        const selectedSkillObjects = selectedSkills.map((item) => item.object);
         const objects = fullCatalogObjects
-            ? mergeObjects([...rankedObjects, ...sqlParentObjects, ...fullCatalogObjects])
-            : mergeObjects([...rankedObjects, ...sqlParentObjects]);
+            ? mergeObjects([...rankedObjects, ...sqlParentObjects, ...fullCatalogObjects, ...selectedSkillObjects])
+            : mergeObjects([...rankedObjects, ...sqlParentObjects, ...selectedSkillObjects]);
         const objectKeys = objects.map((row) => row.objectKey);
+        const allowedObjectKeys = new Set(objectKeys);
         const contextEdges = mergeMetadataEdges([
             ...edgeWalk,
             ...catalog.edgesForKeys(objectKeys, 2),
-        ]);
+        ]).filter((edge) => allowedObjectKeys.has(edge.fromKey) && allowedObjectKeys.has(edge.toKey));
         const queryRuns = catalog.queryRunsForObjectKeys(objectKeys, 20);
         const diagnostics = catalog.diagnostics();
         const warnings = buildWarnings(diagnostics, objects);
@@ -281,7 +306,7 @@ export async function buildLocalContextPack(projectRoot, request) {
         const selectedJoinPaths = buildSelectedJoinPaths(allowedSqlContext, contextEdges);
         const evidenceRoles = buildEvidenceRoles(objects, queryRuns);
         const reranked = rankMetadataObjects({
-            rows: mergeObjects([...searchRows, ...schemaShapeObjects, ...objects]),
+            rows: retrievalObjects(mergeObjects([...searchRows, ...schemaShapeObjects, ...objects])),
             question: searchQueries.join(' '),
             questionPlan,
             limit: request.limit ?? 120,
@@ -323,6 +348,7 @@ export async function buildLocalContextPack(projectRoot, request) {
             trustLabel,
             trustLabelInfo: metadataTrustLabelInfo(trustLabel),
             objects,
+            skills: selectedSkills.map((item) => item.skill),
             edges: contextEdges,
             queryRuns,
             citations,
@@ -416,7 +442,7 @@ export function latestRuntimeSchemaSnapshotForProject(projectRoot) {
         catalog.close();
     }
 }
-export function buildMetadataSnapshot(projectRoot, manifest, semanticLayer) {
+export function buildMetadataSnapshot(projectRoot, manifest, semanticLayer, skills = loadSkills(projectRoot).skills) {
     const manifestGraph = buildKGFromManifest(manifest);
     const semanticGraph = buildKGFromSemanticLayer(semanticLayer);
     const objects = new Map();
@@ -441,11 +467,16 @@ export function buildMetadataSnapshot(projectRoot, manifest, semanticLayer) {
         }
     }
     addManifestBlockDetails(manifest, objects);
+    addSkillObjects(skills, objects, edges);
     addDbtDagObjects(manifest, objects, edges, diagnostics);
     addRawDbtManifestCatalogObjects(projectRoot, manifest, objects, edges, diagnostics);
     addBlockDependencyEdges(manifest, edges);
     addBlockOutputLineageObjects(manifest, objects, edges);
-    addDataLexManifestObjects(projectRoot, manifest, objects, edges, diagnostics);
+    // Manifest v3 is the unified DQL runtime. DataLex is migration input only;
+    // retaining it here would reintroduce a second analytical source of truth.
+    if (manifest.manifestVersion !== 3) {
+        addDataLexManifestObjects(projectRoot, manifest, objects, edges, diagnostics);
+    }
     const nodeKeyMap = new Map();
     for (const node of [...manifestGraph.nodes, ...semanticGraph.nodes]) {
         nodeKeyMap.set(node.nodeId, objectKeyFromKGNode(node));
@@ -1207,6 +1238,7 @@ function objectFromKGNode(node) {
         dimensions: node.dimensions ?? [],
         allowedFilters: node.allowedFilters ?? [],
         parameterPolicy: node.parameterPolicy ?? [],
+        parameters: node.parameters ?? [],
         filterBindings: node.filterBindings ?? [],
         sourceSystems: node.sourceSystems ?? [],
         replacementFor: node.replacementFor ?? [],
@@ -1286,6 +1318,71 @@ function normalizeEdge(edge, fromKey, toKey) {
         payload: { kgSource: edge.src, kgTarget: edge.dst },
     };
 }
+/**
+ * Skills are source-owned context, not a prompt-only side channel. Persist their
+ * parsed fields in the catalog snapshot so selection, provenance, and
+ * fingerprinting all observe the same immutable project state.
+ */
+function addSkillObjects(skills, objects, edges) {
+    for (const skill of skills) {
+        const identity = skill.qualifiedId ?? skill.id;
+        const objectKey = `skill:${identity}`;
+        const domains = uniqueNonBlank([skill.domain, ...(skill.domains ?? [])]);
+        const object = {
+            objectKey,
+            objectType: 'skill',
+            name: skill.id,
+            fullName: skill.qualifiedId ?? skill.id,
+            domain: skill.domain,
+            owner: skill.owner,
+            status: skill.status ?? 'active',
+            description: skill.description ?? compactSkillDescription(skill.body),
+            sourcePath: skill.sourcePath,
+            sourceSystem: 'DQL domain skill',
+            payload: compactObject({
+                skillId: skill.id,
+                localId: skill.localId ?? skill.id,
+                qualifiedId: skill.qualifiedId,
+                scope: skill.scope,
+                user: skill.user,
+                domains,
+                modelAreaRefs: skill.modelAreaRefs ?? [],
+                kind: skill.kind,
+                triggers: skill.triggers ?? [],
+                exclusions: skill.exclusions ?? [],
+                preferredMetrics: skill.preferredMetrics,
+                preferredBlocks: skill.preferredBlocks,
+                preferredDimensions: skill.preferredDimensions ?? [],
+                requiredFilters: skill.requiredFilters ?? [],
+                clarifyWhen: skill.clarifyWhen ?? [],
+                examples: skill.examples ?? [],
+                sourceRefs: skill.sourceRefs ?? [],
+                vocabulary: skill.vocabulary,
+                body: skill.body,
+                isStarter: skill.isStarter,
+                provenance: 'DQL domain skill',
+            }),
+        };
+        objects.set(objectKey, object);
+        for (const domain of domains) {
+            const edge = {
+                edgeType: 'contains',
+                fromKey: `domain:${domain}`,
+                toKey: objectKey,
+                confidence: 1,
+                payload: { provenance: 'DQL domain skill' },
+            };
+            edges.set(`${edge.edgeType}\u0000${edge.fromKey}\u0000${edge.toKey}`, edge);
+        }
+    }
+}
+function compactSkillDescription(body) {
+    const normalized = body.replace(/\s+/g, ' ').trim();
+    return normalized ? normalized.slice(0, 480) : undefined;
+}
+function uniqueNonBlank(values) {
+    return Array.from(new Set(values.map((value) => value?.trim()).filter((value) => Boolean(value))));
+}
 function addDbtDagObjects(manifest, objects, edges, diagnostics) {
     const models = manifest.dbtImport?.dbtDag?.models ?? [];
     for (const model of models) {
@@ -1378,6 +1475,18 @@ function addRawDbtManifestCatalogObjects(projectRoot, manifest, objects, edges,
     const catalogColumns = loadRawDbtCatalogColumns(join(dirname(manifestPath), 'catalog.json'));
     const uniqueColumnsByModel = extractDbtUniqueColumns(raw.nodes ?? {});
     const entries = [];
+    // PERF-001: at enterprise scale, keep columns in their model payload and
+    // load full node detail lazily from the immutable dbt artifact cache. A
+    // separate FTS row + graph edge for every column makes a 300k-column project
+    // consume gigabytes without improving the bounded model-first route.
+    const rawEntries = [...Object.values(raw.nodes ?? {}), ...Object.values(raw.sources ?? {})];
+    const totalColumnCount = rawEntries.reduce((sum, node) => {
+        const columns = node.columns;
+        return sum + (columns && typeof columns === 'object' && !Array.isArray(columns)
+            ? Object.keys(columns).length
+            : 0);
+    }, 0);
+    const includeColumnObjects = totalColumnCount <= 50_000;
     for (const [uniqueId, node] of Object.entries(raw.nodes ?? {})) {
         if (node.resource_type !== 'model')
             continue;
@@ -1403,6 +1512,7 @@ function addRawDbtManifestCatalogObjects(projectRoot, manifest, objects, edges,
             ...entry,
             objects,
             edges,
+            includeColumnObjects,
         });
     }
     for (const [uniqueId, source] of Object.entries(raw.sources ?? {})) {
@@ -1427,6 +1537,7 @@ function addRawDbtManifestCatalogObjects(projectRoot, manifest, objects, edges,
             ...entry,
             objects,
             edges,
+            includeColumnObjects,
         });
     }
     const relationLookup = buildRawDbtRelationLookup(entries);
@@ -1470,36 +1581,37 @@ function addRawDbtCatalogObject(input) {
             uniqueColumns: input.uniqueColumns && input.uniqueColumns.length > 0 ? input.uniqueColumns : undefined,
         }),
     }));
-    for (const column of columns) {
-        const columnKey = `dbt:column:${input.name}.${column.name}`;
-        const existingColumn = input.objects.get(columnKey);
-        input.objects.set(columnKey, mergeObject(existingColumn, {
-            objectKey: columnKey,
-            objectType: 'dbt_column',
-            name: column.name,
-            fullName: `${input.name}.${column.name}`,
-            description: column.description,
-            status: existingColumn?.status ?? 'dbt_catalog',
-            sourcePath: stringValue(input.node.original_file_path) ?? stringValue(input.node.path),
-            sourceSystem: existingColumn?.sourceSystem ?? 'dbt manifest.json catalog',
-            payload: compactObject({
-                ...(existingColumn?.payload ?? {}),
-                model: input.name,
-                uniqueId: input.uniqueId,
-                type: column.type,
-                relation,
-                columnCompleteness: 'partial',
-                catalogOnly: existingColumn ? undefined : true,
-            }),
-        }));
-        putEdge(input.edges, {
-            edgeType: 'contains',
-            fromKey: input.objectKey,
-            toKey: columnKey,
-            confidence: 1,
-            payload: { source: 'raw dbt manifest column catalog' },
-        });
-    }
+    if (input.includeColumnObjects)
+        for (const column of columns) {
+            const columnKey = `dbt:column:${input.name}.${column.name}`;
+            const existingColumn = input.objects.get(columnKey);
+            input.objects.set(columnKey, mergeObject(existingColumn, {
+                objectKey: columnKey,
+                objectType: 'dbt_column',
+                name: column.name,
+                fullName: `${input.name}.${column.name}`,
+                description: column.description,
+                status: existingColumn?.status ?? 'dbt_catalog',
+                sourcePath: stringValue(input.node.original_file_path) ?? stringValue(input.node.path),
+                sourceSystem: existingColumn?.sourceSystem ?? 'dbt manifest.json catalog',
+                payload: compactObject({
+                    ...(existingColumn?.payload ?? {}),
+                    model: input.name,
+                    uniqueId: input.uniqueId,
+                    type: column.type,
+                    relation,
+                    columnCompleteness: 'partial',
+                    catalogOnly: existingColumn ? undefined : true,
+                }),
+            }));
+            putEdge(input.edges, {
+                edgeType: 'contains',
+                fromKey: input.objectKey,
+                toKey: columnKey,
+                confidence: 1,
+                payload: { source: 'raw dbt manifest column catalog' },
+            });
+        }
     for (const dep of rawDbtDependsOn(input.node)) {
         putEdge(input.edges, {
             edgeType: 'depends_on',
@@ -1720,6 +1832,7 @@ function addManifestBlockDetails(manifest, objects) {
                 blockType: block.blockType,
                 tests: block.tests,
                 parameterPolicy: block.parameterPolicy,
+                parameters: block.parameters,
                 filterBindings: block.filterBindings,
                 sqlFingerprints: buildBlockSqlFingerprints(block.sql),
                 businessFingerprint: buildBlockBusinessFingerprint({
@@ -2295,9 +2408,34 @@ async function planContextPackRoute(input) {
     const exactByApplicability = [...applicabilityByKey.values()]
         .filter((item) => item.kind === 'exact_answer' || item.kind === 'safe_parameterized')
         .sort((a, b) => b.score - a.score)[0];
+    // Analytical questions intentionally keep certified applicability conservative:
+    // a lexical/content match alone must not terminate the cascade. A certified
+    // block whose declared/inferred output contract fully covers the requested
+    // answer shape is different, however — that is a proven Tier 1 answer even
+    // when the planner also knows how to generate SQL. Promote only exact/trim-safe
+    // contract fits here; near matches remain context for Tier 2.
+    const exactByContract = input.objects
+        .filter((object) => object.objectType === 'dql_block'
+        && isCertifiedMetadataObject(object)
+        && hasCompatibleMetadataRankingDirection(input.request.question, object))
+        .map((object) => ({
+        object,
+        fit: evaluateCertifiedBlockFit({
+            question: input.request.question,
+            plan: input.questionPlan,
+            block: object,
+            exactExampleMatch: hasExactExampleQuestion(input.request.question, object),
+            definitionLookup: intent === 'definition_lookup',
+        }),
+        applicabilityScore: applicabilityByKey.get(object.objectKey)?.score ?? 0,
+    }))
+        .filter(({ fit }) => (fit.kind === 'exact' || fit.kind === 'trim_safe')
+        && (fit.confidence === 'high' || fit.confidence === 'medium'))
+        .sort((a, b) => (b.fit.confidence === 'high' ? 1 : 0) - (a.fit.confidence === 'high' ? 1 : 0)
+        || b.applicabilityScore - a.applicabilityScore)[0]?.object;
     let exact = exactByApplicability
         ? input.objects.find((object) => object.objectKey === exactByApplicability.objectKey)
-        : findExactCertifiedObject(input.request.question, intent, input.objects);
+        : findExactCertifiedObject(input.request.question, intent, input.objects) ?? exactByContract;
     const contextApplicability = [...applicabilityByKey.values()]
         .filter((item) => item.kind === 'context_only')
         .sort((a, b) => b.score - a.score)[0];
@@ -2316,6 +2454,13 @@ async function planContextPackRoute(input) {
             paraphraseExampleMatch = true;
         }
     }
+    // Keep the strongest context-only certified candidate attached to the route
+    // so the contract and grain gates can explain exactly why it is demoted.
+    // This does not promote a loose match: both gates still have to pass before
+    // Tier 1 is possible.
+    if (!exact && contextApplicability) {
+        exact = input.objects.find((object) => object.objectKey === contextApplicability.objectKey);
+    }
     const certifiedApplicability = exact
         ? applicabilityByKey.get(exact.objectKey) ?? certifiedApplicabilityForObject(exact, input.questionPlan)
         : undefined;
@@ -2382,6 +2527,7 @@ async function planContextPackRoute(input) {
         || intent === 'definition_lookup'
         || exactExampleMatch
         || paraphraseExampleMatch
+        || (blockFit && certifiedFitAllowsTier1(blockFit) && hasCompatibleMetadataRankingDirection(input.request.question, exact))
         || (intent === 'ad_hoc_ranking' && objectNameInQuestion(input.request.question, exact)))) {
         return {
             route: 'certified',
@@ -2407,7 +2553,7 @@ async function planContextPackRoute(input) {
             route: 'generated_sql',
             intent: isGeneratedMetadataIntent(intent) ? intent : 'ad_hoc_ranking',
             reason: `Certified block "${exact.name}" is close but answers a different grain than the question, so it is context only and SQL is generated for the requested grain.`,
-            routeReason: grainGate.reason,
+            routeReason: `${grainGate.reason}; routed to Tier 2 generated SQL`,
             grainGate: grainGateInfo,
             blockFit,
             trustLabel: input.trustLabel === 'certified' ? 'mixed' : input.trustLabel,
@@ -2425,7 +2571,7 @@ async function planContextPackRoute(input) {
             route: 'generated_sql',
             intent: isGeneratedMetadataIntent(intent) ? intent : 'ad_hoc_ranking',
             reason: `Certified block "${exact.name}" is relevant but does not satisfy the requested answer shape, so it is context only and SQL is generated for the requested result.`,
-            routeReason: blockFit.reasons.join('; '),
+            routeReason: `${blockFit.reasons.join('; ')}; routed to Tier 2 generated SQL`,
             grainGate: grainGateInfo,
             blockFit,
             trustLabel: input.trustLabel === 'certified' ? 'mixed' : input.trustLabel,
@@ -2778,7 +2924,8 @@ function hasCompatibleMetadataRankingDirection(question, object) {
     const objectDirection = rankingDirection([
         object.name,
         object.description ?? '',
-        JSON.stringify(object.payload ?? {}),
+        Array.isArray(object.payload?.tags) ? object.payload.tags.join(' ') : '',
+        typeof object.payload?.sql === 'string' ? object.payload.sql : '',
     ].join(' '));
     if (!objectDirection)
         return true;
@@ -4756,6 +4903,121 @@ function reasonForObject(row) {
         return 'Published consumption context';
     return 'Relevant project metadata';
 }
+function filterMetadataObjectsByDomainContext(rows, context) {
+    if (!context?.activeDomain)
+        return rows;
+    const domains = new Set([
+        context.activeDomain,
+        ...context.ancestors,
+        ...context.allowedImports.map((item) => item.providerDomain),
+    ]);
+    return rows.filter((row) => !row.domain || domains.has(row.domain));
+}
+function selectContextPackSkills(objects, question, context) {
+    const byIdentity = new Map();
+    const parsed = objects.flatMap((object) => {
+        const skill = skillFromMetadataObject(object);
+        if (!skill)
+            return [];
+        const identity = skill.qualifiedId ?? skill.id;
+        byIdentity.set(identity, object);
+        return [skill];
+    });
+    const domains = context?.activeDomain
+        ? [context.activeDomain, ...context.ancestors, ...context.allowedImports.map((item) => item.providerDomain)]
+        : [];
+    const selected = selectRelevantSkills(parsed, question, {
+        domains,
+        modelAreaIds: context?.modelAreaId ? [context.modelAreaId] : [],
+    });
+    return selected.flatMap((skill) => {
+        const object = byIdentity.get(skill.qualifiedId ?? skill.id);
+        return object ? [{ object, skill: localContextSkillFromParsed(skill, object) }] : [];
+    });
+}
+function skillFromMetadataObject(object) {
+    if (object.objectType !== 'skill')
+        return null;
+    const payload = object.payload ?? {};
+    const scope = payload.scope === 'personal' ? 'personal' : 'project';
+    const status = payload.status === 'draft' || payload.status === 'deprecated' || payload.status === 'active'
+        ? payload.status
+        : object.status === 'draft' || object.status === 'deprecated' || object.status === 'active'
+            ? object.status
+            : 'active';
+    return {
+        id: stringPayload(payload.skillId) ?? object.name,
+        localId: stringPayload(payload.localId) ?? object.name,
+        qualifiedId: stringPayload(payload.qualifiedId) ?? object.fullName,
+        scope,
+        user: stringPayload(payload.user),
+        domain: object.domain,
+        domains: stringArrayPayload(payload.domains),
+        modelAreaRefs: stringArrayPayload(payload.modelAreaRefs),
+        kind: skillKindPayload(payload.kind),
+        status,
+        owner: object.owner,
+        triggers: stringArrayPayload(payload.triggers),
+        exclusions: stringArrayPayload(payload.exclusions),
+        description: object.description,
+        preferredMetrics: stringArrayPayload(payload.preferredMetrics),
+        preferredBlocks: stringArrayPayload(payload.preferredBlocks),
+        preferredDimensions: stringArrayPayload(payload.preferredDimensions),
+        requiredFilters: stringArrayPayload(payload.requiredFilters),
+        clarifyWhen: stringArrayPayload(payload.clarifyWhen),
+        examples: stringArrayPayload(payload.examples),
+        sourceRefs: stringArrayPayload(payload.sourceRefs),
+        vocabulary: stringRecordPayload(payload.vocabulary),
+        body: stringPayload(payload.body) ?? '',
+        sourcePath: object.sourcePath ?? '',
+        isStarter: payload.isStarter === true,
+    };
+}
+function localContextSkillFromParsed(skill, object) {
+    const guidance = skill.body.slice(0, 4_000);
+    return {
+        objectKey: object.objectKey,
+        id: skill.id,
+        qualifiedId: skill.qualifiedId,
+        domain: skill.domain,
+        domains: [...(skill.domains ?? [])],
+        modelAreaRefs: [...(skill.modelAreaRefs ?? [])],
+        kind: skill.kind,
+        status: skill.status,
+        owner: skill.owner,
+        description: skill.description,
+        triggers: [...(skill.triggers ?? [])],
+        exclusions: [...(skill.exclusions ?? [])],
+        preferredMetrics: [...skill.preferredMetrics],
+        preferredBlocks: [...skill.preferredBlocks],
+        preferredDimensions: [...(skill.preferredDimensions ?? [])],
+        requiredFilters: [...(skill.requiredFilters ?? [])],
+        clarifyWhen: [...(skill.clarifyWhen ?? [])],
+        vocabulary: { ...skill.vocabulary },
+        guidance,
+        guidanceTruncated: guidance.length < skill.body.length,
+        sourceRefs: [...(skill.sourceRefs ?? [])],
+        provenance: stringPayload(object.payload?.provenance) ?? object.sourceSystem ?? 'DQL domain skill',
+        sourcePath: object.sourcePath,
+    };
+}
+function stringPayload(value) {
+    return typeof value === 'string' && value.trim() ? value : undefined;
+}
+function stringArrayPayload(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string' && Boolean(item.trim())) : [];
+}
+function stringRecordPayload(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === 'string'));
+}
+function skillKindPayload(value) {
+    return value === 'domain_reference' || value === 'metric_policy' || value === 'glossary'
+        || value === 'analysis_pattern' || value === 'sql_policy' || value === 'custom'
+        ? value
+        : undefined;
+}
 function mergeObjects(rows) {
     const byKey = new Map();
     for (const row of rows) {