agent-scenario-loop 0.1.2 → 0.1.4

package/dist/core/artifact-contract.js

@@ -11,11 +11,75 @@ exports.evaluateUiContract = evaluateUiContract;
 exports.evaluateProfileBudgets = evaluateProfileBudgets;
 exports.extractCandidateIdentifiers = extractCandidateIdentifiers;
 exports.extractProfileEvents = extractProfileEvents;
+exports.extractProfileSessionEntries = extractProfileSessionEntries;
 exports.findMatchingIdentifier = findMatchingIdentifier;
 exports.percentile = percentile;
 exports.sortValue = sortValue;
+const crypto = require('node:crypto');
 const PROFILE_EVENT_PREFIX = '[profile-event]';
 exports.PROFILE_EVENT_PREFIX = PROFILE_EVENT_PREFIX;
+const PROFILE_SESSION_PREFIX = '[profile-session]';
+const CAUSAL_TIMELINE_PHASES = new Set([
+    'intent',
+    'navigation',
+    'domain',
+    'query',
+    'network',
+    'render',
+    'native',
+    'visual',
+    'completion',
+]);
+const CAUSAL_TIMELINE_STATUSES = new Set([
+    'started',
+    'completed',
+    'failed',
+    'skipped',
+    'observed',
+]);
+const UNKNOWN_LIFECYCLE_ASSERTION = Object.freeze({
+    value: 'unknown',
+    evidence: 'not-asserted',
+});
+const DEFAULT_ENVIRONMENT_PRECONDITIONS = Object.freeze({
+    installedState: UNKNOWN_LIFECYCLE_ASSERTION,
+    appDataState: UNKNOWN_LIFECYCLE_ASSERTION,
+    authState: UNKNOWN_LIFECYCLE_ASSERTION,
+    initialRoute: UNKNOWN_LIFECYCLE_ASSERTION,
+    foregroundState: UNKNOWN_LIFECYCLE_ASSERTION,
+    lifecyclePhase: UNKNOWN_LIFECYCLE_ASSERTION,
+    deviceLockState: UNKNOWN_LIFECYCLE_ASSERTION,
+    permissions: UNKNOWN_LIFECYCLE_ASSERTION,
+    locale: UNKNOWN_LIFECYCLE_ASSERTION,
+    timezone: UNKNOWN_LIFECYCLE_ASSERTION,
+    theme: UNKNOWN_LIFECYCLE_ASSERTION,
+    fontScale: UNKNOWN_LIFECYCLE_ASSERTION,
+    orientation: UNKNOWN_LIFECYCLE_ASSERTION,
+    networkState: UNKNOWN_LIFECYCLE_ASSERTION,
+    animations: UNKNOWN_LIFECYCLE_ASSERTION,
+});
+const DEFAULT_ENVIRONMENT_POSTCONDITIONS = Object.freeze({
+    appState: UNKNOWN_LIFECYCLE_ASSERTION,
+    lifecyclePhase: UNKNOWN_LIFECYCLE_ASSERTION,
+    cleanupState: UNKNOWN_LIFECYCLE_ASSERTION,
+    dataState: UNKNOWN_LIFECYCLE_ASSERTION,
+    artifactState: UNKNOWN_LIFECYCLE_ASSERTION,
+});
+const FAILURE_TERMINAL_STATES = new Set([
+    'failed',
+    'timeout',
+    'cancelled',
+    'aborted',
+    'inconclusive',
+    'unsupported',
+    'unhealthy',
+]);
+const TERMINAL_CLASSIFICATION_CATEGORIES = Object.freeze({
+    timeout: 'timeout',
+    cancelled: 'cancelled',
+    aborted: 'cancelled',
+    unsupported: 'runner',
+});
 /**
  * Converts finite numeric strings to numbers while preserving invalid input as `null`.
  *
@@ -72,6 +136,58 @@ function parseKeyValueProfileEvent(payload) {
     }
     return event;
 }
+/**
+ * Parses key/value `[profile-session]` payloads into structured session entries.
+ *
+ * @param {string} payload
+ * @returns {Record<string, unknown> | null}
+ */
+function parseKeyValueProfileSessionEntry(payload) {
+    const matches = payload.match(/(?:[^\s=]+)=(?:"[^"]*"|'[^']*'|[^\s]+)/gu) ?? [];
+    if (matches.length === 0) {
+        return null;
+    }
+    const entry = {};
+    for (const match of matches) {
+        const separatorIndex = match.indexOf('=');
+        if (separatorIndex <= 0) {
+            continue;
+        }
+        const key = match.slice(0, separatorIndex);
+        let value = match.slice(separatorIndex + 1);
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        entry[key] = value;
+    }
+    if (typeof entry.kind !== 'string' ||
+        typeof entry.scenario !== 'string' ||
+        typeof entry.runId !== 'string') {
+        return null;
+    }
+    const timestamp = coerceNumber(entry.timestamp);
+    const atMs = coerceNumber(entry.atMs);
+    const sequence = coerceNumber(entry.sequence);
+    const waitMs = coerceNumber(entry.waitMs);
+    const waitTimeoutMs = coerceNumber(entry.waitTimeoutMs);
+    if (atMs !== null) {
+        entry.atMs = atMs;
+    }
+    if (timestamp !== null) {
+        entry.timestamp = timestamp;
+    }
+    if (sequence !== null) {
+        entry.sequence = sequence;
+    }
+    if (waitMs !== null) {
+        entry.waitMs = waitMs;
+    }
+    if (waitTimeoutMs !== null) {
+        entry.waitTimeoutMs = waitTimeoutMs;
+    }
+    return entry;
+}
 /**
  * Rounds millisecond values to a stable artifact precision.
  *
@@ -81,6 +197,59 @@ function parseKeyValueProfileEvent(payload) {
 function roundMs(value) {
     return Math.round(value * 1000) / 1000;
 }
+/**
+ * Asserts cross-field attempt semantics that JSON Schema alone does not express.
+ *
+ * @param {Record<string, any>} attempt
+ * @returns {void}
+ */
+function assertAttemptInvariants(attempt) {
+    const { attemptId, attemptNumber, classification, cleanup, maxAttempts, partialArtifacts, retryOfAttemptId, retryReason, status, terminalState, } = attempt;
+    if (status === 'passed' && terminalState !== 'passed') {
+        throw new Error(`Passed attempts must use terminalState "passed", received "${terminalState}".`);
+    }
+    if (status === 'failed' && !FAILURE_TERMINAL_STATES.has(String(terminalState))) {
+        throw new Error(`Failed attempts must use a failure terminalState, received "${terminalState}".`);
+    }
+    const expectedCategory = TERMINAL_CLASSIFICATION_CATEGORIES[String(terminalState)];
+    if (expectedCategory && classification?.category !== expectedCategory) {
+        throw new Error(`terminalState "${terminalState}" requires classification.category "${expectedCategory}".`);
+    }
+    if (terminalState === 'cancelled' || terminalState === 'aborted' || terminalState === 'timeout') {
+        if (partialArtifacts?.valid !== true) {
+            throw new Error(`terminalState "${terminalState}" must preserve valid partialArtifacts for diagnosis.`);
+        }
+        if (!Array.isArray(partialArtifacts.paths) || partialArtifacts.paths.length === 0) {
+            throw new Error(`terminalState "${terminalState}" must record partialArtifacts.paths.`);
+        }
+    }
+    if (cleanup?.status && cleanup.status !== 'not-required' && cleanup.status !== 'unknown' && typeof cleanup.message !== 'string') {
+        throw new Error(`cleanup.status "${cleanup.status}" must include a cleanup message.`);
+    }
+    if (!Number.isInteger(attemptNumber) || attemptNumber < 1) {
+        throw new Error(`attemptNumber must be an integer greater than or equal to 1.`);
+    }
+    if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+        throw new Error(`maxAttempts must be an integer greater than or equal to 1.`);
+    }
+    if (attemptNumber > maxAttempts) {
+        throw new Error(`attemptNumber ${attemptNumber} cannot exceed maxAttempts ${maxAttempts}.`);
+    }
+    if (attemptNumber > 1) {
+        if (typeof retryOfAttemptId !== 'string' || retryOfAttemptId.length === 0) {
+            throw new Error(`retry attempts must record retryOfAttemptId.`);
+        }
+        if (retryOfAttemptId === attemptId) {
+            throw new Error(`retryOfAttemptId must not equal attemptId.`);
+        }
+        if (typeof retryReason !== 'string' || retryReason.length === 0) {
+            throw new Error(`retry attempts must record retryReason.`);
+        }
+    }
+    if (attemptNumber === 1 && (typeof retryOfAttemptId === 'string' || typeof retryReason === 'string')) {
+        throw new Error(`first attempts must not record retry lineage.`);
+    }
+}
 /**
  * Returns a nearest-rank percentile for numeric measurements.
  *
@@ -148,13 +317,61 @@ function extractProfileEvents(logText, filters = {}) {
         }
     });
 }
+/**
+ * Extracts structured profile-session entries from device logs.
+ *
+ * @param {string} logText
+ * @param {{runId?: string, scenario?: string}} [filters]
+ * @returns {Record<string, unknown>[]}
+ */
+function extractProfileSessionEntries(logText, filters = {}) {
+    const { runId, scenario } = filters;
+    return String(logText)
+        .split(/\r?\n/u)
+        .flatMap((line) => {
+        const prefixIndex = line.indexOf(PROFILE_SESSION_PREFIX);
+        if (prefixIndex === -1) {
+            return [];
+        }
+        const payload = line.slice(prefixIndex + PROFILE_SESSION_PREFIX.length).trim();
+        if (!payload) {
+            return [];
+        }
+        try {
+            const entry = JSON.parse(payload);
+            if (!entry || typeof entry !== 'object') {
+                return [];
+            }
+            if (runId && entry.runId !== runId) {
+                return [];
+            }
+            if (scenario && entry.scenario !== scenario) {
+                return [];
+            }
+            return [entry];
+        }
+        catch {
+            const entry = parseKeyValueProfileSessionEntry(payload);
+            if (!entry) {
+                return [];
+            }
+            if (runId && entry.runId !== runId) {
+                return [];
+            }
+            if (scenario && entry.scenario !== scenario) {
+                return [];
+            }
+            return [entry];
+        }
+    });
+}
 /**
  * Builds timing metrics from app-emitted profile events.
  *
- * @param {{scenario: string, runId: string, events: Record<string, unknown>[], expectedIterations: number, timeoutCount?: number, artifacts?: Record<string, unknown>, cycleEventNames?: Record<string, string> | null, budgets?: Record<string, unknown> | null}} options
+ * @param {{scenario: string, runId: string, events: Record<string, unknown>[], expectedIterations: number, timeoutCount?: number, artifacts?: Record<string, unknown>, cycleEventNames?: Record<string, string> | null, milestoneEventsPerIteration?: number, budgets?: Record<string, unknown> | null}} options
  * @returns {Record<string, unknown>}
  */
