@duckcodeailabs/dql-agent 1.13.0 → 1.13.2

package/dist/answer-loop.js

@@ -959,6 +959,7 @@ export async function answer(input) {
                 : selectRelevantSkills(executionInput.skills ?? [], executionInput.question, {
                     userId: executionInput.userId ?? null,
                     modelAreaIds: executionInput.domainContext?.modelAreaId ? [executionInput.domainContext.modelAreaId] : [],
+                    focusObjectKeys: executionInput.contextPack?.focusObjectKey ? [executionInput.contextPack.focusObjectKey] : [],
                     domains: Array.from(new Set([
                         ...domainContextSearchDomains(executionInput.domainContext),
                         ...(executionInput.domain ? [executionInput.domain] : []),
@@ -1062,6 +1063,7 @@ async function runAnswerLoop(input) {
             userId: userId ?? null,
             domains: inferredDomains,
             modelAreaIds: input.domainContext?.modelAreaId ? [input.domainContext.modelAreaId] : [],
+            focusObjectKeys: input.contextPack?.focusObjectKey ? [input.contextPack.focusObjectKey] : [],
         });
     const effectiveBlockHints = Array.from(new Set([
         ...blockHints,
@@ -1757,7 +1759,11 @@ async function runAnswerLoop(input) {
             domainContext: input.domainContext,
         })
         : undefined;
-    const analyticalPlanPrompt = renderAnalyticalPlanPrompt(analyticalPlan);
+    // A multi-entity question gets the certified join plan; a single-entity one
+    // gets that entity's authored grain and business meaning. Before this, only
+    // the former existed, so most everyday questions saw no modeling at all.
+    const analyticalPlanPrompt = renderAnalyticalPlanPrompt(analyticalPlan)
+        ?? renderSingleEntityModelingPrompt(analyticalPlan, input.manifest);
     if (analyticalPlanPrompt)
         messages.push({ role: 'system', content: analyticalPlanPrompt });
     if (questionDomainScope.length > 0) {
@@ -4185,7 +4191,35 @@ function entityIdentifierTokensForMatching(entity) {
         .flatMap((value) => value.toLowerCase().replace(/^(fct|dim|stg)_/, '').split(/[^a-z0-9]+/))
         .filter((token) => token.length > 2 && token !== 'entity');
 }
-function renderAnalyticalPlanPrompt(plan) {
+/**
+ * CTX-008: the authored business identity of a single modeled entity. Most
+ * real questions name exactly one entity, and those used to receive no modeling
+ * context at all because the join planner needs two. Grain and business context
+ * matter just as much to a one-table answer as keys do to a join.
+ */
+export function renderSingleEntityModelingPrompt(plan, manifest) {
+    if (!plan || plan.entities.length !== 1 || !manifest?.modeling)
+        return undefined;
+    const entity = manifest.modeling.entities[plan.entities[0]];
+    if (!entity)
+        return undefined;
+    const relation = manifest.dbtProvenance?.nodes[entity.dbtUniqueId]?.relation;
+    const lines = [
+        `- ${entity.businessName || entity.localId}${relation ? ` (${relation})` : ''}`,
+        entity.businessContext ? `  meaning: ${entity.businessContext}` : '',
+        entity.grain ? `  grain: one row per ${entity.grain}` : '',
+        entity.keys.length ? `  keys: ${entity.keys.join(', ')}` : '',
+        entity.analyticalRole && entity.analyticalRole !== 'unknown' ? `  role: ${entity.analyticalRole}` : '',
+    ].filter(Boolean);
+    if (lines.length === 1 && !entity.businessName)
+        return undefined;
+    return [
+        'DQL MODELED ENTITY (authored business context):',
+        ...lines,
+        'Respect the stated grain: do not aggregate across it in a way that double counts, and use the business meaning to interpret the question.',
+    ].join('\n');
+}
+export function renderAnalyticalPlanPrompt(plan) {
     if (!plan || plan.entities.length < 2)
         return undefined;
     if (!plan.safe) {
@@ -4222,11 +4256,19 @@ function renderAnalyticalPlanPrompt(plan) {
         ...plan.edges.map((edge, index) => [
             `${index + 1}. ${edge.fromEntity} (${edge.fromRelation ?? 'bound dbt model'}) -> ${edge.toEntity} (${edge.toRelation ?? 'bound dbt model'})`,
             `   relationship=${edge.relationshipId}; keys=${edge.keys.map((key) => `${key.from}=${key.to}`).join(', ')}; cardinality=${edge.cardinality}; fanout=${edge.fanout}`,
+            // CTX-008: the authored meaning travels with the keys, so the model can
+            // tell a technically valid join from the one the question actually wants.
+            analyticalEdgeMeaning(edge),
             edge.importRefs.length ? `   imports=${edge.importRefs.join(', ')}` : '',
         ].filter(Boolean).join('\n')),
         'Use only these relationships and exact key pairs. dbt DAG lineage and same-named columns are not join authorization. Any different join must be refused.',
     ].join('\n');
 }
+/** One `means:` line describing what a join represents, when it was authored. */
+function analyticalEdgeMeaning(edge) {
+    const meaning = [edge.verb, edge.description, edge.rationale].filter(Boolean).join(' — ');
+    return meaning ? `   means: ${meaning}` : '';
+}
 /**
  * Missing modeling may enter the narrow EXP-001 host-validated lane. Explicit
  * unsafe, cross-domain, attribution, expiry, purpose, and proof failures never do.
@@ -4560,10 +4602,22 @@ function renderCandidateJoinsForPrompt(contextPack, budget) {
         ...joins.map((join) => `- ${join.leftRelation}.${join.leftColumn} -> ${join.rightRelation}.${join.rightColumn}${join.reason ? ` (${join.reason})` : ''}`),
     ].join('\n');
 }
+/**
+ * CTX-008: `proves_join` edges are the governed relationship graph the user
+ * authored, and the quick budget sets `edgeLimit: 0` — which blacked them out
+ * entirely on exactly the lookup questions that most need them. Governed join
+ * proof always earns a small allowance; every other edge class still respects
+ * the budget.
+ */
+const GOVERNED_JOIN_EDGE_FLOOR = 12;
 function renderContextEdgesForPrompt(contextPack, budget) {
-    if (budget.edgeLimit <= 0)
-        return '';
-    const edges = contextPack.edges.slice(0, budget.edgeLimit);
+    const governed = contextPack.edges
+        .filter((edge) => edge.edgeType === 'proves_join')
+        .slice(0, Math.max(budget.edgeLimit, GOVERNED_JOIN_EDGE_FLOOR));
+    const others = budget.edgeLimit > 0
+        ? contextPack.edges.filter((edge) => edge.edgeType !== 'proves_join').slice(0, budget.edgeLimit)
+        : [];
+    const edges = [...governed, ...others];
     if (edges.length === 0)
         return '';
     return [