@murphai/murph 1.3.0 → 1.3.1

package/node_modules/@murphai/core/dist/mutations.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { assertContractId, compareIsoTimestampsAscending, deviceDataOriginSchema, experimentFrontmatterSchema, externalRefSchema, journalDayFrontmatterSchema, eventRecordSchema, eventImportDecisionSchema, isWritableIsoDateTime, safeParseContract, sampleRecordSchema, } from "@murphai/contracts";
+import { createReadStream } from "node:fs";
+import { auditRecordSchema, assertContractId, collectEventRawReferencePaths, compareIsoTimestampsAscending, deviceDataOriginSchema, experimentFrontmatterSchema, externalRefSchema, journalDayFrontmatterSchema, eventRecordSchema, eventImportDecisionSchema, isWritableIsoDateTime, safeParseContract, sampleRecordSchema, } from "@murphai/contracts";
 import { BASELINE_EVENT_KINDS, BASELINE_SAMPLE_STREAMS, EVENT_SCHEMA_VERSION, EVENT_SOURCES, FRONTMATTER_SCHEMA_VERSIONS, ID_PREFIXES, SAMPLE_QUALITIES, SAMPLE_SCHEMA_VERSION, SAMPLE_SOURCES, VAULT_LAYOUT, } from "./constants.js";
 import { emitAuditRecord } from "./audit.js";
 import { prepareEventAttachments, stagePreparedEventAttachmentsInBatch, } from "./event-attachments.js";
@@ -10,18 +11,19 @@ import { parseFrontmatterDocument, stringifyFrontmatterDocument } from "./frontm
 import { deterministicContractId, generateRecordId } from "./ids.js";
 import { readJsonlRecords, toMonthlyShardRelativePath, visitJsonlRecordsInterruptible, } from "./jsonl.js";
 import { buildEventSpineLifecycle, collapseEventSpineEntries, compareEventSpineEntries, eventSpineRevision, isDeletedEventSpineRecord, selectLatestEventSpineEntry, } from "./history/event-spine.js";
-import { buildPublicEventImportRecord, loadEventLedgerShardsById, selectLatestMatchedEvent, toEventLedgerFile, } from "./domains/events/ledger.js";
+import { buildEventImportDecisionRecord, buildPublicEventImportRecord, loadEventLedgerShardsById, selectLatestMatchedEvent, toEventLedgerFile, } from "./domains/events/ledger.js";
 import { normalizeMealNutrition, } from "./nutrition.js";
-import { stageRawImportManifest } from "./operations/raw-manifests.js";
-import { runCanonicalWrite } from "./operations/write-batch.js";
+import { parseRawImportManifest, resolveRawManifestPath, stageRawImportManifest, } from "./operations/raw-manifests.js";
+import { runCanonicalWrite, } from "./operations/write-batch.js";
 import { assertCanonicalWriteLockScope } from "./operations/canonical-write-lock.js";
 import { resolveVaultPath } from "./path-safety.js";
 import { sanitizePathSegment } from "./path-safety.js";
-import { prepareInlineRawArtifact, prepareRawArtifact, resolveRawAssetDirectory } from "./raw.js";
+import { prepareInlineRawArtifact, prepareRawArtifact, rawDirectoryMatchesOwner, resolveRawAssetDirectory, } from "./raw.js";
 import { buildIntegrationEvidencePart, buildIntegrationIngestAppendPlan, buildIntegrationIngestAppendPlanFromInspection, buildIntegrationIngestRecord, stageIntegrationIngestAppendPlan, compactIntegrationIngestReceipt, inspectIntegrationIngestIdsForImportedAt, selectNovelIntegrationIngestEvidence, } from "./integration-ingests.js";
 import { normalizeUniqueTextList } from "./bank/shared.js";
 import { defaultTimeZone, normalizeTimeZone, toIsoTimestamp, toLocalDayKey, } from "./time.js";
 import { loadVault } from "./vault.js";
