@duckcodeailabs/dql-core 1.10.0 → 1.10.2

package/dist/contracts/analytical.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Versioned cross-surface contracts for analytical composition and repair.
+ *
+ * These types deliberately contain no agent or UI concepts. Ask, Notebook,
+ * CLI, MCP, Chat, and execution adapters exchange the same serialized shapes.
+ *
+ * Acceptance: CONTRACT-002, AGT-017, API-007, SEC-004.
+ */
+export declare const ANALYTICAL_QUESTION_FRAME_VERSION: 2;
+export declare const ANALYTICAL_FAILURE_VERSION: 1;
+export type AnalyticalDimensionRole = 'group_by' | 'filter' | 'display' | 'rank_entity' | 'time_axis';
+export type AnalyticalQuestionType = 'definition' | 'scalar' | 'ranking' | 'trend' | 'comparison' | 'diagnosis' | 'research';
+export type AnalyticalPeriodKind = 'absolute' | 'current' | 'previous_period' | 'previous_year';
+export interface AnalyticalDimensionBindingV2 {
+    dimensionId: string;
+    role: AnalyticalDimensionRole;
+    requestedLabel?: string;
+}
+export interface AnalyticalMemberBindingV2 {
+    dimensionId: string;
+    canonicalValues: unknown[];
+    source: 'question' | 'clarification' | 'prior_result' | 'parameter';
+    confidence: 'exact' | 'high' | 'medium';
+    sourceTurnId?: string;
+}
+export interface AnalyticalPeriodV2 {
+    id: string;
+    kind: AnalyticalPeriodKind;
+    start?: string;
+    end?: string;
+    alignToPeriodId?: string;
+}
+export interface AnalyticalTimeContextV2 {
+    timeDimensionId?: string;
+    timeRole?: string;
+    calendarId?: string;
+    timezone?: string;
+    grain?: string;
+    completenessPolicy?: 'partial_current' | 'latest_complete' | 'closed_period';
+    periods: AnalyticalPeriodV2[];
+}
+export interface AnalyticalComparisonV2 {
+    basePeriodId: string;
+    comparisonPeriodIds: string[];
+    alignment?: 'elapsed_period' | 'calendar_period' | 'fiscal_period';
+    outputs: Array<'value' | 'absolute_delta' | 'percent_delta'>;
+    zeroDenominatorPolicy: 'null' | 'not_applicable';
+}
+export interface AnalyticalRankingV2 {
+    entityDimensionId: string;
+    byMetricId: string;
+    byPeriodId?: string;
+    direction: 'asc' | 'desc';
+    limit: number;
+    tiePolicy: 'stable_secondary_key' | 'include_ties';
+}
+export interface AnalyticalRequestedOutputV2 {
+    id: string;
+    kind: 'dimension' | 'metric_value' | 'delta' | 'percent_delta' | 'rank';
+    metricId?: string;
+    periodId?: string;
+}
+export interface AnalyticalAmbiguityV2 {
+    field: string;
+    candidateIds: string[];
+    reasonCode: string;
+}
+export interface AnalyticalQuestionFrameV2 {
+    version: 2;
+    interpretedQuestion: string;
+    questionType: AnalyticalQuestionType;
+    metricConceptIds: string[];
+    entityGrainIds: string[];
+    dimensions: AnalyticalDimensionBindingV2[];
+    memberBindings: AnalyticalMemberBindingV2[];
+    timeContext?: AnalyticalTimeContextV2;
+    comparison?: AnalyticalComparisonV2;
+    ranking?: AnalyticalRankingV2;
+    requestedOutputs: AnalyticalRequestedOutputV2[];
+    ambiguity: AnalyticalAmbiguityV2[];
+}
+export type AnalyticalOperation = 'filter' | 'group' | 'trend' | 'compare' | 'rank' | 'window' | 'having';
+export interface MetricCapabilityContract {
+    metricId: string;
+    semanticModelId?: string;
+    measureIds: string[];
+    primaryEntityId: string;
+    /** Result grain used when the question requests no grouping dimension. */
+    defaultResultGrainId: string;
+    resultGrainIds: string[];
+    aggregation: string;
+    additivity: {
+        entities: 'additive' | 'semi_additive' | 'non_additive';
+        time: 'additive' | 'semi_additive' | 'non_additive';
+        nonAdditiveDimensionIds?: string[];
+    };
+    dimensions: Array<{
+        dimensionId: string;
+        /** Entity grain produced/filtered by this dimension. */
+        entityId: string;
+        supportedRoles: AnalyticalDimensionRole[];
+        relationshipPathIds?: string[];
+    }>;
+    timeDimensions: Array<{
+        dimensionId: string;
+        role: string;
+        supportedGrains: string[];
+        defaultFor?: Array<'scalar' | 'trend' | 'comparison'>;
+    }>;
+    freshness?: {
+        observedThroughFieldId?: string;
+        defaultCompletenessPolicy?: 'partial_current' | 'latest_complete' | 'closed_period';
+    };
+    operations: AnalyticalOperation[];
+    supportedOutputKinds: AnalyticalRequestedOutputV2['kind'][];
+    /** Certified assets may further restrict the exact output aliases. */
+    declaredOutputIds?: string[];
+    executionCapabilities: Array<{
+        route: 'certified' | 'semantic' | 'governed_sql' | 'exploratory';
+        adapterId?: string;
+    }>;
+    sourceFingerprint: string;
+}
+export interface AnalyticalPolicyContract {
+    policyId: string;
+    sourceHash: string;
+    metricIds?: string[];
+    timeRole?: string;
+    calendarId?: string;
+    timezone?: string;
+    completenessPolicy?: 'partial_current' | 'latest_complete' | 'closed_period';
+    comparisonAlignment?: 'elapsed_period' | 'calendar_period' | 'fiscal_period';
+    defaultRankingPeriod?: 'current' | 'comparison';
+    narrativeGuidance?: string[];
+}
+export type AnalyticalFailureCode = 'COLUMN_NOT_FOUND' | 'RELATION_NOT_FOUND' | 'PERMISSION_DENIED' | 'AMBIGUOUS_COLUMN' | 'DIALECT_ERROR' | 'SNAPSHOT_DRIFT' | 'TIMEOUT' | 'RESULT_CONTRACT_MISMATCH' | 'COMPILATION_FAILED' | 'POLICY_DENIED';
+export type AnalyticalFailurePhase = 'planning' | 'compilation' | 'validation' | 'execution' | 'result_validation';
+export type AnalyticalFailureRecoverability = 'retry_same' | 'refresh_snapshot' | 'edit_dql' | 'edit_sql' | 'change_authorized_connection' | 'request_access' | 'modeling_change' | 'none';
+export interface AnalyticalFailureV1 {
+    version: 1;
+    runId: string;
+    failureId: string;
+    code: AnalyticalFailureCode;
+    phase: AnalyticalFailurePhase;
+    message: string;
+    recoverability: AnalyticalFailureRecoverability;
+    failedBindings: Array<{
+        qualifiedId?: string;
+        role?: string;
+        reasonCode: string;
+    }>;
+    snapshotId: string;
+    planFingerprint?: string;
+    dqlFingerprint?: string;
+    sqlFingerprint?: string;
+    safeActions: string[];
+}
+export type AnalyticalTrustState = 'certified' | 'governed' | 'review_required';
+export type AnalyticalRepairChange = 'parameter_only' | 'display_only' | 'dql_source' | 'sql_text' | 'snapshot_refresh' | 'connection_change' | 'reviewed_draft_promotion';
+export interface AnalyticalRepairTrustTransition {
+    previous: AnalyticalTrustState;
+    next: AnalyticalTrustState;
+    requiresNewReceipt: boolean;
+    requiresReview: boolean;
+    preservesCertifiedAssetIdentity: boolean;
+}
+/** Strictly normalize an untrusted cross-surface analytical frame. */
+export declare function normalizeAnalyticalQuestionFrameV2(value: unknown): AnalyticalQuestionFrameV2 | undefined;
+/** Strictly normalize capability metadata before it becomes routing evidence. */
+export declare function normalizeMetricCapabilityContract(value: unknown): MetricCapabilityContract | undefined;
+/** Strictly normalize a failure returned by any DQL analytical surface. */
+export declare function normalizeAnalyticalFailureV1(value: unknown): AnalyticalFailureV1 | undefined;
+/** Apply the RFC 0005 trust matrix before a derived repair is exposed. */
+export declare function analyticalRepairTrustTransition(input: {
+    previous: AnalyticalTrustState;
+    change: AnalyticalRepairChange;
+    governedValidationPassed?: boolean;
+}): AnalyticalRepairTrustTransition;
+//# sourceMappingURL=analytical.d.ts.map

package/dist/contracts/analytical.d.ts.map

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