@murphai/murph 0.1.15 → 0.1.18

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

@@ -0,0 +1,1109 @@
+import { createHash } from "node:crypto";
+import { experimentFrontmatterSchema, journalDayFrontmatterSchema, eventRecordSchema, 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 { buildAttachmentCompatibilityProjections, buildAttachmentPathCompatibilityProjections, prepareEventAttachments, stagePreparedEventAttachmentsInBatch, } from "./event-attachments.js";
+import { canonicalizeEventRelations } from "./event-links.js";
+import { VaultError } from "./errors.js";
+import { pathExists, readUtf8File, writeVaultTextFile } from "./fs.js";
+import { parseFrontmatterDocument, stringifyFrontmatterDocument } from "./frontmatter.js";
+import { generateRecordId } from "./ids.js";
+import { readJsonlRecords, toMonthlyShardRelativePath } from "./jsonl.js";
+import { stageRawImportManifest } from "./operations/raw-manifests.js";
+import { runCanonicalWrite } from "./operations/write-batch.js";
+import { resolveVaultPath } from "./path-safety.js";
+import { sanitizePathSegment } from "./path-safety.js";
+import { prepareInlineRawArtifact, prepareRawArtifact } from "./raw.js";
+import { defaultTimeZone, normalizeTimeZone, toIsoTimestamp, toLocalDayKey, } from "./time.js";
+import { loadVault } from "./vault.js";
+const EVENT_KIND_SET = new Set(BASELINE_EVENT_KINDS);
+const EVENT_SOURCE_SET = new Set(EVENT_SOURCES);
+const SAMPLE_STREAM_SET = new Set(BASELINE_SAMPLE_STREAMS);
+const SAMPLE_SOURCE_SET = new Set(SAMPLE_SOURCES);
+const SAMPLE_QUALITY_SET = new Set(SAMPLE_QUALITIES);
+function compactRecord(record) {
+    return Object.fromEntries(Object.entries(record).filter(([, value]) => {
+        if (value === undefined || value === null) {
+            return false;
+        }
+        if (Array.isArray(value)) {
+            return true;
+        }
+        if (typeof value === "object") {
+            return Object.keys(value).length > 0;
+        }
+        return true;
+    }));
+}
+function stableSortValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => stableSortValue(entry));
+    }
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => [key, stableSortValue(entry)]);
+        return Object.fromEntries(entries);
+    }
+    return value;
+}
+function stableStringify(value) {
+    return JSON.stringify(stableSortValue(value));
+}
+function normalizeExternalRef(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const candidate = assertPlainObject(value, "VAULT_INVALID_EXTERNAL_REF", "externalRef must be a plain object.");
+    return compactRecord({
+        system: typeof candidate.system === "string" ? candidate.system.trim() : undefined,
+        resourceType: typeof candidate.resourceType === "string" ? candidate.resourceType.trim() : undefined,
+        resourceId: typeof candidate.resourceId === "string" ? candidate.resourceId.trim() : undefined,
+        version: typeof candidate.version === "string" && candidate.version.trim()
+            ? candidate.version.trim()
+            : undefined,
+        facet: typeof candidate.facet === "string" && candidate.facet.trim()
+            ? candidate.facet.trim()
+            : undefined,
+    });
+}
+function normalizeLooseRecord(value, code, message) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    return assertPlainObject(value, code, message);
+}
+function normalizeDayKeyInput(value) {
+    return typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value.trim())
+        ? value.trim()
+        : undefined;
+}
+function normalizeRequiredRole(value, label) {
+    const candidate = String(value ?? "").trim();
+    if (!candidate) {
+        throw new VaultError("VAULT_INVALID_RAW_ROLE", `${label} must be a non-empty string.`);
+    }
+    return candidate;
+}
+function normalizeInlineRawContent(content) {
+    if (typeof content === "string") {
+        return content;
+    }
+    if (content === undefined) {
+        throw new VaultError("VAULT_INVALID_RAW_CONTENT", "raw artifact content is required.");
+    }
+    return `${JSON.stringify(stableSortValue(content), null, 2)}\n`;
+}
+function earliestTimestamp(timestamps, fallback = new Date()) {
+    if (timestamps.length === 0) {
+        return toIsoTimestamp(fallback, "occurredAt");
+    }
+    return [...timestamps].sort()[0];
+}
+function assertPlainObject(value, code, message) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new VaultError(code, message);
+    }
+    return value;
+}
+function assertContractShape(schema, value, code, message) {
+    const result = safeParseContract(schema, value);
+    if (!result.success) {
+        throw new VaultError(code, `${message} ${JSON.stringify(result.errors)}`, { errors: result.errors });
+    }
+}
+function normalizeSource(value, allowed, fallback) {
+    return typeof value === "string" && allowed.has(value) ? value : fallback;
+}
+function normalizeSampleInputRecord(value, code, message) {
+    return assertPlainObject(value, code, message);
+}
+function trimStringList(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const entries = value
+        .filter((entry) => typeof entry === "string")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    return entries.length > 0 ? entries : undefined;
+}
+function uniqueTrimmedStringList(value) {
+    const entries = trimStringList(value);
+    return entries ? [...new Set(entries)] : undefined;
+}
+const NUMERIC_UNIT_ALIASES = {
+    glucose: {
+        "mg/dl": "mg_dL",
+        "mg_dl": "mg_dL",
+        mg_dL: "mg_dL",
+    },
+    heart_rate: {
+        bpm: "bpm",
+    },
+    hrv: {
+        ms: "ms",
+    },
+    steps: {
+        count: "count",
+    },
+    respiratory_rate: {
+        breaths_per_minute: "breaths_per_minute",
+        "breaths/minute": "breaths_per_minute",
+    },
+    temperature: {
+        celsius: "celsius",
+        c: "celsius",
+    },
+    sleep_stage: {
+        stage: "stage",
+    },
+};
+const CROCKFORD_BASE32_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const EVENT_VALIDATION_PLACEHOLDER_ID = `${ID_PREFIXES.event}_00000000000000000000000000`;
+const SAMPLE_VALIDATION_PLACEHOLDER_ID = `${ID_PREFIXES.sample}_00000000000000000000000000`;
+function normalizeNumericUnit(stream, unit) {
+    const normalized = String(unit ?? "").trim();
+    const aliases = NUMERIC_UNIT_ALIASES[stream];
+    const candidate = aliases[normalized] ??
+        aliases[normalized.toLowerCase()];
+    if (!candidate) {
+        throw new VaultError("VAULT_INVALID_SAMPLE_UNIT", `Unsupported unit "${normalized}" for stream "${stream}".`, {
+            stream,
+            unit: normalized,
+        });
+    }
+    return candidate;
+}
+function encodeBase32(bytes, length) {
+    let output = "";
+    let buffer = 0;
+    let bits = 0;
+    for (const byte of bytes) {
+        buffer = (buffer << 8) | byte;
+        bits += 8;
+        while (bits >= 5 && output.length < length) {
+            bits -= 5;
+            output += CROCKFORD_BASE32_ALPHABET[(buffer >> bits) & 31];
+        }
+    }
+    if (bits > 0 && output.length < length) {
+        output += CROCKFORD_BASE32_ALPHABET[(buffer << (5 - bits)) & 31];
+    }
+    return output.padEnd(length, "0").slice(0, length);
+}
+function deterministicContractId(prefix, seed) {
+    const hash = createHash("sha256").update(seed).digest();
+    return `${prefix}_${encodeBase32(hash, 26)}`;
+}
+function buildPreparedAttachmentState(preparedAttachments) {
+    const projections = buildAttachmentPathCompatibilityProjections(preparedAttachments.map((attachment) => ({
+        role: attachment.role,
+        kind: attachment.kind ?? "other",
+        relativePath: attachment.raw.relativePath,
+    })));
+    return {
+        projections: {
+            audioPaths: projections.audioPaths,
+            documentPath: projections.documentPath,
+            photoPaths: projections.photoPaths,
+            rawRefs: projections.rawRefs,
+        },
+    };
+}
+function buildNormalizedEventSeed({ kind, occurredAt, recordedAt = new Date(), dayKey, timeZone, defaultTimeZone: fallbackTimeZone, source, title, note, tags, links, relatedIds, rawRefs, externalRef, fields = {}, }) {
+    if (!EVENT_KIND_SET.has(kind)) {
+        throw new VaultError("VAULT_UNSUPPORTED_EVENT_KIND", `Unsupported baseline event kind "${kind}".`, {
+            kind,
+        });
+    }
+    const normalizedFields = assertPlainObject(fields, "VAULT_INVALID_EVENT_FIELDS", "Event fields must be a plain object.");
+    const occurredTimestamp = toIsoTimestamp(occurredAt, "occurredAt");
+    const recordedTimestamp = toIsoTimestamp(recordedAt, "recordedAt");
+    const resolvedTimeZone = normalizeTimeZone(timeZone ?? fallbackTimeZone);
+    const resolvedDayKey = normalizeDayKeyInput(dayKey) ??
+        toLocalDayKey(occurredTimestamp, resolvedTimeZone ?? defaultTimeZone(), "occurredAt");
+    const canonicalRelations = canonicalizeEventRelations({
+        links,
+        relatedIds,
+        normalizeStringList: uniqueTrimmedStringList,
+        errorCode: "VAULT_INVALID_INPUT",
+        errorMessage: "links entries must be objects with non-empty type and targetId fields.",
+    });
+    const seed = {
+        kind,
+        occurredAt: occurredTimestamp,
+        recordedAt: recordedTimestamp,
+        dayKey: resolvedDayKey,
+        timeZone: resolvedTimeZone,
+        source: normalizeSource(source, EVENT_SOURCE_SET, "manual"),
+        title: typeof title === "string" && title.trim() ? title.trim() : kind,
+        note: typeof note === "string" && note.trim() ? note.trim() : undefined,
+        tags: trimStringList(tags),
+        links: canonicalRelations.links,
+        relatedIds: canonicalRelations.relatedIds,
+        rawRefs: trimStringList(rawRefs),
+        externalRef: normalizeExternalRef(externalRef),
+        fields: normalizedFields,
+    };
+    validateEventSeed(seed);
+    return seed;
+}
+function buildEventContractInput(seed, recordId) {
+    return compactRecord({
+        schemaVersion: EVENT_SCHEMA_VERSION,
+        id: recordId,
+        kind: seed.kind,
+        occurredAt: seed.occurredAt,
+        recordedAt: seed.recordedAt,
+        dayKey: seed.dayKey,
+        timeZone: seed.timeZone,
+        source: seed.source,
+        title: seed.title,
+        note: seed.note,
+        tags: seed.tags,
+        links: seed.links?.length ? seed.links : undefined,
+        relatedIds: seed.relatedIds,
+        rawRefs: seed.rawRefs,
+        externalRef: seed.externalRef,
+        ...seed.fields,
+    });
+}
+function validateEventSeed(seed) {
+    assertContractShape(eventRecordSchema, buildEventContractInput(seed, EVENT_VALIDATION_PLACEHOLDER_ID), "EVENT_INVALID", "Event record failed contract validation before write.");
+}
+function buildStoredEventRecord(seed, recordId) {
+    const record = buildEventContractInput(seed, recordId);
+    assertContractShape(eventRecordSchema, record, "EVENT_INVALID", "Event record failed contract validation before write.");
+    return record;
+}
+function prepareStoredEventLedgerEntry(seed, recordId) {
+    const record = buildStoredEventRecord(seed, recordId);
+    return {
+        relativePath: toMonthlyShardRelativePath(VAULT_LAYOUT.eventLedgerDirectory, record.occurredAt, "occurredAt"),
+        record,
+    };
+}
+function prepareEventLedgerEntry({ recordId, ...input }) {
+    return prepareStoredEventLedgerEntry(buildNormalizedEventSeed(input), recordId ?? generateRecordId(ID_PREFIXES.event));
+}
+async function stageJsonlRecord(batch, relativePath, record) {
+    return batch.stageJsonlAppend(relativePath, `${JSON.stringify(record)}\n`);
+}
+function buildNormalizedSampleSeed({ stream, recordedAt, dayKey, timeZone, defaultTimeZone: fallbackTimeZone, source, quality, sample, unit, externalRef, }) {
+    const recordedTimestamp = toIsoTimestamp(sample.recordedAt ?? recordedAt, "recordedAt");
+    const normalizedUnit = normalizeNumericUnit(stream, unit);
+    const resolvedTimeZone = normalizeTimeZone(timeZone ?? fallbackTimeZone);
+    const resolvedDayKey = normalizeDayKeyInput(dayKey) ??
+        toLocalDayKey(recordedTimestamp, resolvedTimeZone ?? defaultTimeZone(), "recordedAt");
+    const baseSeed = {
+        stream,
+        recordedAt: recordedTimestamp,
+        dayKey: resolvedDayKey,
+        timeZone: resolvedTimeZone,
+        source: normalizeSource(source, SAMPLE_SOURCE_SET, "import"),
+        quality: normalizeSource(quality, SAMPLE_QUALITY_SET, "raw"),
+        externalRef: normalizeExternalRef(externalRef),
+    };
+    const seed = stream === "sleep_stage"
+        ? {
+            ...baseSeed,
+            unit: normalizedUnit,
+            measurement: {
+                kind: "sleep_stage",
+                stage: String(sample.stage ?? "").trim(),
+                startAt: toIsoTimestamp(sample.startAt, "startAt"),
+                endAt: toIsoTimestamp(sample.endAt, "endAt"),
+                durationMinutes: Number(sample.durationMinutes),
+            },
+        }
+        : (() => {
+            if (typeof sample.value !== "number" || !Number.isFinite(sample.value)) {
+                throw new VaultError("VAULT_INVALID_SAMPLE", "Sample value must be a finite number.", {
+                    stream,
+                    sampleSummary: JSON.stringify(sample),
+                });
+            }
+            return {
+                ...baseSeed,
+                unit: normalizedUnit,
+                measurement: {
+                    kind: "numeric",
+                    value: sample.value,
+                },
+            };
+        })();
+    assertContractShape(sampleRecordSchema, materializeSampleRecord({ seed, recordId: SAMPLE_VALIDATION_PLACEHOLDER_ID }), "SAMPLE_INVALID", "Sample record failed contract validation before write.");
+    return seed;
+}
+function materializeSampleRecord({ seed, recordId, }) {
+    const measurementFields = seed.measurement.kind === "sleep_stage"
+        ? {
+            stage: seed.measurement.stage,
+            startAt: seed.measurement.startAt,
+            endAt: seed.measurement.endAt,
+            durationMinutes: seed.measurement.durationMinutes,
+            unit: seed.unit,
+        }
+        : {
+            value: seed.measurement.value,
+            unit: seed.unit,
+        };
+    return compactRecord({
+        schemaVersion: SAMPLE_SCHEMA_VERSION,
+        id: recordId,
+        dayKey: seed.dayKey,
+        timeZone: seed.timeZone,
+        stream: seed.stream,
+        recordedAt: seed.recordedAt,
+        source: seed.source,
+        quality: seed.quality,
+        externalRef: seed.externalRef,
+        ...measurementFields,
+    });
+}
+function finalizeSampleRecord({ seed, recordId, }) {
+    const record = materializeSampleRecord({ seed, recordId });
+    assertContractShape(sampleRecordSchema, record, "SAMPLE_INVALID", "Sample record failed contract validation before write.");
+    return record;
+}
+function buildSampleRecord({ recordId, ...input }) {
+    return finalizeSampleRecord({
+        seed: buildNormalizedSampleSeed(input),
+        recordId: recordId ?? generateRecordId(ID_PREFIXES.sample),
+    });
+}
+async function readExistingRecordIds(vaultRoot, relativePath) {
+    const resolved = resolveVaultPath(vaultRoot, relativePath);
+    if (!(await pathExists(resolved.absolutePath))) {
+        return new Set();
+    }
+    const records = await readJsonlRecords({
+        vaultRoot,
+        relativePath,
+    });
+    return new Set(records
+        .map((record) => (typeof record.id === "string" ? record.id : null))
+        .filter((id) => id !== null));
+}
+async function buildJsonlAppendPlan(vaultRoot, entries, options = {}) {
+    const payloads = new Map();
+    const existingIdsByShard = new Map();
+    const targetShardPaths = [...new Set(entries.map((entry) => entry.relativePath))].sort();
+    for (const entry of entries) {
+        const existingIds = existingIdsByShard.get(entry.relativePath) ??
+            (await readExistingRecordIds(vaultRoot, entry.relativePath));
+        existingIdsByShard.set(entry.relativePath, existingIds);
+        if (existingIds.has(entry.record.id)) {
+            continue;
+        }
+        if (options.dedupeWithinPlan) {
+            existingIds.add(entry.record.id);
+        }
+        const existingPayload = payloads.get(entry.relativePath) ?? "";
+        payloads.set(entry.relativePath, `${existingPayload}${JSON.stringify(entry.record)}\n`);
+    }
+    return {
+        targetShardPaths,
+        appendedShardPaths: [...payloads.keys()].sort(),
+        payloads,
+    };
+}
+async function stageJsonlAppendPlan(batch, appendPlan) {
+    for (const relativePath of appendPlan.appendedShardPaths) {
+        const payload = appendPlan.payloads.get(relativePath);
+        if (!payload) {
+            continue;
+        }
+        await batch.stageJsonlAppend(relativePath, payload);
+    }
+}
+function normalizeDeviceEventInputs(eventInputs, context) {
+    return eventInputs.map((eventInput, index) => {
+        const kind = String(eventInput.kind ?? "").trim();
+        if (!EVENT_KIND_SET.has(kind)) {
+            throw new VaultError("VAULT_UNSUPPORTED_EVENT_KIND", `Unsupported baseline event kind "${String(eventInput.kind ?? "")}".`, { index });
+        }
+        const fields = normalizeLooseRecord(eventInput.fields, "VAULT_INVALID_EVENT_FIELDS", `Device event ${index + 1} fields must be a plain object.`) ?? {};
+        const rawArtifactRoles = trimStringList(eventInput.rawArtifactRoles) ?? [];
+        const seed = buildNormalizedEventSeed({
+            kind,
+            occurredAt: eventInput.occurredAt ?? eventInput.recordedAt ?? context.importedAt,
+            recordedAt: eventInput.recordedAt ?? eventInput.occurredAt,
+            dayKey: typeof eventInput.dayKey === "string" ? eventInput.dayKey : undefined,
+            timeZone: typeof eventInput.timeZone === "string" ? eventInput.timeZone : undefined,
+            defaultTimeZone: context.defaultTimeZone,
+            source: eventInput.source ?? context.source,
+            title: typeof eventInput.title === "string" ? eventInput.title : undefined,
+            note: eventInput.note,
+            tags: eventInput.tags,
+            relatedIds: eventInput.relatedIds,
+            externalRef: eventInput.externalRef,
+            fields,
+        });
+        const { rawRefs: _rawRefs, ...seedRecord } = buildEventContractInput(seed);
+        return {
+            seed,
+            rawArtifactRoles,
+            recordId: deterministicContractId(ID_PREFIXES.event, stableStringify({
+                provider: context.provider,
+                accountId: context.accountId ?? null,
+                rawArtifactRoles,
+                record: seedRecord,
+            })),
+        };
+    });
+}
+function normalizeDeviceSampleInputs(sampleInputs, context) {
+    return sampleInputs.map((sampleInput, index) => {
+        const stream = String(sampleInput.stream ?? "").trim();
+        if (!SAMPLE_STREAM_SET.has(stream)) {
+            throw new VaultError("VAULT_UNSUPPORTED_SAMPLE_STREAM", `Unsupported baseline sample stream "${String(sampleInput.stream ?? "")}".`, { index });
+        }
+        const sample = normalizeSampleInputRecord(sampleInput.sample, "VAULT_INVALID_SAMPLE", `Device sample ${index + 1} must include a sample object.`);
+        const seed = buildNormalizedSampleSeed({
+            stream,
+            recordedAt: sampleInput.recordedAt ?? sample.recordedAt ?? sample.occurredAt,
+            dayKey: typeof sampleInput.dayKey === "string" ? sampleInput.dayKey : undefined,
+            timeZone: typeof sampleInput.timeZone === "string" ? sampleInput.timeZone : undefined,
+            defaultTimeZone: context.defaultTimeZone,
+            source: sampleInput.source ?? context.source,
+            quality: sampleInput.quality ?? "normalized",
+            sample,
+            unit: String(sampleInput.unit ?? ""),
+            externalRef: sampleInput.externalRef,
+        });
+        const record = materializeSampleRecord({ seed });
+        return {
+            seed,
+            recordId: deterministicContractId(ID_PREFIXES.sample, stableStringify({
+                provider: context.provider,
+                accountId: context.accountId ?? null,
+                record,
+            })),
+        };
+    });
+}
+function normalizeDeviceRawArtifactInputs(rawArtifactInputs, provider) {
+    const seenRawRoles = new Set();
+    return rawArtifactInputs.map((artifactInput, index) => {
+        const role = normalizeRequiredRole(artifactInput.role ?? `artifact-${index + 1}`, `raw artifact ${index + 1} role`);
+        if (seenRawRoles.has(role)) {
+            throw new VaultError("VAULT_DUPLICATE_RAW_ROLE", `Device raw artifact role "${role}" may only appear once per batch.`);
+        }
+        seenRawRoles.add(role);
+        const content = normalizeInlineRawContent(artifactInput.content);
+        return {
+            role,
+            fileName: typeof artifactInput.fileName === "string" && artifactInput.fileName.trim()
+                ? artifactInput.fileName.trim()
+                : `${provider}-${String(index + 1).padStart(2, "0")}.json`,
+            mediaType: typeof artifactInput.mediaType === "string" && artifactInput.mediaType.trim()
+                ? artifactInput.mediaType.trim()
+                : undefined,
+            content,
+            metadata: normalizeLooseRecord(artifactInput.metadata, "VAULT_INVALID_RAW_ARTIFACT", `Device raw artifact ${index + 1} metadata must be a plain object.`),
+            sha256: createHash("sha256").update(content).digest("hex"),
+            index,
+        };
+    });
+}
+function normalizeDeviceBatchInputs({ provider, accountId, importedAt = new Date(), defaultTimeZone: fallbackTimeZone, source = "device", events = [], samples = [], rawArtifacts = [], provenance, }) {
+    const normalizedProvider = sanitizePathSegment(provider, "provider");
+    const normalizedAccountId = typeof accountId === "string" && accountId.trim() ? accountId.trim() : undefined;
+    const normalizedImportedAt = toIsoTimestamp(importedAt, "importedAt");
+    const defaultTimeZone = normalizeTimeZone(fallbackTimeZone);
+    const normalizedProvenance = normalizeLooseRecord(provenance, "VAULT_INVALID_DEVICE_PROVENANCE", "Device import provenance must be a plain object.") ?? {};
+    const eventInputs = Array.isArray(events)
+        ? events.map((event, index) => assertPlainObject(event, "VAULT_INVALID_EVENT", `Device event ${index + 1} must be a plain object.`))
+        : [];
+    const sampleInputs = Array.isArray(samples)
+        ? samples.map((sample, index) => assertPlainObject(sample, "VAULT_INVALID_SAMPLE", `Device sample ${index + 1} must be a plain object.`))
+        : [];
+    const rawArtifactInputs = Array.isArray(rawArtifacts)
+        ? rawArtifacts.map((artifact, index) => assertPlainObject(artifact, "VAULT_INVALID_RAW_ARTIFACT", `Device raw artifact ${index + 1} must be a plain object.`))
+        : [];
+    if (eventInputs.length === 0 && sampleInputs.length === 0 && rawArtifactInputs.length === 0) {
+        throw new VaultError("VAULT_INVALID_DEVICE_BATCH", "importDeviceBatch requires at least one event, sample, or raw artifact.");
+    }
+    return {
+        provider: normalizedProvider,
+        accountId: normalizedAccountId,
+        importedAt: normalizedImportedAt,
+        source,
+        defaultTimeZone,
+        provenance: normalizedProvenance,
+        events: normalizeDeviceEventInputs(eventInputs, {
+            provider: normalizedProvider,
+            accountId: normalizedAccountId,
+            importedAt: normalizedImportedAt,
+            source,
+            defaultTimeZone,
+        }),
+        samples: normalizeDeviceSampleInputs(sampleInputs, {
+            provider: normalizedProvider,
+            accountId: normalizedAccountId,
+            source,
+            defaultTimeZone,
+        }),
+        rawArtifacts: normalizeDeviceRawArtifactInputs(rawArtifactInputs, normalizedProvider),
+    };
+}
+function prepareDeviceRawArtifacts(rawArtifacts, options) {
+    return rawArtifacts.map((artifact) => ({
+        role: artifact.role,
+        content: artifact.content,
+        raw: prepareInlineRawArtifact({
+            fileName: artifact.fileName,
+            targetName: `${String(artifact.index + 1).padStart(2, "0")}-${artifact.fileName}`,
+            mediaType: artifact.mediaType,
+            category: "integrations",
+            provider: options.provider,
+            occurredAt: options.effectiveOccurredAt,
+            recordId: options.importId,
+        }),
+        metadata: artifact.metadata,
+        sha256: artifact.sha256,
+    }));
+}
+function prepareDeviceEventEntries(events, preparedRawArtifacts) {
+    const rawArtifactPathByRole = new Map(preparedRawArtifacts.map((artifact) => [artifact.role, artifact.raw.relativePath]));
+    const soleRawArtifactPath = preparedRawArtifacts.length === 1 ? preparedRawArtifacts[0]?.raw.relativePath : undefined;
+    return events.map((event) => {
+        const rawRefs = event.rawArtifactRoles.length > 0
+            ? event.rawArtifactRoles.map((role) => {
+                const rawPath = rawArtifactPathByRole.get(role);
+                if (!rawPath) {
+                    throw new VaultError("VAULT_RAW_ROLE_MISSING", `No staged raw artifact matched role "${role}" for device event ${event.recordId}.`);
+                }
+                return rawPath;
+            })
+            : soleRawArtifactPath
+                ? [soleRawArtifactPath]
+                : undefined;
+        return prepareStoredEventLedgerEntry({
+            ...event.seed,
+            rawRefs,
+        }, event.recordId);
+    });
+}
+function prepareDeviceSampleEntries(samples) {
+    return samples.map((sample) => {
+        const record = finalizeSampleRecord({
+            seed: sample.seed,
+            recordId: sample.recordId,
+        });
+        return {
+            record,
+            relativePath: toMonthlyShardRelativePath(`${VAULT_LAYOUT.sampleLedgerDirectory}/${sample.seed.stream}`, record.recordedAt, "recordedAt"),
+        };
+    });
+}
+function prepareDeviceBatchPlan({ provider, accountId, importedAt = new Date(), defaultTimeZone: fallbackTimeZone, source = "device", events = [], samples = [], rawArtifacts = [], provenance, }) {
+    const normalizedInputs = normalizeDeviceBatchInputs({
+        provider,
+        accountId,
+        importedAt,
+        defaultTimeZone: fallbackTimeZone,
+        source,
+        events,
+        samples,
+        rawArtifacts,
+        provenance,
+    });
+    const effectiveOccurredAt = earliestTimestamp([
+        ...normalizedInputs.events.map(({ seed }) => seed.occurredAt),
+        ...normalizedInputs.samples.map(({ seed }) => seed.recordedAt),
+    ], normalizedInputs.importedAt);
+    const importId = deterministicContractId(ID_PREFIXES.transform, stableStringify({
+        provider: normalizedInputs.provider,
+        accountId: normalizedInputs.accountId ?? null,
+        eventIds: normalizedInputs.events.map(({ recordId }) => recordId),
+        sampleIds: normalizedInputs.samples.map(({ recordId }) => recordId),
+        rawArtifacts: normalizedInputs.rawArtifacts.map((artifact) => ({
+            role: artifact.role,
+            fileName: artifact.fileName,
+            mediaType: artifact.mediaType ?? null,
+            sha256: artifact.sha256,
+        })),
+    }));
+    const preparedRawArtifacts = prepareDeviceRawArtifacts(normalizedInputs.rawArtifacts, {
+        importId,
+        provider: normalizedInputs.provider,
+        effectiveOccurredAt,
+    });
+    const preparedEvents = prepareDeviceEventEntries(normalizedInputs.events, preparedRawArtifacts);
+    const preparedSamples = prepareDeviceSampleEntries(normalizedInputs.samples);
+    return {
+        importId,
+        provider: normalizedInputs.provider,
+        accountId: normalizedInputs.accountId,
+        importedAt: normalizedInputs.importedAt,
+        source: normalizedInputs.source,
+        provenance: normalizedInputs.provenance,
+        effectiveOccurredAt,
+        preparedEvents,
+        preparedSamples,
+        preparedRawArtifacts,
+    };
+}
+export async function importDocument({ vaultRoot, sourcePath, occurredAt = new Date(), title, note, source = "import", }) {
+    const vault = await loadVault({ vaultRoot });
+    const documentId = generateRecordId(ID_PREFIXES.document);
+    const eventId = generateRecordId(ID_PREFIXES.event);
+    const preparedAttachments = prepareEventAttachments({
+        ownerKind: "document",
+        ownerId: documentId,
+        occurredAt,
+        attachments: [
+            {
+                role: "source_document",
+                kind: "document",
+                sourcePath,
+            },
+        ],
+    });
+    const raw = preparedAttachments[0].raw;
+    const pendingAttachmentState = buildPreparedAttachmentState(preparedAttachments);
+    const eventSeed = buildNormalizedEventSeed({
+        kind: "document",
+        occurredAt,
+        recordedAt: new Date(),
+        timeZone: vault.metadata.timezone,
+        source,
+        title: String(title ?? raw.originalFileName).trim(),
+        note,
+        relatedIds: [documentId],
+        rawRefs: pendingAttachmentState.projections.rawRefs,
+        fields: {
+            documentId,
+            documentPath: pendingAttachmentState.projections.documentPath,
+            mimeType: raw.mediaType,
+        },
+    });
+    return runCanonicalWrite({
+        vaultRoot,
+        operationType: "document_import",
+        summary: `Import document ${documentId}`,
+        occurredAt,
+        mutate: async ({ batch }) => {
+            const stagedAttachments = await stagePreparedEventAttachmentsInBatch({
+                batch,
+                importId: documentId,
+                importKind: "document",
+                importedAt: eventSeed.recordedAt,
+                source: eventSeed.source ?? source ?? null,
+                attachments: preparedAttachments,
+                provenance: {
+                    eventId,
+                    lookupId: documentId,
+                    occurredAt: eventSeed.occurredAt,
+                    title: eventSeed.title ?? null,
+                    note: eventSeed.note ?? null,
+                },
+            });
+            if (!stagedAttachments) {
+                throw new VaultError("EVENT_ATTACHMENTS_MISSING", "Document import expected one staged attachment.");
+            }
+            const projections = buildAttachmentCompatibilityProjections(stagedAttachments.attachments);
+            const event = prepareStoredEventLedgerEntry({
+                ...eventSeed,
+                rawRefs: stagedAttachments.rawRefs,
+                fields: {
+                    ...eventSeed.fields,
+                    attachments: stagedAttachments.attachments,
+                    documentPath: projections.documentPath ?? raw.relativePath,
+                },
+            }, eventId);
+            const manifestPath = stagedAttachments.manifestPath;
+            await stageJsonlRecord(batch, event.relativePath, event.record);
+            const audit = await emitAuditRecord({
+                vaultRoot,
+                batch,
+                action: "document_import",
+                commandName: "core.importDocument",
+                summary: `Imported document ${raw.originalFileName}.`,
+                occurredAt,
+                files: [raw.relativePath, manifestPath, event.relativePath],
+                targetIds: [documentId, event.record.id],
+            });
+            return {
+                documentId,
+                raw,
+                event: event.record,
+                eventPath: event.relativePath,
+                auditPath: audit.relativePath,
+                manifestPath,
+            };
+        },
+    });
+}
+export async function addMeal({ vaultRoot, occurredAt = new Date(), note, photoPath, audioPath, source = "manual", }) {
+    const vault = await loadVault({ vaultRoot });
+    if (!photoPath && !audioPath && !note) {
+        throw new VaultError("VAULT_MEAL_CONTENT_REQUIRED", "Meal imports require at least one of photoPath, audioPath, or note.");
+    }
+    const mealId = generateRecordId(ID_PREFIXES.meal);
+    const eventId = generateRecordId(ID_PREFIXES.event);
+    const preparedAttachments = prepareEventAttachments({
+        ownerKind: "meal",
+        ownerId: mealId,
+        occurredAt,
+        attachments: [
+            ...(photoPath
+                ? [
+                    {
+                        role: "photo",
+                        kind: "photo",
+                        sourcePath: photoPath,
+                    },
+                ]
+                : []),
+            ...(audioPath
+                ? [
+                    {
+                        role: "audio",
+                        kind: "audio",
+                        sourcePath: audioPath,
+                    },
+                ]
+                : []),
+        ],
+    });
+    const photo = preparedAttachments.find((attachment) => attachment.role === "photo")?.raw ?? null;
+    const audio = preparedAttachments.find((attachment) => attachment.role === "audio")?.raw ?? null;
+    const rawDirectory = resolveRawMealDirectory(occurredAt, mealId);
+    const pendingAttachmentState = buildPreparedAttachmentState(preparedAttachments);
+    const eventSeed = buildNormalizedEventSeed({
+        kind: "meal",
+        occurredAt,
+        recordedAt: new Date(),
+        timeZone: vault.metadata.timezone,
+        source,
+        title: "Meal",
+        note,
+        relatedIds: [mealId],
+        rawRefs: pendingAttachmentState.projections.rawRefs,
+        fields: {
+            mealId,
+            photoPaths: pendingAttachmentState.projections.photoPaths,
+            audioPaths: pendingAttachmentState.projections.audioPaths,
+        },
+    });
+    return runCanonicalWrite({
+        vaultRoot,
+        operationType: "meal_import",
+        summary: `Import meal ${mealId}`,
+        occurredAt,
+        mutate: async ({ batch }) => {
+            const stagedAttachments = await stagePreparedEventAttachmentsInBatch({
+                batch,
+                importId: mealId,
+                importKind: "meal",
+                importedAt: eventSeed.recordedAt,
+                rawDirectory,
+                source: eventSeed.source ?? source ?? null,
+                attachments: preparedAttachments,
+                provenance: {
+                    eventId,
+                    lookupId: mealId,
+                    occurredAt: eventSeed.occurredAt,
+                    note: eventSeed.note ?? null,
+                },
+            });
+            let rawRefs = eventSeed.rawRefs;
+            let attachments;
+            let photoPaths = eventSeed.fields.photoPaths;
+            let audioPaths = eventSeed.fields.audioPaths;
+            if (stagedAttachments) {
+                const projections = buildAttachmentCompatibilityProjections(stagedAttachments.attachments);
+                rawRefs = projections.rawRefs;
+                attachments = stagedAttachments.attachments;
+                photoPaths = projections.photoPaths;
+                audioPaths = projections.audioPaths;
+            }
+            const manifestPath = stagedAttachments
+                ? stagedAttachments.manifestPath
+                : await stageRawImportManifest({
+                    batch,
+                    importId: mealId,
+                    importKind: "meal",
+                    importedAt: eventSeed.recordedAt,
+                    rawDirectory,
+                    source: eventSeed.source ?? source ?? null,
+                    artifacts: [],
+                    canonicalProvenance: {
+                        eventId,
+                        lookupId: mealId,
+                        occurredAt: eventSeed.occurredAt,
+                        note: eventSeed.note ?? null,
+                    },
+                });
+            if (!stagedAttachments) {
+                rawRefs = [manifestPath];
+            }
+            const event = prepareStoredEventLedgerEntry({
+                ...eventSeed,
+                rawRefs,
+                fields: {
+                    ...eventSeed.fields,
+                    attachments,
+                    photoPaths,
+                    audioPaths,
+                },
+            }, eventId);
+            await stageJsonlRecord(batch, event.relativePath, event.record);
+            const touchedFiles = [photo?.relativePath, audio?.relativePath, manifestPath, event.relativePath].filter((value) => typeof value === "string");
+            const audit = await emitAuditRecord({
+                vaultRoot,
+                batch,
+                action: "meal_add",
+                commandName: "core.addMeal",
+                summary: `Added meal ${mealId}.`,
+                occurredAt,
+                files: touchedFiles,
+                targetIds: [mealId, event.record.id],
+            });
+            return {
+                mealId,
+                event: event.record,
+                eventPath: event.relativePath,
+                photo,
+                audio,
+                auditPath: audit.relativePath,
+                manifestPath,
+            };
+        },
+    });
+}
+function resolveRawMealDirectory(occurredAt, mealId) {
+    const timestamp = toIsoTimestamp(occurredAt, "occurredAt");
+    return `${VAULT_LAYOUT.rawMealsDirectory}/${timestamp.slice(0, 4)}/${timestamp.slice(5, 7)}/${mealId}`;
+}
+export async function importSamples({ vaultRoot, stream, unit, samples, sourcePath, source = "import", quality = "raw", batchProvenance, }) {
+    const vault = await loadVault({ vaultRoot });
+    if (!SAMPLE_STREAM_SET.has(stream)) {
+        throw new VaultError("VAULT_UNSUPPORTED_SAMPLE_STREAM", `Unsupported baseline sample stream "${stream}".`, {
+            stream,
+        });
+    }
+    if (!Array.isArray(samples) || samples.length === 0) {
+        throw new VaultError("VAULT_INVALID_SAMPLES", "importSamples requires a non-empty samples array.");
+    }
+    const normalizedStream = stream;
+    const normalizedSamples = samples.map((sample) => normalizeSampleInputRecord(sample, "VAULT_INVALID_SAMPLE", "Each sample must be a plain object."));
+    const transformFingerprint = normalizedSamples.map((sample) => buildSampleRecord({
+        stream: normalizedStream,
+        recordedAt: sample.recordedAt ?? sample.occurredAt,
+        timeZone: vault.metadata.timezone,
+        source,
+        quality,
+        sample,
+        unit,
+        recordId: `${ID_PREFIXES.sample}_00000000000000000000000000`,
+    }));
+    const transformId = deterministicContractId(ID_PREFIXES.transform, JSON.stringify({
+        stream: normalizedStream,
+        unit,
+        source,
+        quality,
+        sourcePath: sourcePath ?? null,
+        rows: transformFingerprint.map(({ id, ...record }) => record),
+    }));
+    const preparedRecords = [];
+    for (const [index, normalizedSample] of normalizedSamples.entries()) {
+        const record = buildSampleRecord({
+            stream: normalizedStream,
+            recordedAt: normalizedSample.recordedAt ?? normalizedSample.occurredAt,
+            timeZone: vault.metadata.timezone,
+            source,
+            quality,
+            sample: normalizedSample,
+            unit,
+            recordId: deterministicContractId(ID_PREFIXES.sample, `${transformId}:${index}`),
+        });
+        const relativePath = toMonthlyShardRelativePath(`${VAULT_LAYOUT.sampleLedgerDirectory}/${normalizedStream}`, record.recordedAt, "recordedAt");
+        preparedRecords.push({ record, relativePath });
+    }
+    const raw = sourcePath
+        ? prepareRawArtifact({
+            sourcePath,
+            category: "samples",
+            occurredAt: preparedRecords[0]?.record.recordedAt ?? new Date(),
+            recordId: transformId,
+            stream: normalizedStream,
+            allowExistingMatch: true,
+        })
+        : null;
+    const touchedFiles = raw ? [raw.relativePath] : [];
+    const records = preparedRecords.map((entry) => entry.record);
+    const appendPlan = await buildJsonlAppendPlan(vaultRoot, preparedRecords);
+    const rowProvenance = batchProvenance?.rows ?? [];
+    return runCanonicalWrite({
+        vaultRoot,
+        operationType: "sample_batch_import",
+        summary: `Import ${normalizedStream} sample batch ${transformId}`,
+        occurredAt: preparedRecords[0]?.record.recordedAt ?? new Date(),
+        mutate: async ({ batch }) => {
+            const stagedRaw = raw && sourcePath
+                ? await batch.stageRawCopy({
+                    sourcePath,
+                    targetRelativePath: raw.relativePath,
+                    originalFileName: raw.originalFileName,
+                    mediaType: raw.mediaType,
+                    allowExistingMatch: true,
+                })
+                : null;
+            const manifestPath = stagedRaw
+                ? await stageRawImportManifest({
+                    batch,
+                    importId: transformId,
+                    importKind: "sample_batch",
+                    importedAt: records[0]?.recordedAt ?? new Date().toISOString(),
+                    source: source ?? null,
+                    artifacts: [
+                        {
+                            role: "source_csv",
+                            raw: stagedRaw,
+                        },
+                    ],
+                    canonicalProvenance: {
+                        stream: normalizedStream,
+                        unit,
+                        importedCount: records.length,
+                        sampleIds: records.map((record) => record.id),
+                        ledgerFiles: appendPlan.targetShardPaths,
+                        sourceFileName: batchProvenance?.sourceFileName ?? raw?.originalFileName ?? null,
+                        importConfig: batchProvenance?.importConfig ?? null,
+                        rowCount: rowProvenance.length,
+                        rows: rowProvenance,
+                    },
+                })
+                : "";
+            await stageJsonlAppendPlan(batch, appendPlan);
+            const touchedPaths = [...touchedFiles];
+            touchedPaths.push(...(manifestPath ? [manifestPath] : []), ...appendPlan.appendedShardPaths);
+            const audit = await emitAuditRecord({
+                vaultRoot,
+                batch,
+                action: "samples_import_csv",
+                commandName: "core.importSamples",
+                summary: `Imported ${records.length} ${normalizedStream} sample record(s).`,
+                occurredAt: records[0]?.recordedAt ?? new Date(),
+                files: touchedPaths,
+                targetIds: records.map((record) => record.id),
+            });
+            return {
+                count: records.length,
+                records,
+                shardPaths: appendPlan.targetShardPaths,
+                raw,
+                transformId,
+                auditPath: audit.relativePath,
+                manifestPath,
+            };
+        },
+    });
+}
+export async function importDeviceBatch({ vaultRoot, provider, accountId, importedAt = new Date(), source = "device", events = [], samples = [], rawArtifacts = [], provenance, }) {
+    const vault = await loadVault({ vaultRoot });
+    const deviceBatchPlan = prepareDeviceBatchPlan({
+        provider,
+        accountId,
+        importedAt,
+        defaultTimeZone: vault.metadata.timezone,
+        source,
+        events,
+        samples,
+        rawArtifacts,
+        provenance,
+    });
+    const eventAppendPlan = await buildJsonlAppendPlan(vaultRoot, deviceBatchPlan.preparedEvents, {
+        dedupeWithinPlan: true,
+    });
+    const sampleAppendPlan = await buildJsonlAppendPlan(vaultRoot, deviceBatchPlan.preparedSamples, {
+        dedupeWithinPlan: true,
+    });
+    const eventRecords = deviceBatchPlan.preparedEvents.map((entry) => entry.record);
+    const sampleRecords = deviceBatchPlan.preparedSamples.map((entry) => entry.record);
+    return runCanonicalWrite({
+        vaultRoot,
+        operationType: "device_batch_import",
+        summary: `Import ${deviceBatchPlan.provider} device batch ${deviceBatchPlan.importId}`,
+        occurredAt: deviceBatchPlan.effectiveOccurredAt,
+        mutate: async ({ batch }) => {
+            const stagedRawArtifacts = [];
+            for (const artifact of deviceBatchPlan.preparedRawArtifacts) {
+                stagedRawArtifacts.push({
+                    role: artifact.role,
+                    raw: await batch.stageRawText({
+                        targetRelativePath: artifact.raw.relativePath,
+                        originalFileName: artifact.raw.originalFileName,
+                        mediaType: artifact.raw.mediaType,
+                        content: artifact.content,
+                        allowExistingMatch: true,
+                    }),
+                });
+            }
+            const manifestPath = stagedRawArtifacts.length > 0
+                ? await stageRawImportManifest({
+                    batch,
+                    importId: deviceBatchPlan.importId,
+                    importKind: "device_batch",
+                    importedAt: deviceBatchPlan.importedAt,
+                    source: deviceBatchPlan.source ?? null,
+                    artifacts: stagedRawArtifacts,
+                    canonicalProvenance: {
+                        provider: deviceBatchPlan.provider,
+                        accountId: deviceBatchPlan.accountId ?? null,
+                        importedAt: deviceBatchPlan.importedAt,
+                        eventCount: eventRecords.length,
+                        sampleCount: sampleRecords.length,
+                        eventIds: eventRecords.map((record) => record.id),
+                        sampleIds: sampleRecords.map((record) => record.id),
+                        rawArtifacts: deviceBatchPlan.preparedRawArtifacts.map((artifact) => ({
+                            role: artifact.role,
+                            relativePath: artifact.raw.relativePath,
+                            sha256: artifact.sha256,
+                            metadata: artifact.metadata ?? null,
+                        })),
+                    },
+                    operatorMetadata: deviceBatchPlan.provenance,
+                })
+                : "";
+            await stageJsonlAppendPlan(batch, eventAppendPlan);
+            await stageJsonlAppendPlan(batch, sampleAppendPlan);
+            const touchedPaths = [
+                ...deviceBatchPlan.preparedRawArtifacts.map((artifact) => artifact.raw.relativePath),
+                ...(manifestPath ? [manifestPath] : []),
+                ...eventAppendPlan.appendedShardPaths,
+                ...sampleAppendPlan.appendedShardPaths,
+            ];
+            const audit = await emitAuditRecord({
+                vaultRoot,
+                batch,
+                action: "device_import",
+                commandName: "core.importDeviceBatch",
+                summary: `Imported ${deviceBatchPlan.provider} device batch with ${eventRecords.length} event(s) and ${sampleRecords.length} sample(s).`,
+                occurredAt: deviceBatchPlan.importedAt,
+                files: touchedPaths,
+                targetIds: [...eventRecords.map((record) => record.id), ...sampleRecords.map((record) => record.id)],
+            });
+            return {
+                importId: deviceBatchPlan.importId,
+                provider: deviceBatchPlan.provider,
+                accountId: deviceBatchPlan.accountId,
+                importedAt: deviceBatchPlan.importedAt,
+                events: eventRecords,
+                samples: sampleRecords,
+                eventShardPaths: eventAppendPlan.targetShardPaths,
+                sampleShardPaths: sampleAppendPlan.targetShardPaths,
+                rawArtifacts: deviceBatchPlan.preparedRawArtifacts.map((artifact) => artifact.raw),
+                auditPath: audit.relativePath,
+                manifestPath,
+            };
+        },
+    });
+}
+//# sourceMappingURL=mutations.js.map