@duckcodeailabs/dql-agent 1.10.0 → 1.10.2

package/dist/analytical-readiness.js

@@ -0,0 +1,95 @@
+/** Deterministic capability-readiness projection for modeling and diagnostics. */
+import { normalizeMetricCapabilityContract } from '@duckcodeailabs/dql-core';
+/**
+ * Explain what each retrieved metric/certified asset can answer before route
+ * selection. This is a diagnostic report only and grants no capability.
+ *
+ * Acceptance: CONTRACT-002, SKILL-004.
+ */
+export function buildAnalyticalCapabilityReadiness(candidates) {
+    return candidates
+        .filter((candidate) => candidate.kind === 'semantic_metric' || candidate.kind === 'certified_block')
+        .map((candidate) => {
+        const candidateId = candidate.qualifiedId ?? candidate.id;
+        const capability = normalizeMetricCapabilityContract(candidate.analyticalCapability);
+        if (!capability) {
+            const reasons = ['No complete normalized MetricCapabilityContract is present in the active snapshot.'];
+            return {
+                candidateId,
+                status: 'incomplete',
+                support: {
+                    scalar: false,
+                    filter: false,
+                    grouping: false,
+                    trend: false,
+                    comparison: false,
+                    ranking: false,
+                },
+                blockers: {
+                    scalar: reasons,
+                    filter: reasons,
+                    grouping: reasons,
+                    trend: reasons,
+                    comparison: reasons,
+                    ranking: reasons,
+                },
+            };
+        }
+        const hasRoute = capability.executionCapabilities.length > 0;
+        const outputKinds = new Set(capability.supportedOutputKinds);
+        const operations = new Set(capability.operations);
+        const filterDimension = capability.dimensions.some((dimension) => dimension.supportedRoles.includes('filter'));
+        const groupDimension = capability.dimensions.some((dimension) => dimension.supportedRoles.includes('group_by'));
+        const rankDimension = capability.dimensions.some((dimension) => dimension.supportedRoles.includes('rank_entity'));
+        const checks = {
+            scalar: [
+                [hasRoute, 'No execution adapter is declared.'],
+                [outputKinds.has('metric_value'), 'Metric-value output is not declared.'],
+                [Boolean(capability.defaultResultGrainId), 'No default result grain is declared.'],
+            ],
+            filter: [
+                [hasRoute, 'No execution adapter is declared.'],
+                [operations.has('filter'), 'Filter operation is not supported.'],
+                [filterDimension, 'No dimension supports the filter role.'],
+            ],
+            grouping: [
+                [hasRoute, 'No execution adapter is declared.'],
+                [operations.has('group'), 'Group operation is not supported.'],
+                [groupDimension, 'No dimension supports the group_by role.'],
+                [outputKinds.has('dimension'), 'Dimension output is not declared.'],
+            ],
+            trend: [
+                [hasRoute, 'No execution adapter is declared.'],
+                [operations.has('trend'), 'Trend operation is not supported.'],
+                [capability.timeDimensions.length > 0, 'No time dimension is declared.'],
+            ],
+            comparison: [
+                [hasRoute, 'No execution adapter is declared.'],
+                [operations.has('compare'), 'Comparison operation is not supported.'],
+                [capability.timeDimensions.length > 0, 'No time dimension is declared.'],
+                [outputKinds.has('delta') || outputKinds.has('percent_delta'), 'No comparison output is declared.'],
+            ],
+            ranking: [
+                [hasRoute, 'No execution adapter is declared.'],
+                [operations.has('rank'), 'Rank operation is not supported.'],
+                [operations.has('group'), 'Ranking requires post-aggregation grouping support.'],
+                [rankDimension, 'No dimension supports the rank_entity role.'],
+                [outputKinds.has('rank'), 'Rank output is not declared.'],
+            ],
+        };
+        const support = Object.fromEntries(Object.entries(checks).map(([question, values]) => [question, values.every(([ok]) => ok)]));
+        const blockers = Object.fromEntries(Object.entries(checks).flatMap(([question, values]) => {
+            const reasons = values.filter(([ok]) => !ok).map(([, reason]) => reason);
+            return reasons.length > 0 ? [[question, reasons]] : [];
+        }));
+        return {
+            candidateId,
+            metricId: capability.metricId,
+            status: 'complete',
+            support,
+            blockers,
+        };
+    })
+        .sort((left, right) => left.candidateId.localeCompare(right.candidateId));
+}
+//# sourceMappingURL=analytical-readiness.js.map

package/dist/analytical-readiness.js.map

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

