@murphai/murph 0.2.7 → 0.2.10

package/node_modules/@murphai/inboxd/dist/indexing/persist.js

@@ -1,25 +1,11 @@
 import path from "node:path";
 import { createHash } from "node:crypto";
-import { mkdir, readFile, realpath, rename, stat } from "node:fs/promises";
+import { readFile, realpath, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { assertContract, inboxCaptureRecordSchema, } from "@murphai/contracts";
-import { acquireCanonicalWriteLock, applyCanonicalWriteBatch, loadVault, readJsonlRecords, VAULT_LAYOUT, walkVaultFiles, withCanonicalWriteLockScope, } from "@murphai/core";
-import { buildAttachmentId, createDeterministicInboxCaptureId, createInboxCaptureIdentityKey, assertVaultPathOnDisk, normalizeStoredAttachments, normalizeAccountKey, normalizeRelativePath, redactSensitivePaths, resolveVaultPath, sanitizeFileName, sanitizeSegment, sha256File, walkNamedFiles, } from "../shared.js";
-import { INBOX_CAPTURE_LEDGER_DIRECTORY, buildInboxCaptureAuditPathForStoredAt, buildInboxCaptureAuditRecord, buildInboxCaptureEventPathForOccurredAt, buildInboxCaptureEventRecord, buildInboxCaptureLedgerPath, buildInboxCaptureLedgerPathForOccurredAt, buildInboxCaptureRecord, } from "./persist/canonical-records.js";
-const STORED_CAPTURE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/u;
-const QUARANTINED_INVALID_CAPTURE_ID_SUFFIX = "quarantined-invalid-capture-id";
-class UnsafeStoredCaptureIdError extends Error {
-    captureId;
-    canonicalCaptureId;
-    absolutePath;
-    constructor(input) {
-        super(`Stored inbox envelope at ${input.absolutePath} contains unsafe captureId "${input.captureId}".`);
-        this.name = "UnsafeStoredCaptureIdError";
-        this.captureId = input.captureId;
-        this.canonicalCaptureId = input.canonicalCaptureId;
-        this.absolutePath = input.absolutePath;
-    }
-}
+import { acquireCanonicalWriteLock, applyCanonicalWriteBatch, loadVault, listWriteOperationMetadataPaths, readJsonlRecords, readStoredWriteOperation, VAULT_LAYOUT, walkVaultFiles, withCanonicalWriteLockScope, } from "@murphai/core";
+import { buildAttachmentId, createDeterministicInboxCaptureId, createInboxCaptureIdentityKey, normalizeStoredAttachments, normalizeAccountKey, normalizeRelativePath, redactSensitivePaths, resolveVaultPath, sanitizeFileName, sanitizeSegment, sha256File, } from "../shared.js";
+import { INBOX_CAPTURE_LEDGER_DIRECTORY, buildInboxCaptureLedgerPathForOccurredAt, buildInboxCaptureRecord, } from "./persist/canonical-records.js";
 export async function ensureInboxVault(vaultRoot) {
     await loadVault({ vaultRoot });
 }
@@ -204,23 +190,6 @@ async function prepareRawCapturePersistence({ captureId, eventId, input, storedA
         rawContents,
     };
 }
-export async function persistRawCapture({ vaultRoot, captureId, eventId, input, storedAt = new Date().toISOString(), }) {
-    const prepared = await prepareRawCapturePersistence({
-        captureId,
-        eventId,
-        input,
-        storedAt,
-    });
-    await applyCanonicalWriteBatch({
-        vaultRoot,
-        operationType: "inbox_capture_raw_persist",
-        summary: `Persist inbox capture ${captureId}`,
-        occurredAt: prepared.stored.storedAt,
-        rawCopies: prepared.rawCopies,
-        rawContents: prepared.rawContents,
-    });
-    return prepared.stored;
-}
 export async function persistCanonicalInboxCapture({ vaultRoot, captureId, eventId, input, storedAt = new Date().toISOString(), }) {
     const prepared = await prepareRawCapturePersistence({
         captureId,
@@ -266,37 +235,29 @@ export async function findStoredCaptureEnvelope(input) {
     if (storedRecord) {
         return inboxCaptureRecordToStoredCaptureEnvelope(storedRecord);
     }
-    const expectedPath = await resolveVaultPath(input.vaultRoot, buildInboxEnvelopePath(input.inbound, captureId));
-    const expectedEnvelope = await readStoredCaptureEnvelope(expectedPath);
-    if (expectedEnvelope) {
-        return expectedEnvelope;
+    const expectedEnvelopePath = buildInboxEnvelopePath(input.inbound, captureId);
+    const expectedCapturePath = buildInboxCaptureLedgerPathForOccurredAt(input.inbound.occurredAt);
+    const recoverableOperations = await listRecoverableInboxCaptureOperations(input.vaultRoot);
+    const recoverableOperation = recoverableOperations.get(expectedEnvelopePath);
+    if (!recoverableOperation || recoverableOperation.capturePath !== expectedCapturePath) {
+        return null;
     }
-    const accountRoot = await resolveVaultPath(input.vaultRoot, buildInboxAccountDirectory(input.inbound));
-    const envelopeFiles = await walkInboxEnvelopeFiles(accountRoot);
-    let selected = null;
-    const identityKey = createInboxCaptureIdentityKey(input.inbound);
-    for (const envelopePath of envelopeFiles) {
-        const envelope = await readStoredCaptureEnvelope(envelopePath);
-        if (!envelope || createInboxCaptureIdentityKey(envelope.input) !== identityKey) {
-            continue;
-        }
-        const entry = { absolutePath: envelopePath, envelope };
-        if (!selected || compareEnvelopeEntries(entry, selected) < 0) {
-            selected = entry;
-        }
-    }
-    return selected?.envelope ?? null;
+    return await readStoredCaptureEnvelope({
+        vaultRoot: input.vaultRoot,
+        relativePath: expectedEnvelopePath,
+    });
 }
 export async function ensureStoredCaptureCanonicalEvidence(input) {
-    const capturePath = buildInboxCaptureLedgerPath(input.envelope);
+    const relativePath = buildInboxCaptureLedgerPathForOccurredAt(input.envelope.input.occurredAt);
     await withCanonicalWriteLockScope(input.vaultRoot, async () => {
         const lock = await acquireCanonicalWriteLock(input.vaultRoot);
         try {
-            const captureRecords = await readInboxCaptureRecordsIfPresent({
+            const records = await readInboxCaptureRecordsIfPresent({
                 vaultRoot: input.vaultRoot,
-                relativePath: capturePath,
+                relativePath,
             });
-            if (findMatchingInboxCaptureRecord(captureRecords, input.envelope)) {
+            const identityKey = createInboxCaptureIdentityKey(input.envelope.input);
+            if (selectMatchingInboxCaptureRecord(records, identityKey, input.envelope.captureId)) {
                 return;
             }
             await applyCanonicalWriteBatch({
@@ -306,7 +267,7 @@ export async function ensureStoredCaptureCanonicalEvidence(input) {
                 occurredAt: input.envelope.stored.storedAt,
                 jsonlAppends: [
                     {
-                        relativePath: capturePath,
+                        relativePath,
                         record: buildInboxCaptureRecord({
                             eventId: input.envelope.eventId,
                             inbound: input.envelope.input,
@@ -321,53 +282,6 @@ export async function ensureStoredCaptureCanonicalEvidence(input) {
         }
     });
 }
-export async function appendInboxCaptureEvent(input) {
-    const vault = await loadVault({ vaultRoot: input.vaultRoot });
-    const relativePath = buildInboxCaptureEventPathForOccurredAt(input.occurredAt);
-    const record = buildInboxCaptureEventRecord({
-        eventId: input.eventId,
-        inbound: input.inbound,
-        stored: input.stored,
-        timeZone: vault.metadata.timezone,
-    });
-    await applyCanonicalWriteBatch({
-        vaultRoot: input.vaultRoot,
-        operationType: "inbox_capture_event_append",
-        summary: `Append inbox capture event ${input.eventId}`,
-        occurredAt: input.stored.storedAt,
-        jsonlAppends: [
-            {
-                relativePath,
-                record,
-            },
-        ],
-    });
-    return { relativePath, record };
-}
-export async function appendImportAudit(input) {
-    const relativePath = buildInboxCaptureAuditPathForStoredAt(input.stored.storedAt);
-    const record = buildInboxCaptureAuditRecord({
-        auditId: input.auditId,
-        eventId: input.eventId,
-        inbound: input.inbound,
-        stored: input.stored,
-        capturePath: input.capturePath,
-        eventPath: input.eventPath,
-    });
-    await applyCanonicalWriteBatch({
-        vaultRoot: input.vaultRoot,
-        operationType: "inbox_capture_audit_append",
-        summary: `Append inbox capture audit ${input.auditId}`,
-        occurredAt: input.stored.storedAt,
-        jsonlAppends: [
-            {
-                relativePath,
-                record,
-            },
-        ],
-    });
-    return { relativePath, record };
-}
 export async function rebuildRuntimeFromVault(input) {
     const canonicalRecords = await listCanonicalInboxCaptureRecords(input.vaultRoot);
     const restoredIdentityKeys = new Set();
@@ -385,47 +299,24 @@ export async function rebuildRuntimeFromVault(input) {
         });
         restoredIdentityKeys.add(record.identityKey);
     }
-    const inboxRoot = await resolveVaultPath(input.vaultRoot, VAULT_LAYOUT.rawInboxDirectory);
-    try {
-        await mkdir(inboxRoot, { recursive: true });
-    }
-    catch {
-        return;
-    }
-    await assertVaultPathOnDisk(input.vaultRoot, inboxRoot);
-    const envelopeFiles = await walkInboxEnvelopeFiles(inboxRoot);
-    const canonicalEntries = new Map();
-    for (const envelopePath of envelopeFiles) {
-        const envelope = await readStoredCaptureEnvelope(envelopePath);
-        if (!envelope) {
-            continue;
-        }
-        const identityKey = createInboxCaptureIdentityKey(envelope.input);
-        if (restoredIdentityKeys.has(identityKey)) {
-            continue;
-        }
-        const entry = { absolutePath: envelopePath, envelope };
-        const current = canonicalEntries.get(identityKey);
-        if (!current || compareEnvelopeEntries(entry, current) < 0) {
-            canonicalEntries.set(identityKey, entry);
-        }
-    }
-    for (const entry of [...canonicalEntries.values()].sort(compareEnvelopeEntries)) {
+    const recoverableOperations = await listRecoverableInboxCaptureOperations(input.vaultRoot);
+    const recoveredEnvelopes = await listRecoverableRawCaptureEnvelopes(input.vaultRoot, restoredIdentityKeys, recoverableOperations);
+    for (const envelope of recoveredEnvelopes) {
         await ensureStoredCaptureCanonicalEvidence({
             vaultRoot: input.vaultRoot,
-            envelope: entry.envelope,
+            envelope,
         });
         const captureId = input.runtime.upsertCaptureIndex({
-            captureId: entry.envelope.captureId,
-            eventId: entry.envelope.eventId,
-            input: entry.envelope.input,
-            stored: entry.envelope.stored,
+            captureId: envelope.captureId,
+            eventId: envelope.eventId,
+            input: envelope.input,
+            stored: envelope.stored,
         });
         input.runtime.enqueueDerivedJobs({
             captureId,
-            stored: entry.envelope.stored,
+            stored: envelope.stored,
         });
-        restoredIdentityKeys.add(createInboxCaptureIdentityKey(entry.envelope.input));
+        restoredIdentityKeys.add(createInboxCaptureIdentityKey(envelope.input));
     }
 }
 function buildInboxAccountDirectory(input) {
@@ -439,71 +330,78 @@ function buildInboxCaptureDirectory(input, captureId) {
 function buildInboxEnvelopePath(input, captureId) {
     return normalizeRelativePath(path.posix.join(buildInboxCaptureDirectory(input, captureId), "envelope.json"));
 }
-async function walkInboxEnvelopeFiles(directory) {
+async function readStoredCaptureEnvelope(input) {
+    const absolutePath = await resolveVaultPath(input.vaultRoot, input.relativePath);
     try {
-        return (await walkNamedFiles(directory, "envelope.json", { skipDirectories: ["attachments"] })).sort();
+        return normalizeStoredCaptureEnvelope(JSON.parse(await readFile(absolutePath, "utf8")), input.relativePath);
     }
     catch (error) {
         if (isMissingFileError(error)) {
-            return [];
+            return null;
         }
         throw error;
     }
 }
-async function readStoredCaptureEnvelope(absolutePath) {
-    try {
-        return normalizeStoredCaptureEnvelope(JSON.parse(await readFile(absolutePath, "utf8")), absolutePath);
+function normalizeStoredCaptureEnvelope(value, relativePath) {
+    const context = `stored inbox envelope at ${relativePath}`;
+    const envelope = expectRecord(value, context);
+    if (envelope.schema !== "murph.inbox-envelope.v1") {
+        throw new TypeError(`Expected canonical "schema" in ${context}.`);
     }
-    catch (error) {
-        if (isMissingFileError(error)) {
-            return null;
-        }
-        if (error instanceof UnsafeStoredCaptureIdError) {
-            await quarantineStoredCaptureEnvelope(absolutePath);
-            return null;
-        }
-        throw error;
+    const inbound = buildSanitizedInboundCapture(normalizeStoredCaptureInboundInput(envelope.input, `${context}.input`));
+    const captureId = createDeterministicInboxCaptureId(inbound);
+    const eventId = requireStringField(envelope, "eventId", context);
+    const storedAt = requireStringField(envelope, "storedAt", context);
+    if (requireStringField(envelope, "captureId", context) !== captureId) {
+        throw new TypeError(`Stored inbox envelope at ${relativePath} must use the deterministic captureId.`);
     }
-}
-function normalizeStoredCaptureEnvelope(envelope, absolutePath) {
-    if (!envelope || typeof envelope !== "object") {
-        throw new TypeError(`Expected stored inbox envelope object at ${absolutePath}.`);
+    const storedRecord = expectRecord(envelope.stored, `${context}.stored`);
+    const sourceDirectory = requireStringField(storedRecord, "sourceDirectory", `${context}.stored`);
+    const envelopePath = requireStringField(storedRecord, "envelopePath", `${context}.stored`);
+    const attachmentsValue = storedRecord.attachments;
+    if (!Array.isArray(attachmentsValue)) {
+        throw new TypeError(`Expected canonical "attachments" array in ${context}.stored.`);
     }
-    if (!envelope.stored || typeof envelope.stored !== "object") {
-        throw new TypeError(`Missing canonical "stored" payload in stored inbox envelope at ${absolutePath}.`);
+    if (requireStringField(storedRecord, "captureId", `${context}.stored`) !== captureId) {
+        throw new TypeError(`Stored inbox envelope at ${relativePath} has a mismatched stored.captureId.`);
     }
-    if (!envelope.input || typeof envelope.input !== "object") {
-        throw new TypeError(`Missing canonical "input" payload in stored inbox envelope at ${absolutePath}.`);
+    if (requireStringField(storedRecord, "eventId", `${context}.stored`) !== eventId) {
+        throw new TypeError(`Stored inbox envelope at ${relativePath} has a mismatched stored.eventId.`);
     }
-    if (typeof envelope.input.source !== "string" || envelope.input.source.trim().length === 0) {
-        throw new TypeError(`Missing canonical "input.source" in stored inbox envelope at ${absolutePath}.`);
+    if (requireStringField(storedRecord, "storedAt", `${context}.stored`) !== storedAt) {
+        throw new TypeError(`Stored inbox envelope at ${relativePath} has a mismatched stored.storedAt.`);
     }
-    if (typeof envelope.input.externalId !== "string" || envelope.input.externalId.trim().length === 0) {
-        throw new TypeError(`Missing canonical "input.externalId" in stored inbox envelope at ${absolutePath}.`);
+    const expectedSourceDirectory = buildInboxCaptureDirectory(inbound, captureId);
+    if (sourceDirectory !== expectedSourceDirectory) {
+        throw new TypeError(`Stored inbox envelope at ${relativePath} has a mismatched stored.sourceDirectory.`);
     }
-    if (!Array.isArray(envelope.stored.attachments)) {
-        throw new TypeError(`Missing canonical "stored.attachments" array in stored inbox envelope at ${absolutePath}.`);
+    const expectedEnvelopePath = buildInboxEnvelopePath(inbound, captureId);
+    if (envelopePath !== expectedEnvelopePath) {
+        throw new TypeError(`Stored inbox envelope at ${relativePath} has a mismatched stored.envelopePath.`);
     }
-    const canonicalCaptureId = createDeterministicInboxCaptureId(envelope.input);
-    const captureId = normalizeStoredCaptureId({
-        captureId: envelope.captureId,
-        canonicalCaptureId,
-        absolutePath,
+    const attachments = normalizeStoredAttachments(captureId, attachmentsValue, `${context}.stored.attachments`).map((attachment) => {
+        const expectedAttachmentId = buildAttachmentId(captureId, attachment.ordinal);
+        if (attachment.attachmentId !== expectedAttachmentId) {
+            throw new TypeError(`Stored inbox envelope at ${relativePath} has a mismatched attachmentId for ordinal ${attachment.ordinal}.`);
+        }
+        return {
+            ...attachment,
+            attachmentId: expectedAttachmentId,
+            originalPath: null,
+        };
     });
-    return {
-        ...envelope,
-        captureId,
+    return inboxCaptureRecordToStoredCaptureEnvelope(buildInboxCaptureRecord({
+        eventId,
+        inbound,
         stored: {
-            ...envelope.stored,
             captureId,
-            eventId: envelope.eventId,
-            attachments: normalizeStoredAttachmentsForCaptureId({
-                captureId,
-                attachments: envelope.stored.attachments,
-                absolutePath,
-            }),
+            eventId,
+            storedAt,
+            sourceDirectory,
+            envelopePath,
+            attachments,
         },
-    };
+    }));
 }
 async function readJsonlRecordsIfPresent(input) {
     try {
@@ -518,24 +416,80 @@ async function readJsonlRecordsIfPresent(input) {
         throw error;
     }
 }
-function compareEnvelopeEntries(left, right) {
-    const idComparison = comparePreferenceScore(left) - comparePreferenceScore(right);
-    if (idComparison !== 0) {
-        return idComparison;
+async function listRecoverableRawCaptureEnvelopes(vaultRoot, restoredIdentityKeys, recoverableOperations) {
+    const selectedByIdentityKey = new Map();
+    for (const relativePath of [...recoverableOperations.keys()].sort()) {
+        const envelope = await readStoredCaptureEnvelope({ vaultRoot, relativePath });
+        if (!envelope) {
+            continue;
+        }
+        const identityKey = createInboxCaptureIdentityKey(envelope.input);
+        if (restoredIdentityKeys.has(identityKey)) {
+            continue;
+        }
+        const current = selectedByIdentityKey.get(identityKey);
+        const candidate = { relativePath, envelope };
+        if (!current || compareEnvelopeEntries(candidate, current) < 0) {
+            selectedByIdentityKey.set(identityKey, candidate);
+        }
     }
+    return [...selectedByIdentityKey.values()].sort(compareEnvelopeEntries).map((entry) => entry.envelope);
+}
+async function listRecoverableInboxCaptureOperations(vaultRoot) {
+    const relativePaths = await listWriteOperationMetadataPaths(vaultRoot);
+    const selected = new Map();
+    for (const relativePath of relativePaths) {
+        let operation;
+        try {
+            operation = await readStoredWriteOperation(vaultRoot, relativePath);
+        }
+        catch {
+            continue;
+        }
+        const recoverable = selectRecoverableInboxCaptureOperation(operation);
+        if (!recoverable) {
+            continue;
+        }
+        const current = selected.get(recoverable.envelopePath);
+        if (!current || current.updatedAt.localeCompare(recoverable.updatedAt) < 0) {
+            selected.set(recoverable.envelopePath, recoverable);
+        }
+    }
+    return selected;
+}
+function selectRecoverableInboxCaptureOperation(operation) {
+    if (operation.operationType !== "inbox_capture_persist") {
+        return null;
+    }
+    if (operation.status === "committed" || operation.status === "rolled_back") {
+        return null;
+    }
+    const envelopeAction = operation.actions.find((action) => action.kind === "raw_copy" &&
+        action.targetRelativePath.startsWith(`${VAULT_LAYOUT.rawInboxDirectory}/`) &&
+        action.targetRelativePath.endsWith("/envelope.json") &&
+        (action.state === "applied" || action.state === "reused"));
+    const captureAction = operation.actions.find((action) => action.kind === "jsonl_append" &&
+        action.targetRelativePath.startsWith(`${INBOX_CAPTURE_LEDGER_DIRECTORY}/`) &&
+        action.state === "staged");
+    if (!envelopeAction || !captureAction) {
+        return null;
+    }
+    return {
+        envelopePath: envelopeAction.targetRelativePath,
+        capturePath: captureAction.targetRelativePath,
+        updatedAt: operation.updatedAt,
+    };
+}
+function compareEnvelopeEntries(left, right) {
     const storedAtComparison = left.envelope.stored.storedAt.localeCompare(right.envelope.stored.storedAt);
     if (storedAtComparison !== 0) {
         return storedAtComparison;
     }
-    const captureComparison = left.envelope.captureId.localeCompare(right.envelope.captureId);
-    if (captureComparison !== 0) {
-        return captureComparison;
+    const captureIdComparison = left.envelope.captureId.localeCompare(right.envelope.captureId);
+    if (captureIdComparison !== 0) {
+        return captureIdComparison;
     }
-    return left.absolutePath.localeCompare(right.absolutePath);
-}
-function comparePreferenceScore(entry) {
-    const canonicalCaptureId = createDeterministicInboxCaptureId(entry.envelope.input);
-    return path.basename(path.dirname(entry.absolutePath)) === canonicalCaptureId ? 0 : 1;
+    return left.relativePath.localeCompare(right.relativePath);
 }
 function inboxCaptureRecordToStoredCaptureEnvelope(record) {
     const input = {
@@ -666,10 +620,6 @@ function compareInboxCaptureRecords(left, right) {
     }
     return left.envelopePath.localeCompare(right.envelopePath);
 }
-function findMatchingInboxCaptureRecord(records, envelope) {
-    const identityKey = createInboxCaptureIdentityKey(envelope.input);
-    return selectMatchingInboxCaptureRecord(records, identityKey, envelope.captureId);
-}
 function stripEphemeralAttachmentFields(attachment) {
     const { data, ...sanitized } = attachment;
     return sanitized;
@@ -684,55 +634,109 @@ function buildUnstoredAttachment(input) {
         sha256: null,
     };
 }
-function normalizeStoredCaptureId(input) {
-    const captureId = typeof input.captureId === "string" ? input.captureId.trim() : "";
-    if (!captureId) {
-        throw new TypeError(`Missing canonical "captureId" in stored inbox envelope at ${input.absolutePath}.`);
+function normalizeStoredCaptureInboundInput(value, context) {
+    const input = expectRecord(value, context);
+    const thread = expectRecord(input.thread, `${context}.thread`);
+    const actor = expectRecord(input.actor, `${context}.actor`);
+    const raw = expectRecord(input.raw, `${context}.raw`);
+    const attachmentsValue = input.attachments;
+    if (!Array.isArray(attachmentsValue)) {
+        throw new TypeError(`Expected canonical "attachments" array in ${context}.`);
     }
-    if (!STORED_CAPTURE_ID_PATTERN.test(captureId)) {
-        throw new UnsafeStoredCaptureIdError({
-            captureId,
-            canonicalCaptureId: input.canonicalCaptureId,
-            absolutePath: input.absolutePath,
-        });
+    return {
+        source: requireStringField(input, "source", context),
+        externalId: requireStringField(input, "externalId", context),
+        accountId: readOptionalNullableStringField(input, "accountId", context),
+        thread: {
+            id: requireStringField(thread, "id", `${context}.thread`),
+            title: readOptionalNullableStringField(thread, "title", `${context}.thread`),
+            isDirect: readOptionalBooleanField(thread, "isDirect", `${context}.thread`),
+        },
+        actor: {
+            id: readOptionalNullableStringField(actor, "id", `${context}.actor`),
+            displayName: readOptionalNullableStringField(actor, "displayName", `${context}.actor`),
+            isSelf: requireBooleanField(actor, "isSelf", `${context}.actor`),
+        },
+        occurredAt: requireStringField(input, "occurredAt", context),
+        receivedAt: readOptionalNullableStringField(input, "receivedAt", context),
+        text: readOptionalNullableStringField(input, "text", context) ?? null,
+        attachments: attachmentsValue.map((attachment, index) => normalizeStoredCaptureInboundAttachment(attachment, `${context}.attachments[${index}]`)),
+        raw,
+    };
+}
+function normalizeStoredCaptureInboundAttachment(value, context) {
+    const attachment = expectRecord(value, context);
+    const kind = requireStringField(attachment, "kind", context);
+    if (!isInboundAttachmentKind(kind)) {
+        throw new TypeError(`Unsupported canonical attachment kind "${kind}" in ${context}.`);
     }
-    return input.canonicalCaptureId;
+    return {
+        externalId: readOptionalNullableStringField(attachment, "externalId", context),
+        kind,
+        mime: readOptionalNullableStringField(attachment, "mime", context),
+        originalPath: null,
+        fileName: readOptionalNullableStringField(attachment, "fileName", context),
+        byteSize: readOptionalNullableNumberField(attachment, "byteSize", context),
+    };
 }
-function normalizeStoredAttachmentsForCaptureId(input) {
-    const normalizedAttachments = normalizeStoredAttachments(input.captureId, input.attachments, `stored inbox envelope at ${input.absolutePath}`);
-    return normalizedAttachments.map((attachment) => ({
-        ...attachment,
-        attachmentId: buildAttachmentId(input.captureId, attachment.ordinal),
-    }));
+function expectRecord(value, context) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError(`Expected object in ${context}.`);
+    }
+    return value;
 }
-async function quarantineStoredCaptureEnvelope(absolutePath) {
-    const quarantinePath = await resolveQuarantinedEnvelopePath(absolutePath);
-    try {
-        await rename(absolutePath, quarantinePath);
+function requireStringField(value, field, context) {
+    const fieldValue = value[field];
+    if (typeof fieldValue !== "string" || fieldValue.trim().length === 0) {
+        throw new TypeError(`Expected canonical "${field}" string in ${context}.`);
     }
-    catch (error) {
-        if (isMissingFileError(error)) {
-            return;
-        }
-        throw error;
+    return fieldValue;
+}
+function requireBooleanField(value, field, context) {
+    const fieldValue = value[field];
+    if (typeof fieldValue !== "boolean") {
+        throw new TypeError(`Expected canonical "${field}" boolean in ${context}.`);
     }
+    return fieldValue;
 }
-async function resolveQuarantinedEnvelopePath(absolutePath) {
-    const parsed = path.parse(absolutePath);
-    for (let index = 0; index < 1000; index += 1) {
-        const suffix = index === 0 ? "" : `-${index}`;
-        const candidate = path.join(parsed.dir, `${parsed.name}.${QUARANTINED_INVALID_CAPTURE_ID_SUFFIX}${suffix}${parsed.ext}`);
-        try {
-            await stat(candidate);
-        }
-        catch (error) {
-            if (isMissingFileError(error)) {
-                return candidate;
-            }
-            throw error;
-        }
+function readOptionalBooleanField(value, field, context) {
+    const fieldValue = value[field];
+    if (fieldValue === undefined) {
+        return undefined;
+    }
+    if (typeof fieldValue !== "boolean") {
+        throw new TypeError(`Expected canonical "${field}" boolean in ${context}.`);
     }
-    throw new TypeError(`Unable to quarantine stored inbox envelope at ${absolutePath}.`);
+    return fieldValue;
+}
+function readOptionalNullableStringField(value, field, context) {
+    const fieldValue = value[field];
+    if (fieldValue === undefined) {
+        return undefined;
+    }
+    if (fieldValue === null) {
+        return null;
+    }
+    if (typeof fieldValue !== "string") {
+        throw new TypeError(`Expected canonical "${field}" string in ${context}.`);
+    }
+    return fieldValue;
+}
+function readOptionalNullableNumberField(value, field, context) {
+    const fieldValue = value[field];
+    if (fieldValue === undefined) {
+        return undefined;
+    }
+    if (fieldValue === null) {
+        return null;
+    }
+    if (typeof fieldValue !== "number" || !Number.isFinite(fieldValue)) {
+        throw new TypeError(`Expected canonical "${field}" number in ${context}.`);
+    }
+    return fieldValue;
+}
+function isInboundAttachmentKind(value) {
+    return ["image", "audio", "video", "document", "other"].includes(value);
 }
 function isMissingFileError(error) {
     return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";