@duckcodeailabs/dql-agent 1.10.0 → 1.10.2

package/dist/analytical-execution-graph.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Route-neutral executable graph for a fully resolved RFC 0005 analytical
+ * tuple. The graph never searches for members or changes metric meaning. It
+ * expresses period aggregation, alignment, exact-decimal arithmetic, ranking,
+ * projection, and result validation over IDs already frozen in the plan.
+ *
+ * Acceptance: AGT-018, AGT-019.
+ */
+import type { AnalyticalPeriodV2, AnalyticalQuestionFrameV2, MetricCapabilityContract } from '@duckcodeailabs/dql-core';
+import type { AnalyticalFitClass } from './analytical-compatibility.js';
+import type { ResolvedAnalyticalPlan } from './resolved-analytical-plan.js';
+export type AnalyticalExecutionRoute = 'certified' | 'semantic' | 'governed_sql' | 'exploratory';
+export type AnalyticalExecutionGraphBlockedCode = 'PLAN_V2_REQUIRED' | 'PLAN_BLOCKED' | 'CAPABILITY_MISMATCH' | 'ROUTE_MISMATCH' | 'PERIOD_CONTRACT_INVALID' | 'PERIOD_BOUNDS_REQUIRED' | 'OUTPUT_CONTRACT_INVALID' | 'RANKING_CONTRACT_INVALID';
+export interface AnalyticalGraphMemberFilter {
+    dimensionId: string;
+    canonicalValues: unknown[];
+}
+export interface AnalyticalGraphSourceInvocationNode {
+    id: string;
+    kind: 'source_invocation';
+    dependencies: [];
+    strategy: 'complete_asset' | 'period_aggregate';
+    route: AnalyticalExecutionRoute;
+    adapterId?: string;
+    metricId: string;
+    entityGrainIds: string[];
+    groupByDimensionIds: string[];
+    memberFilters: AnalyticalGraphMemberFilter[];
+    period?: {
+        id: string;
+        kind: AnalyticalPeriodV2['kind'];
+        timeDimensionId: string;
+        timeRole: string;
+        grain: string;
+        calendarId: string;
+        timezone: string;
+        completenessPolicy: NonNullable<AnalyticalQuestionFrameV2['timeContext']>['completenessPolicy'];
+        startInclusive: string;
+        endExclusive: string;
+    };
+    outputAliases: {
+        dimensions: Array<{
+            dimensionId: string;
+            outputId: string;
+        }>;
+        metric?: {
+            metricId: string;
+            periodId?: string;
+            outputId: string;
+        };
+        completeAssetOutputIds?: string[];
+    };
+}
+export interface AnalyticalGraphAlignNode {
+    id: string;
+    kind: 'align_periods';
+    dependencies: string[];
+    keyOutputIds: string[];
+    periodMetricOutputIds: Array<{
+        periodId: string;
+        outputId: string;
+    }>;
+    alignment: NonNullable<NonNullable<AnalyticalQuestionFrameV2['comparison']>['alignment']>;
+}
+export interface AnalyticalGraphCalculateNode {
+    id: string;
+    kind: 'calculate_comparison';
+    dependencies: [string];
+    expressions: Array<{
+        outputId: string;
+        kind: 'delta' | 'percent_delta';
+        baseOutputId: string;
+        comparisonOutputId: string;
+        zeroDenominatorPolicy: 'null' | 'not_applicable';
+    }>;
+}
+export interface AnalyticalGraphRankNode {
+    id: string;
+    kind: 'rank';
+    dependencies: [string];
+    entityDimensionId: string;
+    entityOutputId: string;
+    byMetricId: string;
+    byPeriodId?: string;
+    byOutputId: string;
+    direction: 'asc' | 'desc';
+    limit: number;
+    tiePolicy: 'stable_secondary_key' | 'include_ties';
+    rankOutputId?: string;
+}
+export interface AnalyticalGraphValidateNode {
+    id: string;
+    kind: 'project_validate';
+    dependencies: [string];
+    outputIds: string[];
+    entityGrainIds: string[];
+    maxRows: number;
+}
+export type AnalyticalExecutionGraphNode = AnalyticalGraphSourceInvocationNode | AnalyticalGraphAlignNode | AnalyticalGraphCalculateNode | AnalyticalGraphRankNode | AnalyticalGraphValidateNode;
+export interface AnalyticalExecutionGraphV1 {
+    schemaVersion: 1;
+    graphId: string;
+    fingerprint: string;
+    planId: string;
+    planFingerprint: string;
+    snapshotId: string;
+    route: AnalyticalExecutionRoute;
+    adapterId?: string;
+    fitClass: AnalyticalFitClass;
+    metricId: string;
+    capabilityFingerprint: string;
+    nodes: AnalyticalExecutionGraphNode[];
+    terminalNodeId: string;
+}
+export type BuildAnalyticalExecutionGraphResult = {
+    status: 'ready';
+    graph: AnalyticalExecutionGraphV1;
+} | {
+    status: 'blocked';
+    code: AnalyticalExecutionGraphBlockedCode;
+    reason: string;
+    field?: string;
+};
+export interface AnalyticalSourceResult {
+    columns: string[];
+    rows: Array<Record<string, unknown>>;
+    receiptFingerprint: string;
+}
+export interface AnalyticalExecutionReceiptV1 {
+    version: 1;
+    receiptId: string;
+    graphId: string;
+    graphFingerprint: string;
+    planId: string;
+    planFingerprint: string;
+    snapshotId: string;
+    route: AnalyticalExecutionRoute;
+    trustState: 'certified' | 'governed' | 'review_required';
+    subReceipts: Array<{
+        nodeId: string;
+        receiptFingerprint: string;
+    }>;
+    outputColumns: string[];
+    rowCount: number;
+    rowBound: number;
+    resultFingerprint: string;
+}
+export type AnalyticalGraphExecutionFailureCode = 'SOURCE_RESULT_MISSING' | 'SUB_RECEIPT_REQUIRED' | 'RESULT_CONTRACT_MISMATCH' | 'DECIMAL_VALUE_REQUIRED' | 'ROW_BOUND_EXCEEDED';
+export type AnalyticalGraphExecutionResult = {
+    status: 'completed';
+    columns: string[];
+    rows: Array<Record<string, unknown>>;
+    receipt: AnalyticalExecutionReceiptV1;
+} | {
+    status: 'failed';
+    code: AnalyticalGraphExecutionFailureCode;
+    reason: string;
+    nodeId: string;
+    missingOutputIds?: string[];
+};
+export declare function buildAnalyticalExecutionGraph(input: {
+    plan: ResolvedAnalyticalPlan;
+    capability: MetricCapabilityContract;
+    route: AnalyticalExecutionRoute;
+    adapterId?: string;
+    fitClass?: AnalyticalFitClass;
+    maxRows?: number;
+}): BuildAnalyticalExecutionGraphResult;
+export declare function executeAnalyticalExecutionGraph(input: {
+    graph: AnalyticalExecutionGraphV1;
+    sourceResults: Record<string, AnalyticalSourceResult>;
+    percentScale?: number;
+}): AnalyticalGraphExecutionResult;
+//# sourceMappingURL=analytical-execution-graph.d.ts.map

package/dist/analytical-execution-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytical-execution-graph.d.ts","sourceRoot":"","sources":["../src/analytical-execution-graph.ts"],"names":[],"mappings":"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"}