@murphai/murph 1.2.0 → 1.2.3

package/node_modules/@murphai/query/dist/experiments.js

@@ -1,13 +1,18 @@
-import { EXPERIMENT_OUTCOME_SCHEMA_VERSION, EXPERIMENT_PROGRESS_SCHEMA_VERSION, experimentFrontmatterSchema, experimentOutcomeSchema, experimentProgressSnapshotSchema, safeParseContract, toLocalDayKey, } from "@murphai/contracts";
+import { EXPERIMENT_OUTCOME_SCHEMA_VERSION, EXPERIMENT_PROGRESS_SCHEMA_VERSION, deviceDataOriginSchema, experimentFrontmatterSchema, experimentOutcomeSchema, experimentProgressSnapshotSchema, safeParseContract, toLocalDayKey, activityTextMatchesKind, } from "@murphai/contracts";
 import { getExperiment } from "./read-model.js";
-import { buildExperimentAdherenceCalendar, resolveExperimentAdherenceRollupTarget, synthesizeLegacySessionAdherenceTargets, } from "./experiment-adherence.js";
+import { buildExperimentAdherenceCalendar, countAdherenceConfidenceSessions, countCompletedAdherenceSessions, eventKindIsCandidateForEvidence, experimentAdherenceTargetPlansDate, resolveActivityEvidenceLocalDate, resolveAdherenceObservationActivityKind, resolveExperimentAdherenceRollupTarget, resolveInterventionSessionLocalDate, synthesizeLegacySessionAdherenceTargets, } from "./experiment-adherence.js";
 import { matchesExperimentMetricIdentity, resolveExperimentMetricIdentity, } from "./experiment-metrics.js";
 import { metricPointRecordIds } from "./metrics/index.js";
 import { readExperimentProtocolProjectionFields, } from "./protocols.js";
 import { resolveMetricDefinition, resolveMetricDefinitionForBiomarker, normalizeMetricKey, selectMetricSeries, selectMetricValue, selectMetricWindowComparison, } from "./metrics/index.js";
 import { buildMetricProjection } from "./metrics/projection.js";
 import { summarizeWearableDay } from "./wearables.js";
+import { readWearableExternalRef } from "./wearables/observation.js";
+import { inferJunctionWearableDataOriginFromExternalRef, resolveWearablePublicSourceProvider, } from "./wearables/origin.js";
 const MAX_EXPERIMENT_ANALYSIS_WINDOW_DAYS = 366;