package/dist/analytical-result-facts.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Deterministic result facts and narration guards for RFC 0005. Numeric claims
+ * are copied only from validated graph outputs and every fact is bound to the
+ * terminal receipt. No causal explanation is inferred from analytical rows.
+ *
+ * Acceptance: AGT-020.
+ */
+import type { AnalyticalQuestionFrameV2 } from '@duckcodeailabs/dql-core';
+import type { AnalyticalExecutionGraphV1, AnalyticalExecutionReceiptV1 } from './analytical-execution-graph.js';
+export type AnalyticalResultFactKind = 'scope' | 'metric_value' | 'delta' | 'percent_delta' | 'rank' | 'freshness' | 'caveat';
+export interface AnalyticalResultFactV1 {
+    factId: string;
+    kind: AnalyticalResultFactKind;
+    receiptId: string;
+    graphFingerprint: string;
+    resultFingerprint: string;
+    outputIds: string[];
+    rowIndex?: number;
+    periodId?: string;
+    value?: unknown;
+    coordinates?: Record<string, unknown>;
+    code?: 'PARTIAL_CURRENT_PERIOD' | 'LATEST_COMPLETE_PERIOD' | 'MISSING_COMPARISON_VALUE' | 'ZERO_COMPARISON_DENOMINATOR';
+    details?: Record<string, unknown>;
+}
+export interface AnalyticalResultFactSetV1 {
+    version: 1;
+    factSetId: string;
+    planId: string;
+    graphId: string;
+    graphFingerprint: string;
+    receiptId: string;
+    resultFingerprint: string;
+    facts: AnalyticalResultFactV1[];
+}
+export type BuildAnalyticalResultFactsResult = {
+    status: 'ready';
+    factSet: AnalyticalResultFactSetV1;
+} | {
+    status: 'blocked';
+    code: 'RECEIPT_MISMATCH' | 'RESULT_CONTRACT_MISMATCH';
+    reason: string;
+};
+export interface AnalyticalNarrativeClaimV1 {
+    claimId: string;
+    factIds: string[];
+    text: string;
+}
+export interface AnalyticalNarrativeV1 {
+    version: 1;
+    factSetId: string;
+    text: string;
+    claims: AnalyticalNarrativeClaimV1[];
+}
+export type AnalyticalNarrativeValidationResult = {
+    status: 'valid';
+    citedFactIds: string[];
+} | {
+    status: 'invalid';
+    code: 'UNKNOWN_FACT' | 'UNSUPPORTED_NUMBER' | 'CAUSAL_CLAIM' | 'MATERIAL_CAVEAT_HIDDEN';
+    reason: string;
+    claimId?: string;
+};
+export declare function buildAnalyticalResultFacts(input: {
+    frame: AnalyticalQuestionFrameV2;
+    graph: AnalyticalExecutionGraphV1;
+    receipt: AnalyticalExecutionReceiptV1;
+    columns: string[];
+    rows: Array<Record<string, unknown>>;
+}): BuildAnalyticalResultFactsResult;
+export declare function renderDeterministicAnalyticalNarrative(input: {
+    frame: AnalyticalQuestionFrameV2;
+    factSet: AnalyticalResultFactSetV1;
+    maxRows?: number;
+}): AnalyticalNarrativeV1;
+export declare function validateAnalyticalNarrativeClaims(input: {
+    factSet: AnalyticalResultFactSetV1;
+    claims: AnalyticalNarrativeClaimV1[];
+}): AnalyticalNarrativeValidationResult;
+//# sourceMappingURL=analytical-result-facts.d.ts.map

package/dist/analytical-result-facts.d.ts.map

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

package/dist/analytical-result-facts.js