+import { statAndHashVaultFile } from "./raw-artifact-integrity.js";
 const DENSE_DEVICE_TELEMETRY_NOT_ALLOWED_CODE = "VAULT_DENSE_DEVICE_TELEMETRY_NOT_ALLOWED";
 const DENSE_DEVICE_SAMPLES_NOT_ALLOWED_LEGACY_CODE = "VAULT_DENSE_DEVICE_SAMPLES_NOT_ALLOWED";
 const RESERVED_DEVICE_EVENT_FIELD_NAMES = new Set([
@@ -785,6 +787,80 @@ function compareIncomingExternalRefVersion(existing, incoming) {
     }
     return compareIsoTimestampsAscending(incomingVersion, existingVersion);
 }
+const JUNCTION_SPARSE_INTERVAL_RESOURCE_TYPE_SUFFIXES = [
+    "-caffeine",
+    "-mindfulness-minutes",
+    "-water",
+];
+const MAX_JUNCTION_SPARSE_AFFECTED_DAY_KEYS = 64;
+function isJunctionSparseIntervalExternalRef(externalRef) {
+    return externalRef.system === "junction"
+        && externalRef.facet === "interval"
+        && JUNCTION_SPARSE_INTERVAL_RESOURCE_TYPE_SUFFIXES.some((suffix) => externalRef.resourceType.endsWith(suffix));
+}
+function junctionSparseAffectedCalendarTargets(events, index) {
+    const targets = new Map();
+    for (const event of events) {
+        if (!event.externalRef || !isJunctionSparseIntervalExternalRef(event.externalRef)) {
+            continue;
+        }
+        const sourceProviderSlug = event.dataOrigin?.sourceProviderSlug;
+        const externalRefSourceProviderSlug = JUNCTION_SPARSE_INTERVAL_RESOURCE_TYPE_SUFFIXES
+            .find((suffix) => event.externalRef?.resourceType.endsWith(suffix));
+        const resolvedSourceProviderSlug = sourceProviderSlug ?? (externalRefSourceProviderSlug
+            ? event.externalRef.resourceType.slice("junction-".length, -externalRefSourceProviderSlug.length)
+            : "");
+        if (!resolvedSourceProviderSlug) {
+            continue;
+        }
+        const addTarget = (dayKey) => {
+            const target = {
+                dayKey,
+                sourceProviderSlug: resolvedSourceProviderSlug,
+                ...(event.dataOrigin?.sourceInstanceId === undefined
+                    ? {}
+                    : { sourceInstanceId: event.dataOrigin.sourceInstanceId }),
+                ...(event.dataOrigin?.sourceType
+                    ? { sourceType: event.dataOrigin.sourceType }
+                    : {}),
+            };
+            targets.set(stableStringify(target), target);
+        };
+        addTarget(event.dayKey);
+        // Include the immediately displaced provider day so the caller can persist
+        // one calendar-refresh job for each side of this accepted transition.
+        const previousRevision = eventSpineRevision(event) - 1;
+        if (previousRevision < 1) {
+            continue;
+        }
+        const dayHistory = index.junctionSparseDayHistoryById.get(event.id);
+        const previousDayKey = dayHistory?.latest.revision === previousRevision
+            ? dayHistory.latest.dayKey
+            : dayHistory?.previous?.revision === previousRevision
+                ? dayHistory.previous.dayKey
+                : undefined;
+        if (previousDayKey) {
+            addTarget(previousDayKey);
+        }
+    }
+    const affectedTargets = [...targets.values()].sort((left, right) => left.dayKey.localeCompare(right.dayKey)
+        || left.sourceProviderSlug.localeCompare(right.sourceProviderSlug)
+        || (left.sourceType ?? "").localeCompare(right.sourceType ?? "")
+        || (left.sourceInstanceId ?? "").localeCompare(right.sourceInstanceId ?? ""));
+    const affectedDayKeys = new Set(affectedTargets.map((target) => target.dayKey));
+    if (affectedDayKeys.size > MAX_JUNCTION_SPARSE_AFFECTED_DAY_KEYS
+        || affectedTargets.length > MAX_JUNCTION_SPARSE_AFFECTED_DAY_KEYS) {
+        throw new VaultError("DEVICE_IMPORT_AFFECTED_DAY_LIMIT_EXCEEDED", "Junction sparse import exceeded the affected provider-day limit; nothing was imported.", {
+            affectedDayCount: affectedDayKeys.size,
+            affectedTargetCount: affectedTargets.length,
+            maxAllowed: MAX_JUNCTION_SPARSE_AFFECTED_DAY_KEYS,
+        });
+    }
+    return affectedTargets;
+}
+function junctionSparseAffectedDayKeys(targets) {
+    return [...new Set(targets.map((target) => target.dayKey))].sort();
+}
 // Device-sync content equality ignores per-import identity (id, lifecycle,
 // recordedAt) AND rawRefs, because device imports mint fresh raw-artifact
 // paths on every sync run.
@@ -873,6 +949,7 @@ function orderEventImportDecisionsBySourceVersion(decisions) {
 }
 async function indexLatestEventsByExternalRef(vaultRoot, relativePaths, signal) {
     const deviceOwnerRevisionsByRefKeyAndFingerprint = new Map();
+    const junctionSparseDayHistoryById = new Map();
     const latestByRefKey = new Map();
     const latestById = new Map();
     const maxRevisionById = new Map();
@@ -897,8 +974,27 @@ async function indexLatestEventsByExternalRef(vaultRoot, relativePaths, signal)
                 const entry = { relativePath, record: parsed.data };
                 maxRevisionById.set(entry.record.id, Math.max(maxRevisionById.get(entry.record.id) ?? 0, eventSpineRevision(entry.record)));
                 const revisions = revisionsById.get(entry.record.id) ?? new Set();
-                revisions.add(eventSpineRevision(entry.record));
+                const revision = eventSpineRevision(entry.record);
+                revisions.add(revision);
                 revisionsById.set(entry.record.id, revisions);
+                if (entry.record.externalRef
+                    && isJunctionSparseIntervalExternalRef(entry.record.externalRef)) {
+                    const candidate = { dayKey: entry.record.dayKey, revision };
+                    const history = junctionSparseDayHistoryById.get(entry.record.id);
+                    if (!history || revision > history.latest.revision) {
+                        junctionSparseDayHistoryById.set(entry.record.id, {
+                            latest: candidate,
+                            ...(history ? { previous: history.latest } : {}),
+                        });
+                    }
+                    else if (revision < history.latest.revision
+                        && (!history.previous || revision > history.previous.revision)) {
+                        junctionSparseDayHistoryById.set(entry.record.id, {
+                            latest: history.latest,
+                            previous: candidate,
+                        });
+                    }
+                }
                 const state = entriesById.get(entry.record.id);
                 const latestDeviceExternalRefEntryByRefKey = state?.latestDeviceExternalRefEntryByRefKey ?? new Map();
                 if (entry.record.source === "device" && entry.record.externalRef) {
@@ -968,6 +1064,7 @@ async function indexLatestEventsByExternalRef(vaultRoot, relativePaths, signal)
     }
     return {
         deviceOwnerRevisionsByRefKeyAndFingerprint,
+        junctionSparseDayHistoryById,
         latestByRefKey,
         latestById,
         maxRevisionById,
@@ -1222,6 +1319,7 @@ async function buildDeviceEventIdentityContext(vaultRoot, entries) {
         return {
             index: {
                 deviceOwnerRevisionsByRefKeyAndFingerprint: new Map(),
+                junctionSparseDayHistoryById: new Map(),
                 latestByRefKey: new Map(),
                 latestById: new Map(),
                 maxRevisionById: new Map(),
@@ -1243,6 +1341,7 @@ function cloneDeviceEventIdentityContext(context) {
     return {
         index: {
             deviceOwnerRevisionsByRefKeyAndFingerprint: context.index.deviceOwnerRevisionsByRefKeyAndFingerprint,
+            junctionSparseDayHistoryById: context.index.junctionSparseDayHistoryById,
             latestByRefKey: new Map(context.index.latestByRefKey),
             latestById: new Map(context.index.latestById),
             maxRevisionById: new Map(context.index.maxRevisionById),
@@ -1254,6 +1353,7 @@ function cloneDeviceEventIdentityContext(context) {
 function buildEmptyDeviceEventIdentityContext(entries) {
     const index = {
         deviceOwnerRevisionsByRefKeyAndFingerprint: new Map(),
+        junctionSparseDayHistoryById: new Map(),
         latestByRefKey: new Map(),
         latestById: new Map(),
         maxRevisionById: new Map(),
@@ -1551,6 +1651,34 @@ async function reconcileDeviceEventEntriesByExternalRef(vaultRoot, entries, exis
         if (entry.externalRefUpdatePolicy === "immutable") {
             throw new VaultError("EVENT_IMMUTABLE_EXTERNAL_REF_CONFLICT", "Immutable device event externalRef already exists with different content; nothing was imported.");
         }
+        if (indexedProviderMatch
+            && isJunctionSparseIntervalExternalRef(indexedProviderMatch.indexedExternalRef)
+            && isJunctionSparseIntervalExternalRef(externalRef)
+            && (indexedProviderMatch.indexedExternalRef.version !== undefined
+                || externalRef.version !== undefined)) {
+            const sourceVersionComparison = compareIncomingExternalRefVersion(indexedProviderMatch.indexedExternalRef, externalRef);
+            if (sourceVersionComparison === null) {
+                const incomingVersion = externalRef.version;
+                const existingVersion = indexedProviderMatch.indexedExternalRef.version;
+                const replacesUnorderedBaseline = incomingVersion !== undefined
+                    && isWritableIsoDateTime(incomingVersion)
+                    && (existingVersion === undefined || !isWritableIsoDateTime(existingVersion));
+                if (!replacesUnorderedBaseline) {
+                    throw new VaultError("EVENT_SOURCE_REVISION_UNORDERED", "Changed Junction sparse intervals require comparable explicit provider revisions; nothing was imported.");
+                }
+            }
+            if (sourceVersionComparison !== null && sourceVersionComparison < 0) {
+                skippedDuplicateCount += 1;
+                if (eventSpineRevisionsAreComplete(index, latest.id)) {
+                    retainedPreparedIds.add(entry.record.id);
+                }
+                records.push(latest);
+                continue;
+            }
+            if (sourceVersionComparison === 0) {
+                throw new VaultError("EVENT_SOURCE_REVISION_CONFLICT", "Junction sparse interval content conflicts at the same provider revision; nothing was imported.");
+            }
+        }
         if (indexedProviderMatch
             && indexedProviderMatch.indexedExternalRef.system === "whoop"
             && externalRef.system === "whoop") {
@@ -1665,6 +1793,22 @@ async function reconcileEventImportDecisionsByExternalRef(vaultRoot, decisions,
         signal,
     });
     const index = await indexLatestEventsByExternalRef(vaultRoot, shardPaths, signal);
+    for (const decision of decisions) {
+        signal?.throwIfAborted();
+        if (decision.action !== "upsert" || !decision.expectedLatest) {
+            continue;
+        }
+        const externalRef = decision.entry.record.externalRef;
+        const latestById = index.latestById.get(decision.expectedLatest.eventId);
+        const latestByRef = externalRef
+            ? index.latestByRefKey.get(eventExternalRefKey(externalRef))?.record
+            : undefined;
+        if (!latestById
+            || latestById.id !== latestByRef?.id
+            || eventSpineRevision(latestById) !== decision.expectedLatest.lifecycleRevision) {
+            throw new VaultError("EVENT_EXPECTED_LATEST_MISMATCH", "An imported event changed after it was inspected; the whole batch was rejected without writes.");
+        }
+    }
     const appendEntries = [];
     const forceAppendIds = new Set();
     const eventIds = [];
@@ -2103,8 +2247,396 @@ function prepareDeviceBatchPlan({ provider, accountId, importedAt = new Date(),
         preparedEvidenceParts,
     };
 }
-export async function importDocument({ vaultRoot, sourcePath, occurredAt = new Date(), title, note, source = "import", }) {
+async function hashSourceFile(sourcePath) {
+    const hash = createHash("sha256");
+    let byteLength = 0;
+    await new Promise((resolve, reject) => {
+        const stream = createReadStream(sourcePath);
+        stream.on("data", (chunk) => {
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            byteLength += bytes.byteLength;
+            hash.update(bytes);
+        });
+        stream.on("error", reject);
+        stream.on("end", resolve);
+    });
+    return { byteLength, sha256: hash.digest("hex") };
+}
+const DOCUMENT_SOURCE_AUDIT_COMMAND = "core.importDocument";
+const WORKOUT_SOURCE_IMPORT_AUDIT_COMMAND = "core.importEventBatch.sourceRawRefOnce";
+function buildRawSourceReceiptTarget(sourceReceipt) {
+    return `raw-source-v1:sha256:${sourceReceipt.sha256}:bytes:${sourceReceipt.byteLength}`;
+}
+function rejectDamagedExactDocumentEvidence(input) {
+    throw new VaultError("RAW_MANIFEST_INVALID", "Preserved exact source evidence is incomplete or damaged. Exact reuse will not create a replacement identity.", {
+        documentId: input.documentId,
+        ...(input.manifestPath ? { manifestPath: input.manifestPath } : {}),
+        reason: input.reason,
+    });
+}
+async function inspectExactSourceAuditEvidence(input) {
+    const targetId = buildRawSourceReceiptTarget(input.sourceReceipt);
+    const auditPaths = await walkVaultFiles(input.vaultRoot, VAULT_LAYOUT.auditDirectory, {
+        extension: ".jsonl",
+    });
+    const completionTargetEventIds = new Set();
+    const documentIdsByEventId = new Map();
+    for (const relativePath of auditPaths) {
+        for (const rawRecord of await readJsonlRecords({ vaultRoot: input.vaultRoot, relativePath })) {
+            const parsed = safeParseContract(auditRecordSchema, rawRecord);
+            if (!parsed.success
+                || parsed.data.status !== "success"
+                || parsed.data.targetIds?.includes(targetId) !== true) {
+                continue;
+            }
+            const targetIds = parsed.data.targetIds;
+            if (parsed.data.commandName === DOCUMENT_SOURCE_AUDIT_COMMAND) {
+                let documentId;
+                let eventId;
+                try {
+                    if (targetIds.length !== 3 || targetIds[0] !== targetId) {
+                        throw new TypeError("source receipt audit must retain exactly one owner");
+                    }
+                    documentId = assertContractId(targetIds[1], ID_PREFIXES.document, "documentId");
+                    eventId = assertContractId(targetIds[2], ID_PREFIXES.event, "eventId");
+                }
+                catch {
+                    rejectDamagedExactDocumentEvidence({
+                        documentId: typeof targetIds[1] === "string" ? targetIds[1] : "unknown",
+                        reason: "source receipt audit does not retain one valid document owner",
+                    });
+                }
+                const existing = documentIdsByEventId.get(eventId);
+                if (existing && existing !== documentId) {
+                    rejectDamagedExactDocumentEvidence({
+                        documentId,
+                        reason: "source receipt audit assigns one event to multiple document owners",
+                    });
+                }
+                documentIdsByEventId.set(eventId, documentId);
+                continue;
+            }
+            if (parsed.data.commandName === WORKOUT_SOURCE_IMPORT_AUDIT_COMMAND) {
+                for (const candidate of targetIds.slice(1)) {
+                    try {
+                        completionTargetEventIds.add(assertContractId(candidate, ID_PREFIXES.event, "eventId"));
+                    }
+                    catch {
+                        // The bounded audit target list may contain non-event context.
+                    }
+                }
+            }
+        }
+    }
+    return { completionTargetEventIds, documentIdsByEventId };
+}
+async function inspectExactDocumentSourceSet(input) {
+    const auditEvidence = await inspectExactSourceAuditEvidence(input);
+    const emptyActivityIndex = new Map();
+    if (auditEvidence.documentIdsByEventId.size === 0
+        && auditEvidence.completionTargetEventIds.size === 0) {
+        return {
+            activityEventIdsByRawRef: emptyActivityIndex,
+            completionAuditEventIds: new Set(),
+            deletedExactSourceExists: false,
+            liveSources: [],
+        };
+    }
+    const shardPaths = await walkVaultFiles(input.vaultRoot, VAULT_LAYOUT.eventLedgerDirectory, {
+        extension: ".jsonl",
+    });
+    const entries = [];
+    const activityEventIds = new Set();
+    const activityEventIdsByRawRef = new Map();
+    for (const relativePath of shardPaths) {
+        for (const rawRecord of await readJsonlRecords({ vaultRoot: input.vaultRoot, relativePath })) {
+            const parsed = safeParseContract(eventRecordSchema, rawRecord);
+            const rawEventId = typeof rawRecord === "object"
+                && rawRecord !== null
+                && "id" in rawRecord
+                && typeof rawRecord.id === "string"
+                ? rawRecord.id
+                : null;
+            if (!parsed.success) {
+                if (rawEventId && auditEvidence.documentIdsByEventId.has(rawEventId)) {
+                    rejectDamagedExactDocumentEvidence({
+                        documentId: auditEvidence.documentIdsByEventId.get(rawEventId) ?? "unknown",
+                        reason: "source receipt audit points to a contract-invalid document event",
+                    });
+                }
+                continue;
+            }
+            if (parsed.data.kind === "document"
+                && auditEvidence.documentIdsByEventId.has(parsed.data.id)) {
+                entries.push({ relativePath, record: parsed.data });
+            }
+            if (parsed.data.kind === "activity_session") {
+                activityEventIds.add(parsed.data.id);
+                for (const rawRef of collectEventRawReferencePaths(parsed.data)) {
+                    const ids = activityEventIdsByRawRef.get(rawRef) ?? new Set();
+                    ids.add(parsed.data.id);
+                    activityEventIdsByRawRef.set(rawRef, ids);
+                }
+            }
+        }
+    }
+    const completionAuditEventIds = new Set([...auditEvidence.completionTargetEventIds].filter((eventId) => activityEventIds.has(eventId)));
+    if (auditEvidence.documentIdsByEventId.size === 0) {
+        if (completionAuditEventIds.size > 0) {
+            rejectDamagedExactDocumentEvidence({
+                documentId: "unknown",
+                reason: "whole-source completion survives without its source receipt owner",
+            });
+        }
+        return {
+            activityEventIdsByRawRef,
+            completionAuditEventIds,
+            deletedExactSourceExists: false,
+            liveSources: [],
+        };
+    }
+    // Exact-source identity needs the latest revision even when it is a
+    // tombstone. The ordinary collapse helper intentionally removes deleted
+    // records, which would make a deleted source look like it never existed.
+    const latestDocuments = new Map();
+    for (const entry of entries) {
+        const current = latestDocuments.get(entry.record.id);
+        if (!current || compareEventSpineEntries(current, entry) < 0) {
+            latestDocuments.set(entry.record.id, entry);
+        }
+    }
+    // The content-derived import audit owns source recreation identity. Its
+    // document/event targets select the lifecycle row; that row derives the one
+    // manifest and raw artifact to verify. No vault-wide manifest discovery or
+    // compatibility reader participates in the decision.
+    const claims = new Map();
+    for (const [eventId, documentId] of auditEvidence.documentIdsByEventId) {
+        let origin = null;
+        let raw = null;
+        for (const entry of entries) {
+            if (entry.record.id !== eventId || entry.record.documentId !== documentId) {
+                continue;
+            }
+            const candidateRaw = entry.record.attachments?.find((attachment) => attachment.role === "source_document"
+                && attachment.sha256 === input.sourceReceipt.sha256);
+            if (candidateRaw
+                && (!origin || compareEventSpineEntries(entry, origin) < 0)) {
+                origin = entry;
+                raw = candidateRaw;
+            }
+        }
+        if (!origin || !raw) {
+            rejectDamagedExactDocumentEvidence({
+                documentId,
+                reason: "source receipt audit has no matching canonical document event",
+            });
+        }
+        claims.set(eventId, { entry: origin, raw });
+    }
+    const verified = new Map();
+    for (const claim of [...claims.values()]
+        .sort((left, right) => left.entry.record.id.localeCompare(right.entry.record.id))) {
+        const documentId = claim.entry.record.documentId;
+        const manifestPath = resolveRawManifestPath({
+            artifacts: [claim.raw],
+            importId: documentId,
+            importedAt: claim.entry.record.recordedAt,
+        });
+        const latest = latestDocuments.get(claim.entry.record.id);
+        if (!latest
+            || latest.record.documentId !== documentId
+            || !claim.entry.record.rawRefs?.includes(claim.raw.relativePath)) {
+            rejectDamagedExactDocumentEvidence({
+                documentId,
+                manifestPath,
+                reason: "canonical document history does not retain one stable source owner",
+            });
+        }
+        let manifestText;
+        try {
+            manifestText = await readUtf8File(input.vaultRoot, manifestPath);
+        }
+        catch (error) {
+            if (error instanceof VaultError && error.code === "VAULT_FILE_MISSING") {
+                rejectDamagedExactDocumentEvidence({
+                    documentId,
+                    manifestPath,
+                    reason: "required raw manifest is missing",
+                });
+            }
+            throw error;
+        }
+        let manifest;
+        try {
+            manifest = parseRawImportManifest(JSON.parse(manifestText));
+        }
+        catch {
+            rejectDamagedExactDocumentEvidence({
+                documentId,
+                manifestPath,
+                reason: "required raw manifest is malformed",
+            });
+        }
+        const sourceArtifacts = manifest.artifacts.filter((artifact) => artifact.role === "source_document");
+        const artifact = sourceArtifacts[0];
+        let resolvedManifestPath = null;
+        try {
+            resolvedManifestPath = resolveRawManifestPath({
+                artifacts: manifest.artifacts,
+                rawDirectory: manifest.rawDirectory,
+                importId: manifest.importId,
+                importedAt: manifest.importedAt,
+            });
+        }
+        catch {
+            // The shared resolver supplies the semantic owner/directory check below.
+        }
+        if (manifest.importKind !== "document"
+            || manifest.importId !== documentId
+            || manifest.importedAt !== claim.entry.record.recordedAt
+            || manifest.owner.kind !== "document"
+            || manifest.owner.id !== documentId
+            || !rawDirectoryMatchesOwner(manifest.rawDirectory, manifest.owner)
+            || resolvedManifestPath !== manifestPath
+            || sourceArtifacts.length !== 1
+            || !artifact
+            || artifact.relativePath !== claim.raw.relativePath
+            || artifact.originalFileName !== claim.raw.originalFileName
+            || artifact.mediaType !== claim.raw.mediaType
+            || artifact.byteSize !== input.sourceReceipt.byteLength
+            || artifact.sha256 !== input.sourceReceipt.sha256) {
+            rejectDamagedExactDocumentEvidence({
+                documentId,
+                manifestPath,
+                reason: "raw manifest does not match its canonical document owner",
+            });
+        }
+        const integrity = await statAndHashVaultFile(input.vaultRoot, artifact.relativePath);
+        if (!integrity) {
+            throw new VaultError("RAW_REFERENCE_MISSING", "Preserved exact source evidence is missing its immutable raw artifact. Exact reuse will not create a replacement identity.", { documentId, manifestPath, relativePath: artifact.relativePath });
+        }
+        if (integrity.byteSize !== artifact.byteSize
+            || integrity.sha256 !== artifact.sha256) {
+            rejectDamagedExactDocumentEvidence({
+                documentId,
+                manifestPath,
+                reason: "raw artifact bytes do not match the immutable manifest",
+            });
+        }
+        const latestRaw = latest.record.attachments?.find((attachment) => attachment.role === "source_document"
+            && attachment.relativePath === artifact.relativePath
+            && attachment.sha256 === artifact.sha256);
+        if (!latest.record.rawRefs?.includes(artifact.relativePath) || !latestRaw) {
+            rejectDamagedExactDocumentEvidence({
+                documentId,
+                manifestPath,
+                reason: "latest document lifecycle no longer retains its source attachment",
+            });
+        }
+        verified.set(claim.entry.record.id, {
+            latest,
+            manifestPath,
+            raw: claim.raw,
+        });
+    }
+    // A deleted identity must fence the whole exact-byte equivalence set. An
+    // ordinary import may have created a live alias later, but returning that
+    // alias would reset raw-reference-scoped workout completion.
+    const deletedExactSourceExists = [...verified.values()].some(({ latest }) => isDeletedEventSpineRecord(latest.record));
+    const liveSources = [];
+    for (const stored of verified.values()) {
+        const entry = stored.latest;
+        if (isDeletedEventSpineRecord(entry.record)) {
+            continue;
+        }
+        liveSources.push({
+            rawRef: stored.raw.relativePath,
+            result: {
+                created: false,
+                documentId: entry.record.documentId,
+                raw: {
+                    relativePath: stored.raw.relativePath,
+                    originalFileName: stored.raw.originalFileName,
+                    mediaType: stored.raw.mediaType,
+                },
+                event: entry.record,
+                eventPath: entry.relativePath,
+                auditPath: null,
+                manifestPath: stored.manifestPath,
+            },
+        });
+    }
+    return {
+        activityEventIdsByRawRef,
+        completionAuditEventIds,
+        deletedExactSourceExists,
+        liveSources,
+    };
+}
+async function findExactDocumentImport(input) {
+    const exactSources = await inspectExactDocumentSourceSet(input);
+    if (exactSources.deletedExactSourceExists) {
+        throw new VaultError("DOCUMENT_EXACT_SOURCE_DELETED", "An exact source document existed but was deleted. Exact reuse will not create a replacement identity.");
+    }
+    return exactSources.liveSources[0]?.result ?? null;
+}
+export const WORKOUT_SOURCE_IMPORT_STATUS_VALUES = [
+    "not_imported",
+    "completed",
+    "partial_conflict",
+];
+async function inspectWorkoutSourceImportStatus(input) {
+    const sourceIntegrity = await statAndHashVaultFile(input.vaultRoot, input.rawRef);
+    if (sourceIntegrity === null) {
+        throw new VaultError("EVENT_BATCH_SOURCE_RAW_REF_MISSING", "The workout source does not exist as a vault file.");
+    }
+    const sourceReceipt = {
+        byteLength: sourceIntegrity.byteSize,
+        sha256: sourceIntegrity.sha256,
+    };
+    const exactSources = await inspectExactDocumentSourceSet({
+        vaultRoot: input.vaultRoot,
+        sourceReceipt,
+    });
+    if (!exactSources.liveSources.some((source) => source.rawRef === input.rawRef)) {
+        throw new VaultError("EVENT_BATCH_SOURCE_DOCUMENT_NOT_LIVE", "The workout source is no longer owned by a live source document.");
+    }
+    if (exactSources.deletedExactSourceExists) {
+        throw new VaultError("DOCUMENT_EXACT_SOURCE_DELETED", "An exact source document existed but was deleted. Workout import will not reuse a replacement identity.");
+    }
+    const completionTargetId = buildRawSourceReceiptTarget(sourceReceipt);
+    const exactRawRefs = new Set(exactSources.liveSources.map((source) => source.rawRef));
+    const sourceEventIds = new Set();
+    for (const rawRef of exactRawRefs) {
+        for (const eventId of exactSources.activityEventIdsByRawRef.get(rawRef) ?? []) {
+            sourceEventIds.add(eventId);
+        }
+    }
+    if ([...exactSources.completionAuditEventIds].some((eventId) => sourceEventIds.has(eventId))) {
+        return { status: "completed", completionTargetId };
+    }
+    return {
+        status: sourceEventIds.size > 0 ? "partial_conflict" : "not_imported",
+        completionTargetId,
+    };
+}
+export async function resolveWorkoutSourceImportStatus(input) {
+    return (await inspectWorkoutSourceImportStatus(input)).status;
+}
+export async function importDocument({ vaultRoot, sourcePath, occurredAt = new Date(), title, note, source = "import", reuseExact = false, }) {
     const vault = await loadVault({ vaultRoot });
+    const sourceReceipt = await hashSourceFile(sourcePath);
+    if (reuseExact) {
+        const existing = await findExactDocumentImport({ vaultRoot, sourceReceipt });
+        if (existing) {
+            const verifiedSourceReceipt = await hashSourceFile(sourcePath);
+            if (verifiedSourceReceipt.byteLength !== sourceReceipt.byteLength
+                || verifiedSourceReceipt.sha256 !== sourceReceipt.sha256) {
+                throw new VaultError("DOCUMENT_SOURCE_CHANGED", "Document source changed while exact reuse was being verified.");
+            }
+            return existing;
+        }
+    }
     const documentId = generateRecordId(ID_PREFIXES.document);
     const eventId = generateRecordId(ID_PREFIXES.event);
     const preparedAttachments = prepareEventAttachments({
@@ -2116,6 +2648,7 @@ export async function importDocument({ vaultRoot, sourcePath, occurredAt = new D
                 role: "source_document",
                 kind: "document",
                 sourcePath,
+                expectedSourceReceipt: sourceReceipt,
             },
         ],
     });
@@ -2164,6 +2697,14 @@ export async function importDocument({ vaultRoot, sourcePath, occurredAt = new D
             if (!stagedAttachments) {
                 throw new VaultError("EVENT_ATTACHMENTS_MISSING", "Document import expected one staged attachment.");
             }
+            const stagedSourceAttachment = stagedAttachments.attachments.find((attachment) => attachment.role === "source_document");
+            if (!stagedSourceAttachment) {
+                throw new VaultError("EVENT_ATTACHMENTS_MISSING", "Document import expected one source attachment receipt.");
+            }
+            const sourceTargetId = buildRawSourceReceiptTarget({
+                byteLength: sourceReceipt.byteLength,
+                sha256: stagedSourceAttachment.sha256,
+            });
             const event = prepareStoredEventLedgerEntry({
                 ...eventSeed,
                 rawRefs: stagedAttachments.rawRefs,
@@ -2182,9 +2723,10 @@ export async function importDocument({ vaultRoot, sourcePath, occurredAt = new D
                 summary: `Imported document ${raw.originalFileName}.`,
                 occurredAt,
                 files: [raw.relativePath, manifestPath, event.relativePath],
-                targetIds: [documentId, event.record.id],
+                targetIds: [sourceTargetId, documentId, event.record.id],
             });
             return {
+                created: true,
                 documentId,
                 raw,
                 event: event.record,
@@ -2935,15 +3477,22 @@ export async function importDeviceBatch({ vaultRoot, provider, accountId, import
             throw new VaultError("INTEGRATION_INGEST_ID_CONFLICT", `Device ingest id "${incrementalEvidenceImportId}" already belongs to a different delivery.`, { ingestId: incrementalEvidenceImportId });
         }
     };
-    const buildExactNoopResult = (storedDelivery) => buildStoredDeviceDeliveryNoopResult({
-        associationEvidenceRolesByPreparedRecordId,
-        currentEventOwners,
-        deviceBatchPlan,
-        eventTargetShardPaths,
-        preparedEventOutputOwners,
-        sampleRecords,
-        storedDelivery,
-    });
+    const buildExactNoopResult = (storedDelivery) => {
+        const result = buildStoredDeviceDeliveryNoopResult({
+            associationEvidenceRolesByPreparedRecordId,
+            currentEventOwners,
+            deviceBatchPlan,
+            eventTargetShardPaths,
+            preparedEventOutputOwners,
+            sampleRecords,
+            storedDelivery,
+        });
+        const affectedSparseCalendarTargets = junctionSparseAffectedCalendarTargets(result.events, eventIdentityContext.index);
+        const affectedEventDayKeys = junctionSparseAffectedDayKeys(affectedSparseCalendarTargets);
+        return affectedSparseCalendarTargets.length > 0
+            ? { ...result, affectedEventDayKeys, affectedSparseCalendarTargets }
+            : result;
+    };
     let fullInspectionAttempted = false;
     const ensureFullInspection = async () => {
         if (fullInspectionAttempted || (ingestIdInspection.historyComplete && !ingestIdInspection.unsafe)) {
@@ -3207,6 +3756,8 @@ export async function importDeviceBatch({ vaultRoot, provider, accountId, import
             const preparedId = deviceBatchPlan.preparedEvents[index]?.record.id;
             return preparedId !== undefined && associablePreparedEventIds.has(preparedId);
         });
+        const affectedSparseCalendarTargets = junctionSparseAffectedCalendarTargets(canonicalEventRecords, eventIdentityContext.index);
+        const affectedEventDayKeys = junctionSparseAffectedDayKeys(affectedSparseCalendarTargets);
         const persistenceEvidenceRolesByPreparedRecordId = new Map(deviceBatchPlan.preparedEvents
             .filter((entry) => associablePreparedEventIds.has(entry.record.id)
             && acceptedEvidenceRolesByPreparedRecordId.has(entry.record.id))
@@ -3270,6 +3821,9 @@ export async function importDeviceBatch({ vaultRoot, provider, accountId, import
         }
         const eventOutputs = buildIntegrationEventOutputs(shouldPersistDelivery ? persistencePreparedEvents : [], canonicalIdByPreparedId, retainedEvidenceRolesByPreparedRecordId);
         const buildNoopResult = () => ({
+            ...(affectedEventDayKeys.length > 0
+                ? { affectedEventDayKeys, affectedSparseCalendarTargets }
+                : {}),
             applied: false,
             ingestId: null,
             ingestShardPath: null,
@@ -3285,6 +3839,8 @@ export async function importDeviceBatch({ vaultRoot, provider, accountId, import
             auditPath: null,
         });
         return {
+            affectedEventDayKeys,
+            affectedSparseCalendarTargets,
             buildNoopResult,
             eventAppendPlan,
             eventOutputs,
@@ -3334,7 +3890,7 @@ export async function importDeviceBatch({ vaultRoot, provider, accountId, import
         assertInspectionCanAuthorizeNoop();
         return persistence.buildNoopResult();
     }
-    const { buildNoopResult, eventAppendPlan, eventOutputs, eventReconciliation, canonicalEventRecords, retainedEvidenceParts, } = persistence;
+    const { affectedEventDayKeys, affectedSparseCalendarTargets, buildNoopResult, eventAppendPlan, eventOutputs, eventReconciliation, canonicalEventRecords, retainedEvidenceParts, } = persistence;
     const currentImportIdOccupied = ingestIdInspection.entriesById.has(deviceBatchPlan.importId)
         || ingestIdInspection.invalidIds.has(deviceBatchPlan.importId);
     const finalAssociationImportId = buildAssociationImportId(eventOutputs);
@@ -3411,6 +3967,9 @@ export async function importDeviceBatch({ vaultRoot, provider, accountId, import
                 targetIds: [persistedImportId],
             });
             return {
+                ...(affectedEventDayKeys.length > 0
+                    ? { affectedEventDayKeys, affectedSparseCalendarTargets }
+                    : {}),
                 applied: true,
                 ingestId: persistedImportId,
                 ingestShardPath,
@@ -3471,6 +4030,12 @@ export async function importEventBatch(input) {
     if (usesPayloads === usesDecisions) {
         throw new VaultError("EVENT_BATCH_INVALID", "Event batch must define exactly one of payloads or decisions.");
     }
+    const sourceRawRef = usesPayloads
+        ? input.rejectIfSourceRawRefAlreadyImported?.trim()
+        : undefined;
+    if (usesPayloads && input.rejectIfSourceRawRefAlreadyImported !== undefined && !sourceRawRef) {
+        throw new VaultError("EVENT_BATCH_INVALID", "Event batch source raw reference must not be empty.");
+    }
     const normalizedRows = usesDecisions
         ? normalizeImportEventBatchDecisions(input.decisions, signal)
         : normalizeImportEventBatchPayloads(input.payloads, signal);
@@ -3519,11 +4084,15 @@ export async function importEventBatch(input) {
                 });
                 return;
             }
-            const record = buildPublicEventImportRecord({ ...decision.payload }, vault.metadata.timezone);
+            // Decisions are the trusted importer-owner path. Their contract permits
+            // verified workout CSV evidence to retain an unknown duration, while the
+            // generic public payload path above remains stricter.
+            const record = buildEventImportDecisionRecord({ ...decision.payload }, vault.metadata.timezone);
             decisions.push({
                 action: "upsert",
                 allowsKindReplacement: true,
                 entry: { relativePath: toEventLedgerFile(record.occurredAt), record },
+                ...(decision.expectedLatest ? { expectedLatest: decision.expectedLatest } : {}),
             });
         }
         catch (error) {
@@ -3539,6 +4108,29 @@ export async function importEventBatch(input) {
             failures: failures.slice(0, EVENT_BATCH_FAILURE_REPORT_LIMIT),
         });
     }
+    let sourceCompletionTargetId = null;
+    if (sourceRawRef) {
+        const invalidSourceIndexes = decisions.flatMap((decision, index) => decision.action === "upsert"
+            && decision.entry.record.kind === "activity_session"
+            && decision.entry.record.externalRef === undefined
+            && collectEventRawReferencePaths(decision.entry.record).includes(sourceRawRef)
+            ? []
+            : [index]);
+        if (invalidSourceIndexes.length > 0) {
+            throw new VaultError("EVENT_BATCH_SOURCE_ROW_INVALID", "Every event in a source-guarded batch must be an externalRef-free activity session that references the guarded raw source; nothing was imported.", { indexes: invalidSourceIndexes.slice(0, EVENT_BATCH_FAILURE_REPORT_LIMIT) });
+        }
+        const sourceState = await inspectWorkoutSourceImportStatus({
+            vaultRoot,
+            rawRef: sourceRawRef,
+        });
+        if (sourceState.status === "completed") {
+            throw new VaultError("EVENT_BATCH_SOURCE_ALREADY_IMPORTED", "The atomic workout import for this exact source already completed; nothing was imported.");
+        }
+        if (sourceState.status === "partial_conflict") {
+            throw new VaultError("EVENT_BATCH_SOURCE_PARTIAL_CONFLICT", "This exact source has workout history without a whole-source completion receipt; nothing was imported. Resolve the partial import before retrying.");
+        }
+        sourceCompletionTargetId = sourceState.completionTargetId;
+    }
     signal?.throwIfAborted();
     const reconciliation = await reconcileEventImportDecisionsByExternalRef(vaultRoot, decisions, signal);
     const appendPlan = await buildJsonlAppendPlan(vaultRoot, reconciliation.appendEntries, {
@@ -3581,14 +4173,19 @@ export async function importEventBatch(input) {
                 vaultRoot,
                 batch,
                 action: "event_upsert",
-                commandName: "core.importEventBatch",
+                commandName: sourceCompletionTargetId
+                    ? WORKOUT_SOURCE_IMPORT_AUDIT_COMMAND
+                    : "core.importEventBatch",
                 summary: `Imported event batch: ${counts.createdCount} created, ` +
                     `${counts.supersededCount} superseded, ` +
                     `${counts.retractedCount} retracted, ` +
                     `${counts.skippedExistingCount} skipped existing of ${counts.receivedCount} received.`,
                 occurredAt,
                 files: appendPlan.appendedShardPaths,
-                targetIds: [...new Set(appendPlan.appendedRecordIds)].slice(0, AUDIT_TARGET_ID_LIMIT),
+                targetIds: [
+                    ...(sourceCompletionTargetId ? [sourceCompletionTargetId] : []),
+                    ...new Set(appendPlan.appendedRecordIds),
+                ].slice(0, AUDIT_TARGET_ID_LIMIT),
             });
             return {
                 applied: true,