+const MAX_DATA_COVERAGE_PROVIDERS = 20;
+// Answers whether the vault is currently receiving workout events.
+const ACTIVITY_PROVIDER_COVERAGE_WINDOW_DAYS = 30;
 export function summarizeExperimentProgress(vault, slug, options = {}) {
     const context = buildExperimentSummaryContext(vault, slug, options);
     const signals = buildMetricResults(context);
@@ -33,6 +38,7 @@ export function summarizeExperimentProgress(vault, slug, options = {}) {
         sessionEventIds: completedSessionEventIds,
     };
     const dataCoverage = buildCoverageSummary({
+        asOf: context.asOf,
         baselineDaysAvailable,
         interventionDaysAvailable,
         primarySignal,
@@ -40,6 +46,7 @@ export function summarizeExperimentProgress(vault, slug, options = {}) {
         frontmatter: context.frontmatter,
         signals,
         summariesByDate: context.summariesByDate,
+        vault,
     });
     const setupReadiness = buildSetupReadiness(context.frontmatter);
     const analysisReadiness = buildAnalysisReadiness(context.frontmatter);
@@ -148,8 +155,15 @@ function buildExperimentSummaryContext(vault, slug, options) {
     const frontmatter = requireExperimentFrontmatter(experiment);
     const asOf = normalizeAsOfDate(options.asOf);
     const progressPhase = resolveProgressPhase(frontmatter, asOf);
+    const adherenceTargets = resolveAdherenceTargetsFromFrontmatter(frontmatter);
     const events = findExperimentEvents(vault, experiment, frontmatter, asOf);
-    const completedSessions = events.filter(isCompletedSessionEvent).length;
+    const adherenceEvents = findAdherenceEvidenceEvents({
+        asOf,
+        events,
+        frontmatter,
+        targets: adherenceTargets,
+        vault,
+    });
     const dateSet = new Set([
         ...dateRange(frontmatter.runPlan?.baselineStart, frontmatter.runPlan?.baselineEnd),
         ...dateRange(frontmatter.runPlan?.interventionStart, minIsoDate(frontmatter.runPlan?.interventionEnd, asOf)),
@@ -159,9 +173,9 @@ function buildExperimentSummaryContext(vault, slug, options) {
         summariesByDate.set(date, summarizeWearableDay(vault, date));
     }
     return {
+        adherenceEvents,
         asOf,
         baselineDates: dateRange(frontmatter.runPlan?.baselineStart, frontmatter.runPlan?.baselineEnd),
-        completedSessions,
         confounders: summarizeConfounders(events),
         events,
         experiment,
@@ -178,8 +192,18 @@ function buildExperimentFollowupContext(vault, slug, asOf) {
         throw new Error(`Experiment "${slug}" was not found in the query read model.`);
     }
     const frontmatter = requireExperimentFrontmatter(experiment);
+    const events = findExperimentEvents(vault, experiment, frontmatter, asOf);
+    const adherenceTargets = resolveAdherenceTargetsFromFrontmatter(frontmatter);
     return {
-        events: findExperimentEvents(vault, experiment, frontmatter, asOf),
+        adherenceEvents: findAdherenceEvidenceEvents({
+            asOf,
+            events,
+            frontmatter,
+            targets: adherenceTargets,
+            vault,
+        }),
+        adherenceTargets,
+        events,
         frontmatter,
         progressPhase: resolveProgressPhase(frontmatter, asOf),
     };
@@ -261,9 +285,12 @@ export function collectExperimentAdherenceCalendar(vault, slug, options = {}) {
     return buildAdherenceCalendarFromContext(buildExperimentSummaryContext(vault, slug, options));
 }
 function resolveAdherenceTargets(context) {
-    return (context.frontmatter.runPlan?.adherenceTargets ??
+    return resolveAdherenceTargetsFromFrontmatter(context.frontmatter);
+}
+function resolveAdherenceTargetsFromFrontmatter(frontmatter) {
+    return (frontmatter.runPlan?.adherenceTargets ??
         synthesizeLegacySessionAdherenceTargets({
-            runPlan: context.frontmatter.runPlan,
+            runPlan: frontmatter.runPlan,
         }));
 }
 function buildAdherenceCalendarFromContext(context) {
@@ -286,48 +313,109 @@ function buildAdherenceSummary(context) {
         (hasAmbiguousTargets ? null : context.frontmatter.runPlan?.targetSessions ?? null);
     const minimumUsefulSessions = rollupTarget?.rollup?.minimumUsefulCompletions ??
         (hasAmbiguousTargets ? null : context.frontmatter.runPlan?.minimumUsefulSessions ?? null);
+    const progressTarget = hasAmbiguousTargets ? null : rollupTarget ?? targets[0] ?? null;
     const adherenceCalendar = buildAdherenceCalendarFromContext(context);
-    const rollupCells = rollupTarget && adherenceCalendar
+    const rollupCells = progressTarget?.calendar && rollupTarget && adherenceCalendar
         ? adherenceCalendar.cells.filter((cell) => cell.targetId === rollupTarget.targetId)
         : null;
-    const completedSessions = hasAmbiguousTargets
-        ? 0
-        : rollupCells
-            ? rollupCells.filter((cell) => cell.status === "satisfied").length
-            : context.completedSessions;
+    const progressObservations = progressTarget
+        ? buildAdherenceObservations(context, [progressTarget])
+        : [];
+    const progressCounts = progressTarget && !progressTarget.calendar
+        ? countCompletedAdherenceSessions({
+            asOfDate: context.asOf,
+            observations: progressObservations,
+            target: progressTarget,
+            windows: buildWindowSummary(context.frontmatter),
+        })
+        : null;
+    const progressCells = progressTarget?.calendar
+        ? rollupCells ?? adherenceCalendar?.cells ?? []
+        : [];
+    const confidenceCounts = !hasAmbiguousTargets && progressTarget?.calendar
+        ? countAdherenceConfidenceSessions({
+            cells: progressCells,
+            observations: progressObservations,
+        })
+        : progressCounts ?? {
+            sensedSessions: 0,
+            confirmedSessions: 0,
+            assumedSessions: 0,
+        };
+    let completedSessions = 0;
+    let partialSessions = 0;
+    if (!hasAmbiguousTargets) {
+        if (progressTarget?.calendar) {
+            completedSessions = progressCells.filter((cell) => cell.status === "satisfied" || cell.status === "assumed").length;
+            partialSessions = progressCells.filter((cell) => cell.status === "partial").length;
+        }
+        else {
+            completedSessions = progressCounts?.completedSessions ?? 0;
+            partialSessions = progressCounts?.partialSessions ?? 0;
+        }
+    }
+    const loggedSessions = completedSessions + partialSessions;
     const expectedSessionsByNow = hasAmbiguousTargets
         ? null
-        : adherenceCalendar
+        : progressTarget?.calendar && adherenceCalendar
             ? (rollupCells ?? adherenceCalendar.cells).filter((cell) => cell.status !== "scheduled").length
             : computeExpectedSessionsByNow(context.frontmatter, context.asOf, targetSessions);
+    const evidence = buildProgressAdherenceEvidence(progressTarget);
     let status = "unknown";
     if (hasAmbiguousTargets) {
         status = "unknown";
     }
-    else if (completedSessions === 0) {
+    else if (loggedSessions === 0) {
         status = "not_started";
     }
-    else if (targetSessions !== null && completedSessions >= targetSessions) {
+    else if (targetSessions !== null && loggedSessions >= targetSessions) {
         status = "met_target";
     }
     else if (minimumUsefulSessions !== null &&
-        completedSessions >= minimumUsefulSessions) {
+        loggedSessions >= minimumUsefulSessions) {
         status = "met_minimum";
     }
     else if (expectedSessionsByNow !== null &&
-        completedSessions < expectedSessionsByNow) {
+        loggedSessions < expectedSessionsByNow) {
         status = "behind";
     }
-    else if (completedSessions > 0) {
+    else if (loggedSessions > 0) {
         status = "on_track";
     }
-    return {
+    const summary = {
         completedSessions,
+        ...(evidence ? { evidence } : {}),
         expectedSessionsByNow,
+        loggedSessions,
+        ...(partialSessions > 0 ? { partialSessions } : {}),
         minimumUsefulSessions,
         status,
         targetSessions,
     };
+    if (confidenceCounts.sensedSessions > 0) {
+        summary.sensedSessions = confidenceCounts.sensedSessions;
+    }
+    if (confidenceCounts.confirmedSessions > 0) {
+        summary.confirmedSessions = confidenceCounts.confirmedSessions;
+    }
+    if (confidenceCounts.assumedSessions > 0) {
+        // Calendar-less targets have no per-day plan to assume; derived count-style events can still report as assumed.
+        summary.assumedSessions = confidenceCounts.assumedSessions;
+    }
+    return summary;
+}
+function buildProgressAdherenceEvidence(target) {
+    if (!target || target.evidence.kind !== "linkedEventCount") {
+        return null;
+    }
+    if (target.evidence.eventKind !== "activity_session" &&
+        target.evidence.eventKind !== "intervention_session") {
+        return null;
+    }
+    return {
+        eventKind: target.evidence.eventKind,
+        ...(target.evidence.activityKind ? { activityKind: target.evidence.activityKind } : {}),
+    };
 }
 function buildAdherenceObservations(context, targets) {
     const observations = [];
@@ -335,16 +423,24 @@ function buildAdherenceObservations(context, targets) {
         switch (target.evidence.kind) {
             case "linkedEventCount":
                 const linkedEvidence = target.evidence;
-                observations.push(...context.events
-                    .filter((event) => event.kind === linkedEvidence.eventKind)
+                observations.push(...context.adherenceEvents
+                    .filter((event) => eventKindIsCandidateForEvidence(event.kind, linkedEvidence))
                     .map((event) => ({
+                    activityKind: resolveAdherenceObservationActivityKind({
+                        attributes: event.attributes,
+                    }),
                     evidenceId: event.entityId,
                     eventKind: event.kind,
-                    localDate: readStringAttribute(event, "scheduledLocalDate") ??
-                        readStringAttribute(event, "sessionLocalDate") ??
-                        (event.occurredAt
-                            ? toLocalDayKey(new Date(event.occurredAt), target.calendar.timeZone)
-                            : event.date ?? context.asOf),
+                    localDate: event.kind === "activity_session"
+                        ? resolveActivityEvidenceLocalDate(event) ?? context.asOf
+                        : event.kind === "intervention_session"
+                            ? resolveInterventionSessionLocalDate(event) ?? context.asOf
+                            : readStringAttribute(event, "scheduledLocalDate") ??
+                                readStringAttribute(event, "sessionLocalDate") ??
+                                (target.calendar && event.occurredAt
+                                    ? toLocalDayKey(new Date(event.occurredAt), target.calendar?.timeZone ?? "UTC")
+                                    : event.date ?? extractDate(event.occurredAt) ?? context.asOf),
+                    source: readStringAttribute(event, "source"),
                     status: readExperimentSessionStatus(event),
                     targetId: target.targetId,
                 })));
@@ -418,8 +514,10 @@ function buildCoverageSummary(input) {
     else {
         status = "insufficient";
     }
-    const wearableProviders = [...new Set([...input.summariesByDate.values()].flatMap((summary) => summary?.providers ?? []))].sort((left, right) => left.localeCompare(right));
+    const activityProviders = buildActivityProviderCoverage(input.vault, input.asOf);
+    const wearableProviders = normalizeDataCoverageProviderList([...input.summariesByDate.values()].flatMap((summary) => summary?.providers ?? []));
     return {
+        activityProviders,
         baselineDaysAvailable: input.baselineDaysAvailable,
         interventionDaysAvailable: input.interventionDaysAvailable,
         primaryBiomarkerKey: input.primarySignal?.biomarkerKey ?? null,
@@ -428,6 +526,53 @@ function buildCoverageSummary(input) {
         wearableProviders,
     };
 }
+function buildActivityProviderCoverage(vault, asOf) {
+    const windowStart = addDaysToIsoDate(asOf, -(ACTIVITY_PROVIDER_COVERAGE_WINDOW_DAYS - 1));
+    return normalizeDataCoverageProviderList(vault.events.flatMap((event) => {
+        if (event.kind !== "activity_session") {
+            return [];
+        }
+        const localDate = resolveActivityEvidenceLocalDate(event);
+        if (!localDate || localDate < windowStart || localDate > asOf) {
+            return [];
+        }
+        const provider = resolveActivitySessionProviderCoverageLabel(event);
+        return provider ? [provider] : [];
+    }));
+}
+function resolveActivitySessionProviderCoverageLabel(event) {
+    const externalRef = readWearableExternalRef(event.attributes.externalRef);
+    const dataOrigin = readActivitySessionDataOrigin(event.attributes.dataOrigin, externalRef);
+    const provider = resolveWearablePublicSourceProvider({
+        dataOrigin,
+        externalRef,
+        provider: externalRef?.system,
+    }, {
+        suppressJunctionSourceInstanceFallback: true,
+    });
+    if (provider && provider !== "unknown" && provider !== "manual") {
+        return provider;
+    }
+    const source = readCoverageString(event.attributes.source);
+    if (source === "device" ||
+        dataOrigin !== null ||
+        (externalRef !== null && externalRef.system !== "manual")) {
+        return "wearable";
+    }
+    return null;
+}
+function readActivitySessionDataOrigin(value, externalRef) {
+    const parsed = deviceDataOriginSchema.safeParse(value);
+    return parsed.success ? parsed.data : inferJunctionWearableDataOriginFromExternalRef(externalRef);
+}
+function normalizeDataCoverageProviderList(values) {
+    return [...new Set(values.map((value) => value.trim()).filter(Boolean))]
+        .sort((left, right) => left.localeCompare(right))
+        .slice(0, MAX_DATA_COVERAGE_PROVIDERS);
+}
+function readCoverageString(value) {
+    return typeof value === "string" && value.trim() ? value.trim().toLowerCase() : null;
+}
 function summarizeSignalDayCoverage(signals) {
     return signals.reduce((summary, signal) => ({
         baselineDaysAvailable: Math.max(summary.baselineDaysAvailable, signal.baselineDayCount),
@@ -515,12 +660,17 @@ function buildProgressRecommendation(input) {
 function buildOutcomeConfidence(input) {
     const reasons = [];
     const primary = input.metricResults[0] ?? null;
+    const loggedSessions = readLoggedAdherenceSessions(input.adherence);
     if (!primary || primary.completeness === "insufficient") {
         reasons.push("Primary biomarker coverage is insufficient for a strong before-and-after read.");
     }
     if (input.adherence.minimumUsefulSessions !== null &&
-        input.adherence.completedSessions < input.adherence.minimumUsefulSessions) {
-        reasons.push("Completed session count stayed below the minimum useful target.");
+        loggedSessions < input.adherence.minimumUsefulSessions) {
+        reasons.push("Logged session count stayed below the minimum useful target.");
+    }
+    if ((input.adherence.assumedSessions ?? 0) >
+        (input.adherence.sensedSessions ?? 0) + (input.adherence.confirmedSessions ?? 0)) {
+        reasons.push("Most sessions are assumed rather than confirmed.");
     }
     if (input.confounders.length > 0) {
         reasons.push("Context and confounder logs were present during the run.");
@@ -537,6 +687,10 @@ function buildOutcomeConfidence(input) {
         reasons,
     };
 }
+function readLoggedAdherenceSessions(adherence) {
+    return adherence.loggedSessions ??
+        adherence.completedSessions + (adherence.partialSessions ?? 0);
+}
 function buildOutcomeConclusion(primary, confidenceLevel) {
     if (!primary || primary.deltaAbs === null || primary.interventionMean === null) {
         return {
@@ -630,14 +784,31 @@ function decideMissedLogDue(context, date) {
     if (assistantSupport.missedLogFollowup === "never") {
         return buildFollowupBase(context, date, "missed-log", "missed_log_followup_disabled", "skip", null);
     }
+    if (hasSessionLogForDate(context, date)) {
+        return buildFollowupBase(context, date, "missed-log", "session_already_logged", "skip", date);
+    }
+    if (hasAssumedAfterGraceCalendarSessionTarget(context, date)) {
+        return buildFollowupBase(context, date, "missed-log", "session_assumed", "skip", date);
+    }
     if (!isDailyInterventionSchedule(context.frontmatter)) {
         return buildFollowupBase(context, date, "missed-log", "unsupported_session_schedule", "skip", null);
     }
-    if (hasSessionLogForDate(context.events, date)) {
-        return buildFollowupBase(context, date, "missed-log", "session_already_logged", "skip", date);
-    }
     return buildFollowupBase(context, date, "missed-log", "planned_session_log_missing", "notify", date);
 }
+function hasAssumedAfterGraceCalendarSessionTarget(context, date) {
+    const rollupTarget = resolveExperimentAdherenceRollupTarget(context.adherenceTargets);
+    const targets = rollupTarget ? [rollupTarget] : context.adherenceTargets;
+    const windows = buildWindowSummary(context.frontmatter);
+    const plannedCalendarTargets = targets.filter((target) => target.calendar !== undefined &&
+        experimentAdherenceTargetPlansDate({
+            localDate: date,
+            target,
+            windows,
+        }));
+    return plannedCalendarTargets.length > 0 &&
+        plannedCalendarTargets.every((target) => target.evidence.kind === "linkedEventCount" &&
+            target.evidence.missing === "assumed_after_grace");
+}
 function decideWeeklyDigestDue(context, date) {
     if (context.frontmatter.status !== "active") {
         return buildFollowupBase(context, date, "weekly-digest", "experiment_not_active", "skip", null);
@@ -665,8 +836,36 @@ function isWeeklyDigestDueOnDate(frontmatter, date) {
     }
     return daysBetweenInclusive(interventionStart, date) % 7 === 0;
 }
-function hasSessionLogForDate(events, date) {
-    return events.some((event) => event.kind === "intervention_session" && event.date === date);
+function hasSessionLogForDate(context, date) {
+    if (context.events.some((event) => event.kind === "intervention_session" &&
+        resolveInterventionSessionLocalDate(event) === date)) {
+        return true;
+    }
+    const activityEvidenceTargets = context.adherenceTargets.flatMap((target) => target.evidence.kind === "linkedEventCount" &&
+        target.evidence.eventKind === "activity_session"
+        ? [target.evidence]
+        : []);
+    if (activityEvidenceTargets.length === 0) {
+        return false;
+    }
+    return context.adherenceEvents.some((event) => {
+        if (event.kind !== "activity_session") {
+            return false;
+        }
+        const eventDate = resolveActivityEvidenceLocalDate(event);
+        if (eventDate !== date) {
+            return false;
+        }
+        const activityKind = resolveAdherenceObservationActivityKind({
+            attributes: event.attributes,
+        });
+        return activityEvidenceTargets.some((evidence) => {
+            if (!evidence.activityKind) {
+                return true;
+            }
+            return activityTextMatchesKind(activityKind, evidence.activityKind);
+        });
+    });
 }
 function isDailyInterventionSchedule(frontmatter) {
     const runPlan = frontmatter.runPlan;
@@ -958,7 +1157,9 @@ function findExperimentEvents(vault, experiment, frontmatter, asOf) {
     const from = frontmatter.runPlan?.baselineStart ?? frontmatter.startedOn;
     const experimentId = frontmatter.experimentId;
     return vault.events.filter((event) => {
-        const date = event.date ?? extractDate(event.occurredAt);
+        const date = event.kind === "intervention_session"
+            ? resolveInterventionSessionLocalDate(event)
+            : event.date ?? extractDate(event.occurredAt);
         if (from && date && date < from) {
             return false;
         }
@@ -980,6 +1181,34 @@ function findExperimentEvents(vault, experiment, frontmatter, asOf) {
         return event.links.some((link) => link.targetId === experiment.entityId);
     });
 }
+function findAdherenceEvidenceEvents(input) {
+    const byId = new Map(input.events.map((event) => [event.entityId, event]));
+    const needsActivityEvidence = input.targets.some((target) => target.evidence.kind === "linkedEventCount" &&
+        target.evidence.eventKind === "activity_session");
+    if (!needsActivityEvidence) {
+        return [...byId.values()];
+    }
+    const interventionStart = input.frontmatter.runPlan?.interventionStart;
+    const interventionEnd = input.frontmatter.runPlan?.interventionEnd;
+    if (!interventionStart || !interventionEnd || input.asOf < interventionStart) {
+        return [...byId.values()];
+    }
+    const effectiveEnd = minIsoDate(interventionEnd, input.asOf);
+    if (!effectiveEnd) {
+        return [...byId.values()];
+    }
+    for (const event of input.vault.events) {
+        if (event.kind !== "activity_session") {
+            continue;
+        }
+        const date = resolveActivityEvidenceLocalDate(event);
+        if (!date || date < interventionStart || date > effectiveEnd) {
+            continue;
+        }
+        byId.set(event.entityId, event);
+    }
+    return [...byId.values()];
+}
 function isCompletedSessionEvent(event) {
     if (event.kind !== "intervention_session") {
         return false;