bunnyquery 1.8.6 → 1.8.8

package/src/engine/index.ts

@@ -43,7 +43,7 @@ export * from './prompts';
 
 // Pure helpers (Tier-1.5): error detection, token budgeting, link/path
 // normalization, and history mapping — shared so both consumers stay identical.
-export { getErrorMessage, isErrorResponseBody, isAuthExpiredError, isNonRetryableRequestError } from './errors';
+export { getErrorMessage, isErrorResponseBody, isAuthExpiredError, isNonRetryableRequestError, isProviderApiKeyError } from './errors';
 export * from './budget';
 // Per-format UTF-8 declaration for files offered as a download. Shared so a fenced
 // block and a server-published file open identically in Excel, Word and a browser.
@@ -64,6 +64,12 @@ export {
 	// read it the same way or the two will not group together.
 	isIndexingRequestText,
 	parseIndexingRequestText,
+	// One bounded look at the bg-indexing queue: which files still have a live
+	// pass. The dbfile browser's "indexed" badge uses this so a file only goes
+	// green once the run is confirmed over, not when its src:: record appears.
+	fetchLiveIndexingKeys,
+	getSplitChatHistory,
+	__resetSplitHistoryState,
 	type IndexingRequestRef,
 	type MapHistoryOptions,
 } from './history';
