@duckcodeailabs/dql-agent 1.10.0 → 1.10.1

package/dist/analytical-frame.js

@@ -0,0 +1,299 @@
+/**
+ * Zero-provider construction of an RFC 0005 analytical frame from an already
+ * resolved metric, parsed request hints, retrieved semantic members, and an
+ * explicit normalized capability contract.
+ *
+ * This is intentionally conservative: unresolved roles become ambiguity or no
+ * frame instead of name-based execution authority.
+ *
+ * Acceptance: AGT-017, AGT-018.
+ */
+import { normalizeMetricCapabilityContract } from '@duckcodeailabs/dql-core';
+import { questionTypeFromText } from './meaning-resolution.js';
+export function buildDeterministicAnalyticalFrame(input) {
+    const capability = normalizeMetricCapabilityContract(input.metricCandidate.analyticalCapability);
+    if (!capability)
+        return undefined;
+    const meaningType = questionTypeFromText(input.question);
+    if (meaningType === 'definition')
+        return undefined;
+    const queryIntent = {
+        measures: input.evidence.parsedIntent?.measures ?? [],
+        dimensions: input.evidence.parsedIntent?.dimensions ?? [],
+        filters: input.evidence.parsedIntent?.filters ?? [],
+        ...(input.evidence.parsedIntent?.timeRange ? { timeRange: input.evidence.parsedIntent.timeRange } : {}),
+        ...(input.evidence.parsedIntent?.timeGrain ? { timeGrain: input.evidence.parsedIntent.timeGrain } : {}),
+        ...(input.evidence.parsedIntent?.order ? { order: input.evidence.parsedIntent.order } : {}),
+        ...(input.evidence.parsedIntent?.limit !== undefined ? { limit: input.evidence.parsedIntent.limit } : {}),
+    };
+    const requestedDimensionTerms = new Set(queryIntent.dimensions.map(normalize).filter(Boolean));
+    for (const filter of queryIntent.filters)
+        requestedDimensionTerms.add(normalize(filter.field));
+    for (const candidate of input.candidates) {
+        if (candidate.kind !== 'semantic_member')
+            continue;
+        const capabilityDimension = resolveCapabilityDimension(candidate.qualifiedId ?? candidate.id, capability);
+        if (!capabilityDimension)
+            continue;
+        const terms = [candidate.name, ...(candidate.aliases ?? [])].map(normalize).filter(Boolean);
+        if (terms.some((term) => phraseAppears(input.question, term))) {
+            requestedDimensionTerms.add(normalize(candidate.qualifiedId ?? candidate.id));
+        }
+    }
+    const ambiguity = [];
+    const resolvedDimensions = new Map();
+    for (const requested of requestedDimensionTerms) {
+        const matches = resolveDimensionTerm(requested, capability, input.candidates);
+        if (matches.length === 1)
+            resolvedDimensions.set(matches[0].dimensionId, matches[0]);
+        else if (matches.length > 1) {
+            ambiguity.push({
+                field: `dimensions.${requested}`,
+                candidateIds: matches.map((dimension) => dimension.dimensionId).sort(),
+                reasonCode: 'DIMENSION_AMBIGUOUS',
+            });
+        }
+    }
+    const filterDimensionIds = new Set();
+    const memberBindings = [];
+    for (const filter of queryIntent.filters) {
+        const matches = resolveDimensionTerm(normalize(filter.field), capability, input.candidates);
+        if (matches.length !== 1)
+            continue;
+        const dimension = matches[0];
+        filterDimensionIds.add(dimension.dimensionId);
+        resolvedDimensions.set(dimension.dimensionId, dimension);
+        memberBindings.push({
+            dimensionId: dimension.dimensionId,
+            canonicalValues: [filter.value],
+            source: 'question',
+            confidence: 'exact',
+        });
+    }
+    const rankingRequested = meaningType === 'ranking' || queryIntent.limit !== undefined || /\b(top|bottom|highest|lowest|rank)\b/i.test(input.question);
+    const groupRequested = rankingRequested || /\b(by|per|for each|breakdown)\b/i.test(input.question);
+    const dimensions = [];
+    for (const dimension of resolvedDimensions.values()) {
+        const onlyFilter = filterDimensionIds.has(dimension.dimensionId) && !groupRequested;
+        if (onlyFilter) {
+            dimensions.push({ dimensionId: dimension.dimensionId, role: 'filter' });
+            continue;
+        }
+        if (dimension.supportedRoles.includes('group_by')) {
+            dimensions.push({ dimensionId: dimension.dimensionId, role: 'group_by' });
+            if (rankingRequested && dimension.supportedRoles.includes('rank_entity')) {
+                dimensions.push({
+                    dimensionId: dimension.dimensionId,
+                    role: 'rank_entity',
+                });
+            }
+        }
+        else if (filterDimensionIds.has(dimension.dimensionId)) {
+            dimensions.push({ dimensionId: dimension.dimensionId, role: 'filter' });
+        }
+    }
+    const timeRequested = Boolean(queryIntent.timeRange || queryIntent.timeGrain) ||
+        /\b(today|current|this (?:day|week|month|quarter|year)|month[ -]to[ -]date|mtd|last year|previous year|year over year|yoy)\b/i.test(input.question);
+    const previousYearRequested = /\b(last year|previous year|year over year|yoy)\b/i.test(input.question);
+    const currentRequested = /\b(today|current|this (?:day|week|month|quarter|year)|month[ -]to[ -]date|mtd)\b/i.test(input.question) || previousYearRequested;
+    const timeContext = timeRequested
+        ? {
+            ...(capability.timeDimensions.length === 1
+                ? {
+                    timeDimensionId: capability.timeDimensions[0].dimensionId,
+                    timeRole: capability.timeDimensions[0].role,
+                }
+                : {}),
+            grain: queryIntent.timeGrain ?? inferTimeGrain(input.question),
+            ...(capability.freshness?.defaultCompletenessPolicy
+                ? {
+                    completenessPolicy: capability.freshness.defaultCompletenessPolicy,
+                }
+                : {}),
+            periods: [
+                ...(currentRequested ? [{ id: 'current', kind: 'current' }] : []),
+                ...(previousYearRequested
+                    ? [
+                        {
+                            id: 'previous_year',
+                            kind: 'previous_year',
+                            alignToPeriodId: 'current',
+                        },
+                    ]
+                    : []),
+                ...(!currentRequested && queryIntent.timeRange ? [{ id: 'requested_period', kind: 'absolute' }] : []),
+            ],
+        }
+        : undefined;
+    if (timeContext) {
+        for (const policy of input.evidence.analyticalPolicies ?? []) {
+            if (policy.metricIds?.length && !policy.metricIds.includes(capability.metricId))
+                continue;
+            timeContext.timeRole ??= policy.timeRole;
+            timeContext.calendarId ??= policy.calendarId;
+            timeContext.timezone ??= policy.timezone;
+            timeContext.completenessPolicy ??= policy.completenessPolicy;
+        }
+        dimensions.push({
+            dimensionId: capability.timeDimensions.length === 1 ? capability.timeDimensions[0].dimensionId : '',
+            role: 'time_axis',
+        });
+    }
+    const filteredDimensions = dimensions.filter((dimension) => Boolean(dimension.dimensionId));
+    const grouped = [...resolvedDimensions.values()].filter((dimension) => filteredDimensions.some((binding) => binding.dimensionId === dimension.dimensionId && (binding.role === 'group_by' || binding.role === 'rank_entity')));
+    const entityGrainIds = grouped.length > 0 ? [...new Set(grouped.map((dimension) => dimension.entityId))] : [capability.defaultResultGrainId];
+    const comparison = previousYearRequested
+        ? {
+            basePeriodId: 'current',
+            comparisonPeriodIds: ['previous_year'],
+            outputs: ['value', 'absolute_delta', 'percent_delta'],
+            zeroDenominatorPolicy: 'null',
+        }
+        : undefined;
+    const rankDimension = filteredDimensions.find((dimension) => dimension.role === 'rank_entity');
+    const ranking = rankingRequested && rankDimension
+        ? {
+            entityDimensionId: rankDimension.dimensionId,
+            byMetricId: capability.metricId,
+            ...(currentRequested ? { byPeriodId: 'current' } : {}),
+            direction: queryIntent.order ?? (/\b(bottom|lowest)\b/i.test(input.question) ? 'asc' : 'desc'),
+            limit: queryIntent.limit ?? extractLimit(input.question) ?? 10,
+            tiePolicy: 'stable_secondary_key',
+        }
+        : undefined;
+    const localMetric = localId(capability.metricId);
+    const projectedTimeDimensions = meaningType === 'trend' && timeContext?.timeDimensionId
+        ? [{
+                dimensionId: timeContext.timeDimensionId,
+                outputId: localId(timeContext.timeDimensionId),
+            }]
+        : [];
+    const requestedOutputs = [
+        ...grouped.map((dimension) => ({
+            id: localId(dimension.dimensionId),
+            kind: 'dimension',
+        })),
+        ...projectedTimeDimensions.map((dimension) => ({
+            id: dimension.outputId,
+            kind: 'dimension',
+        })),
+        ...(comparison
+            ? [
+                {
+                    id: `${localMetric}__current`,
+                    kind: 'metric_value',
+                    metricId: capability.metricId,
+                    periodId: 'current',
+                },
+                {
+                    id: `${localMetric}__previous_year`,
+                    kind: 'metric_value',
+                    metricId: capability.metricId,
+                    periodId: 'previous_year',
+                },
+                {
+                    id: `${localMetric}__delta`,
+                    kind: 'delta',
+                    metricId: capability.metricId,
+                },
+                {
+                    id: `${localMetric}__percent_delta`,
+                    kind: 'percent_delta',
+                    metricId: capability.metricId,
+                },
+            ]
+            : [
+                {
+                    id: localMetric,
+                    kind: 'metric_value',
+                    metricId: capability.metricId,
+                    ...(timeContext?.periods[0]?.id ? { periodId: timeContext.periods[0].id } : {}),
+                },
+            ]),
+        ...(ranking ? [{ id: 'rank', kind: 'rank' }] : []),
+    ];
+    return {
+        version: 2,
+        interpretedQuestion: input.question.trim(),
+        questionType: meaningType === 'value' ? 'scalar' : meaningType,
+        metricConceptIds: [capability.metricId],
+        entityGrainIds,
+        dimensions: filteredDimensions,
+        memberBindings,
+        ...(timeContext ? { timeContext } : {}),
+        ...(comparison ? { comparison } : {}),
+        ...(ranking ? { ranking } : {}),
+        requestedOutputs,
+        ambiguity,
+    };
+}
+function resolveDimensionTerm(requested, capability, candidates) {
+    const candidateIds = new Set();
+    for (const candidate of candidates) {
+        if (candidate.kind !== 'semantic_member')
+            continue;
+        const terms = [candidate.name, ...(candidate.aliases ?? []), candidate.qualifiedId ?? '', candidate.id].map(normalize).filter(Boolean);
+        if (terms.some((term) => termsMatch(term, requested))) {
+            candidateIds.add(candidate.qualifiedId ?? candidate.id);
+        }
+    }
+    return capability.dimensions.filter((dimension) => termsMatch(normalize(dimension.dimensionId), requested) || candidateIds.has(dimension.dimensionId));
+}
+function resolveCapabilityDimension(id, capability) {
+    return capability.dimensions.find((dimension) => dimension.dimensionId === id || termsMatch(normalize(dimension.dimensionId), normalize(id)));
+}
+function phraseAppears(question, phrase) {
+    const questionTokens = new Set(normalize(question).split(' ').map(singularize));
+    const significant = phrase
+        .split(' ')
+        .map(singularize)
+        .filter((token) => token.length >= 3 && !['name', 'dimension'].includes(token));
+    return significant.length > 0 && significant.some((token) => questionTokens.has(token));
+}
+function termsMatch(left, right) {
+    if (!left || !right)
+        return false;
+    if (left === right || left.endsWith(` ${right}`) || right.endsWith(` ${left}`))
+        return true;
+    const leftTokens = new Set(left.split(' ').map(singularize));
+    const rightTokens = right
+        .split(' ')
+        .map(singularize)
+        .filter((token) => token.length >= 3);
+    return rightTokens.length > 0 && rightTokens.every((token) => leftTokens.has(token));
+}
+function normalize(value) {
+    return value
+        .toLowerCase()
+        .replace(/[_./:-]+/g, ' ')
+        .replace(/[^a-z0-9 ]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function singularize(value) {
+    return value.length > 3 && value.endsWith('s') ? value.slice(0, -1) : value;
+}
+function localId(value) {
+    return (value
+        .split(/::|[:./]/)
+        .filter(Boolean)
+        .at(-1) ?? value);
+}
+function inferTimeGrain(question) {
+    if (/\b(today|day|daily)\b/i.test(question))
+        return 'day';
+    if (/\b(week|weekly)\b/i.test(question))
+        return 'week';
+    if (/\b(month|monthly|mtd)\b/i.test(question))
+        return 'day';
+    if (/\b(quarter|quarterly)\b/i.test(question))
+        return 'quarter';
+    if (/\b(year|yearly|annual|yoy)\b/i.test(question))
+        return 'year';
+    return undefined;
+}
+function extractLimit(question) {
+    const match = /\b(?:top|bottom)\s+(\d{1,4})\b/i.exec(question);
+    return match ? Math.max(1, Number(match[1])) : undefined;
+}
+//# sourceMappingURL=analytical-frame.js.map

package/dist/analytical-frame.js.map

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

package/dist/analytical-period-resolution.d.ts

@@ -0,0 +1,53 @@
+import type { AnalyticalQuestionFrameV2 } from '@duckcodeailabs/dql-core';
+/** Snapshot-bound freshness observation supplied by an authorized runtime. */
+export interface AnalyticalFreshnessObservationV1 {
+    version: 1;
+    snapshotId: string;
+    metricId: string;
+    timeDimensionId: string;
+    /** Maximum governed event/reporting instant visible to the selected route. */
+    observedThrough: string;
+    observedAt?: string;
+}
+export interface AnalyticalFreshnessRequestV1 {
+    version: 1;
+    snapshotId: string;
+    metricId: string;
+    timeDimensionId: string;
+    observedThroughFieldId?: string;
+    /**
+     * Exact adapter members resolved from the immutable plan and pinned registry.
+     * The host may execute this bounded lookup, but must not search, rematch, or
+     * change the selected metric/time route. Acceptance: AGT-019, SEC-004.
+     */
+    authorizedAdapterRequest?: {
+        route: 'semantic';
+        metric: string;
+        timeDimension: string;
+        granularity: string;
+        outputField: string;
+    };
+}
+export type ResolveAnalyticalPeriodsResult = {
+    status: 'resolved';
+    frame: AnalyticalQuestionFrameV2;
+    asOf: string;
+    freshnessObservation?: AnalyticalFreshnessObservationV1;
+} | {
+    status: 'blocked';
+    code: 'TIME_CONTEXT_REQUIRED' | 'TIME_POLICY_INCOMPLETE' | 'FRESHNESS_REQUIRED' | 'FRESHNESS_MISMATCH' | 'UNSUPPORTED_CALENDAR' | 'UNSUPPORTED_TIME_GRAIN' | 'EXPLICIT_PERIOD_BOUNDS_REQUIRED' | 'INVALID_TIME_INSTANT';
+    reason: string;
+};
+/**
+ * Resolve relative analytical periods without interpreting prose or choosing a
+ * time dimension. Meaning is already frozen in the frame; this function only
+ * binds governed temporal policy to concrete start-inclusive/end-exclusive
+ * instants. Acceptance: AGT-017, AGT-019, E2E-013.
+ */
+export declare function resolveAnalyticalPeriods(input: {
+    frame: AnalyticalQuestionFrameV2;
+    snapshotId: string;
+    referenceInstant: string;
+    freshnessObservation?: AnalyticalFreshnessObservationV1;
+}): ResolveAnalyticalPeriodsResult;
+//# sourceMappingURL=analytical-period-resolution.d.ts.map

package/dist/analytical-period-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytical-period-resolution.d.ts","sourceRoot":"","sources":["../src/analytical-period-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAE9F,8EAA8E;AAC9E,MAAM,WAAW,gCAAgC;IAC/C,OAAO,EAAE,CAAC,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,CAAC,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,wBAAwB,CAAC,EAAE;QACzB,KAAK,EAAE,UAAU,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,EAAE,MAAM,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,MAAM,8BAA8B,GACtC;IACE,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,yBAAyB,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,gCAAgC,CAAC;CACzD,GACD;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EACA,uBAAuB,GACvB,wBAAwB,GACxB,oBAAoB,GACpB,oBAAoB,GACpB,sBAAsB,GACtB,wBAAwB,GACxB,iCAAiC,GACjC,sBAAsB,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEN;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,KAAK,EAAE,yBAAyB,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,gCAAgC,CAAC;CACzD,GAAG,8BAA8B,CAmFjC"}

package/dist/analytical-period-resolution.js

@@ -0,0 +1,218 @@
+/**
+ * Resolve relative analytical periods without interpreting prose or choosing a
+ * time dimension. Meaning is already frozen in the frame; this function only
+ * binds governed temporal policy to concrete start-inclusive/end-exclusive
+ * instants. Acceptance: AGT-017, AGT-019, E2E-013.
+ */
+export function resolveAnalyticalPeriods(input) {
+    const time = input.frame.timeContext;
+    if (!time)
+        return { status: 'resolved', frame: structuredClone(input.frame), asOf: input.referenceInstant };
+    if (!time.timeDimensionId || !time.timeRole || !time.calendarId || !time.timezone || !time.grain || !time.completenessPolicy) {
+        return { status: 'blocked', code: 'TIME_POLICY_INCOMPLETE', reason: 'Relative periods require an exact time dimension, role, calendar, timezone, grain, and completeness policy.' };
+    }
+    if (!['calendar:gregorian', 'gregorian'].includes(time.calendarId.toLowerCase())) {
+        return { status: 'blocked', code: 'UNSUPPORTED_CALENDAR', reason: `Calendar ${time.calendarId} requires a configured calendar adapter.` };
+    }
+    if (!['day', 'week', 'month', 'quarter', 'year'].includes(time.grain.toLowerCase())) {
+        return { status: 'blocked', code: 'UNSUPPORTED_TIME_GRAIN', reason: `Time grain ${time.grain} is not supported by the Gregorian period resolver.` };
+    }
+    const reference = parseInstant(input.referenceInstant);
+    if (!reference)
+        return { status: 'blocked', code: 'INVALID_TIME_INSTANT', reason: 'The analytical reference instant is invalid.' };
+    const needsFreshness = time.periods.some((period) => !period.start || !period.end)
+        && time.completenessPolicy !== 'partial_current';
+    const freshness = input.freshnessObservation;
+    if (needsFreshness && !freshness) {
+        return { status: 'blocked', code: 'FRESHNESS_REQUIRED', reason: 'Latest-complete and closed-period execution require a snapshot-bound freshness observation.' };
+    }
+    if (freshness
+        && (freshness.version !== 1
+            || freshness.snapshotId !== input.snapshotId
+            || freshness.metricId !== input.frame.metricConceptIds[0]
+            || freshness.timeDimensionId !== time.timeDimensionId)) {
+        return { status: 'blocked', code: 'FRESHNESS_MISMATCH', reason: 'The freshness observation does not match the selected snapshot, metric, and time dimension.' };
+    }
+    const observedThrough = freshness ? parseInstant(freshness.observedThrough) : undefined;
+    if (freshness && !observedThrough) {
+        return { status: 'blocked', code: 'INVALID_TIME_INSTANT', reason: 'The freshness observation instant is invalid.' };
+    }
+    const resolved = new Map();
+    for (const period of time.periods) {
+        if (period.start && period.end) {
+            if (!parseInstant(period.start) || !parseInstant(period.end)) {
+                return { status: 'blocked', code: 'INVALID_TIME_INSTANT', reason: `Period ${period.id} contains an invalid bound.` };
+            }
+            resolved.set(period.id, { ...period });
+            continue;
+        }
+        if (period.kind === 'absolute') {
+            return { status: 'blocked', code: 'EXPLICIT_PERIOD_BOUNDS_REQUIRED', reason: `Absolute period ${period.id} requires explicit bounds.` };
+        }
+        if (period.kind === 'previous_year' || period.kind === 'previous_period')
+            continue;
+        const bounds = currentBounds({
+            reference,
+            observedThrough,
+            timezone: time.timezone,
+            grain: time.grain,
+            completenessPolicy: time.completenessPolicy,
+        });
+        resolved.set(period.id, { ...period, start: bounds.start.toISOString(), end: bounds.end.toISOString() });
+    }
+    for (const period of time.periods) {
+        if (resolved.has(period.id))
+            continue;
+        const alignedId = period.alignToPeriodId ?? input.frame.comparison?.basePeriodId;
+        const aligned = alignedId ? resolved.get(alignedId) : undefined;
+        if (!aligned?.start || !aligned.end) {
+            return { status: 'blocked', code: 'EXPLICIT_PERIOD_BOUNDS_REQUIRED', reason: `Period ${period.id} has no resolved alignment period.` };
+        }
+        const start = parseInstant(aligned.start);
+        const end = parseInstant(aligned.end);
+        const shifted = period.kind === 'previous_year'
+            ? shiftZonedYears(start, end, time.timezone, -1)
+            : previousPeriod(start, end, time.timezone, time.grain);
+        resolved.set(period.id, { ...period, start: shifted.start.toISOString(), end: shifted.end.toISOString() });
+    }
+    const frame = structuredClone(input.frame);
+    frame.timeContext.periods = time.periods.map((period) => resolved.get(period.id));
+    const baseId = input.frame.comparison?.basePeriodId ?? time.periods[0]?.id;
+    const base = baseId ? resolved.get(baseId) : undefined;
+    return {
+        status: 'resolved',
+        frame,
+        asOf: base?.end ?? input.referenceInstant,
+        ...(freshness ? { freshnessObservation: { ...freshness } } : {}),
+    };
+}
+function currentBounds(input) {
+    if (input.completenessPolicy === 'partial_current') {
+        const local = zonedDate(input.reference, input.timezone);
+        return { start: startOfGrain(local, input.grain, input.timezone), end: input.reference };
+    }
+    const observed = input.observedThrough;
+    const completeDate = latestCompleteLocalDate(observed, input.timezone);
+    if (input.completenessPolicy === 'latest_complete') {
+        if (input.grain === 'day') {
+            return {
+                start: zonedStart(completeDate, input.timezone),
+                end: zonedStart(addLocalDays(completeDate, 1), input.timezone),
+            };
+        }
+        return {
+            start: startOfGrain(completeDate, input.grain, input.timezone),
+            end: zonedStart(addLocalDays(completeDate, 1), input.timezone),
+        };
+    }
+    const currentStart = startOfGrain(completeDate, input.grain, input.timezone);
+    const currentEnd = endOfGrain(completeDate, input.grain, input.timezone);
+    if (currentEnd.getTime() <= observed.getTime())
+        return { start: currentStart, end: currentEnd };
+    const previousDate = addLocalDays(zonedDate(currentStart, input.timezone), -1);
+    return {
+        start: startOfGrain(previousDate, input.grain, input.timezone),
+        end: endOfGrain(previousDate, input.grain, input.timezone),
+    };
+}
+function latestCompleteLocalDate(observedThrough, timezone) {
+    const local = zonedDate(observedThrough, timezone);
+    const nextStart = zonedStart(addLocalDays(local, 1), timezone);
+    return nextStart.getTime() <= observedThrough.getTime() ? local : addLocalDays(local, -1);
+}
+function startOfGrain(local, grain, timezone) {
+    if (grain === 'day')
+        return zonedStart(local, timezone);
+    if (grain === 'week') {
+        const weekday = new Date(Date.UTC(local.year, local.month - 1, local.day)).getUTCDay();
+        return zonedStart(addLocalDays(local, -(weekday === 0 ? 6 : weekday - 1)), timezone);
+    }
+    if (grain === 'month')
+        return zonedStart({ ...local, day: 1 }, timezone);
+    if (grain === 'quarter')
+        return zonedStart({ year: local.year, month: Math.floor((local.month - 1) / 3) * 3 + 1, day: 1 }, timezone);
+    return zonedStart({ year: local.year, month: 1, day: 1 }, timezone);
+}
+function endOfGrain(local, grain, timezone) {
+    const start = zonedDate(startOfGrain(local, grain, timezone), timezone);
+    if (grain === 'day')
+        return zonedStart(addLocalDays(start, 1), timezone);
+    if (grain === 'week')
+        return zonedStart(addLocalDays(start, 7), timezone);
+    if (grain === 'month')
+        return zonedStart(addLocalMonths(start, 1), timezone);
+    if (grain === 'quarter')
+        return zonedStart(addLocalMonths(start, 3), timezone);
+    return zonedStart({ year: start.year + 1, month: 1, day: 1 }, timezone);
+}
+function previousPeriod(start, end, timezone, grain) {
+    const localStart = zonedDate(start, timezone);
+    if (grain === 'day')
+        return { start: zonedStart(addLocalDays(localStart, -1), timezone), end: start };
+    if (grain === 'week')
+        return { start: zonedStart(addLocalDays(localStart, -7), timezone), end: start };
+    if (grain === 'month')
+        return { start: zonedStart(addLocalMonths(localStart, -1), timezone), end: start };
+    if (grain === 'quarter')
+        return { start: zonedStart(addLocalMonths(localStart, -3), timezone), end: start };
+    return shiftZonedYears(start, end, timezone, -1);
+}
+function shiftZonedYears(start, end, timezone, years) {
+    const shift = (instant) => {
+        const local = zonedDate(instant, timezone);
+        const targetYear = local.year + years;
+        const day = Math.min(local.day, daysInMonth(targetYear, local.month));
+        const time = zonedTime(instant, timezone);
+        return zonedInstant({ year: targetYear, month: local.month, day }, time, timezone);
+    };
+    return { start: shift(start), end: shift(end) };
+}
+function zonedDate(value, timezone) {
+    const parts = zonedParts(value, timezone);
+    return { year: parts.year, month: parts.month, day: parts.day };
+}
+function zonedTime(value, timezone) {
+    const parts = zonedParts(value, timezone);
+    return { hour: parts.hour, minute: parts.minute, second: parts.second, millisecond: value.getUTCMilliseconds() };
+}
+function zonedParts(value, timezone) {
+    const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone: timezone,
+        year: 'numeric', month: '2-digit', day: '2-digit',
+        hour: '2-digit', minute: '2-digit', second: '2-digit', hourCycle: 'h23',
+    }).formatToParts(value);
+    const number = (type) => Number(parts.find((part) => part.type === type).value);
+    return { year: number('year'), month: number('month'), day: number('day'), hour: number('hour'), minute: number('minute'), second: number('second') };
+}
+function zonedStart(local, timezone) {
+    return zonedInstant(local, { hour: 0, minute: 0, second: 0, millisecond: 0 }, timezone);
+}
+function zonedInstant(local, time, timezone) {
+    const target = Date.UTC(local.year, local.month - 1, local.day, time.hour, time.minute, time.second, time.millisecond);
+    let guess = target;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const observed = zonedParts(new Date(guess), timezone);
+        const observedAsUtc = Date.UTC(observed.year, observed.month - 1, observed.day, observed.hour, observed.minute, observed.second, time.millisecond);
+        const adjustment = target - observedAsUtc;
+        guess += adjustment;
+        if (adjustment === 0)
+            break;
+    }
+    return new Date(guess);
+}
+function addLocalDays(local, days) {
+    const value = new Date(Date.UTC(local.year, local.month - 1, local.day + days));
+    return { year: value.getUTCFullYear(), month: value.getUTCMonth() + 1, day: value.getUTCDate() };
+}
+function addLocalMonths(local, months) {
+    const value = new Date(Date.UTC(local.year, local.month - 1 + months, 1));
+    return { year: value.getUTCFullYear(), month: value.getUTCMonth() + 1, day: Math.min(local.day, daysInMonth(value.getUTCFullYear(), value.getUTCMonth() + 1)) };
+}
+function daysInMonth(year, month) {
+    return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+function parseInstant(value) {
+    const parsed = new Date(value);
+    return Number.isFinite(parsed.getTime()) ? parsed : undefined;
+}
+//# sourceMappingURL=analytical-period-resolution.js.map

package/dist/analytical-period-resolution.js.map

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

package/dist/analytical-readiness.d.ts

@@ -0,0 +1,17 @@
+import type { AgentEvidenceCandidate } from './meaning-resolution.js';
+export type AnalyticalReadinessQuestion = 'scalar' | 'filter' | 'grouping' | 'trend' | 'comparison' | 'ranking';
+export interface AnalyticalCapabilityReadiness {
+    candidateId: string;
+    metricId?: string;
+    status: 'complete' | 'incomplete';
+    support: Record<AnalyticalReadinessQuestion, boolean>;
+    blockers: Partial<Record<AnalyticalReadinessQuestion, string[]>>;
+}
+/**
+ * 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 declare function buildAnalyticalCapabilityReadiness(candidates: AgentEvidenceCandidate[]): AnalyticalCapabilityReadiness[];
+//# sourceMappingURL=analytical-readiness.d.ts.map

package/dist/analytical-readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytical-readiness.d.ts","sourceRoot":"","sources":["../src/analytical-readiness.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEtE,MAAM,MAAM,2BAA2B,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,GAAG,YAAY,GAAG,SAAS,CAAC;AAEhH,MAAM,WAAW,6BAA6B;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,GAAG,YAAY,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC,2BAA2B,EAAE,OAAO,CAAC,CAAC;IACtD,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,2BAA2B,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;CAClE;AAED;;;;;GAKG;AACH,wBAAgB,kCAAkC,CAAC,UAAU,EAAE,sBAAsB,EAAE,GAAG,6BAA6B,EAAE,CA0FxH"}