@memberjunction/ai-agents 6.2.0-edge.2 → 6.2.0-edge.4

package/dist/realtime/realtime-recording-store.js

@@ -5,9 +5,16 @@
  * recording storage account, upload the audio, link it to the `AIAgentSession`, and stamp the session's
  * recording fields. Keeps the storage policy in one place rather than duplicated per topology.
  *
+ * Also hosts server-side recovery ({@link RecoverRealtimeRecordingFromSegments}): rebuilding a recording
+ * from its crash-recovery shards when the end-of-call upload never arrived. Recovery defers to a
+ * recording that already exists on a best-effort basis: it re-checks the session immediately before
+ * its stamp, but `BaseEntity` has no compare-and-set, so a writer landing inside that one load -> save
+ * window can still be overwritten.
+ *
  * @module @memberjunction/ai-agents
  */
-import { LogError } from '@memberjunction/core';
+import { randomBytes } from 'crypto';
+import { LogError, LogStatus } from '@memberjunction/core';
 import { FileStorageEngine } from '@memberjunction/storage';
 /**
  * Resolves the storage account a session recording should be written to: the agent's
@@ -39,20 +46,41 @@ export async function ResolveRecordingStorageAccountID(agent, contextUser, provi
 export async function resolveRecordingStorageAccountID(agent, contextUser, provider) {
     return ResolveRecordingStorageAccountID(agent, contextUser, provider);
 }
-/** A short, stable file extension for the recording's MIME type. */
+/** A short, stable file extension for the recording's MIME type (MIME types are case-insensitive). */
 function extensionForMime(mimeType) {
-    if (mimeType.includes('webm'))
+    const type = mimeType.toLowerCase();
+    if (type.includes('webm'))
         return 'webm';
-    if (mimeType.includes('ogg'))
+    if (type.includes('ogg'))
         return 'ogg';
-    if (mimeType.includes('mp4') || mimeType.includes('m4a'))
+    if (type.includes('mp4') || type.includes('m4a'))
         return 'm4a';
     // Header-less raw PCM crash-recovery shards (audio/L16 / audio/pcm) — NOT individually playable;
     // recovery concatenates them in order and WAV-wraps. The consolidated file is always WAV.
-    if (mimeType.includes('L16') || mimeType.includes('pcm'))
+    if (type.includes('l16') || type.includes('pcm'))
         return 'pcm';
     return 'wav';
 }