@@ -94,6 +100,8 @@ export {
 	type IndexingGroup,
 	type IndexingGroupStatus,
 	type BuildDisplayListOptions,
+	type RunStubInfo,
+	RUN_RECORD_WORKING_STALE_MS,
 } from './indexing_groups';
 
 export {
@@ -105,6 +113,11 @@ export {
 	BG_INDEXING_QUEUE_SUFFIX,
 	bgIndexingQueueName,
 	isBgIndexingQueue,
+	indexDoneUniqueId,
+	runIndexUniqueId,
+	upsertIndexRunRecordSafe,
+	type IndexRunStatus,
+	type IndexRunPatch,
 	MCP_NAME,
 	DEFAULT_CLAUDE_MODEL,
 	DEFAULT_OPENAI_MODEL,
@@ -116,6 +129,7 @@ export {
 	listClaudeModels,
 	listOpenAIModels,
 	getChatHistory,
+	buildHistoryItemFullId,
 	// response extraction
 	extractClaudeText,
 	extractOpenAIText,

package/src/engine/indexing_groups.ts

@@ -198,6 +198,15 @@ export type IndexingGroup = {
 	 *  loaded ones. 'status': the queue has not yet said whether this file is still
 	 *  being worked on, which is the only thing that can end a worker-driven run. */
 	resolvingReason?: 'history' | 'status';
+	/** Synthesized from a durable run:: record: none of the run's passes are
+	 *  among the loaded messages (bg history still deferred, or the run is older
+	 *  than the paging cap). Header-and-status only — members/visibleMembers are
+	 *  empty and there is nothing to cancel; the row is replaced by the real
+	 *  group the moment actual passes load (same `key`, so expansion state
+	 *  carries over). */
+	stub?: boolean;
+	/** The run:: record's stored error text, for a stub row's meta line. */
+	stubError?: string;
 };
 
 export type DisplayEntry =
@@ -222,6 +231,14 @@ export type BuildDisplayListOptions = {
 	/** Whether `liveIndexKeys` has been answered at least once for this chat. False
 	 *  is "we do not know", and a worker-driven run stays unfinished on it. */
 	liveIndexChecked?: boolean;
+	/** Files carrying the durable done:: completion marker (one prefix sweep),
+	 *  keyed like IndexingGroup.key (storage path; the bare-name fallback keys
+	 *  of very old prompts simply never match — they keep the queue inference).
+	 *  A marker is PROOF the file was read to the end: it settles a worker-run
+	 *  green without waiting for the queue answer, and it is never withheld by
+	 *  the resolving logic. A live queue hit still outranks it (a re-index in
+	 *  flight whose marker-cascade delete lagged). */
+	doneKeys?: { [fileKey: string]: boolean };
 	/** Server item ids of passes that were on a row when the user STOPPED it
 	 *  (ChatSession.state.stoppedIndexIds). A run holding any of them is a run the
 	 *  user stopped — see the status derivation for why a stop usually leaves no
@@ -232,8 +249,52 @@ export type BuildDisplayListOptions = {
 	 *  windowedIndexing). Passed in rather than read from config so this stays a
 	 *  pure function of its inputs and can be exercised for both settings. */
 	windowedIndexing?: boolean;
+	/** Durable run:: records, keyed by STORAGE PATH (the consumer's marker
+	 *  sweep). Each key with no real group in the loaded messages gets a
+	 *  synthesized header-only row (see IndexingGroup.stub), placed by its
+	 *  `started` timestamp. A real group for the same file — matched by key,
+	 *  path, or name — always suppresses the stub: loaded passes are evidence,
+	 *  the record is only a summary. */
+	runStubs?: { [storagePath: string]: RunStubInfo };
+	/** The platform whose chat this list is for. run:: records are per-FILE,
+	 *  but a chat is per (project, platform): a run started under Claude has
+	 *  its passes in the Claude conversation and is invisible to the
+	 *  OpenAI-scoped queue probe, so its stub could never be covered and never
+	 *  be confirmed — it just sat there, in a chat it did not belong to.
+	 *  Records minted before this was stamped carry no platform and are shown
+	 *  in both, which keeps the leak to the historical set. */
+	stubPlatform?: 'claude' | 'openai';
+	/** The chat's clear-history horizon (ms epoch). Run records are service-
+	 *  wide and know nothing about a cleared chat, so without this every
+	 *  "Clear chat history" resurrects one row per indexed file. A stub whose
+	 *  run ended (or, unfinished, began) at or before this moment is dropped —
+	 *  unless the queue says the file is live RIGHT NOW, which no horizon can
+	 *  make untrue. */
+	stubClearedAt?: number;
+	/** Clock injection for tests; defaults to Date.now(). Only run-stub
+	 *  staleness reads it. */
+	now?: number;
 };
 
+/** The display-relevant fields of a run:: record (see requests.ts
+ *  runIndexUniqueId for the record's contract). */
+export type RunStubInfo = {
+	status: 'working' | 'done' | 'error' | 'cancelled';
+	filename?: string;
+	started?: number;
+	finished?: number;
+	error?: string;
+	/** Chat that owns this run. Absent on records minted before it was
+	 *  stamped; see BuildDisplayListOptions.stubPlatform. */
+	platform?: 'claude' | 'openai';
+};
+
+/** A 'working' run record older than this with no live-queue confirmation is
+ *  treated as unknown rather than live: a chain that died without reaching any
+ *  error path leaves 'working' dangling, and a row must not spin forever on a
+ *  claim nothing can end. */
+export const RUN_RECORD_WORKING_STALE_MS = 6 * 60 * 60 * 1000;
+
 // The indexing label is view-formatted (formatIndexingLabel), so parsing it is
 // the FALLBACK path only: it exists for bubbles restored from a history cache
 // written before `_indexFile` was stamped. Live and freshly-mapped bubbles carry
@@ -324,12 +385,14 @@ export function buildChatDisplayList(
 	var list = Array.isArray(messages) ? messages : [];
 	var liveIndexKeys = (opts && opts.liveIndexKeys) || {};
 	var liveIndexChecked = !!(opts && opts.liveIndexChecked);
+	var doneKeys = (opts && opts.doneKeys) || {};
 	var stoppedIndexIds = (opts && opts.stoppedIndexIds) || {};
 	var windowedIndexing = opts && opts.windowedIndexing !== undefined
 		? !!opts.windowedIndexing
 		: windowedIndexingEnabled();
 	var hasMoreHistory = !!(opts && opts.hasMoreHistory);
 	var loadingOlderHistory = !!(opts && opts.loadingOlderHistory);
+	var stubPlatform = opts && opts.stubPlatform;
 
 	// One entry per RUN (see IndexingGroup.runKey), addressed by an internal id
 	// while the list is being walked; runKey is assigned at the end, once the
@@ -629,7 +692,13 @@ export function buildChatDisplayList(
 			// permanently false and the two tests below were already carrying the whole
 			// decision. It is gone rather than left as a hook, so this reads as what it
 			// actually is: for a worker-driven run, ONLY the queue can say it is over.
+			// The done:: marker is the third — and strongest — disjunct: written
+			// only at a chain's true end (backend worker, or a client's own
+			// deterministic completion), it answers without any queue round
+			// trip. Gated on the queue NOT claiming the file live, so a
+			// re-index whose marker-cascade delete lagged still shows yellow.
 			grp.finished = !newestRunOfKey[order[oi]] ||
+				(!!doneKeys[grp.key] && !liveIndexKeys[grp.key]) ||
 				(liveIndexChecked && !liveIndexKeys[grp.key]);
 		}
 
@@ -645,7 +714,7 @@ export function buildChatDisplayList(
 			// newest pass's own outcome, and newest-first paging always has that pass.
 			grp.resolving = false;
 		} else if (grp.mayHaveOlder && loadingOlderHistory &&
-			!liveIndexKeys[grp.key] && newestRunOfKey[order[oi]]) {
+			!liveIndexKeys[grp.key] && !doneKeys[grp.key] && newestRunOfKey[order[oi]]) {
 			// The line this draws, and it is the same line the 'status' branch draws:
 			// withhold what is UNKNOWN, and what is only INFERRED settled. Never
 			// withhold what is PROVEN, in either direction. Two proofs, and an older
@@ -692,15 +761,191 @@ export function buildChatDisplayList(
 		}
 	}
 
+	// --- durable run:: stubs ---------------------------------------------------
+	// A run record whose passes are not among the loaded messages still deserves
+	// a row: on a fresh open the bg history is deferred, and a run older than the
+	// paging cap never loads at all. Synthesized as header-only groups and placed
+	// by `started` among the messages' own timestamps; a real group for the same
+	// file always wins (see BuildDisplayListOptions.runStubs).
+	var stubList: { started: number; group: IndexingGroup }[] = [];
+	var runStubs = opts && opts.runStubs;
+	if (runStubs) {
+		// Two namespaces, deliberately NOT one map: storage paths are
+		// project-relative and folder trees repeat basenames routinely, so a
+		// flat map let a real group for "2025/report.pdf" delete the stub for
+		// "2026/report.pdf" with nothing replacing it. A bare NAME only covers
+		// a stub when the group itself has no path (the legacy compact-label
+		// case) and the record has no filename of its own to disambiguate.
+		var coveredPaths: { [k: string]: boolean } = {};
+		var coveredPathlessNames: { [k: string]: boolean } = {};
+		for (var ci = 0; ci < order.length; ci++) {
+			var cg = groups[order[ci]];
+			if (cg.path) { coveredPaths[cg.path] = true; if (cg.key) coveredPaths[cg.key] = true; }
+			else if (cg.name) coveredPathlessNames[cg.name] = true;
+			else if (cg.key) coveredPaths[cg.key] = true;
+		}
+		var now = opts && typeof opts.now === 'number' ? opts.now : Date.now();
+		var stubClearedAt = (opts && typeof opts.stubClearedAt === 'number' && opts.stubClearedAt > 0)
+			? opts.stubClearedAt : 0;
+		for (var sp in runStubs) {
+			var rec = runStubs[sp];
+			if (!sp || !rec || !rec.status || coveredPaths[sp]) continue;
+			var fname = rec.filename || sp.split('/').pop() || sp;
+			// A PATHLESS group (legacy compact label) can only be matched by
+			// name, and that is still the right match: the file already has a
+			// row, so suppressing avoids a duplicate rather than creating a
+			// void. What is gone is the reverse — a group WITH a path no longer
+			// writes into the name namespace, so it can no longer delete a
+			// same-basename stub from another folder.
+			if (coveredPathlessNames[fname]) continue;
+			// A run recorded under the OTHER platform's chat belongs to that
+			// conversation: its passes live in that history (so no real group
+			// can ever cover this stub) and the queue probe is platform-scoped
+			// (so it can never confirm it). Records with no platform are
+			// legacy and keep the old behaviour rather than vanishing.
+			if (stubPlatform && rec.platform && rec.platform !== stubPlatform) continue;
+			// Mirrors the real groups' status precedence: a live queue hit outranks
+			// whatever the record says (a lagged update must not paint a verdict over
+			// visible work), then the record's own terminal statuses, then the
+			// queue's authoritative ABSENCE, and only then the stated wait.
+			var live = !!liveIndexKeys[sp] || !!liveIndexKeys[fname];
+			// Cleared-history horizon: a run that ended at or before the clear is
+			// part of what the user asked to forget. A live queue hit survives it
+			// (see BuildDisplayListOptions.stubClearedAt). A record carrying NO
+			// timestamp at all is unplaceable, not old — the horizon cannot judge
+			// it, so it is never dropped by one.
+			var recWhen = typeof rec.finished === 'number' ? rec.finished
+				: typeof rec.started === 'number' ? rec.started : undefined;
+			if (stubClearedAt && !live && recWhen !== undefined && recWhen <= stubClearedAt) continue;
+			var st: IndexingGroupStatus = 'active';
+			var fin = false;
+			var res = false;
+			var reason: 'history' | 'status' | undefined;
+			if (!live) {
+				// A done:: marker from the same sweep is as terminal as the record's
+				// own 'done' — it settles a dangling 'working' the chain never
+				// flipped (mirrors the real-group doneKeys disjunct).
+				if (rec.status === 'done' || doneKeys[sp] || doneKeys[fname]) { st = 'done'; fin = true; }
+				else if (rec.status === 'error') { st = 'error'; fin = true; }
+				else if (rec.status === 'cancelled') { st = 'cancelled'; fin = true; }
+				else if (liveIndexChecked) {
+					// 'working' is a CLAIM. The queue has now answered, untruncated,
+					// and holds nothing for this file — the same proof the real-group
+					// ladder settles on. Without this disjunct a stub had no
+					// terminator at all: worker-driven runs are never flipped by this
+					// client, so the row sat grey forever (the reported "checking
+					// status that never resolves").
+					st = 'done'; fin = true;
+				} else if (typeof rec.started === 'number' && now - rec.started > RUN_RECORD_WORKING_STALE_MS) {
+					// Older than any real run and still unconfirmed: a dead claim, not
+					// an open question. Same horizon the files page applies.
+					st = 'error'; fin = true;
+				} else {
+					// Genuinely unanswered — the queue reply is one round trip away
+					// and this self-heals the moment it lands.
+					res = true; reason = 'status';
+				}
+			}
+			var sg: IndexingGroup = {
+				key: sp,
+				// ONE identity for the run whether it renders from the record or
+				// from its loaded passes: the views key the DOM off runKey, so a
+				// 'stub:'-prefixed key meant every handoff was an unmount plus a
+				// remount somewhere else. Named after the record's start, which
+				// the real group below reuses when it has one.
+				runKey: 'run:' + sp + '#' + (typeof rec.started === 'number' ? rec.started : 'n'),
+				name: fname,
+				path: sp,
+				mime: undefined,
+				size: undefined,
+				isReindex: false,
+				members: [],
+				passCount: 0,
+				status: st,
+				cancellableIds: [],
+				cancelling: false,
+				stopped: st === 'cancelled',
+				mayHaveOlder: hasMoreHistory,
+				anchorIndex: -1,
+				anchorId: '',
+				visibleMembers: [],
+				driver: !isPagedReadFile(fname, undefined) ? 'single'
+					: isImageVisionFile(fname, undefined) ? 'worker'
+						: (windowedIndexing ? 'worker' : 'client'),
+				finished: fin,
+				resolving: res,
+				resolvingReason: reason,
+				stub: true,
+				stubError: rec.error || (st === 'error' && !rec.error
+					? 'Indexing did not finish.' : undefined),
+			};
+			// A record with no `started` cannot be placed in the conversation.
+			// Infinity sorts it to the END (nearest the newest turns) instead of
+			// above every message the user has ever sent — the row is about
+			// something recent, not about the beginning of time.
+			stubList.push({ started: typeof rec.started === 'number' ? rec.started : Infinity, group: sg });
+		}
+	}
+
+	// --- timestamp-anchor INCOMPLETE real runs ---------------------------------
+	// A real run's row renders at its first LOADED pass, and while older history
+	// pages in (newest-first) that is a moving target: the run first appears at
+	// its newest pass — down by the recent bubbles — then relocates upward as
+	// earlier passes arrive, so the row visibly jumps. The run:: record's
+	// `started` is a stable anchor for exactly that window: emit the row at its
+	// timestamp position instead, and once the true first pass loads
+	// (mayHaveOlder false) emission returns to the anchor, which by then IS the
+	// same spot. Newest run of the file only — the record describes it, and an
+	// older run's passes are already fully placed around it.
+	//
+	// NOT gated on mayHaveOlder: that made the position depend on WHICH passes
+	// happened to be loaded, so a row moved when the sweep resolved, again when
+	// the first pass paged in, and again when paging ended. A record with a
+	// `started` places the run at ONE spot for as long as the record exists.
+	var suppressAnchor: { [runId: string]: boolean } = {};
+	if (runStubs) {
+		for (var ti2 = 0; ti2 < order.length; ti2++) {
+			var tg = groups[order[ti2]];
+			if (!newestRunOfKey[order[ti2]]) continue;
+			var trec = (tg.path && runStubs[tg.path]) || runStubs[tg.key];
+			if (!trec || typeof trec.started !== 'number') continue;
+			if (stubPlatform && trec.platform && trec.platform !== stubPlatform) continue;
+			suppressAnchor[order[ti2]] = true;
+			// Same identity the stub form uses, so a row that upgrades from
+			// record-only to loaded-passes keeps its DOM node and its position.
+			tg.runKey = 'run:' + (tg.path || tg.key) + '#' + trec.started;
+			stubList.push({ started: trec.started, group: tg });
+		}
+	}
+	stubList.sort(function (a, b) { return a.started - b.started; });
+
 	var out: DisplayEntry[] = [];
+	var si = 0;
 	for (var j = 0; j < list.length; j++) {
+		// Splice stubs in by time: everything that started before this message
+		// goes above it. Messages without a timestamp decide nothing.
+		var mts = list[j] && typeof list[j]._ts === 'number' ? (list[j]._ts as number) : undefined;
+		if (mts !== undefined) {
+			while (si < stubList.length && stubList[si].started <= mts) {
+				out.push({ kind: 'indexing', group: stubList[si].group, index: -1 - si });
+				si++;
+			}
+		}
 		var r = runOfIndex[j];
 		if (r === undefined) {
 			out.push({ kind: 'message', msg: list[j], index: j });
 			continue;
 		}
-		// Every other member of the run is represented by the row at the anchor.
-		if (groups[r].anchorIndex === j) out.push({ kind: 'indexing', group: groups[r], index: j });
+		// Every other member of the run is represented by the row at the anchor —
+		// unless the row is timestamp-anchored (incomplete run with a run::
+		// record), in which case the flush above already emitted it.
+		if (groups[r].anchorIndex === j && !suppressAnchor[r]) {
+			out.push({ kind: 'indexing', group: groups[r], index: j });
+		}
+	}
+	while (si < stubList.length) {
+		out.push({ kind: 'indexing', group: stubList[si].group, index: -1 - si });
+		si++;
 	}
 	return out;
 }

package/src/engine/office.ts

@@ -231,7 +231,28 @@ export interface ComposedUserMessage {
 export function composeUserMessage(
 	text: string,
 	attachmentUrls: Array<{ name: string; url: string; storagePath?: string }>,
+	opts?: {
+		/**
+		 * Inline each server-extractable attachment's whole text into the
+		 * prompt (the `_skapi_extract` directives + BEGIN/END FILE CONTENT
+		 * block). Default true, which is right when the file's content is
+		 * nowhere else yet.
+		 *
+		 * Pass FALSE when the turn is dispatched AFTER the file's indexing run
+		 * has drained. Extraction is the same server-side download+parse the
+		 * indexing pass already performed, so inlining repeats it: the worker
+		 * fetches and re-parses every attachment a second time (which reads,
+		 * from the outside, exactly like the file being indexed again), and the
+		 * whole file text is re-sent as prompt tokens. It is also the WORSE
+		 * copy for anything large, because inline extraction truncates at
+		 * MAX_EXTRACTED_CHARS while the indexed records cover the file end to
+		 * end. The model reaches the content through the records
+		 * (getRecords with reference "src::<path>") or readFileContent.
+		 */
+		inlineExtractedContent?: boolean;
+	},
 ): ComposedUserMessage {
+	const inlineExtracted = opts?.inlineExtractedContent !== false;
 	let composed = text;
 	let composedForLlm = composed;
 	if (attachmentUrls.length > 0) {
@@ -242,7 +263,9 @@ export function composeUserMessage(
 	let extractContent: ExtractDirective[] | undefined;
 	let fileUrls: FileUrlDirective[] | undefined;
 	if (attachmentUrls.length > 0) {
-		const extractFiles = attachmentUrls.filter((u) => isServerExtractable(u.name));
+		const extractFiles = inlineExtracted
+			? attachmentUrls.filter((u) => isServerExtractable(u.name))
+			: [];
 		if (extractFiles.length > 0) {
 			const directives: ExtractDirective[] = [];
 			const sections = extractFiles.map((u) => {

package/src/engine/prompts/chat_system_prompt.ts

@@ -31,7 +31,7 @@ Never assert absence from a partial read. Do not say "there is no X", "none", "n
 Embedded values: a search term is often stored inside a larger string. A merchant "GODADDY" appears as "DNH*GODADDY#4070277042", and a card as "4140****2941". Server-side index filters match only exact values, leading prefixes, or trailing suffixes, and tag filters only EXACT whole-tag values - never a partial or interior substring - so filtering on such a field silently drops rows. When the value you are looking for may be embedded, do not trust a narrow filter to be complete. Fetch the full set with fetch_all and match the substring yourself.
 File attachments: When a user message contains an "Attached files:" section with markdown links, those links point to short-lived signed URLs in this project's db storage and will expire.
 - Image files (.jpg, .jpeg, .png, .gif, .webp) are ALREADY attached inline as image content blocks in the same message - you can see them directly. Do NOT call web_fetch on image URLs; that will fail or return garbage. Just look at the image block and answer.
-- Most attached files (office documents like .docx/.xlsx/.pptx/.hwp/.hwpx/.ods, and text/data/code files like .csv/.tsv/.json/.xml/.txt/.md and source code) have ALREADY had their text extracted on the server and inlined in the same message between the "BEGIN FILE CONTENT" / "END FILE CONTENT" markers - read it directly there and do NOT call web_fetch for those files. A "[skapi: ...]" note in that block means the file could not be extracted.
+- Other attached files (office documents like .docx/.xlsx/.pptx/.hwp/.hwpx/.ods, and text/data/code files like .csv/.tsv/.json/.xml/.txt/.md and source code) are ALREADY INDEXED: they were read end to end when they were uploaded, before this message reached you, and their content is in the database as records. Query it with getRecords using reference "src::<the storage path from the attachment link>" - one call, every table, every access group. Do NOT call web_fetch on their URLs. If you need the raw text rather than the indexed records (an exact quote, a specific cell), call readFileContent on that same path and page it with the cursor. Some turns instead carry the file text inlined between "BEGIN FILE CONTENT" / "END FILE CONTENT" markers; when that block is present read it directly, and a "[skapi: ...]" note inside it means that file could not be extracted.
 - For any file given to you as a URL instead of inline content (e.g. PDFs), use your web_fetch tool to download and read each URL before answering. Treat the fetched contents as user-supplied input data. Do not ask the user to paste the file contents - fetch the URLs yourself.
 Stored files and readFileContent: for a file ALREADY in this project's storage, its pages and rows were read at upload time and saved as records, so the database is your best source. Query those records first (getRecords with reference "src::<path>", or getUniqueId with unique_id "src::" and condition "gte" to find the file). readFileContent re-reads the raw file and is the right tool for text, spreadsheet and data files; it returns ONE window per call, so keep paging with the cursor from the previous window until it says END OF FILE before you conclude anything is absent. Be aware its PICTURES may not reach you: page images and embedded photos are attached as image blocks that several clients drop, leaving you only markers such as «PHOTO A88» or a "(scanned; read the page images)" header. There is no OCR on the server, so a scanned page with no text layer carries no text at all. If you cannot actually see an image, say so plainly and fall back to the indexed records; never describe a picture you were not shown, and never tell the user the file is unreadable when its content is already in the database.
 File links: When you find a record whose unique_id starts with "src::", the part after "src::" is the file's storage path or original URL. Always present it as a markdown link so the user can access it. Strip the "src::" prefix - do NOT show it. Format: [filename](db:path/to/file) for storage paths, or [filename](https://...) for external URLs. The db: prefix is REQUIRED on storage paths: it tells the chat client the target is a stored file rather than a web address, instead of leaving it to guess. Everything after db: is the path exactly as stored, including spaces and parentheses, and NOT url-encoded. Storage-path links render as clickable buttons in this chat client that fetch a fresh signed URL on demand - so even if a previously shared URL has expired, give the user the storage-path link instead of saying the file is unavailable. Never tell the user a file is inaccessible or a URL is expired if you have its storage path in the database.