-function buildMetricsFromProfileEvents({ scenario, runId, events, expectedIterations, timeoutCount = 0, artifacts = {}, cycleEventNames = null, budgets = null, }) {
+function buildMetricsFromProfileEvents({ scenario, runId, events, expectedIterations, timeoutCount = 0, artifacts = {}, cycleEventNames = null, milestoneEventsPerIteration = 1, budgets = null, }) {
     const resolvedCycleEventNames = {
         openRequested: cycleEventNames?.openRequested ?? 'surface_open_requested',
         opened: cycleEventNames?.opened ?? 'surface_opened',
@@ -163,17 +380,35 @@ function buildMetricsFromProfileEvents({ scenario, runId, events, expectedIterat
         milestone: cycleEventNames?.milestone,
     };
     const usesMilestoneOnlyCycle = typeof resolvedCycleEventNames.milestone === 'string';
+    const requiredMilestoneEventsPerIteration = usesMilestoneOnlyCycle &&
+        Number.isInteger(milestoneEventsPerIteration) &&
+        milestoneEventsPerIteration > 1
+        ? milestoneEventsPerIteration
+        : 1;
     const iterations = new Map();
+    let nextImplicitMilestoneIteration = 1;
+    let nextImplicitMilestoneCount = 0;
     for (const event of [...events].sort((left, right) => {
         const leftAt = typeof left.atMs === 'number' ? left.atMs : Number.POSITIVE_INFINITY;
         const rightAt = typeof right.atMs === 'number' ? right.atMs : Number.POSITIVE_INFINITY;
         return leftAt - rightAt;
     })) {
-        const eventIteration = typeof event.iteration === 'number'
+        let eventIteration = typeof event.iteration === 'number'
             ? event.iteration
             : expectedIterations === 1
                 ? 1
                 : null;
+        if (eventIteration === null &&
+            usesMilestoneOnlyCycle &&
+            event.event === resolvedCycleEventNames.milestone &&
+            nextImplicitMilestoneIteration <= expectedIterations) {
+            eventIteration = nextImplicitMilestoneIteration;
+            nextImplicitMilestoneCount += 1;
+            if (nextImplicitMilestoneCount >= requiredMilestoneEventsPerIteration) {
+                nextImplicitMilestoneIteration += 1;
+                nextImplicitMilestoneCount = 0;
+            }
+        }
         if (eventIteration === null) {
             continue;
         }
@@ -203,8 +438,10 @@ function buildMetricsFromProfileEvents({ scenario, runId, events, expectedIterat
             event.atMs >= current.closeRequestedAt) {
             current.dismissedAt = event.atMs;
         }
-        if (event.event === resolvedCycleEventNames.milestone &&
-            typeof current.milestoneAt !== 'number') {
+        if (event.event === resolvedCycleEventNames.milestone) {
+            current.milestoneCount = typeof current.milestoneCount === 'number'
+                ? current.milestoneCount + 1
+                : 1;
             current.milestoneAt = event.atMs;
         }
         iterations.set(eventIteration, current);
@@ -232,6 +469,9 @@ function buildMetricsFromProfileEvents({ scenario, runId, events, expectedIterat
             record.dismissedAt >= record.closeRequestedAt;
         const hasMilestoneDuration = usesMilestoneOnlyCycle &&
             typeof record.milestoneAt === 'number' &&
+            (requiredMilestoneEventsPerIteration <= 1 ||
+                (typeof record.milestoneCount === 'number' &&
+                    record.milestoneCount >= requiredMilestoneEventsPerIteration)) &&
             record.milestoneAt >= 0;
         if (hasMilestoneDuration) {
             durationsMs.push(roundMs(record.milestoneAt));
@@ -269,7 +509,8 @@ function buildMetricsFromProfileEvents({ scenario, runId, events, expectedIterat
         incompleteIterations,
         artifacts: sortValue(artifacts),
     };
-    const budgetEvaluation = evaluateProfileBudgets({ metrics, budgets });
+    const intervalBudgetChecks = evaluateIntervalBudgetChecks({ events, expectedIterations, budgets });
+    const budgetEvaluation = evaluateProfileBudgets({ metrics, budgets, extraChecks: intervalBudgetChecks });
     if (budgetEvaluation) {
         metrics.budgetEvaluation = sortValue(budgetEvaluation);
     }
@@ -294,15 +535,111 @@ function evaluateBudgetCheck({ name, actual, limit }) {
         unit: 'ms',
     };
 }
+/**
+ * Collects duration samples for one named interval budget.
+ *
+ * @param {{events: ProfileEvent[], fromEvent: string, toEvent: string, expectedIterations: number}} options
+ * @returns {number[]}
+ */
+function collectIntervalDurations({ events, fromEvent, toEvent, expectedIterations, }) {
+    const sortedEvents = [...events].sort((left, right) => {
+        const leftAt = typeof left.atMs === 'number' ? left.atMs : Number.POSITIVE_INFINITY;
+        const rightAt = typeof right.atMs === 'number' ? right.atMs : Number.POSITIVE_INFINITY;
+        return leftAt - rightAt;
+    });
+    const hasIterationPairs = sortedEvents.some((event) => (typeof event.iteration === 'number' && (event.event === fromEvent || event.event === toEvent)));
+    if (hasIterationPairs) {
+        const durations = [];
+        for (let iteration = 1; iteration <= expectedIterations; iteration += 1) {
+            const from = sortedEvents.find((event) => (event.event === fromEvent &&
+                event.iteration === iteration &&
+                typeof event.atMs === 'number'));
+            const to = sortedEvents.find((event) => (event.event === toEvent &&
+                event.iteration === iteration &&
+                typeof event.atMs === 'number' &&
+                typeof from?.atMs === 'number' &&
+                event.atMs >= from.atMs));
+            if (typeof from?.atMs === 'number' && typeof to?.atMs === 'number') {
+                durations.push(roundMs(to.atMs - from.atMs));
+            }
+        }
+        return durations;
+    }
+    const durations = [];
+    let pendingFrom = null;
+    for (const event of sortedEvents) {
+        if (typeof event.atMs !== 'number') {
+            continue;
+        }
+        if (event.event === fromEvent && pendingFrom === null) {
+            pendingFrom = event.atMs;
+            continue;
+        }
+        if (event.event === toEvent && pendingFrom !== null && event.atMs >= pendingFrom) {
+            durations.push(roundMs(event.atMs - pendingFrom));
+            pendingFrom = null;
+            if (durations.length >= expectedIterations) {
+                break;
+            }
+        }
+    }
+    return durations;
+}
+/**
+ * Evaluates named interval budgets that should not define scenario health completeness.
+ *
+ * @param {{events: ProfileEvent[], expectedIterations: number, budgets?: Record<string, unknown> | null}} options
+ * @returns {BudgetCheck[]}
+ */
+function evaluateIntervalBudgetChecks({ events, expectedIterations, budgets, }) {
+    if (!Array.isArray(budgets?.intervals)) {
+        return [];
+    }
+    return budgets.intervals
+        .map((budget) => {
+        if (typeof budget.name !== 'string' ||
+            typeof budget.metric !== 'string' ||
+            typeof budget.limit !== 'number' ||
+            typeof budget.fromEvent !== 'string' ||
+            typeof budget.toEvent !== 'string') {
+            return null;
+        }
+        const durations = collectIntervalDurations({
+            events,
+            fromEvent: budget.fromEvent,
+            toEvent: budget.toEvent,
+            expectedIterations,
+        });
+        const actual = budget.metric === 'p50'
+            ? percentile(durations, 50)
+            : budget.metric === 'p95'
+                ? percentile(durations, 95)
+                : null;
+        return evaluateBudgetCheck({
+            name: budget.name,
+            actual,
+            limit: budget.limit,
+        });
+    })
+        .filter((check) => Boolean(check));
+}
 /**
  * Evaluates configured profile budgets against generated metrics.
  *
- * @param {{metrics: Record<string, unknown>, budgets?: Record<string, unknown> | null}} options
+ * @param {{metrics: Record<string, unknown>, budgets?: Record<string, unknown> | null, extraChecks?: BudgetCheck[]}} options
  * @returns {Record<string, unknown> | null}
  */
-function evaluateProfileBudgets({ metrics, budgets }) {
+function evaluateProfileBudgets({ metrics, budgets, extraChecks = [], }) {
     if (!budgets?.pass || typeof budgets.pass !== 'object') {
-        return null;
+        if (extraChecks.length === 0) {
+            return null;
+        }
+        return {
+            metric: budgets?.metric ?? metrics.measurement ?? 'profile budget',
+            pass: extraChecks.every((check) => check.pass),
+            checks: extraChecks,
+            failedChecks: extraChecks.filter((check) => !check.pass).map((check) => check.name),
+        };
     }
     const checks = [
         evaluateBudgetCheck({
@@ -376,7 +713,7 @@ function evaluateProfileBudgets({ metrics, budgets }) {
             }
             : null,
     ].filter((check) => Boolean(check));
-    const allChecks = [...thresholdChecks, ...checks];
+    const allChecks = [...thresholdChecks, ...checks, ...extraChecks];
     if (allChecks.length === 0) {
         return null;
     }
@@ -407,6 +744,54 @@ function sortValue(value) {
     }
     return value;
 }
+/**
+ * Returns a deterministic SHA-256 hash for a JSON-compatible value.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function hashStableValue(value) {
+    return crypto.createHash('sha256').update(JSON.stringify(sortValue(value))).digest('hex');
+}
+/**
+ * Normalizes optional run cohort provenance into schema-safe scalar fields.
+ *
+ * @param {Record<string, unknown> | null | undefined} cohort
+ * @returns {Record<string, unknown> | null}
+ */
+function normalizeProvenanceCohort(cohort) {
+    if (!cohort || typeof cohort !== 'object') {
+        return null;
+    }
+    const normalized = {
+        ...(typeof cohort.appId === 'string' ? { appId: cohort.appId } : {}),
+        ...(typeof cohort.appVersion === 'string' ? { appVersion: cohort.appVersion } : {}),
+        ...(typeof cohort.buildId === 'string' ? { buildId: cohort.buildId } : {}),
+        ...(typeof cohort.buildMode === 'string' ? { buildMode: cohort.buildMode } : {}),
+        ...(typeof cohort.commandTransport === 'string' ? { commandTransport: cohort.commandTransport } : {}),
+        ...(typeof cohort.deviceClass === 'string' ? { deviceClass: cohort.deviceClass } : {}),
+        ...(typeof cohort.osVersion === 'string' ? { osVersion: cohort.osVersion } : {}),
+        ...(typeof cohort.platform === 'string' ? { platform: cohort.platform } : {}),
+        ...(typeof cohort.runnerName === 'string' ? { runnerName: cohort.runnerName } : {}),
+        ...(typeof cohort.runnerVersion === 'string' ? { runnerVersion: cohort.runnerVersion } : {}),
+        ...(typeof cohort.seedIdentity === 'string' ? { seedIdentity: cohort.seedIdentity } : {}),
+        ...(cohort.featureFlags && typeof cohort.featureFlags === 'object' && !Array.isArray(cohort.featureFlags)
+            ? { featureFlags: sortValue(cohort.featureFlags) }
+            : {}),
+        ...(Array.isArray(cohort.providers)
+            ? {
+                providers: cohort.providers
+                    .filter((provider) => provider && typeof provider === 'object')
+                    .map((provider) => sortValue({
+                    ...(typeof provider.name === 'string' ? { name: provider.name } : {}),
+                    ...(typeof provider.version === 'string' ? { version: provider.version } : {}),
+                }))
+                    .filter((provider) => typeof provider.name === 'string' || typeof provider.version === 'string'),
+            }
+            : {}),
+    };
+    return Object.keys(normalized).length > 0 ? sortValue(normalized) : null;
+}
 /**
  * Normalizes event timestamps to milliseconds since run start.
  *
@@ -513,14 +898,101 @@ function inferTimelineStatus(eventName) {
     }
     return 'observed';
 }
+/**
+ * Keeps causal-run timeline values within the public artifact schema.
+ *
+ * App-owned events may carry richer phase/status vocabulary than ASL's stable
+ * artifact contract. Preserve that vocabulary in metadata, but emit only schema
+ * values at the timeline top level.
+ *
+ * @param {{phase: string, status: string, metadata: Record<string, unknown>}} options
+ * @returns {{phase: string, status: string, metadata: Record<string, unknown>}}
+ */
+function normalizeTimelineContractValues({ metadata, phase, status, }) {
+    const normalizedMetadata = { ...metadata };
+    let normalizedPhase = phase;
+    let normalizedStatus = status;
+    if (!CAUSAL_TIMELINE_PHASES.has(normalizedPhase)) {
+        normalizedMetadata.appPhase = normalizedPhase;
+        normalizedPhase = 'domain';
+    }
+    if (!CAUSAL_TIMELINE_STATUSES.has(normalizedStatus)) {
+        normalizedMetadata.appStatus = normalizedStatus;
+        normalizedStatus = 'observed';
+    }
+    return {
+        metadata: normalizedMetadata,
+        phase: normalizedPhase,
+        status: normalizedStatus,
+    };
+}
+/**
+ * Converts profile-session command control entries into causal timeline events.
+ *
+ * These are ASL control-plane acknowledgements, not product truth events. They
+ * let agents verify command ordering and delivery while keeping product verdicts
+ * based on app-owned profile events.
+ *
+ * @param {{entries: Record<string, unknown>[], startedAt?: string}} options
+ * @returns {Record<string, unknown>[]}
+ */
+function buildCommandAcknowledgementTimeline({ entries, startedAt, }) {
+    return [...(Array.isArray(entries) ? entries : [])]
+        .map((entry) => {
+        if (!entry || typeof entry !== 'object' || entry.kind !== 'command') {
+            return null;
+        }
+        const atMs = normalizeEventTimestamp({
+            event: entry,
+            ...(typeof startedAt === 'string' ? { startedAt } : {}),
+        });
+        if (atMs === null) {
+            return null;
+        }
+        const commandStatus = typeof entry.status === 'string' ? entry.status : 'observed';
+        const status = commandStatus === 'completed' || commandStatus === 'delivered'
+            ? 'completed'
+            : commandStatus === 'skipped'
+                ? 'skipped'
+                : commandStatus === 'failed'
+                    ? 'failed'
+                    : commandStatus === 'received' || commandStatus === 'queued'
+                        ? 'started'
+                        : 'observed';
+        const metadata = {
+            ...(typeof entry.command === 'string' ? { command: entry.command } : {}),
+            ...(typeof entry.commandId === 'string' ? { commandId: entry.commandId } : {}),
+            ...(typeof entry.id === 'string' ? { entryId: entry.id } : {}),
+            ...(typeof entry.queueId === 'string' ? { queueId: entry.queueId } : {}),
+            ...(typeof entry.sequence === 'number' ? { sequence: entry.sequence } : {}),
+            ...(typeof entry.source === 'string' ? { source: entry.source } : {}),
+            commandStatus,
+            ...(typeof entry.result === 'string' ? { result: entry.result } : {}),
+            ...(typeof entry.reason === 'string' ? { reason: entry.reason } : {}),
+            ...(typeof entry.waitForMilestone === 'string' ? { waitForMilestone: entry.waitForMilestone } : {}),
+            ...(typeof entry.waitMs === 'number' ? { waitMs: entry.waitMs } : {}),
+            ...(typeof entry.waitTimeoutMs === 'number' ? { waitTimeoutMs: entry.waitTimeoutMs } : {}),
+        };
+        return sortValue({
+            phase: 'intent',
+            name: `profile_command_${commandStatus}`,
+            atMs,
+            status,
+            owner: 'asl-command-transport',
+            metadata,
+        });
+    })
+        .filter(Boolean)
+        .sort((left, right) => left.atMs - right.atMs);
+}
 /**
  * Builds a causal timeline from app-owned profile events.
  *
  * @param {{events: Record<string, unknown>[], startedAt?: string, phaseMap?: Record<string, string> | null, owner?: string | null}} options
  * @returns {Record<string, unknown>[]}
  */
-function buildCausalTimeline({ events, startedAt, phaseMap = null, owner = null, }) {
-    return [...(Array.isArray(events) ? events : [])]
+function buildCausalTimeline({ events, sessionEntries = [], startedAt, phaseMap = null, owner = null, }) {
+    const eventTimeline = [...(Array.isArray(events) ? events : [])]
         .map((event) => {
         if (!event || typeof event !== 'object' || typeof event.event !== 'string') {
             return null;
@@ -545,20 +1017,78 @@ function buildCausalTimeline({ events, startedAt, phaseMap = null, owner = null,
             ...(typeof event.flowId === 'string' ? { flowId: event.flowId } : {}),
             ...(typeof event.route === 'string' ? { route: event.route } : {}),
             ...(typeof event.iteration === 'number' ? { iteration: event.iteration } : {}),
+            ...(typeof event.sequence === 'number' ? { sequence: event.sequence } : {}),
+            ...(typeof event.queueId === 'string' ? { queueId: event.queueId } : {}),
+            ...(typeof event.commandId === 'string' ? { commandId: event.commandId } : {}),
+            ...(typeof event.operationId === 'string' ? { operationId: event.operationId } : {}),
+            ...(typeof event.attemptId === 'string' ? { attemptId: event.attemptId } : {}),
+            ...(typeof event.clockDomain === 'string' ? { clockDomain: event.clockDomain } : {}),
         };
-        return sortValue({
+        const timelineValues = normalizeTimelineContractValues({
+            metadata,
             phase: explicitPhase ?? inferTimelinePhase(event.event),
+            status: typeof event.status === 'string' ? event.status : inferTimelineStatus(event.event),
+        });
+        return sortValue({
+            phase: timelineValues.phase,
             name: event.event,
             atMs,
-            status: typeof event.status === 'string' ? event.status : inferTimelineStatus(event.event),
+            status: timelineValues.status,
             ...((typeof event.owner === 'string' && event.owner.length > 0) || owner
                 ? { owner: event.owner || owner }
                 : {}),
-            ...(Object.keys(metadata).length > 0 ? { metadata } : {}),
+            ...(Object.keys(timelineValues.metadata).length > 0 ? { metadata: timelineValues.metadata } : {}),
         });
     })
-        .filter(Boolean)
-        .sort((left, right) => left.atMs - right.atMs);
+        .filter(Boolean);
+    const commandTimeline = buildCommandAcknowledgementTimeline({
+        entries: sessionEntries,
+        ...(typeof startedAt === 'string' ? { startedAt } : {}),
+    });
+    return [...eventTimeline, ...commandTimeline].sort((left, right) => left.atMs - right.atMs);
+}
+/**
+ * Summarizes repeated scenario accounting for causal artifacts.
+ *
+ * Metrics already decide product health; this summary makes the iteration
+ * evidence explicit for agents reading `causal-run.json`.
+ *
+ * @param {Record<string, unknown>} metrics
+ * @returns {Record<string, unknown> | null}
+ */
+function buildIterationSummary(metrics) {
+    if (typeof metrics.iterations !== 'number' || metrics.iterations < 1) {
+        return null;
+    }
+    const expected = Math.trunc(metrics.iterations);
+    const failed = typeof metrics.failures === 'number' && metrics.failures > 0
+        ? Math.trunc(metrics.failures)
+        : 0;
+    const timeouts = typeof metrics.timeouts === 'number' && metrics.timeouts > 0
+        ? Math.trunc(metrics.timeouts)
+        : 0;
+    const incomplete = Array.isArray(metrics.incompleteIterations)
+        ? [...new Set(metrics.incompleteIterations.filter((iteration) => (typeof iteration === 'number' &&
+                Number.isInteger(iteration) &&
+                iteration >= 1 &&
+                iteration <= expected)))].sort((left, right) => left - right)
+        : [];
+    const completed = Math.max(0, expected - incomplete.length);
+    const status = timeouts > 0
+        ? 'timeout'
+        : failed === 0 && incomplete.length === 0
+            ? 'complete'
+            : completed > 0
+                ? 'partial'
+                : 'failed';
+    return {
+        completed,
+        expected,
+        failed,
+        incomplete,
+        status,
+        timeouts,
+    };
 }
 /**
  * Builds the `budget-verdict.json` profile artifact from budget evaluation.
@@ -647,6 +1177,8 @@ function normalizeBudgetsForCausalRun(budgets) {
  * @returns {Record<string, unknown>}
  */
 function buildCausalRun({ scenario, flowId, runId, platform = 'ios', buildFlavor = 'unknown', interactionDriver, trigger = null, budgets = null, timeline = [], artifacts, manifest, metrics, }) {
+    const iterationSummary = buildIterationSummary(metrics);
+    const videoPath = typeof artifacts.captures?.video === 'string' ? artifacts.captures.video : null;
     return sortValue({
         schemaVersion: '1.0.0',
         flowId,
@@ -664,13 +1196,21 @@ function buildCausalRun({ scenario, flowId, runId, platform = 'ios', buildFlavor
                 kind: 'unknown',
                 label: scenario.description ?? scenario.name,
             },
+        provenanceRef: {
+            manifest: artifacts.manifest,
+            runId,
+            ...(typeof manifest.scenarioHash === 'string' && manifest.scenarioHash.length > 0
+                ? { scenarioHash: manifest.scenarioHash }
+                : {}),
+        },
         budgets: normalizeBudgetsForCausalRun(budgets),
         timeline,
+        ...(iterationSummary ? { iterationSummary } : {}),
         artifacts: {
             summary: artifacts.summary,
             metrics: artifacts.metrics,
             manifest: artifacts.manifest,
-            video: artifacts.captures?.video,
+            ...(videoPath ? { video: videoPath } : {}),
             screenshot: Array.isArray(artifacts.captures?.screenshots)
                 ? artifacts.captures.screenshots[0] ?? null
                 : null,
@@ -689,7 +1229,61 @@ function buildCausalRun({ scenario, flowId, runId, platform = 'ios', buildFlavor
  * @param {Record<string, unknown>} options
  * @returns {Record<string, unknown>}
  */
-function buildManifest({ scenario, scenarioHash, runId, platform = 'ios', status, startedAt, endedAt, interactionDriver, comparisonLane, simulator, bundleId, gitSha, toolVersions, artifacts, failureReason = null, }) {
+function buildManifest({ scenario, scenarioHash, runId, attemptId, attemptNumber, maxAttempts, retryOfAttemptId, retryReason, platform = 'ios', status, terminalState, startedAt, endedAt, interactionDriver, comparisonLane, classification, cleanup, partialArtifacts, preconditions, postconditions, simulator, bundleId, gitSha, toolVersions, cohort, artifacts, failureReason = null, }) {
+    const durationMs = roundMs(Math.max(0, Date.parse(endedAt) - Date.parse(startedAt)));
+    const sortedToolVersions = sortValue(toolVersions);
+    const sortedSimulator = sortValue(simulator);
+    const normalizedCohort = normalizeProvenanceCohort(cohort);
+    const cohortHash = normalizedCohort ? hashStableValue(normalizedCohort) : null;
+    const resolvedTerminalState = typeof terminalState === 'string' && terminalState.length > 0 ? terminalState : status;
+    const resolvedAttemptNumber = Number.isInteger(attemptNumber) ? attemptNumber : 1;
+    const resolvedMaxAttempts = Number.isInteger(maxAttempts) ? maxAttempts : Math.max(1, resolvedAttemptNumber);
+    const resolvedAttemptId = typeof attemptId === 'string' && attemptId.length > 0 ? attemptId : runId;
+    const resolvedClassification = classification
+        ? sortValue(classification)
+        : {
+            category: status === 'passed' ? 'none' : 'unknown',
+        };
+    const resolvedCleanup = cleanup
+        ? sortValue(cleanup)
+        : {
+            status: 'not-required',
+        };
+    const resolvedPartialArtifacts = partialArtifacts
+        ? sortValue(partialArtifacts)
+        : {
+            valid: status !== 'passed',
+            reason: status === 'passed'
+                ? 'complete successful run artifacts are present'
+                : 'failed run artifacts are preserved for diagnosis and must not be treated as product proof unless health passes',
+        };
+    const resolvedAttempt = {
+        attemptId: resolvedAttemptId,
+        attemptNumber: resolvedAttemptNumber,
+        maxAttempts: resolvedMaxAttempts,
+        ...(typeof retryOfAttemptId === 'string' && retryOfAttemptId.length > 0 ? { retryOfAttemptId } : {}),
+        ...(typeof retryReason === 'string' && retryReason.length > 0 ? { retryReason } : {}),
+        runId,
+        status,
+        terminalState: resolvedTerminalState,
+        startedAt,
+        endedAt,
+        durationMs,
+        interactionDriver,
+        ...(typeof comparisonLane === 'string' && comparisonLane.length > 0 ? { comparisonLane } : {}),
+        classification: resolvedClassification,
+        cleanup: resolvedCleanup,
+        partialArtifacts: resolvedPartialArtifacts,
+    };
+    const resolvedPreconditions = sortValue({
+        ...DEFAULT_ENVIRONMENT_PRECONDITIONS,
+        ...(preconditions && typeof preconditions === 'object' ? preconditions : {}),
+    });
+    const resolvedPostconditions = sortValue({
+        ...DEFAULT_ENVIRONMENT_POSTCONDITIONS,
+        ...(postconditions && typeof postconditions === 'object' ? postconditions : {}),
+    });
+    assertAttemptInvariants(resolvedAttempt);
     return {
         scenario,
         ...(typeof scenarioHash === 'string' && scenarioHash.length > 0 ? { scenarioHash } : {}),
@@ -698,13 +1292,28 @@ function buildManifest({ scenario, scenarioHash, runId, platform = 'ios', status
         status,
         startedAt,
         endedAt,
-        durationMs: roundMs(Math.max(0, Date.parse(endedAt) - Date.parse(startedAt))),
+        durationMs,
         interactionDriver,
         ...(typeof comparisonLane === 'string' && comparisonLane.length > 0 ? { comparisonLane } : {}),
-        simulator: sortValue(simulator),
+        provenance: {
+            ...(typeof scenarioHash === 'string' && scenarioHash.length > 0 ? { scenarioHash } : {}),
+            ...(normalizedCohort ? { cohort: normalizedCohort, cohortHash } : {}),
+            gitSha,
+            toolVersions: sortedToolVersions,
+        },
+        attempt: resolvedAttempt,
+        environment: {
+            platform,
+            bundleId,
+            runtimeTarget: sortedSimulator,
+            ...(typeof sortedToolVersions.node === 'string' ? { nodeVersion: sortedToolVersions.node } : {}),
+            preconditions: resolvedPreconditions,
+            postconditions: resolvedPostconditions,
+        },
+        simulator: sortedSimulator,
         bundleId,
         gitSha,
-        toolVersions: sortValue(toolVersions),
+        toolVersions: sortedToolVersions,
         artifacts: sortValue(artifacts),
         failureReason,
     };
@@ -734,9 +1343,34 @@ function buildSummaryMarkdown({ manifest, metrics }) {
     const evidenceAttachments = Array.isArray(manifest.artifacts.evidenceAttachments)
         ? manifest.artifacts.evidenceAttachments
         : [];
+    const diagnostics = Array.isArray(manifest.artifacts.diagnostics)
+        ? manifest.artifacts.diagnostics
+        : [];
     const evidenceAttachmentLines = evidenceAttachments.length > 0
         ? evidenceAttachments.map((attachment) => `- ${attachment.channel}/${attachment.kind}: \`${attachment.path}\` (${attachment.sizeBytes} bytes, sha256 ${attachment.sha256})`)
         : ['- none'];
+    const diagnosticLines = diagnostics.length > 0
+        ? diagnostics.map((diagnostic) => {
+            const label = diagnostic.name ? `${diagnostic.kind}/${diagnostic.name}` : diagnostic.kind;
+            const pathLabel = typeof diagnostic.path === 'string' ? ` \`${diagnostic.path}\`` : '';
+            const reasonLabel = typeof diagnostic.reason === 'string' ? ` - ${diagnostic.reason}` : '';
+            return `- ${label}: ${diagnostic.status}${diagnostic.required ? ' (required)' : ''}${pathLabel}${reasonLabel}`;
+        })
+        : ['- none'];
+    const attempt = manifest.attempt && typeof manifest.attempt === 'object' ? manifest.attempt : {};
+    const attemptLines = [
+        `- Attempt ID: \`${attempt.attemptId ?? manifest.runId}\``,
+        `- Attempt number: ${attempt.attemptNumber ?? 1}/${attempt.maxAttempts ?? 1}`,
+        `- Terminal state: ${attempt.terminalState ?? manifest.status}`,
+        ...(typeof attempt.retryOfAttemptId === 'string'
+            ? [`- Retry of: \`${attempt.retryOfAttemptId}\``]
+            : []),
+        ...(typeof attempt.retryReason === 'string'
+            ? [`- Retry reason: ${attempt.retryReason}`]
+            : []),
+        `- Cleanup: ${attempt.cleanup?.status ?? 'unknown'}`,
+        `- Partial artifacts valid: ${attempt.partialArtifacts?.valid === true ? 'yes' : 'no'}`,
+    ];
     const lines = [
         `# ${String(manifest.platform || 'ios').toUpperCase()} profile run: ${manifest.scenario}`,
         '',
@@ -755,6 +1389,10 @@ function buildSummaryMarkdown({ manifest, metrics }) {
         `- p50 cycle: ${metrics.p50Ms === null ? 'n/a' : `${metrics.p50Ms}ms`}`,
         `- p95 cycle: ${metrics.p95Ms === null ? 'n/a' : `${metrics.p95Ms}ms`}`,
         '',
+        '## Attempt',
+        '',
+        ...attemptLines,
+        '',
         '## Artifact paths',
         '',
         `- Causal run: \`${manifest.artifacts.causalRun}\``,
@@ -762,10 +1400,18 @@ function buildSummaryMarkdown({ manifest, metrics }) {
         `- Manifest: \`${manifest.artifacts.manifest}\``,
         `- Scenario: \`${manifest.artifacts.scenario}\``,
         `- Metrics: \`${manifest.artifacts.metrics}\``,
-        `- Interaction log: \`${manifest.artifacts.raw.interactionLog}\``,
-        `- Device log: \`${manifest.artifacts.raw.deviceLog}\``,
-        `- Video: \`${manifest.artifacts.captures.video}\``,
-        `- UI tree: \`${manifest.artifacts.captures.uiTree}\``,
+        `- Interaction log: ${typeof manifest.artifacts.raw.interactionLog === 'string'
+            ? `\`${manifest.artifacts.raw.interactionLog}\``
+            : 'none'}`,
+        `- Device log: ${typeof manifest.artifacts.raw.deviceLog === 'string'
+            ? `\`${manifest.artifacts.raw.deviceLog}\``
+            : 'none'}`,
+        `- Video: ${typeof manifest.artifacts.captures.video === 'string'
+            ? `\`${manifest.artifacts.captures.video}\``
+            : 'none'}`,
+        `- UI tree: ${typeof manifest.artifacts.captures.uiTree === 'string'
+            ? `\`${manifest.artifacts.captures.uiTree}\``
+            : 'none'}`,
         `- Screenshots: ${screenshots.length > 0
             ? screenshots.map((item) => `\`${item}\``).join(', ')
             : 'none'}`,
@@ -777,6 +1423,10 @@ function buildSummaryMarkdown({ manifest, metrics }) {
         '## Evidence attachments',
         '',
         ...evidenceAttachmentLines,
+        '',
+        '## Diagnostic inventory',
+        '',
+        ...diagnosticLines,
     ];
     if (metrics.budgetEvaluation) {
         lines.push('', '## Budget', '', `- Metric: ${metrics.budgetEvaluation.metric}`, `- Status: ${metrics.budgetEvaluation.pass ? 'pass' : 'fail'}`);