@@ -0,0 +1,301 @@
+/**
+ * Deterministic result facts and narration guards for RFC 0005. Numeric claims
+ * are copied only from validated graph outputs and every fact is bound to the
+ * terminal receipt. No causal explanation is inferred from analytical rows.
+ *
+ * Acceptance: AGT-020.
+ */
+import { createHash } from 'node:crypto';
+export function buildAnalyticalResultFacts(input) {
+    const { frame, graph, receipt } = input;
+    if (receipt.graphId !== graph.graphId ||
+        receipt.graphFingerprint !== graph.fingerprint ||
+        receipt.planId !== graph.planId ||
+        receipt.planFingerprint !== graph.planFingerprint) {
+        return {
+            status: 'blocked',
+            code: 'RECEIPT_MISMATCH',
+            reason: 'The result receipt does not bind the supplied graph and plan.',
+        };
+    }
+    const expected = frame.requestedOutputs.map((output) => output.id);
+    if (input.columns.length !== expected.length ||
+        expected.some((outputId, index) => input.columns[index] !== outputId) ||
+        input.rows.length !== receipt.rowCount ||
+        input.rows.some((row) => expected.some((outputId) => !Object.prototype.hasOwnProperty.call(row, outputId)))) {
+        return {
+            status: 'blocked',
+            code: 'RESULT_CONTRACT_MISMATCH',
+            reason: 'The validated rows do not match the frame output order or receipt row count.',
+        };
+    }
+    const dimensionOutputs = frame.requestedOutputs.filter((output) => output.kind === 'dimension');
+    const facts = [];
+    facts.push(makeFact(receipt, {
+        kind: 'scope',
+        outputIds: dimensionOutputs.map((output) => output.id),
+        details: {
+            entityGrainIds: [...frame.entityGrainIds],
+            dimensions: frame.dimensions.map((dimension) => ({ ...dimension })),
+            memberBindings: frame.memberBindings.map((binding) => ({
+                ...binding,
+                canonicalValues: [...binding.canonicalValues],
+            })),
+        },
+    }));
+    input.rows.forEach((row, rowIndex) => {
+        const coordinates = Object.fromEntries(dimensionOutputs.map((output) => [output.id, row[output.id]]));
+        for (const output of frame.requestedOutputs) {
+            if (output.kind === 'dimension')
+                continue;
+            facts.push(makeFact(receipt, {
+                kind: output.kind,
+                outputIds: [output.id],
+                rowIndex,
+                ...(output.periodId ? { periodId: output.periodId } : {}),
+                value: row[output.id],
+                ...(dimensionOutputs.length ? { coordinates } : {}),
+            }));
+        }
+        if (frame.comparison) {
+            for (const periodId of frame.comparison.comparisonPeriodIds) {
+                const comparisonOutput = frame.requestedOutputs.find((output) => output.kind === 'metric_value' && output.periodId === periodId);
+                if (comparisonOutput && row[comparisonOutput.id] == null) {
+                    facts.push(makeFact(receipt, {
+                        kind: 'caveat',
+                        code: 'MISSING_COMPARISON_VALUE',
+                        outputIds: [comparisonOutput.id],
+                        rowIndex,
+                        periodId,
+                        ...(dimensionOutputs.length ? { coordinates } : {}),
+                    }));
+                }
+                const percentOutput = frame.requestedOutputs.find((output) => output.kind === 'percent_delta');
+                if (comparisonOutput && percentOutput && isExactZero(row[comparisonOutput.id]) && row[percentOutput.id] == null) {
+                    facts.push(makeFact(receipt, {
+                        kind: 'caveat',
+                        code: 'ZERO_COMPARISON_DENOMINATOR',
+                        outputIds: [comparisonOutput.id, percentOutput.id],
+                        rowIndex,
+                        periodId,
+                        ...(dimensionOutputs.length ? { coordinates } : {}),
+                    }));
+                }
+            }
+        }
+    });
+    if (frame.timeContext) {
+        for (const period of frame.timeContext.periods) {
+            facts.push(makeFact(receipt, {
+                kind: 'freshness',
+                outputIds: frame.requestedOutputs
+                    .filter((output) => output.periodId === period.id)
+                    .map((output) => output.id),
+                periodId: period.id,
+                value: period.end,
+                details: {
+                    startInclusive: period.start,
+                    endExclusive: period.end,
+                    timeDimensionId: frame.timeContext.timeDimensionId,
+                    timeRole: frame.timeContext.timeRole,
+                    calendarId: frame.timeContext.calendarId,
+                    timezone: frame.timeContext.timezone,
+                    grain: frame.timeContext.grain,
+                    completenessPolicy: frame.timeContext.completenessPolicy,
+                },
+            }));
+        }
+        if (frame.timeContext.completenessPolicy === 'partial_current') {
+            facts.push(makeFact(receipt, {
+                kind: 'caveat',
+                code: 'PARTIAL_CURRENT_PERIOD',
+                outputIds: frame.requestedOutputs.filter((output) => output.periodId === frame.comparison?.basePeriodId || output.periodId === frame.timeContext?.periods[0]?.id).map((output) => output.id),
+                details: { completenessPolicy: frame.timeContext.completenessPolicy },
+            }));
+        }
+        if (frame.timeContext.completenessPolicy === 'latest_complete') {
+            facts.push(makeFact(receipt, {
+                kind: 'caveat',
+                code: 'LATEST_COMPLETE_PERIOD',
+                outputIds: frame.requestedOutputs.filter((output) => output.periodId === frame.comparison?.basePeriodId || output.periodId === frame.timeContext?.periods[0]?.id).map((output) => output.id),
+                details: { completenessPolicy: frame.timeContext.completenessPolicy },
+            }));
+        }
+    }
+    const payload = {
+        version: 1,
+        planId: graph.planId,
+        graphId: graph.graphId,
+        graphFingerprint: graph.fingerprint,
+        receiptId: receipt.receiptId,
+        resultFingerprint: receipt.resultFingerprint,
+        facts,
+    };
+    return {
+        status: 'ready',
+        factSet: deepFreeze({
+            ...payload,
+            factSetId: `analytical-facts:${hash(stableStringify(payload)).slice(0, 24)}`,
+        }),
+    };
+}
+export function renderDeterministicAnalyticalNarrative(input) {
+    const claims = [];
+    const outputById = new Map(input.frame.requestedOutputs.map((output) => [output.id, output]));
+    const rowFacts = new Map();
+    for (const fact of input.factSet.facts) {
+        if (fact.rowIndex === undefined || fact.kind === 'caveat')
+            continue;
+        const current = rowFacts.get(fact.rowIndex) ?? [];
+        current.push(fact);
+        rowFacts.set(fact.rowIndex, current);
+    }
+    const maxRows = Math.min(Math.max(1, input.maxRows ?? 5), 20);
+    for (const [rowIndex, facts] of [...rowFacts.entries()].sort(([left], [right]) => left - right).slice(0, maxRows)) {
+        const coordinates = facts.find((fact) => fact.coordinates)?.coordinates ?? {};
+        const coordinateText = Object.values(coordinates).map(displayValue).join(' · ');
+        const values = facts
+            .filter((fact) => fact.kind !== 'freshness')
+            .map((fact) => {
+            const outputId = fact.outputIds[0] ?? fact.kind;
+            const label = humanizeOutput(outputId, outputById.get(outputId)?.kind);
+            const suffix = fact.kind === 'percent_delta' && fact.value != null && fact.value !== 'not_applicable' ? '%' : '';
+            return `${label}: ${displayValue(fact.value)}${suffix}`;
+        });
+        const text = `${coordinateText ? `${coordinateText} — ` : ''}${values.join('; ')}.`;
+        claims.push({
+            claimId: `claim:row:${rowIndex}`,
+            factIds: facts.map((fact) => fact.factId),
+            text,
+        });
+    }
+    for (const freshness of input.factSet.facts.filter((fact) => fact.kind === 'freshness')) {
+        const start = displayValue(freshness.details?.startInclusive);
+        const end = displayValue(freshness.details?.endExclusive);
+        const policy = String(freshness.details?.completenessPolicy ?? 'declared completeness');
+        claims.push({
+            claimId: `claim:freshness:${freshness.factId}`,
+            factIds: [freshness.factId],
+            text: `${humanizeOutput(freshness.periodId ?? 'period')} covers ${start} through ${end} under the ${policy.replace(/_/g, ' ')} policy.`,
+        });
+    }
+    for (const caveat of input.factSet.facts.filter((fact) => fact.kind === 'caveat')) {
+        claims.push({
+            claimId: `claim:caveat:${caveat.factId}`,
+            factIds: [caveat.factId],
+            text: caveatText(caveat),
+        });
+    }
+    const text = claims.map((claim) => claim.text).join(' ');
+    return deepFreeze({ version: 1, factSetId: input.factSet.factSetId, text, claims });
+}
+export function validateAnalyticalNarrativeClaims(input) {
+    const facts = new Map(input.factSet.facts.map((fact) => [fact.factId, fact]));
+    const cited = new Set();
+    for (const claim of input.claims) {
+        if (/\b(?:because|caused?|causing|drove|driven by|led to|resulted in|responsible for)\b/i.test(claim.text)) {
+            return { status: 'invalid', code: 'CAUSAL_CLAIM', reason: 'Analytical result narration cannot infer causality.', claimId: claim.claimId };
+        }
+        const claimFacts = claim.factIds.flatMap((factId) => {
+            const fact = facts.get(factId);
+            return fact ? [fact] : [];
+        });
+        if (claimFacts.length !== claim.factIds.length || claimFacts.length === 0) {
+            return { status: 'invalid', code: 'UNKNOWN_FACT', reason: 'Every narrative claim must cite existing result facts.', claimId: claim.claimId };
+        }
+        claim.factIds.forEach((factId) => cited.add(factId));
+        const allowedNumbers = new Set(claimFacts.flatMap((fact) => numericTokens(stableStringify({
+            value: fact.value,
+            coordinates: fact.coordinates,
+            details: fact.details,
+            rowIndex: fact.rowIndex,
+            periodId: fact.periodId,
+        }))));
+        const unsupported = numericTokens(claim.text).filter((token) => !allowedNumbers.has(token));
+        if (unsupported.length > 0) {
+            return {
+                status: 'invalid',
+                code: 'UNSUPPORTED_NUMBER',
+                reason: `Claim ${claim.claimId} contains unsupported numeric text: ${unsupported.join(', ')}.`,
+                claimId: claim.claimId,
+            };
+        }
+    }
+    const hiddenCaveat = input.factSet.facts.find((fact) => fact.kind === 'caveat' && !cited.has(fact.factId));
+    if (hiddenCaveat) {
+        return {
+            status: 'invalid',
+            code: 'MATERIAL_CAVEAT_HIDDEN',
+            reason: `Material caveat ${hiddenCaveat.code ?? hiddenCaveat.factId} is not cited by the narrative.`,
+        };
+    }
+    return { status: 'valid', citedFactIds: [...cited].sort() };
+}
+function makeFact(receipt, input) {
+    const payload = {
+        ...input,
+        receiptId: receipt.receiptId,
+        graphFingerprint: receipt.graphFingerprint,
+        resultFingerprint: receipt.resultFingerprint,
+    };
+    return { ...payload, factId: `fact:${hash(stableStringify(payload)).slice(0, 24)}` };
+}
+function caveatText(fact) {
+    if (fact.code === 'PARTIAL_CURRENT_PERIOD')
+        return 'The current period is partial; values may increase before it closes.';
+    if (fact.code === 'LATEST_COMPLETE_PERIOD')
+        return 'The current value uses the latest complete governed period, not a partial in-progress period.';
+    if (fact.code === 'MISSING_COMPARISON_VALUE')
+        return `A comparison value is unavailable${coordinateSuffix(fact)}.`;
+    if (fact.code === 'ZERO_COMPARISON_DENOMINATOR')
+        return `Percentage change is not available; the comparison value is zero${coordinateSuffix(fact)}.`;
+    return 'The result includes a material analytical caveat.';
+}
+function coordinateSuffix(fact) {
+    const coordinates = Object.values(fact.coordinates ?? {}).map(displayValue).filter(Boolean);
+    return coordinates.length ? ` for ${coordinates.join(' · ')}` : '';
+}
+function humanizeOutput(value, kind) {
+    if (kind === 'percent_delta')
+        return 'change';
+    return value.replace(/[_-]+/g, ' ').replace(/\b\w/g, (letter) => letter.toUpperCase());
+}
+function displayValue(value) {
+    if (value === null || value === undefined)
+        return 'not available';
+    if (typeof value === 'string')
+        return value === 'not_applicable' ? 'not applicable' : value;
+    if (typeof value === 'number' || typeof value === 'bigint' || typeof value === 'boolean')
+        return String(value);
+    return JSON.stringify(value);
+}
+function isExactZero(value) {
+    return (typeof value === 'number' && value === 0) || (typeof value === 'bigint' && value === 0n) || (typeof value === 'string' && /^[+-]?0+(?:\.0+)?$/.test(value.trim()));
+}
+function numericTokens(value) {
+    return value.match(/-?\d+(?:,\d{3})*(?:\.\d+)?%?/g)?.map((token) => token.replace(/,/g, '').replace(/%$/, '')) ?? [];
+}
+function hash(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function stableStringify(value) {
+    if (value === undefined || value === null)
+        return 'null';
+    if (typeof value === 'bigint')
+        return JSON.stringify(value.toString());
+    if (typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(',')}}`;
+}
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const nested of Object.values(value))
+            deepFreeze(nested);
+    }
+    return value;
+}
+//# sourceMappingURL=analytical-result-facts.js.map

package/dist/analytical-result-facts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytical-result-facts.js","sourceRoot":"","sources":["../src/analytical-result-facts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA4EzC,MAAM,UAAU,0BAA0B,CAAC,KAM1C;IACC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IACxC,IACE,OAAO,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO;QACjC,OAAO,CAAC,gBAAgB,KAAK,KAAK,CAAC,WAAW;QAC9C,OAAO,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;QAC/B,OAAO,CAAC,eAAe,KAAK,KAAK,CAAC,eAAe,EACjD,CAAC;QACD,OAAO;YACL,MAAM,EAAE,SAAS;YACjB,IAAI,EAAE,kBAAkB;YACxB,MAAM,EAAE,+DAA+D;SACxE,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACnE,IACE,KAAK,CAAC,OAAO,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM;QACxC,QAAQ,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC;QACrE,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,OAAO,CAAC,QAAQ;QACtC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,EAC3G,CAAC;QACD,OAAO;YACL,MAAM,EAAE,SAAS;YACjB,IAAI,EAAE,0BAA0B;YAChC,MAAM,EAAE,8EAA8E;SACvF,CAAC;IACJ,CAAC;IACD,MAAM,gBAAgB,GAAG,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC;IAChG,MAAM,KAAK,GAA6B,EAAE,CAAC;IAC3C,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE;QAC3B,IAAI,EAAE,OAAO;QACb,SAAS,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;QACtD,OAAO,EAAE;YACP,cAAc,EAAE,CAAC,GAAG,KAAK,CAAC,cAAc,CAAC;YACzC,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;YACnE,cAAc,EAAE,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;gBACrD,GAAG,OAAO;gBACV,eAAe,EAAE,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC;aAC9C,CAAC,CAAC;SACJ;KACF,CAAC,CAAC,CAAC;IACJ,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE;QACnC,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACtG,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;YAC5C,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW;gBAAE,SAAS;YAC1C,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE;gBAC3B,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,SAAS,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;gBACtB,QAAQ;gBACR,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACzD,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBACrB,GAAG,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACpD,CAAC,CAAC,CAAC;QACN,CAAC;QACD,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;YACrB,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,mBAAmB,EAAE,CAAC;gBAC5D,MAAM,gBAAgB,GAAG,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAClD,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,cAAc,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAC3E,CAAC;gBACF,IAAI,gBAAgB,IAAI,GAAG,CAAC,gBAAgB,CAAC,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;oBACzD,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE;wBAC3B,IAAI,EAAE,QAAQ;wBACd,IAAI,EAAE,0BAA0B;wBAChC,SAAS,EAAE,CAAC,gBAAgB,CAAC,EAAE,CAAC;wBAChC,QAAQ;wBACR,QAAQ;wBACR,GAAG,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;qBACpD,CAAC,CAAC,CAAC;gBACN,CAAC;gBACD,MAAM,aAAa,GAAG,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,eAAe,CAAC,CAAC;gBAC/F,IAAI,gBAAgB,IAAI,aAAa,IAAI,WAAW,CAAC,GAAG,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,aAAa,CAAC,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;oBAChH,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE;wBAC3B,IAAI,EAAE,QAAQ;wBACd,IAAI,EAAE,6BAA6B;wBACnC,SAAS,EAAE,CAAC,gBAAgB,CAAC,EAAE,EAAE,aAAa,CAAC,EAAE,CAAC;wBAClD,QAAQ;wBACR,QAAQ;wBACR,GAAG,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;qBACpD,CAAC,CAAC,CAAC;gBACN,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IACH,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;QACtB,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;YAC/C,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE;gBAC3B,IAAI,EAAE,WAAW;gBACjB,SAAS,EAAE,KAAK,CAAC,gBAAgB;qBAC9B,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,KAAK,MAAM,CAAC,EAAE,CAAC;qBACjD,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC7B,QAAQ,EAAE,MAAM,CAAC,EAAE;gBACnB,KAAK,EAAE,MAAM,CAAC,GAAG;gBACjB,OAAO,EAAE;oBACP,cAAc,EAAE,MAAM,CAAC,KAAK;oBAC5B,YAAY,EAAE,MAAM,CAAC,GAAG;oBACxB,eAAe,EAAE,KAAK,CAAC,WAAW,CAAC,eAAe;oBAClD,QAAQ,EAAE,KAAK,CAAC,WAAW,CAAC,QAAQ;oBACpC,UAAU,EAAE,KAAK,CAAC,WAAW,CAAC,UAAU;oBACxC,QAAQ,EAAE,KAAK,CAAC,WAAW,CAAC,QAAQ;oBACpC,KAAK,EAAE,KAAK,CAAC,WAAW,CAAC,KAAK;oBAC9B,kBAAkB,EAAE,KAAK,CAAC,WAAW,CAAC,kBAAkB;iBACzD;aACF,CAAC,CAAC,CAAC;QACN,CAAC;QACD,IAAI,KAAK,CAAC,WAAW,CAAC,kBAAkB,KAAK,iBAAiB,EAAE,CAAC;YAC/D,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE;gBAC3B,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,wBAAwB;gBAC9B,SAAS,EAAE,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,KAAK,KAAK,CAAC,UAAU,EAAE,YAAY,IAAI,MAAM,CAAC,QAAQ,KAAK,KAAK,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC5L,OAAO,EAAE,EAAE,kBAAkB,EAAE,KAAK,CAAC,WAAW,CAAC,kBAAkB,EAAE;aACtE,CAAC,CAAC,CAAC;QACN,CAAC;QACD,IAAI,KAAK,CAAC,WAAW,CAAC,kBAAkB,KAAK,iBAAiB,EAAE,CAAC;YAC/D,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE;gBAC3B,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,wBAAwB;gBAC9B,SAAS,EAAE,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,KAAK,KAAK,CAAC,UAAU,EAAE,YAAY,IAAI,MAAM,CAAC,QAAQ,KAAK,KAAK,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC5L,OAAO,EAAE,EAAE,kBAAkB,EAAE,KAAK,CAAC,WAAW,CAAC,kBAAkB,EAAE;aACtE,CAAC,CAAC,CAAC;QACN,CAAC;IACH,CAAC;IACD,MAAM,OAAO,GAAG;QACd,OAAO,EAAE,CAAU;QACnB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,gBAAgB,EAAE,KAAK,CAAC,WAAW;QACnC,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,iBAAiB,EAAE,OAAO,CAAC,iBAAiB;QAC5C,KAAK;KACN,CAAC;IACF,OAAO;QACL,MAAM,EAAE,OAAO;QACf,OAAO,EAAE,UAAU,CAAC;YAClB,GAAG,OAAO;YACV,SAAS,EAAE,oBAAoB,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE;SAC7E,CAAC;KACH,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sCAAsC,CAAC,KAItD;IACC,MAAM,MAAM,GAAiC,EAAE,CAAC;IAChD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC9F,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAoC,CAAC;IAC7D,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACvC,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,SAAS;QACpE,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QAClD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC9D,KAAK,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC;QAClH,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,WAAW,IAAI,EAAE,CAAC;QAC9E,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChF,MAAM,MAAM,GAAG,KAAK;aACjB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,WAAW,CAAC;aAC3C,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;YACZ,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC;YAChD,MAAM,KAAK,GAAG,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,CAAC;YACvE,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,KAAK,eAAe,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,IAAI,IAAI,CAAC,KAAK,KAAK,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YACjH,OAAO,GAAG,KAAK,KAAK,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,MAAM,EAAE,CAAC;QAC1D,CAAC,CAAC,CAAC;QACL,MAAM,IAAI,GAAG,GAAG,cAAc,CAAC,CAAC,CAAC,GAAG,cAAc,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QACpF,MAAM,CAAC,IAAI,CAAC;YACV,OAAO,EAAE,aAAa,QAAQ,EAAE;YAChC,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC;YACzC,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IACD,KAAK,MAAM,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,WAAW,CAAC,EAAE,CAAC;QACxF,MAAM,KAAK,GAAG,YAAY,CAAC,SAAS,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;QAC9D,MAAM,GAAG,GAAG,YAAY,CAAC,SAAS,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAC1D,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,kBAAkB,IAAI,uBAAuB,CAAC,CAAC;QACxF,MAAM,CAAC,IAAI,CAAC;YACV,OAAO,EAAE,mBAAmB,SAAS,CAAC,MAAM,EAAE;YAC9C,OAAO,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC;YAC3B,IAAI,EAAE,GAAG,cAAc,CAAC,SAAS,CAAC,QAAQ,IAAI,QAAQ,CAAC,WAAW,KAAK,YAAY,GAAG,cAAc,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,UAAU;SACxI,CAAC,CAAC;IACL,CAAC;IACD,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,EAAE,CAAC;QAClF,MAAM,CAAC,IAAI,CAAC;YACV,OAAO,EAAE,gBAAgB,MAAM,CAAC,MAAM,EAAE;YACxC,OAAO,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC;YACxB,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC;SACzB,CAAC,CAAC;IACL,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzD,OAAO,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;AACtF,CAAC;AAED,MAAM,UAAU,iCAAiC,CAAC,KAGjD;IACC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9E,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACjC,IAAI,qFAAqF,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3G,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,qDAAqD,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;QAC5I,CAAC;QACD,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE;YAClD,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC/B,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5B,CAAC,CAAC,CAAC;QACH,IAAI,UAAU,CAAC,MAAM,KAAK,KAAK,CAAC,OAAO,CAAC,MAAM,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1E,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,wDAAwD,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;QAC/I,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;QACrD,MAAM,cAAc,GAAG,IAAI,GAAG,CAC5B,UAAU,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,eAAe,CAAC;YACzD,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;SACxB,CAAC,CAAC,CAAC,CACL,CAAC;QACF,MAAM,WAAW,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5F,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,OAAO;gBACL,MAAM,EAAE,SAAS;gBACjB,IAAI,EAAE,oBAAoB;gBAC1B,MAAM,EAAE,SAAS,KAAK,CAAC,OAAO,uCAAuC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBAC9F,OAAO,EAAE,KAAK,CAAC,OAAO;aACvB,CAAC;QACJ,CAAC;IACH,CAAC;IACD,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3G,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO;YACL,MAAM,EAAE,SAAS;YACjB,IAAI,EAAE,wBAAwB;YAC9B,MAAM,EAAE,mBAAmB,YAAY,CAAC,IAAI,IAAI,YAAY,CAAC,MAAM,iCAAiC;SACrG,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;AAC9D,CAAC;AAED,SAAS,QAAQ,CACf,OAAqC,EACrC,KAAsG;IAEtG,MAAM,OAAO,GAAG;QACd,GAAG,KAAK;QACR,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;QAC1C,iBAAiB,EAAE,OAAO,CAAC,iBAAiB;KAC7C,CAAC;IACF,OAAO,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,QAAQ,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;AACvF,CAAC;AAED,SAAS,UAAU,CAAC,IAA4B;IAC9C,IAAI,IAAI,CAAC,IAAI,KAAK,wBAAwB;QAAE,OAAO,sEAAsE,CAAC;IAC1H,IAAI,IAAI,CAAC,IAAI,KAAK,wBAAwB;QAAE,OAAO,+FAA+F,CAAC;IACnJ,IAAI,IAAI,CAAC,IAAI,KAAK,0BAA0B;QAAE,OAAO,oCAAoC,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC;IACnH,IAAI,IAAI,CAAC,IAAI,KAAK,6BAA6B;QAAE,OAAO,mEAAmE,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC;IACrJ,OAAO,mDAAmD,CAAC;AAC7D,CAAC;AAED,SAAS,gBAAgB,CAAC,IAA4B;IACpD,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC5F,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACrE,CAAC;AAED,SAAS,cAAc,CAAC,KAAa,EAAE,IAAa;IAClD,IAAI,IAAI,KAAK,eAAe;QAAE,OAAO,QAAQ,CAAC;IAC9C,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;AACzF,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,eAAe,CAAC;IAClE,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,KAAK,gBAAgB,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,KAAK,CAAC;IAC5F,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/G,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,CAAC,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AAC7K,CAAC;AAED,SAAS,aAAa,CAAC,KAAa;IAClC,OAAO,KAAK,CAAC,KAAK,CAAC,+BAA+B,CAAC,EAAE,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACvH,CAAC;AAED,SAAS,IAAI,CAAC,KAAa;IACzB,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IACzD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;IACvE,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC5D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAC7E,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,eAAe,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAC5H,CAAC;AAED,SAAS,UAAU,CAAI,KAAQ;IAC7B,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAClE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrB,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,KAAgC,CAAC;YAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC3F,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/answer-loop.d.ts

@@ -14,7 +14,7 @@
  * step. Tests can mock the provider with a canned response and exercise the
  * full pipeline.
  */
-import { type SemanticLayer, type ResolvedTrustLabel, type TrustLabelId, type DqlArtifactReference, type DqlArtifactExecutionReceipt, type DQLManifest } from '@duckcodeailabs/dql-core';
+import { type SemanticLayer, type ResolvedTrustLabel, type TrustLabelId, type DqlArtifactReference, type DqlArtifactExecutionReceipt, type DQLManifest, type AnalyticalFailureV1 } from '@duckcodeailabs/dql-core';
 import type { KGStore } from './kg/sqlite-fts.js';
 import type { KGNode, KGSearchHit } from './kg/types.js';
 import type { AgentProvider, AgentToolDefinition } from './providers/types.js';
@@ -34,8 +34,11 @@ import { type AnalyticalExploratoryPath, type AnalyticalPolicyCode } from './met
 import { type SemanticFilterValueBinding, type SemanticMemberSelection } from './semantic-bridge/compose.js';
 import { type CascadeAnswerResult } from './cascade/cascade.js';
 import { type ResolvedAnalyticalPlan, type ResolvedAnalyticalPlanDelta } from './resolved-analytical-plan.js';
-import { type PlanExecutionBinding, type PlanExecutionBlockedCode } from './plan-execution-adapter.js';
-import { type GovernedCompilationReceipt, type GovernedRelationalCompileResult } from './governed-relational-compiler.js';
+import { type PlanExecutionBinding, type PlanExecutionBlockedCode, type SemanticGraphExecutionBinding } from './plan-execution-adapter.js';
+import { type GovernedCompilationReceipt, type GovernedAnalyticalGraphCompilationReceipt, type GovernedAnalyticalGraphCompileResult, type GovernedRelationalCompileResult } from './governed-relational-compiler.js';
+import { type AnalyticalExecutionGraphBlockedCode, type AnalyticalExecutionGraphV1, type AnalyticalExecutionReceiptV1, type AnalyticalGraphExecutionFailureCode } from './analytical-execution-graph.js';
+import { type AnalyticalNarrativeV1, type AnalyticalResultFactSetV1 } from './analytical-result-facts.js';
+import { type AnalyticalFreshnessObservationV1, type AnalyticalFreshnessRequestV1, type ResolveAnalyticalPeriodsResult } from './analytical-period-resolution.js';
 import { type CascadeAnalysisDepth, type PartialCascadeBudgetModel } from './cascade/budgets.js';
 export type AnswerKind = 'certified' | 'uncertified' | 'no_answer';
 export type AnswerSourceTier = 'certified_artifact' | 'business_context' | 'semantic_layer' | 'dbt_manifest' | 'no_answer';
@@ -85,7 +88,11 @@ export interface AgentRefusalDetails {
      * grounding gaps, this preserves the exact validation code so repair loops can
      * re-ground the named identifier instead of parsing prose.
      */
-    code?: AnswerRefusalCode | SqlContextValidationCode | AnalyticalPolicyCode | PlanExecutionBlockedCode | 'semantic_runtime_required';
+    code?: AnswerRefusalCode | SqlContextValidationCode | AnalyticalPolicyCode | PlanExecutionBlockedCode | AnalyticalExecutionGraphBlockedCode | AnalyticalGraphExecutionFailureCode | Extract<ResolveAnalyticalPeriodsResult, {
+        status: 'blocked';
+    }>['code'] | Extract<GovernedAnalyticalGraphCompileResult, {
+        status: 'blocked';
+    }>['code'] | 'COMPILATION_FAILED' | 'EXECUTION_FAILED' | 'semantic_runtime_required';
     message: string;
     offending?: SqlContextValidationOffending;
 }
@@ -326,8 +333,22 @@ export interface AgentAnswer {
     resolvedAnalyticalPlan?: ResolvedAnalyticalPlan;
     /** Versioned identity-only executable projection of the resolved plan. */
     executablePlan?: PlanExecutionBinding;
+    /** Immutable multi-period graph compiled from the v2 plan. */
+    analyticalExecutionGraph?: AnalyticalExecutionGraphV1;
+    /** Terminal receipt binding every source execution and validated output. */
+    analyticalExecutionReceipt?: AnalyticalExecutionReceiptV1;
+    /** Deterministic facts copied from validated result columns and bound to the receipt. */
+    analyticalFacts?: AnalyticalResultFactSetV1;
+    /** Business narration whose every claim cites those facts. */
+    analyticalNarrative?: AnalyticalNarrativeV1;
+    /** Snapshot-bound freshness proof used to resolve relative periods. */
+    analyticalFreshnessObservation?: AnalyticalFreshnessObservationV1;
+    /** Stable redacted diagnostics for the immutable failed analytical run. */
+    analyticalFailure?: AnalyticalFailureV1;
     /** Compiler/result receipt for the authoritative governed relational lane. */
     governedCompilationReceipt?: GovernedCompilationReceipt;
+    /** Multi-statement compilation receipt for a governed relational graph. */
+    governedAnalyticalGraphCompilationReceipt?: GovernedAnalyticalGraphCompilationReceipt;
     /** Final answer text (NL summary). */
     text: string;
     /**
@@ -455,8 +476,34 @@ export interface AnswerLoopInput {
     resolvedAnalyticalPlan?: ResolvedAnalyticalPlan;
     /** Internal: the single adapter result prepared once at the answer boundary. */
     resolvedPlanExecutionBinding?: PlanExecutionBinding;
+    /** Internal: immutable route-neutral graph prepared once at the answer boundary. */
+    analyticalExecutionGraph?: AnalyticalExecutionGraphV1;
+    /** Internal: deterministic graph-build gap; never reopens routing. */
+    analyticalExecutionGraphFailure?: {
+        code: AnalyticalExecutionGraphBlockedCode;
+        reason: string;
+        field?: string;
+    };
+    /** Internal: governed relative-time binding gap; never reopens routing. */
+    analyticalPeriodResolutionFailure?: {
+        code: Extract<ResolveAnalyticalPeriodsResult, {
+            status: 'blocked';
+        }>['code'];
+        reason: string;
+        error?: unknown;
+    };
+    /** Internal: exact per-period semantic adapter selections. */
+    semanticGraphExecutionBinding?: SemanticGraphExecutionBinding;
     /** Internal: constrained AST/SQL compilation prepared at the answer boundary. */
     governedRelationalCompilation?: GovernedRelationalCompileResult;
+    /** Internal: per-period governed relational graph compilation. */
+    governedAnalyticalGraphCompilation?: GovernedAnalyticalGraphCompileResult;
+    /** Captured once by the host for deterministic relative-period resolution. */
+    analyticalReferenceInstant?: string;
+    /** Optional pre-fetched authorized freshness proof for this snapshot. */
+    analyticalFreshnessObservation?: AnalyticalFreshnessObservationV1;
+    /** At most one authorized freshness lookup; it cannot search or change route. */
+    resolveAnalyticalFreshness?: (request: AnalyticalFreshnessRequestV1) => Promise<AnalyticalFreshnessObservationV1>;
     /**
      * Current notebook/app context, such as upstream SQL or selected filters.
      * This is prompt context only. It is intentionally excluded from KG and