+/**
+ * Sample rate (Hz) carried by a raw-PCM MIME type such as `audio/L16;rate=48000`. Case-insensitive on
+ * the type and parameter name; whitespace and extra parameters are tolerated. Returns `null` for any
+ * other type, a missing `rate`, or a rate that is not a positive integer. Shared by the shard-key
+ * writer and the recovery's content-type fallback so the two cannot disagree on what counts as a rate.
+ */
+function parsePcmRate(mimeType) {
+    const [type, ...params] = mimeType.split(';').map(part => part.trim());
+    if (!/^audio\/(l16|pcm)$/i.test(type)) {
+        return null;
+    }
+    for (const param of params) {
+        const match = /^rate\s*=\s*(\d+)$/i.exec(param);
+        const rate = match ? Number(match[1]) : 0;
+        if (Number.isSafeInteger(rate) && rate > 0) {
+            return rate;
+        }
+    }
+    return null;
+}
 /** The per-session folder all of a session's recording artifacts live in (shards + final file). */
 function recordingFolder(sessionID) {
     return `realtime-recordings/${sessionID}`;
@@ -99,12 +127,24 @@ export async function readRealtimeRecordingFile(fileID, contextUser, provider) {
     return ReadRealtimeRecordingFile(fileID, contextUser, provider);
 }
 /**
- * Writes ONE crash-recovery segment shard (`seg-NNNN.<ext>`) into the session's folder as a RAW
+ * `seg-NNNN.<ext>`, or `seg-NNNN.r<rate>.pcm` for a PCM shard whose MIME carries a rate. Header-less
+ * PCM has no way to say how fast to play it back, and recovery runs after the browser (and its
+ * `RecordingStartedAt`/rate bookkeeping) is gone, so the rate travels in the key itself.
+ */
+function segmentFileName(segmentIndex, mimeType) {
+    const index = String(segmentIndex).padStart(4, '0');
+    const extension = extensionForMime(mimeType);
+    const rate = extension === 'pcm' ? parsePcmRate(mimeType) : null;
+    return rate === null ? `seg-${index}.${extension}` : `seg-${index}.r${rate}.${extension}`;
+}
+/**
+ * Writes ONE crash-recovery segment shard (`seg-NNNN[.r<rate>].<ext>`) into the session's folder as a RAW
  * storage object — no `MJ: Files` row, no session stamping. Shards are durability insurance during a
  * live call (so a browser/tab death loses at most the last window); they are byte-slices of one
  * continuous stream (only the first carries the container header), so they are NOT individually
- * playable — recovery is "concatenate the folder's shards in order". They are deleted once the
- * canonical consolidated file lands ({@link deleteRealtimeRecordingSegments}). Never throws.
+ * playable — recovery (see {@link RecoverRealtimeRecordingFromSegments}) concatenates them in index order,
+ * filling absent indexes with silence. They are deleted once the canonical consolidated file lands
+ * ({@link DeleteRealtimeRecordingSegments}), or by the recovery path once it has stamped its own file. Never throws.
  *
  * @returns `true` on success.
  */
@@ -112,7 +152,7 @@ export async function WriteRealtimeRecordingSegment(input) {
     const { SessionID, SegmentIndex, Audio, MimeType, StorageAccountID, ContextUser } = input;
     try {
         const driver = await FileStorageEngine.Instance.GetDriver(StorageAccountID, ContextUser);
-        const name = `seg-${String(SegmentIndex).padStart(4, '0')}.${extensionForMime(MimeType)}`;
+        const name = segmentFileName(SegmentIndex, MimeType);
         return await driver.PutObject(`${recordingFolder(SessionID)}/${name}`, Audio, MimeType);
     }
     catch (error) {
@@ -151,8 +191,10 @@ export async function writeRecordingPeaksSidecar(sessionID, storageAccountID, pe
     return WriteRecordingPeaksSidecar(sessionID, storageAccountID, peaks, contextUser);
 }
 /**
- * Deletes the `seg-*` shards in a session's folder, leaving the consolidated `recording.*` file. Called
- * after {@link storeRealtimeRecording} writes the canonical file at end of call. Never throws.
+ * Deletes every `seg-*` shard in a session's folder, leaving the consolidated `recording.*` file. Called
+ * after {@link StoreRealtimeRecording} writes the canonical file at end of call. The recovery path
+ * ({@link RecoverRealtimeRecordingFromSegments}) does not use this: it deletes only the shards it listed
+ * and assembled, so a shard written after its listing is not lost. Never throws.
  *
  * @returns The number of shards deleted.
  */
@@ -160,7 +202,9 @@ export async function DeleteRealtimeRecordingSegments(sessionID, storageAccountI
     try {
         const driver = await FileStorageEngine.Instance.GetDriver(storageAccountID, contextUser);
         const folder = recordingFolder(sessionID);
-        const listed = await driver.ListObjects(folder);
+        // List the folder's CONTENTS: without the trailing slash, delimiter-based drivers (S3, GCS)
+        // return the folder itself as a common prefix and no objects, so no shard was ever deleted.
+        const listed = await driver.ListObjects(`${folder}/`);
         let deleted = 0;
         for (const obj of listed.objects ?? []) {
             const base = (obj.name.split('/').pop() ?? obj.name);
@@ -190,13 +234,14 @@ export async function deleteRealtimeRecordingSegments(sessionID, storageAccountI
  * @returns The created `MJ: Files` id, or the failure reason.
  */
 export async function StoreRealtimeRecording(input) {
-    const { Audio, MimeType, Media, StartedAt, StorageAccountID, SessionID, ContextUser, Provider, Peaks } = input;
+    const { Audio, MimeType, StorageAccountID, SessionID, ContextUser, Provider, Peaks } = input;
     try {
         // Canonical consolidated file in the session's own folder, alongside (then replacing) its shards.
         const uploaded = await FileStorageEngine.Instance.UploadFile({
             content: Audio,
-            fileName: `recording.${extensionForMime(MimeType)}`,
+            fileName: input.FileName ?? `recording.${extensionForMime(MimeType)}`,
             mimeType: MimeType,
+            description: input.Description,
             contextUser: ContextUser,
             storageAccountId: StorageAccountID,
             provider: Provider,
@@ -205,38 +250,459 @@ export async function StoreRealtimeRecording(input) {
         // Best-effort waveform-peaks sidecar (peaks.json) next to the recording, for fast waveform
         // rendering without re-decoding the audio. A sidecar failure never fails the recording itself.
         await WriteRecordingPeaksSidecar(SessionID, StorageAccountID, Peaks, ContextUser);
-        // Link the file to the session record so it's discoverable via MJ: File Entity Record Links.
-        const sessionEntityID = Provider.EntityByName('MJ: AI Agent Sessions')?.ID;
-        if (sessionEntityID) {
-            const link = await Provider.GetEntityObject('MJ: File Entity Record Links', ContextUser);
-            link.NewRecord();
-            link.FileID = uploaded.FileID;
-            link.EntityID = sessionEntityID;
-            link.RecordID = SessionID;
-            if (!await link.Save()) {
-                LogError(`storeRealtimeRecording: failed to link recording to session ${SessionID}: ${link.LatestResult?.CompleteMessage ?? 'unknown error'}`);
-            }
-        }
-        // Stamp the recording fields on the session (file + media kind + t0).
-        const session = await Provider.GetEntityObject('MJ: AI Agent Sessions', ContextUser);
-        if (await session.Load(SessionID)) {
-            session.RecordingFileID = uploaded.FileID;
-            session.RecordingMedia = Media;
-            session.RecordingStartedAt = StartedAt;
-            if (!await session.Save()) {
-                LogError(`storeRealtimeRecording: failed to stamp recording fields on session ${SessionID}: ${session.LatestResult?.CompleteMessage ?? 'unknown error'}`);
-            }
-        }
-        return { FileID: uploaded.FileID, ErrorMessage: null };
+        return input.PreserveExistingRecording
+            ? await stampPreservingExisting(input, uploaded.FileID)
+            : await linkAndStamp(input, uploaded.FileID);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         LogError(`storeRealtimeRecording failed for session ${SessionID}: ${message}`);
-        return { FileID: null, ErrorMessage: message };
+        return { FileID: null, ErrorMessage: message, Superseded: false };
+    }
+}
+/**
+ * End-of-call path: link, then stamp unconditionally, so the browser's own recording replaces whatever
+ * the session pointed at. A session that cannot be loaded is still linked but not stamped (unchanged
+ * long-standing behaviour; the upload is reported as stored).
+ */
+async function linkAndStamp(input, fileID) {
+    const { Media, StartedAt, SessionID, ContextUser, Provider } = input;
+    const session = await Provider.GetEntityObject('MJ: AI Agent Sessions', ContextUser);
+    const sessionLoaded = await session.Load(SessionID);
+    await linkRecordingToSession(fileID, SessionID, ContextUser, Provider);
+    if (sessionLoaded) {
+        await stampRecordingOnSession(session, fileID, Media, StartedAt);
+    }
+    return { FileID: fileID, ErrorMessage: null, Superseded: false };
+}
+/**
+ * Recovery path: re-check -> stamp -> link. The re-check is the last read before the stamp, so the
+ * window in which a late recording can still be overwritten is one load -> save. The link is written
+ * only once the stamp saved, so a `Superseded` or failed result never leaves a link row behind.
+ */
+async function stampPreservingExisting(input, fileID) {
+    const { Media, StartedAt, SessionID, ContextUser, Provider } = input;
+    const session = await Provider.GetEntityObject('MJ: AI Agent Sessions', ContextUser);
+    if (!await session.Load(SessionID)) {
+        const message = `could not re-read session ${SessionID} before stamping; file ${fileID} is orphaned and was not linked or stamped`;
+        LogError(`storeRealtimeRecording: ${message}`);
+        return { FileID: fileID, ErrorMessage: message, Superseded: false };
+    }
+    if (session.RecordingFileID) {
+        LogStatus(`storeRealtimeRecording: session ${SessionID} already has recording file ${session.RecordingFileID}; the just-uploaded file ${fileID} is orphaned and was not linked or stamped`);
+        return { FileID: fileID, ErrorMessage: null, Superseded: true };
+    }
+    if (!await stampRecordingOnSession(session, fileID, Media, StartedAt)) {
+        const reason = session.LatestResult?.CompleteMessage ?? 'unknown error';
+        return { FileID: fileID, ErrorMessage: `could not stamp file ${fileID} on session ${SessionID} (file orphaned, not linked): ${reason}`, Superseded: false };
+    }
+    await linkRecordingToSession(fileID, SessionID, ContextUser, Provider);
+    return { FileID: fileID, ErrorMessage: null, Superseded: false };
+}
+/** Links the file to the session record so it's discoverable via MJ: File Entity Record Links. */
+async function linkRecordingToSession(fileID, sessionID, contextUser, provider) {
+    const sessionEntityID = provider.EntityByName('MJ: AI Agent Sessions')?.ID;
+    if (!sessionEntityID) {
+        return;
+    }
+    const link = await provider.GetEntityObject('MJ: File Entity Record Links', contextUser);
+    link.NewRecord();
+    link.FileID = fileID;
+    link.EntityID = sessionEntityID;
+    link.RecordID = sessionID;
+    if (!await link.Save()) {
+        LogError(`storeRealtimeRecording: failed to link recording to session ${sessionID}: ${link.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+    }
+}
+/** Stamps the recording fields on an already-loaded session (file + media kind + t0). Logs and returns false on a failed save. */
+async function stampRecordingOnSession(session, fileID, media, startedAt) {
+    session.RecordingFileID = fileID;
+    session.RecordingMedia = media;
+    session.RecordingStartedAt = startedAt;
+    if (!await session.Save()) {
+        LogError(`storeRealtimeRecording: failed to stamp recording fields on session ${session.ID}: ${session.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        return false;
     }
+    return true;
 }
 /** @deprecated Use {@link StoreRealtimeRecording}. */
 export async function storeRealtimeRecording(input) {
     return StoreRealtimeRecording(input);
 }
+const RECORDING_WAV_HEADER_BYTES = 44;
+const RECORDING_BYTES_PER_SAMPLE = 2; // mono, 16-bit PCM
+/** WAV stores sizes as uint32; the RIFF chunk size is `36 + dataSize`, so data tops out 36 bytes short of the max. */
+const RECORDING_MAX_DATA_BYTES = 0xFFFFFFFF - 36;
+/**
+ * Assembles recovered recording shards into one WAV, in index order, filling every absent index with
+ * silence. Silence (rather than skipping the gap) keeps all later audio at its true time offset, so it
+ * stays aligned with transcript cues, which are offsets from the session's `RecordingStartedAt`.
+ *
+ * The gap length is the median length of the present shards excluding the highest present index (that
+ * one is normally a partial window); with a single shard, that shard's length. It is rounded down to
+ * an even byte count (whole 16-bit samples), minimum 2.
+ *
+ * The byte ceiling does not bound the index range on its own: under the default ceiling a single shard
+ * at index ~10^9 still fits, and the missing-index list grows with the highest index. Callers handling
+ * untrusted shards must cap the shard count and highest index themselves (recovery does, via
+ * {@link MAX_RECOVERY_SEGMENTS}) and pass a smaller `maxDataBytes`.
+ *
+ * @param segments Recovered shards; any order, unique non-negative integer indexes starting from 0.
+ * @param sampleRate Sample rate of the PCM data, in Hz.
+ * @param maxDataBytes Ceiling on the PCM data size (shards plus gap fill), checked before anything is
+ *   allocated. Defaults to the WAV format's own limit; callers handling untrusted shards pass less.
+ * @throws Error on no segments, an invalid sample rate or index, a duplicate index, an empty or
+ *   odd-length shard, or a result too large for a WAV.
+ */
+export function BuildRecordingFromSegments(segments, sampleRate, maxDataBytes = RECORDING_MAX_DATA_BYTES) {
+    validateRecordingInputs(segments, sampleRate);
+    const ordered = [...segments].sort((a, b) => a.Index - b.Index);
+    const gapBytes = computeRecordingGapBytes(ordered);
+    // Count gaps arithmetically (indexes are unique and non-negative) so an absurd index fails the size
+    // check below instead of first enumerating billions of missing indexes.
+    const missingCount = ordered[ordered.length - 1].Index - (ordered.length - 1);
+    const dataSize = ordered.reduce((sum, s) => sum + s.Bytes.length, 0) + missingCount * gapBytes;
+    const limit = Math.min(maxDataBytes, RECORDING_MAX_DATA_BYTES);
+    if (dataSize > limit) {
+        throw new Error(`BuildRecordingFromSegments: data of ${dataSize} bytes exceeds the maximum WAV data size of ${limit} bytes`);
+    }
+    // Buffer.alloc zero-fills, so gaps need no explicit write.
+    const wav = Buffer.alloc(RECORDING_WAV_HEADER_BYTES + dataSize);
+    writeRecordingWavHeader(wav, sampleRate, dataSize);
+    let offset = RECORDING_WAV_HEADER_BYTES;
+    let expectedIndex = 0;
+    for (const segment of ordered) {
+        offset += (segment.Index - expectedIndex) * gapBytes;
+        offset += segment.Bytes.copy(wav, offset);
+        expectedIndex = segment.Index + 1;
+    }
+    return { Wav: wav, MissingIndexes: findMissingIndexes(ordered), GapBytes: gapBytes };
+}
+function validateRecordingInputs(segments, sampleRate) {
+    if (segments.length === 0) {
+        throw new Error('BuildRecordingFromSegments: no segments to assemble');
+    }
+    if (!Number.isInteger(sampleRate) || sampleRate <= 0) {
+        throw new Error(`BuildRecordingFromSegments: sample rate must be a positive integer, got ${sampleRate}`);
+    }
+    const seen = new Set();
+    for (const { Index, Bytes } of segments) {
+        if (!Number.isInteger(Index) || Index < 0) {
+            throw new Error(`BuildRecordingFromSegments: segment index must be a non-negative integer, got ${Index}`);
+        }
+        if (seen.has(Index)) {
+            throw new Error(`BuildRecordingFromSegments: duplicate segment index ${Index}`);
+        }
+        seen.add(Index);
+        if (Bytes.length === 0) {
+            throw new Error(`BuildRecordingFromSegments: segment ${Index} is empty`);
+        }
+        if (Bytes.length % RECORDING_BYTES_PER_SAMPLE !== 0) {
+            throw new Error(`BuildRecordingFromSegments: segment ${Index} has odd length ${Bytes.length}; PCM16 needs an even byte count`);
+        }
+    }
+}
+/** Median length of the present shards minus the highest-indexed one (a partial window), floored to even, min 2. */
+function computeRecordingGapBytes(ordered) {
+    const basis = ordered.length > 1 ? ordered.slice(0, -1) : ordered;
+    const lengths = basis.map(s => s.Bytes.length).sort((a, b) => a - b);
+    const mid = Math.floor(lengths.length / 2);
+    const median = lengths.length % 2 === 1 ? lengths[mid] : (lengths[mid - 1] + lengths[mid]) / 2;
+    const even = Math.floor(median / RECORDING_BYTES_PER_SAMPLE) * RECORDING_BYTES_PER_SAMPLE;
+    return Math.max(RECORDING_BYTES_PER_SAMPLE, even);
+}
+/** Indexes in [0, highest present) with no shard. `ordered` is sorted ascending. */
+function findMissingIndexes(ordered) {
+    const highestIndex = ordered[ordered.length - 1].Index;
+    const present = new Set(ordered.map(s => s.Index));
+    const missing = [];
+    for (let i = 0; i < highestIndex; i++) {
+        if (!present.has(i)) {
+            missing.push(i);
+        }
+    }
+    return missing;
+}
+/** Same canonical header layout as `RealtimeRecordingCapture.encodeWavBuffer` (mono, 16-bit, PCM). */
+function writeRecordingWavHeader(buffer, sampleRate, dataSize) {
+    buffer.write('RIFF', 0, 'ascii');
+    buffer.writeUInt32LE(36 + dataSize, 4);
+    buffer.write('WAVE', 8, 'ascii');
+    buffer.write('fmt ', 12, 'ascii');
+    buffer.writeUInt32LE(16, 16);
+    buffer.writeUInt16LE(1, 20);
+    buffer.writeUInt16LE(1, 22);
+    buffer.writeUInt32LE(sampleRate, 24);
+    buffer.writeUInt32LE(sampleRate * RECORDING_BYTES_PER_SAMPLE, 28);
+    buffer.writeUInt16LE(RECORDING_BYTES_PER_SAMPLE, 32);
+    buffer.writeUInt16LE(16, 34);
+    buffer.write('data', 36, 'ascii');
+    buffer.writeUInt32LE(dataSize, 40);
+}
+/**
+ * Most shards recovery will assemble. At ~15 s per shard this is an hour of audio, far past any real
+ * call; a listing at or beyond it (by count or by highest index) is treated as corrupt or hostile and
+ * fails closed rather than allocating a huge WAV.
+ */
+export const MAX_RECOVERY_SEGMENTS = 240;
+/**
+ * Ceiling on the PCM data a recovery will assemble: 384 MiB covers an hour of 48 kHz mono PCM16
+ * (345.6 MB) with headroom. Shard sizes are client-controlled (the GraphQL body limit is 50 MB, so one
+ * shard can be ~37 MB) and gaps are filled with silence, so without this a session owner could make the
+ * janitor allocate gigabytes. Checked against listed sizes, running actual bytes, and the assembled size.
+ *
+ * It caps the data, not the process's memory: the shard buffers are still held while the WAV is
+ * assembled (2x), and storage drivers can copy on read (the S3 driver copies each shard once more), so
+ * peak memory for one recovery is up to about three times this: two 288 MB recoveries raised the API
+ * process's RSS by 730 MB and 920 MB.
+ */
+export const MAX_RECOVERY_BYTES = 384 * 1024 * 1024;
+/**
+ * Seconds of audio in one full shard written before shard keys carried a rate. Those clients flushed a
+ * shard every 15 s. The legacy format is frozen, so this deliberately does not follow the client's
+ * current flush interval: it is only used to infer the rate of shards that declare none.
+ */
+const LEGACY_SHARD_SECONDS = 15;
+/** Sample rates a legacy shard's rate may be inferred as. */
+const STANDARD_PCM_RATES = [8000, 11025, 16000, 22050, 24000, 32000, 44100, 48000];
+/**
+ * How far a full legacy shard's size-implied rate may be from a standard rate (relative). Real full
+ * shards are within ~0.2% of 15 s; the closest pair of standard rates is ~9% apart.
+ */
+const RATE_SNAP_TOLERANCE = 0.02;
+/** `seg-0003.pcm` or `seg-0003.r48000.pcm`: index, optional keyed rate, extension. */
+const SEGMENT_KEY_PATTERN = /^seg-(\d+)(?:\.r(\d+))?\.([A-Za-z0-9]+)$/;
+/**
+ * A fresh name per recovery attempt (`recording-recovered-<epoch ms>-<random hex>.wav`). Storage keys are
+ * `<folder>/<file name>`, so a fixed name would make retries and concurrent instances write the SAME
+ * object behind several `MJ: Files` rows: deleting an orphan row would delete the stamped recording, and
+ * a late attempt could overwrite it with a mostly silent WAV.
+ */
+function recoveredFileName() {
+    return `recording-recovered-${Date.now()}-${randomBytes(4).toString('hex')}.wav`;
+}
+/**
+ * Rebuilds a session's recording from the `seg-*` crash-recovery shards left in its storage folder —
+ * for a call whose browser died or whose end-of-call upload never ran, so no `recording.*` exists.
+ * Shards are concatenated in order (silence for absent ones), uploaded under a per-attempt
+ * `recording-recovered-<epoch ms>-<random hex>.wav`, stamped on the session, linked, and only then
+ * deleted. Deletion happens only after a reload confirms the session points at the recovered file, so a
+ * failure at any step leaves the shards for the next try. If the session has (or gains) another
+ * recording, the outcome is `Superseded` and the shards are kept. Deferring to that recording is best
+ * effort: the session is re-checked immediately before the stamp, but a recording stamped inside that
+ * one load -> save window is overwritten (there is no compare-and-set).
+ *
+ * The sample rate comes from the shard keys (`seg-NNNN.r<rate>.pcm`) or, for legacy `seg-NNNN.pcm`
+ * shards, from each object's stored content type. When no shard declares a rate (a legacy shard on a
+ * driver that keeps no content type, such as Box), it is inferred from the size of the full shards; see
+ * {@link LEGACY_SHARD_SECONDS}.
+ *
+ * Once the stamp has saved, the outcome is `Recovered` even if the confirming reload or a shard delete
+ * fails; the shards it could not remove are named in a `LogError` (nothing revisits a stamped session).
+ *
+ * Never throws: every failure is logged with the session id and returned as `Failed`.
+ *
+ * @param input Session, storage account, recording `t0`, and server context.
+ */
+export async function RecoverRealtimeRecordingFromSegments(input) {
+    try {
+        return await recoverFromSegments(input);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        LogError(`RecoverRealtimeRecordingFromSegments failed (session ${input.SessionID}): ${message}`);
+        return recoveryResult('Failed', { ErrorMessage: message });
+    }
+}
+function recoveryResult(outcome, fields = {}) {
+    return { Outcome: outcome, FileID: null, SegmentCount: 0, MissingIndexes: [], ErrorMessage: null, ...fields };
+}
+async function recoverFromSegments(input) {
+    const { SessionID, StorageAccountID, StartedAt, ContextUser, Provider } = input;
+    const driver = await FileStorageEngine.Instance.GetDriver(StorageAccountID, ContextUser);
+    const shards = await listRecordingShards(driver, SessionID);
+    if (shards.length === 0) {
+        LogStatus(`RecoverRealtimeRecordingFromSegments: no shards for session ${SessionID} in storage account ${StorageAccountID}`);
+        return recoveryResult('NoSegments');
+    }
+    assertRecoverable(shards);
+    const declaredRate = await resolveDeclaredSampleRate(driver, shards);
+    const segments = await readShardBytes(driver, shards);
+    const sampleRate = declaredRate ?? inferSampleRateFromShardSizes(segments, shards);
+    if (declaredRate === null) {
+        LogStatus(`RecoverRealtimeRecordingFromSegments (session ${SessionID}): no shard declares a sample rate; inferred ${sampleRate} Hz from the size of its full shards`);
+    }
+    const assembled = BuildRecordingFromSegments(segments, sampleRate, MAX_RECOVERY_BYTES);
+    const description = describeRecovery(shards.length, assembled, sampleRate);
+    if (assembled.MissingIndexes.length > 0) {
+        LogStatus(`RecoverRealtimeRecordingFromSegments (session ${SessionID}): ${description}`);
+    }
+    const stored = await StoreRealtimeRecording({
+        Audio: assembled.Wav, MimeType: 'audio/wav', Media: 'Audio', StartedAt, StorageAccountID, SessionID,
+        ContextUser, Provider, FileName: recoveredFileName(), Description: description, PreserveExistingRecording: true,
+    });
+    const found = { FileID: stored.FileID, SegmentCount: shards.length, MissingIndexes: assembled.MissingIndexes };
+    if (stored.Superseded) {
+        return recoveryResult('Superseded', found);
+    }
+    // An ErrorMessage with a FileID is an uploaded-but-unstamped orphan (re-read or stamp failed).
+    if (!stored.FileID || stored.ErrorMessage) {
+        throw new Error(stored.ErrorMessage ?? 'storing the recovered recording failed');
+    }
+    return finishRecovery(input, stored.FileID, found, shards);
+}
+/** Confirms the stamp stuck, then (and only then) deletes the shards. */
+async function finishRecovery(input, fileID, found, shards) {
+    const { SessionID, StorageAccountID, ContextUser, Provider } = input;
+    const session = await Provider.GetEntityObject('MJ: AI Agent Sessions', ContextUser);
+    if (!await session.Load(SessionID)) {
+        // The stamp and link already saved, so the recording is in place; only the overwrite check could
+        // not run. Keep the shards (they might belong to a recording that replaced ours) and name them.
+        LogError(`RecoverRealtimeRecordingFromSegments (session ${SessionID}): recovered file ${fileID} is stamped, but the session ` +
+            `could not be reloaded to confirm it before deleting shards; kept for manual cleanup: ${shards.map(s => s.Path).join(', ')}`);
+        return recoveryResult('Recovered', found);
+    }
+    if (session.RecordingFileID && session.RecordingFileID !== fileID) {
+        LogStatus(`RecoverRealtimeRecordingFromSegments (session ${SessionID}): session now points at ${session.RecordingFileID}, not recovered file ${fileID}; keeping shards`);
+        return recoveryResult('Superseded', found);
+    }
+    if (session.RecordingFileID !== fileID) {
+        throw new Error(`recovered file ${fileID} uploaded but not stamped on session ${SessionID}; shards kept`);
+    }
+    const notDeleted = await deleteListedShards(StorageAccountID, ContextUser, shards);
+    if (notDeleted.length > 0) {
+        LogError(`RecoverRealtimeRecordingFromSegments (session ${SessionID}): deleted ${shards.length - notDeleted.length} of ${shards.length} ` +
+            `shards after recovery; left for manual cleanup: ${notDeleted.join(', ')}`);
+    }
+    return recoveryResult('Recovered', found);
+}
+/**
+ * Deletes exactly the shards that were assembled. A re-list would also take shards written after our
+ * listing, whose audio is not in the recovered file. Returns the paths it could not delete.
+ */
+async function deleteListedShards(storageAccountID, contextUser, shards) {
+    const driver = await FileStorageEngine.Instance.GetDriver(storageAccountID, contextUser);
+    const notDeleted = [];
+    for (const shard of shards) {
+        if (!await driver.DeleteObject(shard.Path)) {
+            notDeleted.push(shard.Path);
+        }
+    }
+    return notDeleted;
+}
+/** Lists the session folder's `seg-*` objects. Other objects (recording.*, peaks.json) are ignored. */
+async function listRecordingShards(driver, sessionID) {
+    const folder = recordingFolder(sessionID);
+    const listed = await driver.ListObjects(`${folder}/`);
+    const shards = [];
+    for (const obj of listed.objects ?? []) {
+        const name = obj.name.split('/').pop() ?? obj.name;
+        const match = SEGMENT_KEY_PATTERN.exec(name);
+        if (match) {
+            const keyedRate = match[2] === undefined ? null : Number(match[2]);
+            if (keyedRate !== null && !(Number.isSafeInteger(keyedRate) && keyedRate > 0)) {
+                throw new Error(`shard ${name} has an invalid sample rate in its key`);
+            }
+            shards.push({
+                Name: name, Path: `${folder}/${name}`, Index: Number(match[1]),
+                KeyedRate: keyedRate, Extension: match[3], ListedSize: obj.size ?? 0,
+            });
+        }
+    }
+    return shards;
+}
+/** Fail closed on an oversized listing and on anything that is not raw PCM (webm/ogg shards cannot be concatenated). */
+function assertRecoverable(shards) {
+    const highestIndex = Math.max(...shards.map(s => s.Index));
+    if (shards.length >= MAX_RECOVERY_SEGMENTS || highestIndex >= MAX_RECOVERY_SEGMENTS) {
+        throw new Error(`refusing to recover ${shards.length} shards (highest index ${highestIndex}); limit is ${MAX_RECOVERY_SEGMENTS}`);
+    }
+    const listedBytes = shards.reduce((sum, s) => sum + s.ListedSize, 0);
+    if (listedBytes > MAX_RECOVERY_BYTES) {
+        throw new Error(`shards total ${listedBytes} bytes, over the recovery limit of ${MAX_RECOVERY_BYTES} bytes`);
+    }
+    const notPcm = shards.find(s => s.Extension !== 'pcm');
+    if (notPcm) {
+        throw new Error(`shard ${notPcm.Name} is not raw PCM; only .pcm shards can be reassembled`);
+    }
+}
+/**
+ * The one sample rate the shards declare: from the key when present, else the object's stored content
+ * type. Null when no shard declares one (left to {@link inferSampleRateFromShardSizes}). Throws when
+ * shards disagree, or when some declare a rate and others do not.
+ */
+async function resolveDeclaredSampleRate(driver, shards) {
+    const declared = [];
+    for (const shard of shards) {
+        const rate = shard.KeyedRate ?? parsePcmRate((await driver.GetObjectMetadata({ fullPath: shard.Path })).contentType ?? '');
+        declared.push({ shard, rate });
+    }
+    const withRate = declared.filter(d => d.rate !== null);
+    if (withRate.length === 0) {
+        return null;
+    }
+    const undeclared = declared.find(d => d.rate === null);
+    if (undeclared) {
+        throw new Error(`cannot determine the sample rate of shard ${undeclared.shard.Name}`);
+    }
+    const first = withRate[0];
+    const disagreeing = withRate.find(d => d.rate !== first.rate);
+    if (disagreeing) {
+        throw new Error(`shards disagree on sample rate: ${first.shard.Name} is ${first.rate} Hz but ${disagreeing.shard.Name} is ${disagreeing.rate} Hz`);
+    }
+    return first.rate;
+}
+/**
+ * Infers the sample rate of shards that declare none from the size of their full shards: every shard
+ * but the highest-indexed (normally a partial window) holds {@link LEGACY_SHARD_SECONDS} of mono PCM16.
+ * Each full shard's implied rate must be within {@link RATE_SNAP_TOLERANCE} of a standard rate, and all
+ * must agree. A lone shard is refused, since it may be a partial window.
+ */
+function inferSampleRateFromShardSizes(segments, shards) {
+    const nameOf = (index) => shards.find(s => s.Index === index)?.Name ?? `index ${index}`;
+    const ordered = [...segments].sort((a, b) => a.Index - b.Index);
+    const full = ordered.slice(0, -1);
+    if (full.length === 0) {
+        throw new Error(`cannot determine the sample rate of shard ${nameOf(ordered[0].Index)}: neither its key nor its content type carries one, ` +
+            `and a lone shard may be a partial window, so its size cannot be trusted`);
+    }
+    const rates = full.map(segment => {
+        const implied = segment.Bytes.length / RECORDING_BYTES_PER_SAMPLE / LEGACY_SHARD_SECONDS;
+        const snapped = STANDARD_PCM_RATES.find(r => Math.abs(implied - r) / r <= RATE_SNAP_TOLERANCE);
+        if (snapped === undefined) {
+            throw new Error(`cannot determine the sample rate of shard ${nameOf(segment.Index)}: its size (${segment.Bytes.length} bytes) ` +
+                `implies ${Math.round(implied)} Hz, not a standard rate`);
+        }
+        return snapped;
+    });
+    const disagreeing = rates.findIndex(r => r !== rates[0]);
+    if (disagreeing !== -1) {
+        throw new Error(`shards disagree on sample rate: ${nameOf(full[0].Index)}'s size implies ${rates[0]} Hz ` +
+            `but ${nameOf(full[disagreeing].Index)}'s implies ${rates[disagreeing]} Hz`);
+    }
+    return rates[0];
+}
+/** Sequential on purpose: bounds memory and request concurrency against the storage account. */
+async function readShardBytes(driver, shards) {
+    const segments = [];
+    let total = 0;
+    for (const shard of shards) {
+        const bytes = await driver.GetObject({ fullPath: shard.Path });
+        total += bytes.length;
+        // Listed sizes can be 0 or wrong, so the real total is enforced as bytes arrive.
+        if (total > MAX_RECOVERY_BYTES) {
+            throw new Error(`shards read so far total ${total} bytes (at ${shard.Name}), over the recovery limit of ${MAX_RECOVERY_BYTES} bytes`);
+        }
+        segments.push({ Index: shard.Index, Bytes: bytes });
+    }
+    return segments;
+}
+function describeRecovery(shardCount, assembled, sampleRate) {
+    const head = `Recovered from ${shardCount} crash-recovery segment(s)`;
+    if (assembled.MissingIndexes.length === 0) {
+        return `${head}.`;
+    }
+    const seconds = assembled.GapBytes / RECORDING_BYTES_PER_SAMPLE / sampleRate;
+    return `${head}; missing segment(s) ${assembled.MissingIndexes.join(', ')} filled with estimated silence (~${seconds.toFixed(1)} s each).`;
+}
 //# sourceMappingURL=realtime-recording-store.js.map