bunnyquery 1.9.7 → 1.10.0

package/src/engine/host.ts

@@ -130,6 +130,91 @@ export interface ChatMessage {
 	 *  still dimmed. Cleared (with _dimSending) by markStagedMessageReady the moment
 	 *  the queue drains, which is when the turn genuinely becomes "(In queue)". */
 	isAwaitingIndexing?: boolean;
+	/** PROTOCOL + PRESENTATIONAL: this bubble is being painted from a LIVE stream.
+	 *
+	 *  It sits alongside `isPending`, never instead of it. The bubble is still the
+	 *  turn's "Thinking..." placeholder as far as every queue mechanism is concerned
+	 *  (_ownThinkingIndex, resolveQueuedUserBubble, typewriteLatestReply and the
+	 *  stray-pending sweep all find their target by isPending), and clearing that flag
+	 *  to mean "it has text now" would strand the turn's real answer beside an orphan.
+	 *  What this adds is the one thing those mechanisms do not care about and the VIEW
+	 *  does: `content` is already worth rendering, so draw the text instead of the
+	 *  spinner.
+	 *
+	 *  Cleared the moment the turn settles, BEFORE the authoritative answer replaces
+	 *  the live text: from that instant the bubble is an ordinary reply being typed.
+	 *  The partially painted `content` is deliberately left in place across that clear,
+	 *  because it is what the typewriter resumes from instead of replaying from zero.
+	 *
+	 *  Also read by shouldRescueInFlightMessage: a streaming bubble that has no server
+	 *  id yet is unrepresentable in a freshly fetched page, so it must survive the
+	 *  merge or its stream is orphaned with nothing left to paint into. */
+	_streaming?: boolean;
+	/**
+	 * This turn's row is TERMINAL but carries no stored answer, because the answer
+	 * was streamed and nobody ever finalized it: the bytes are in the chunk store,
+	 * not on the row. The bubble's `content` is therefore UNKNOWN, not empty.
+	 *
+	 * That distinction is the whole of the fix for two bugs that looked unrelated.
+	 * A refetch landing in the window between the row going 'resolved' and finalize
+	 * storing the body used to ERASE the answer off the screen (the server copy has
+	 * no content, so the merge dropped the local bubble that did); and a turn that
+	 * settled while no poll was attached (closed tab, slept device) used to be
+	 * unrecoverable, because the mapper emitted no assistant bubble at all for a
+	 * terminal-but-empty row. Both are the same question, "what should the merge
+	 * believe when the server copy is authoritative but empty", and the answer is
+	 * this flag: an unknown answer NEVER overwrites a known one, and an unknown one
+	 * left over after the merge is resolved by reading the chunks back
+	 * (ChatSession.recoverStreamedAnswer).
+	 *
+	 * For a view it is a rendering hint and nothing more: a bubble carrying it with
+	 * empty content is being fetched, so draw whatever this client draws for a
+	 * loading answer. A host that ignores it renders an empty bubble for the second
+	 * or two the recovery takes, which is what it would have rendered anyway.
+	 *
+	 * WHEN IT COMES OFF, because that is the half that loses answers. It comes off
+	 * for a FACT about the turn and never for an event in the client: an answer was
+	 * recovered and written in, or the chunks were read and were genuinely empty (in
+	 * which case the empty bubble is removed as well, restoring the list the mapper
+	 * used to produce). It stays ON when the read FAILED, when the read was STOPPED,
+	 * and when a live turn settled having painted nothing - three states that say
+	 * nothing whatever about the turn, and in which the chunks are all still there.
+	 * A marker cleared on one of those is an answer nothing will ever go back for,
+	 * so a host may see the same bubble marked across several loads while the reads
+	 * keep failing; that is the recoverable state, not a stuck one.
+	 */
+	_streamPending?: boolean;
+	/**
+	 * IS ANYTHING ACTUALLY DRIVING THIS BUBBLE RIGHT NOW? The second half of
+	 * `_streamPending`, and the half a view cannot do without.
+	 *
+	 * `_streamPending` says the answer is elsewhere; it does NOT say somebody is on
+	 * their way to fetch it, and the two are different states that used to render
+	 * identically. Recovery is capped per history load (STREAM_RECOVERY_PER_LOAD),
+	 * so the third and later marked turns on a page are marked and nobody is reading
+	 * them; a read that FAILED leaves the marker on with the attempt forgotten, which
+	 * is also nobody. Both drew the same loader as a live turn, so a bubble could
+	 * spin for the rest of the session with nothing behind it - the one thing a
+	 * spinner must never do, because it is a promise that something is coming.
+	 *
+	 * Three states, and only the first of them may draw a spinner:
+	 *   'active'   a chunk read is in flight or queued for this turn. Something IS
+	 *              coming; the loader is honest.
+	 *   'failed'   the last read failed. Nothing is coming until somebody asks
+	 *              again, so the view owes the reader a way to ask.
+	 *   undefined  nothing has been tried, or the attempt is over. Same obligation.
+	 *
+	 * Written by the engine only, and never persisted anywhere: it describes THIS
+	 * session's fetching, not the turn. A fresh history page therefore arrives
+	 * without it, and _adoptLocalAnswers re-stamps the page's still-marked bubbles
+	 * from the session's own bookkeeping, so a reload during a read does not turn a
+	 * live loader into a button (and back a second later).
+	 *
+	 * Read it through streamRecoveryPhase(msg), never directly: the phase folds in
+	 * "does this bubble need the affordance at all", and both clients must not
+	 * answer that twice.
+	 */
+	_streamRecovery?: 'active' | 'failed';
 	_serverItemId?: string;
 	_localId?: string;
 	_cancelling?: boolean;

package/src/engine/index.ts

@@ -11,11 +11,31 @@ export {
 	configureChatEngine,
 	chatEngineConfig,
 	type ChatEngineConfig,
+	// The live-stream observation hook's payload. Exported so a consumer can type
+	// its handler against the engine rather than restate the shape.
+	type LiveStreamUpdate,
+	// "Can a streamed turn whose answer never reached its row be read back?" - which
+	// asks for the chunk READER and deliberately not for liveStreaming, because a
+	// row that already streamed stays recoverable long after streaming is switched
+	// off. Exported because a client with its OWN history mapper (agent.vue's fork)
+	// has to gate the `_streamPending` mark on exactly this predicate: gate it on
+	// liveStreaming and every already-streamed row is stranded the day the flag goes
+	// back off; gate it on nothing and a host with no reader gets a permanently
+	// empty bubble where it used to get none, which is strictly worse than the bug.
+	streamRecoveryEnabled,
+	// Whether a given skapi INSTANCE can carry skapi's half of the stream flag. Both
+	// clients gate their liveStreaming opt-in on it and degrade to buffered when it
+	// says no: an SDK too old to know the key drops it silently, leaving the
+	// destination streaming SSE into a buffered row that reads back empty.
+	skapiSupportsStreaming,
 } from './config';
 
 export {
 	isServerExtractable,
 	isOfficeFile,
+	isPagedReadFile,
+	isImageVisionFile,
+	isWindowedReadFile,
 	makeExtractPlaceholder,
 	composeUserMessage,
 	type ExtractDirective,
@@ -47,7 +67,15 @@ export { buildChatGreeting, type ChatGreetingParams, type ChatGreetingParts } fr
 
 // 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, isProviderApiKeyError } from './errors';
+export {
+	getErrorMessage, isErrorResponseBody, isAuthExpiredError, isNonRetryableRequestError, isProviderApiKeyError,
+	// The csr-poll STATUS ENVELOPE, and the provider error nested one level inside a
+	// failed one. Exported because "is this an envelope or a body" is asked in two
+	// places that must agree (the streamed settle, and every error reader), and it
+	// was answered twice before, one of the two one level too shallow, which is how
+	// a wrong API key on a streamed turn reported "No text response received".
+	isCsrStatusEnvelope, csrEnvelopeError,
+} 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.
@@ -57,6 +85,11 @@ export * from './link_markup';
 export * from './image_preview';
 export * from './time';
 export * from './ai_agent';
+// The SSE parser. skapi relays the provider's bytes without reading them, so this is
+// where BunnyQuery's knowledge of the Anthropic and OpenAI wire formats lives. It has
+// to be on the barrel or the built engine bundle does not contain it and
+// www.skapi.com's `bunnyquery/engine` import resolves to undefined at runtime.
+export * from './sse';
 export {
 	filterListByClearHorizon,
 	normalizeTextContent,
@@ -73,6 +106,11 @@ export {
 	// rendered twice and then persisted into the history cache.
 	shouldRescueInFlightMessage,
 	type RescueDecisionContext,
+	// What the merge does when the server's copy of a turn is authoritative but
+	// EMPTY (a streamed row nobody finalized): the local answer wins, because an
+	// unknown answer is not an empty one. Shared for the same reason the rescue
+	// rule is: a client mapper that forks it erases answers off the screen.
+	adoptLocalAnswerIntoPage,
 	// 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.
@@ -114,7 +152,31 @@ export {
 
 // Tier-2: the stateful chat orchestration (queue/poll/cancel, typewriter,
 // bg-task drain, resolution). DOM-free; the consumer implements ChatHost.
-export { ChatSession } from './session';
+//
+// liveSafePrefix / typewriterResumeIndex are the two pure halves of live
+// rendering: what is safe to show while the answer is still arriving, and where
+// the typewriter picks up once the authoritative answer replaces it. Exported so
+// they can be tested (and read) without a DOM.
+//
+// mayKeepStreamedAnswer is the ONE keep policy for a streamed turn: may this parse
+// be stored as the row's permanent answer, given the row's own status. It is on the
+// barrel because finalize is also the only way to release chunks, so every path
+// that can reach it has to answer this identically - the live settle and the
+// read-back once answered it separately and disagreed, and the disagreement
+// released the chunks of a failed turn.
+//
+// streamRecoveryPhase / streamRecoveryLabels are the RENDER half of the same
+// policy: given a bubble whose answer is still in the chunk store, is anything
+// actually fetching it, and if not, what does the reader get offered instead of a
+// spinner that will never resolve. Both clients read the phase from here rather
+// than from `_streamRecovery` directly - the alternative is each of them deciding
+// on its own when a loader is honest, which is precisely the fork this barrel
+// exists to prevent.
+export {
+	ChatSession, liveSafePrefix, typewriterResumeIndex, mayKeepStreamedAnswer,
+	streamRecoveryPhase, streamRecoveryLabels,
+	type StreamDispatchContext,
+} from './session';
 export type { ChatHost, ChatIdentity, ChatState, ChatMessage, IndexingFileRef, PinnedDispatchContext } from './host';
 
 // Display transform: collapse a file's many background-indexing turns into one
@@ -133,6 +195,7 @@ export {
 export {
 	// constants
 	POLL_INTERVAL,
+	STREAM_POLL_INTERVAL,
 	MAX_CONCURRENT_BG_POLLS,
 	getVisionProfile,
 	type VisionProfile,
@@ -147,6 +210,11 @@ export {
 	MCP_NAME,
 	DEFAULT_CLAUDE_MODEL,
 	DEFAULT_OPENAI_MODEL,
+	// The ONE producer of the two `stream` flags a streamed chat turn needs. Exported
+	// so a test can assert the pair moves together, which is the whole point of it
+	// being a single function.
+	chatStreamWiring,
+	type ChatStreamWiring,
 	// request builders + dispatch
 	callClaudeWithMcp,
 	callClaudeWithPublicMcp,
@@ -179,3 +247,44 @@ export {
 	type AttachmentSaveInfo,
 	type BgTaskEntry,
 } from './requests';
+
+// The project's BunnyQuery settings, stored as a public record in the customer's
+// own project ("bq::settings" in "__SETTINGS__") rather than on the skapi service
+// record. Both clients prime it when a chat page opens and await it before the
+// first upload writes an access group onto a record. See project_settings.ts.
+export {
+	// where the record lives
+	PROJECT_SETTINGS_TABLE,
+	PROJECT_SETTINGS_UNIQUE_ID,
+	PROJECT_SETTINGS_ACCESS_GROUP,
+	// the choice, its labels and its default
+	UPLOAD_ACCESS_GROUPS,
+	UPLOAD_ACCESS_LABELS,
+	UPLOAD_ACCESS_HINTS,
+	UPLOAD_ACCESS_OPTIONS,
+	DEFAULT_UPLOAD_ACCESS_GROUP,
+	// pure readers over a settings `data` object
+	normalizeUploadAccessGroup,
+	normalizeProjectAccessSetting,
+	accessSettingFrom,
+	uploadAccessGroupFrom,
+	asksUploadAccessFrom,
+	// the per-project store
+	configureProjectSettings,
+	loadProjectSettings,
+	primeProjectSettings,
+	readyProjectSettings,
+	cachedProjectSettings,
+	projectSettingsSettled,
+	projectAccessSetting,
+	projectUploadAccessGroup,
+	projectAsksUploadAccess,
+	setProjectSettings,
+	patchProjectSettings,
+	clearProjectSettings,
+	// types
+	type UploadAccessGroup,
+	type ProjectAccessSetting,
+	type ProjectSettingsData,
+	type ProjectSettingsReader,
+} from './project_settings';

package/src/engine/office.ts

@@ -2,7 +2,8 @@
  * Office-file server-side extraction helpers.
  *
  * Office documents (Microsoft .docx/.xlsx/.pptx, Hancom .hwpx, etc.) can't be
- * read by web_fetch (binary/zip). The proxy worker downloads them from db
+ * read by web_fetch (binary/zip), and neither can an RFC822 email (.eml), whose
+ * body and attachments are MIME-encoded. The proxy worker downloads them from db
  * storage, extracts their text server-side, and substitutes that text for a
  * placeholder token in the request body (carried under the reserved
  * `_skapi_extract` key, which the producer strips before the upstream call).
@@ -36,7 +37,11 @@ export type FileUrlDirective = {
 // Files whose text the worker extracts SERVER-SIDE and inlines for indexing,
 // instead of handing the agent a URL to fetch. Two groups:
 //   (1) BINARY document formats the model can't read at all (OOXML, Hancom
-//       HWP/HWPX, OpenDocument, EPUB) — the worker parses them.
+//       HWP/HWPX, OpenDocument, EPUB): the worker parses them. RFC822 email
+//       (.eml) belongs here although it is nominally text: it is a MIME
+//       container whose body is quoted-printable/base64 and whose attachments
+//       are base64 blobs, so it must be PARSED on the server, never decoded as
+//       text (a text route would inline the attachment blobs as prose).
 //   (2) TEXT/data/markup/code formats. These ARE readable via web_fetch, BUT
 //       some providers (OpenAI's Responses API) have no working file-fetch tool,
 //       so the agent can't retrieve the URL at all. Extracting them server-side
@@ -48,6 +53,7 @@ const OFFICE_FILE_EXTENSIONS = new Set([
 	'hwp', 'hwpx',
 	'ods', 'odt', 'odp',
 	'epub',
+	'eml',
 ]);
 
 const TEXT_FILE_EXTENSIONS = new Set([
@@ -129,6 +135,11 @@ export const isOfficeFile = isServerExtractable;
 // .sql, .css, .toml ...). They are windowable, but adding them moves every small code
 // upload from one pass to multi-pass worker indexing, which is a cost change that wants
 // measuring on its own rather than riding along with this one.
+//
+// .eml is paged for the same reason the documents are: an email carrying a
+// spreadsheet or a long reply thread routinely exceeds the 200k one-shot cap, and
+// its layer extractor ships in the same change as this entry (listed before the
+// layer lands, it would page UNSUPPORTED_FORMAT on every window).
 const PAGED_READ_EXTENSIONS = new Set([
 	// grids
 	'xls', 'xlsx', 'xlsm', 'ods',
@@ -142,6 +153,7 @@ const PAGED_READ_EXTENSIONS = new Set([
 	'odt', 'odp',
 	// other long-form documents
 	'epub', 'rtf', 'html', 'htm',
+	'eml', // email (RFC822): body plus attachment text, char-windowed
 	// plain text / data / markup
 	'txt', 'md', 'markdown', 'log', 'json', 'jsonl', 'ndjson', 'xml', 'yaml', 'yml',
 ]);
@@ -239,8 +251,8 @@ export interface ComposedUserMessage {
 
 // Compose the user's chat message from the typed text + uploaded attachment URLs.
 // Identical for every consumer (agent.vue + the BunnyQuery widget): appends a
-// markdown "Attached files" link block, and for office files
-// (.docx/.xlsx/.pptx/.hwpx) adds inline extraction placeholders to the LLM copy
+// markdown "Attached files" link block, and for server-extractable files
+// (.docx/.xlsx/.pptx/.hwpx/.eml, text/data/code) adds inline extraction placeholders to the LLM copy
 // ONLY (the proxy worker substitutes their text server-side; the display/history
 // copy stays clean so stale tokens never accumulate across replayed turns).
 // The directive `path` is the db storage path (uid-prefixed where applicable),

package/src/engine/project_settings.ts

@@ -0,0 +1,303 @@
+/**
+ * The project's BunnyQuery settings, held as a record in the project's own
+ * database rather than on the skapi service record.
+ *
+ * WHY A RECORD. The upload access group used to live on the service record as
+ * `default_access_group`, which was ALSO the skapi SDK's project-wide default
+ * for `table.access_group`. One field meant two things: "what BunnyQuery indexes
+ * new files at" and "what every SDK record call on this project defaults to".
+ * That coupling is gone. The SDK no longer has a project default at all, so this
+ * setting needs a home of its own, and a plain public record in the customer's
+ * own project is one every client can already reach with the calls it has.
+ *
+ * SHAPE. One record per project, holding an OBJECT rather than a single value:
+ *
+ *     unique_id: 'bq::settings'
+ *     table:     { name: '__SETTINGS__', access_group: 'public' }
+ *     data:      { upload_access_group: 'authorized' }
+ *
+ * One record and one fetch covers every present and future project setting. A
+ * second setting is a new key, not a new record, so the "wait for settings
+ * before the first upload" hand-off below never has to become several waits.
+ *
+ * WHY PUBLIC. The widget reads this, and the widget frequently runs before there
+ * is any session. Group 0 is the only group an unauthenticated caller is served
+ * (`check_rec_access` returns immediately for "00" and refuses the rest). Note
+ * this is NOT sufficient on its own: skapi's `require_login` gate refuses ALL
+ * database reads from a signed-out visitor, and it defaults to true, so on most
+ * projects a signed-out widget still cannot read this and falls back to the
+ * default. That is survivable because the only thing a signed-out visitor could
+ * do with the value is upload, which they cannot do either.
+ *
+ * WHY THE VALUE MATTERS. The file BYTES are not what the access group controls.
+ * BunnyQuery uploads to db storage, whose object key carries no access group and
+ * whose read path performs no access check. What carries the group is the
+ * RECORDS: the `src::` file record in `file_summaries`, the `run::`/`done::`
+ * markers in `__INDEXING__`, and every content record the indexing agent
+ * extracts. Those are what a chat answers from, so those are what decide who the
+ * file is visible to. The same value is also handed to the chat system prompt as
+ * `indexAccessGroup`, because a record written under a different group is in a
+ * different table and never comes back with the rest of the file.
+ *
+ * TRANSPORT-FREE, like the rest of the engine. The store never imports a skapi
+ * instance; the consumer injects a reader. See configureProjectSettings.
+ */
+
+/** The access groups a BunnyQuery upload may be recorded at. */
+export type UploadAccessGroup = 'public' | 'authorized' | 'private';
+
+export const UPLOAD_ACCESS_GROUPS: UploadAccessGroup[] = ['public', 'authorized', 'private'];
+
+/**
+ * What the project's upload-access setting may be: one of the three groups the
+ * dashboard offers, or 'ask' to be prompted per upload.
+ *
+ * `'admin'` (99) is deliberately not offered: a file only a master can read is
+ * indistinguishable from one that failed to upload, and no dashboard control
+ * would produce it.
+ */
+export type ProjectAccessSetting = UploadAccessGroup | 'ask';
+
+/**
+ * `authorized` is the default because it is what every record written before
+ * this setting existed was hardcoded to. A project that never opens the setting
+ * keeps exactly the visibility it already had. It is also what the abandoned
+ * `default_access_group` service field was seeded to at project creation, so a
+ * project carrying that old value reads the same before and after the move.
+ */
+export const DEFAULT_UPLOAD_ACCESS_GROUP: UploadAccessGroup = 'authorized';
+
+/** Where the settings record lives. Shared so no client re-derives it. */
+export const PROJECT_SETTINGS_TABLE = '__SETTINGS__';
+export const PROJECT_SETTINGS_UNIQUE_ID = 'bq::settings';
+export const PROJECT_SETTINGS_ACCESS_GROUP = 'public';
+
+export const UPLOAD_ACCESS_LABELS: Record<UploadAccessGroup, string> = {
+	public: 'Public',
+	authorized: 'Signed in users',
+	private: 'Only me',
+};
+
+export const UPLOAD_ACCESS_HINTS: Record<UploadAccessGroup, string> = {
+	public: 'Anyone can ask about this file, including visitors who are not logged in.',
+	authorized: 'Only users signed in to this project can ask about this file.',
+	private: 'Only you can ask about this file.',
+};
+
+/** Menu/modal option list, in the order they should be shown. */
+export const UPLOAD_ACCESS_OPTIONS = UPLOAD_ACCESS_GROUPS.map((value) => ({
+	value,
+	label: UPLOAD_ACCESS_LABELS[value],
+	hint: UPLOAD_ACCESS_HINTS[value],
+}));
+
+/** The settings record's `data`. Open-ended: future settings are new keys. */
+export type ProjectSettingsData = {
+	upload_access_group?: unknown;
+	[key: string]: unknown;
+};
+
+/** Narrow an unknown stored value to a usable group, falling back to the default. */
+export function normalizeUploadAccessGroup(value: any): UploadAccessGroup {
+	return UPLOAD_ACCESS_GROUPS.indexOf(value) === -1
+		? DEFAULT_UPLOAD_ACCESS_GROUP
+		: (value as UploadAccessGroup);
+}
+
+/**
+ * The stored setting as written, or null when the project has never set one.
+ *
+ * Returns null rather than a default so callers can tell "unset" from "set to
+ * authorized". The settings page needs that distinction to decide what the
+ * control shows; upload paths do not and use uploadAccessGroupFrom instead.
+ */
+export function normalizeProjectAccessSetting(value: any): ProjectAccessSetting | null {
+	if (value === 'ask') return 'ask';
+	return UPLOAD_ACCESS_GROUPS.indexOf(value) === -1 ? null : (value as ProjectAccessSetting);
+}
+
+/** The setting held in a settings-record `data`, or null when unset. */
+export function accessSettingFrom(
+	data: ProjectSettingsData | null | undefined,
+): ProjectAccessSetting | null {
+	return normalizeProjectAccessSetting(data?.upload_access_group);
+}
+
+/** The group an upload lands in when the project is NOT set to 'ask'. */
+export function uploadAccessGroupFrom(
+	data: ProjectSettingsData | null | undefined,
+): UploadAccessGroup {
+	const v = accessSettingFrom(data);
+	return v && v !== 'ask' ? v : DEFAULT_UPLOAD_ACCESS_GROUP;
+}
+
+/** True when the project wants to be asked per upload rather than told once. */
+export function asksUploadAccessFrom(data: ProjectSettingsData | null | undefined): boolean {
+	return accessSettingFrom(data) === 'ask';
+}
+
+/**
+ * Fetch one project's settings record. Resolves the record's `data`, or null
+ * when there is no record.
+ *
+ * MAY REJECT, and the store treats a rejection as "no record": a signed-out
+ * visitor on a `require_login` project gets REQUIRE_LOGIN here, which is a
+ * normal outcome and not an error the user should ever see.
+ */
+export type ProjectSettingsReader = (service: string) => Promise<ProjectSettingsData | null>;
+
+type Entry = {
+	/** Resolved data, or null for "fetched, and there is none". */
+	data: ProjectSettingsData | null;
+	/** True once a fetch has SETTLED, so `data` is authoritative rather than absent. */
+	settled: boolean;
+	/** The in-flight fetch, deduped so N callers share ONE request. */
+	inflight: Promise<ProjectSettingsData | null> | null;
+};
+
+let reader: ProjectSettingsReader | null = null;
+
+/**
+ * Keyed by service id, NEVER global.
+ *
+ * One client routinely serves MANY projects: the console switches projects
+ * without reloading, and an upload outlives the page that started it. A flat
+ * single-value cache lets one project's setting decide another project's upload
+ * group, which is a silent cross-project data-visibility bug, not a stale-read
+ * annoyance. Every accessor takes the service id for this reason.
+ */
+const cache = new Map<string, Entry>();
+
+export function configureProjectSettings(fn: ProjectSettingsReader | null): void {
+	reader = fn;
+}
+
+function entry(service: string): Entry {
+	let e = cache.get(service);
+	if (!e) {
+		e = { data: null, settled: false, inflight: null };
+		cache.set(service, e);
+	}
+	return e;
+}
+
+/**
+ * Start the fetch and hand back the promise, deduping concurrent callers.
+ *
+ * Never rejects: a failed read settles as null, which every accessor reads as
+ * "unset" and answers with the default. A settings fetch must not be able to
+ * fail an upload.
+ */
+export function loadProjectSettings(service: string): Promise<ProjectSettingsData | null> {
+	if (!service) return Promise.resolve(null);
+	const e = entry(service);
+	if (e.settled) return Promise.resolve(e.data);
+	if (e.inflight) return e.inflight;
+	if (!reader) return Promise.resolve(null);
+
+	const run: Promise<ProjectSettingsData | null> = reader(service)
+		.then((data) => (data && typeof data === 'object' ? data : null))
+		.catch(() => null)
+		.then((data) => {
+			// Guard against a clear() that landed while this was in flight: the
+			// entry may have been replaced, so write through the map rather than
+			// through the captured object.
+			const cur = entry(service);
+			if (cur.inflight === run) {
+				cur.data = data;
+				cur.settled = true;
+				cur.inflight = null;
+			}
+			return data;
+		});
+
+	e.inflight = run;
+	return run;
+}
+
+/**
+ * Kick the fetch off without waiting for it. Call on chat/page open.
+ *
+ * Fire-and-forget by design: the page paints on the default and the first upload
+ * awaits the real value via readyProjectSettings. Nothing blocks on this.
+ */
+export function primeProjectSettings(service: string): void {
+	void loadProjectSettings(service);
+}
+
+/**
+ * Await the settings for this project. What the FIRST upload calls.
+ *
+ * Cheap after the first call: a settled entry resolves immediately, and a
+ * primed-but-unsettled one joins the in-flight request rather than starting a
+ * second.
+ */
+export function readyProjectSettings(service: string): Promise<ProjectSettingsData | null> {
+	return loadProjectSettings(service);
+}
+
+/**
+ * The cached data WITHOUT waiting, or null when nothing has settled yet.
+ *
+ * For synchronous readers (a template, a menu's current value). A caller that is
+ * about to WRITE an access group onto a record must use readyProjectSettings
+ * instead: answering from an unsettled cache is how a file lands in the wrong
+ * group on the first upload after a page load.
+ */
+export function cachedProjectSettings(service: string): ProjectSettingsData | null {
+	const e = cache.get(service);
+	return e && e.settled ? e.data : null;
+}
+
+/** True once this project's settings have been fetched (whether or not one existed). */
+export function projectSettingsSettled(service: string): boolean {
+	const e = cache.get(service);
+	return !!e && e.settled;
+}
+
+/** Sync convenience: the project's setting as stored, or null when unset/unsettled. */
+export function projectAccessSetting(service: string): ProjectAccessSetting | null {
+	return accessSettingFrom(cachedProjectSettings(service));
+}
+
+/** Sync convenience: the upload group, falling back to the default. */
+export function projectUploadAccessGroup(service: string): UploadAccessGroup {
+	return uploadAccessGroupFrom(cachedProjectSettings(service));
+}
+
+/** Sync convenience: does this project want a per-upload prompt? */
+export function projectAsksUploadAccess(service: string): boolean {
+	return asksUploadAccessFrom(cachedProjectSettings(service));
+}
+
+/**
+ * Adopt a value the caller just WROTE, so the settings page reflects its own
+ * save without a re-fetch.
+ *
+ * Marks the entry settled: the writer knows the stored value better than a
+ * refetch would, and leaving it unsettled would send the next upload back to the
+ * network for a value already in hand.
+ */
+export function setProjectSettings(service: string, data: ProjectSettingsData | null): void {
+	if (!service) return;
+	cache.set(service, { data: data || null, settled: true, inflight: null });
+}
+
+/** Merge one key into the cached settings, preserving the rest. */
+export function patchProjectSettings(service: string, patch: ProjectSettingsData): void {
+	if (!service) return;
+	const cur = cachedProjectSettings(service) || {};
+	setProjectSettings(service, Object.assign({}, cur, patch));
+}
+
+/**
+ * Drop cached settings. Pass a service to drop one, omit to drop all.
+ *
+ * An in-flight fetch is abandoned rather than cancelled: its `.then` checks that
+ * the entry it is writing into is still its own, so a late response cannot
+ * repopulate a cleared project.
+ */
+export function clearProjectSettings(service?: string): void {
+	if (service) cache.delete(service);
+	else cache.clear();
+}