harper 5.1.20 → 5.2.0-alpha.5

package/dist/resources/Table.js

@@ -42,6 +42,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EVICTED = exports.INVALIDATED = void 0;
+exports.freezeRecord = freezeRecord;
 exports.makeTable = makeTable;
 exports.coerceType = coerceType;
 const hdbTerms_ts_1 = require("../utility/hdbTerms.js");
@@ -120,6 +121,18 @@ function isFrozenRecordObject(value) {
         !(value instanceof ArrayBuffer) &&
         Object.isFrozen(value));
 }
+// Freeze a decoded record value for cache integrity, guarding the bare-TypedArray-root case:
+// V8 throws "Cannot freeze array buffer views with elements" on Object.freeze of a non-empty
+// TypedArray/DataView (#1298). _writeUpdate now rejects such roots on write, but this read-side
+// guard still backstops records that bypass validation (source/cache population, replication of
+// legacy data) and lets an already-poisoned table be read again after upgrade. The freeze is
+// shallow anyway, so a typed-array root needs none. Only freeze plain objects: skip ArrayBuffer
+// views/ArrayBuffers, and short-circuit primitives/null/undefined to avoid a needless native
+// Object.freeze call on the hot read/scan path.
+function freezeRecord(value) {
+    if (value !== null && typeof value === 'object' && !ArrayBuffer.isView(value) && !(value instanceof ArrayBuffer))
+        Object.freeze(value);
+}
 exports.INVALIDATED = 1;
 exports.EVICTED = 8; // note that 2 is reserved for timestamps
 const TEST_WRITE_KEY_BUFFER = Buffer.allocUnsafeSlow(8192);
@@ -145,7 +158,7 @@ const FULL_PERMISSIONS = {
  */
 // #section: setup-and-factory
 function makeTable(options) {
-    const { primaryKey, indices, tableId, tableName, primaryStore, databasePath, databaseName, auditStore, schemaDefined, dbisDB: dbisDb, sealed, splitSegments, replicate, description, hidden, } = options;
+    const { primaryKey, indices, tableId, tableName, primaryStore, databasePath, databaseName, auditStore, schemaDefined, dbisDB: dbisDb, sealed, splitSegments, replicate, description, hidden, cacheControl, } = options;
     let { expirationMS: expirationMs, evictionMS: evictionMs, audit, trackDeletes } = options;
     evictionMs ??= 0;
     // Eviction without explicit expiration means expiration:0. Apply at construction so
@@ -249,6 +262,8 @@ function makeTable(options) {
         static description = description;
         static properties = properties;
         static hidden = hidden;
+        // default `Cache-Control` for anonymous REST reads (from `@table(cacheControl: "...")`), see REST.ts
+        static cacheControl = cacheControl;
         static outputSchemas;
         static mcp;
         static replicate = replicate;
@@ -669,8 +684,8 @@ function makeTable(options) {
                         // dictates not to go to source
                         if (!this.doesExist())
                             throw new hdbError_ts_1.ServerError('Entry is not cached', 504);
-                        if (hasSourceGet && target)
-                            target.loadedFromSource = false; // mark it as cached
+                        if (hasSourceGet)
+                            setLoadedFromSource(target, false); // mark it as cached
                     }
                     else if (resourceOptions?.ensureLoaded) {
                         const loadingFromSource = ensureLoadedFromSource(this.constructor.source, id, entry, request, this, target);
@@ -682,7 +697,7 @@ function makeTable(options) {
                             });
                         }
                         else if (hasSourceGet)
-                            target.loadedFromSource = false; // mark it as cached
+                            setLoadedFromSource(target, false); // mark it as cached
                     }
                     return this;
                 });
@@ -1139,7 +1154,13 @@ function makeTable(options) {
                 let allowed = true;
                 if (target?.checkPermission) {
                     // requesting authorization verification
-                    allowed = this.allowRead(context.user, target, context);
+                    try {
+                        allowed = this.allowRead(context.user, target, context);
+                    }
+                    catch {
+                        // allow* threw — fail closed rather than letting the request proceed
+                        throw new hdbError_ts_1.AccessViolation(context.user);
+                    }
                 }
                 return (0, when_ts_1.promiseNormalize)((0, when_ts_1.when)((0, when_ts_1.when)(allowed, (allowed) => {
                     if (!allowed) {
@@ -1153,6 +1174,8 @@ function makeTable(options) {
                             // dictates not to go to source
                             if (!entry?.value)
                                 throw new hdbError_ts_1.ServerError('Entry is not cached', 504);
+                            if (hasSourceGet)
+                                setLoadedFromSource(target, false); // mark it as cached
                         }
                         else if (ensureLoaded) {
                             const loadingFromSource = ensureLoadedFromSource(constructor.source, id, entry, context, this, target);
@@ -1160,6 +1183,8 @@ function makeTable(options) {
                                 txn?.disregardReadTxn(); // this could take some time, so don't keep the transaction open if possible
                                 return loadingFromSource.then((entry) => entry?.value);
                             }
+                            else if (hasSourceGet)
+                                setLoadedFromSource(target, false); // mark it as cached
                         }
                         return entry?.value;
                     });
@@ -1223,7 +1248,10 @@ function makeTable(options) {
                                         property = { name: property };
                                     if (!property.checkPermission && target.checkPermission)
                                         property.checkPermission = target.checkPermission;
-                                    if (!relatedTable.prototype.allowRead.call(null, user, property, context))
+                                    // Invoke the related table's allowRead on a properly-bound instance rather than
+                                    // `.call(null, ...)` so `this` is a valid resource of the related type.
+                                    const relatedResource = new relatedTable(undefined, context);
+                                    if (!relatedResource.allowRead(user, property, context))
                                         return false;
                                     if (!property.select)
                                         return property.name; // no select was applied, just return the name
@@ -1798,6 +1826,30 @@ function makeTable(options) {
                     if (fullUpdate || (recordUpdate && (0, tracked_ts_1.hasChanges)(this.#changes === recordUpdate ? this : recordUpdate))) {
                         if (!context?.source) {
                             transaction.checkOverloaded();
+                            // A record must be a plain object. Reject primitive, string/number, bare-binary,
+                            // and bare-array roots — e.g. a raw Buffer from an application/octet-stream PUT, a
+                            // JSON string/number body, or a top-level JSON array. Such roots carry no primary
+                            // key or attributes, are meaningless to SQL/get-attributes, and a bare TypedArray
+                            // root additionally throws on Object.freeze during scans (#1298). Binary data belongs
+                            // in a Bytes/Blob attribute. (Messages go through _writePublish, not here, so raw
+                            // publish payloads are unaffected.)
+                            const isBinaryRoot = ArrayBuffer.isView(recordUpdate) || recordUpdate instanceof ArrayBuffer;
+                            if (recordUpdate === null ||
+                                typeof recordUpdate !== 'object' ||
+                                isBinaryRoot ||
+                                Array.isArray(recordUpdate)) {
+                                // Avoid dumping every byte of a large binary body or huge payload into the error.
+                                let received;
+                                if (isBinaryRoot) {
+                                    received = `${recordUpdate.constructor?.name ?? 'binary'} of ${recordUpdate.byteLength} bytes`;
+                                }
+                                else {
+                                    const full = stringify(recordUpdate) ?? typeof recordUpdate;
+                                    received = full.length > 200 ? full.slice(0, 200) + '...' : full;
+                                }
+                                throw new hdbError_ts_1.ClientError(`A record must be an object, but received ${received}. To store binary data, put it ` +
+                                    `in a Bytes or Blob attribute (e.g. a record like { "${primaryKey ?? 'id'}": …, "data": <bytes> }).`);
+                            }
                             // Records are intentionally immutable: decoded records are frozen (and 5.2 record
                             // caching relies on it), so mutating in place would corrupt cached/shared state.
                             // validate() coerces values and we stamp created/updated times + the primary key
@@ -1853,6 +1905,16 @@ function makeTable(options) {
                 },
                 before: writeToSource(),
                 commit: (txnTime, existingEntry, retry, transaction) => {
+                    // Whether a prior attempt of THIS write appended its own audit entry (sticky, set in
+                    // save(); log entries are not part of the aborted rocks transaction, so they survive).
+                    // Only such a write can find its own orphaned entry in the dedup lookups below and must
+                    // not treat it as "already applied". Per-write on purpose: the transaction-wide retry
+                    // flag would also suppress dedup for a genuine re-delivered duplicate co-batched with
+                    // the conflicting write (double-applying it) and for fresh writes staged through a
+                    // reused transaction whose retries counter is stale. Sticky on purpose: a proxy read
+                    // from the last attempt's skipped state launders when a recommit round self-skips
+                    // (walk identity tie against its own staged record) before a fresh-transaction replay.
+                    const stagedOwnAuditEntry = retry && write.appendedAuditEntry === true;
                     write.skipped = false; // reset on each retry; cleanup happens after commit if still true
                     if (retry) {
                         if (context && existingEntry?.version > (context.lastModified || 0))
@@ -1964,8 +2026,12 @@ function makeTable(options) {
                             // local audit time, not version, so this version-keyed lookup doesn't apply there (LMDB keeps the
                             // exact unbounded walk). A miss (the keyed lookup can lag a back-to-back re-delivery — #1137)
                             // simply falls through to the walk, so this never changes correctness; the additionalAuditRefs
-                            // check above remains the read-your-writes guard.
-                            if (isRocksDB && dedupVersionCouldBeRetained(txnTime)) {
+                            // check above remains the read-your-writes guard. Never when this write staged in a prior
+                            // failed attempt: that attempt already appended this write's own audit entry, so the lookup
+                            // would find it and skip the write as "already applied" when the record was never committed.
+                            // A recommit of the same transaction survived that skip only because the old write batch
+                            // still carried the put; a fresh-transaction replay (ERR_TRY_AGAIN) would drop the write.
+                            if (isRocksDB && !stagedOwnAuditEntry && dedupVersionCouldBeRetained(txnTime)) {
                                 const priorAudit = auditStore.get(txnTime, tableId, id, options?.nodeId);
                                 if (priorAudit &&
                                     priorAudit.version === txnTime &&
@@ -2007,7 +2073,12 @@ function makeTable(options) {
                             // A re-delivered write whose exact (version, nodeId) is already in the audit log was already
                             // applied; drop it rather than re-applying it (double-applying commutative ops) or writing a
                             // duplicate audit-only record. Used by the early-out and the depth-cap block below.
+                            // Never a duplicate for a write that staged in a prior failed attempt: that attempt already
+                            // appended this write's own audit entry, so the lookup would match it while the record was
+                            // never committed (see the up-front keyed dedup above).
                             const isReDeliveredDuplicate = () => {
+                                if (stagedOwnAuditEntry)
+                                    return false;
                                 if (!dedupVersionCouldBeRetained(txnTime))
                                     return false; // pre-retention version — skip the end-of-log scan (best-effort; see above)
                                 const duplicate = auditStore.get(txnTime, tableId, id, options?.nodeId);
@@ -2390,7 +2461,14 @@ function makeTable(options) {
                 throw target.parseError; // if there was a parse error, we can throw it now
             if (target.checkPermission) {
                 // requesting authorization verification
-                const allowed = this.allowRead(context.user, target, context);
+                let allowed;
+                try {
+                    allowed = this.allowRead(context.user, target, context);
+                }
+                catch {
+                    // allow* threw — fail closed rather than letting the request proceed
+                    throw new hdbError_ts_1.AccessViolation(context.user);
+                }
                 if (!allowed) {
                     throw new hdbError_ts_1.AccessViolation(context.user);
                 }
@@ -2590,10 +2668,32 @@ function makeTable(options) {
             // transaction, and we really don't care if the
             // counts are done in the same read transaction because they are just estimates) until the search
             // results have been iterated and finished.
-            const readTxn = txn.useReadTxn();
-            const entries = (0, search_ts_1.executeConditions)(conditions, operator, TableResource, readTxn, target, context, (results, filters) => transformToEntries(results, select, context, readTxn, filters), filtered);
+            // When the query opts out of a snapshot (`snapshot: false`, e.g. long-running analytics
+            // scans), the read transaction reads against the latest committed data without pinning a
+            // consistent snapshot, so the scan doesn't hold a snapshot that blocks compaction.
+            const readTxn = txn.useReadTxn(target.snapshot === false);
+            // Record-level read guard (#1241): a resource may define a static allowReadRecord(user, record)
+            // that participates in query execution (pushed into HNSW traversal for vector sorts, applied as a
+            // post-filter otherwise). Resolve off the actual (possibly subclassed) constructor so overrides win.
+            // SCOPE: this is a QUERY-result filter, not a general read-authorization boundary — direct
+            // single-record get(id) does not consult it (use allowRead/instance hooks for that). It must be
+            // synchronous, side-effect free, and fast; it can run once per candidate record during traversal.
+            const allowReadRecord = this.constructor.allowReadRecord;
+            const recordAccess = typeof allowReadRecord === 'function' || typeof target.vectorFilter === 'function'
+                ? { allowReadRecord, user: context?.user, vectorFilter: target.vectorFilter }
+                : undefined;
+            const entries = (0, search_ts_1.executeConditions)(conditions, operator, TableResource, readTxn, target, context, (results, filters) => transformToEntries(results, select, context, readTxn, filters), filtered, recordAccess);
             const ensure_loaded = target.ensureLoaded !== false;
-            const transformToRecord = TableResource.transformEntryForSelect(select, context, readTxn, filtered, ensure_loaded, true);
+            // Authoritative RBAC enforcement (#1241): the guards inside executeConditions evaluate the LOCAL
+            // record, but on a caching table transformEntryForSelect may then revalidate an expired/invalidated
+            // row from source and return a DIFFERENT record. An authorization check must hold on the record
+            // actually returned, so allowReadRecord is re-checked there, after materialization (the earlier
+            // evaluation stays as a prune that also bounds HNSW traversal). vectorFilter and condition filters
+            // intentionally keep the local-record semantics all query filters have on caching tables.
+            const recordGuard = typeof allowReadRecord === 'function'
+                ? (record) => allowReadRecord(context?.user, record)
+                : undefined;
+            const transformToRecord = TableResource.transformEntryForSelect(select, context, readTxn, filtered, ensure_loaded, true, recordGuard);
             let results = TableResource.transformToOrderedSelect(entries, select, postOrdering, context, readTxn, transformToRecord);
             // apply any offset/limit after all the sorting and filtering
             if (target.offset || target.limit !== undefined)
@@ -2807,9 +2907,12 @@ function makeTable(options) {
          * @param filtered
          * @param ensure_loaded
          * @param canSkip
+         * @param recordGuard record-level read check (#1241) applied to the record actually being
+         * returned — i.e. AFTER any caching-source revalidation replaces a stale local copy — so an
+         * authorization verdict can't be made on bytes that differ from what the caller receives.
          * @returns
          */
-        static transformEntryForSelect(select, context, readTxn, filtered, ensure_loaded, canSkip) {
+        static transformEntryForSelect(select, context, readTxn, filtered, ensure_loaded, canSkip, recordGuard) {
             let checkLoaded;
             if (ensure_loaded &&
                 hasSourceGet &&
@@ -2828,6 +2931,7 @@ function makeTable(options) {
             }
             let transformCache;
             const source = this.source;
+            const resourceClass = this;
             // Transform an entry to a record. Note that *this* instance is intended to be the iterator.
             const transform = function (entry) {
                 let record;
@@ -2859,7 +2963,23 @@ function makeTable(options) {
                                 message: 'This entry has expired',
                             };
                         }
-                        const loadingFromSource = ensureLoadedFromSource(source, entry.key ?? entry, entry, context);
+                        // Stale-while-revalidate is an instance method, but a query has no per-row resource
+                        // instance to consult (the single-record `get` path passes `this`). Construct one for this
+                        // row — via the same `new constructor(id, context)` the framework's getResource uses — so
+                        // the hook sees the current row's identity (this.getId()) and record state, matching the
+                        // single-record path. It must be a real instance, not the bare class prototype: every
+                        // resource prototype chain ends in a tracked-property Proxy, so reading an absent property
+                        // (probing for an undefined `allowStaleWhileRevalidate`, or a hook touching `this.x`) on a
+                        // non-instance invokes getChanges() with no backing state and throws (harper#1578). We also
+                        // load the stale entry into it (as the single-record path does via _updateResource) so a
+                        // hook consulting this.getRecord()/this.<field> sees the stale row, not undefined. `entry`
+                        // here may be lazy (its `.value` is a GC-able deref, undefined once collected), so we set the
+                        // already-dereferenced `record` explicitly rather than relying on `entry.value`. This runs
+                        // only for the expired/invalidated rows already headed to source, so the cost is negligible.
+                        const swrResource = new resourceClass(entry.key ?? entry, context);
+                        resourceClass._updateResource(swrResource, entry);
+                        swrResource.setRecord(record);
+                        const loadingFromSource = ensureLoadedFromSource(source, entry.key ?? entry, entry, context, swrResource);
                         if (loadingFromSource?.then) {
                             return loadingFromSource.then(transform);
                         }
@@ -2867,6 +2987,11 @@ function makeTable(options) {
                 }
                 if (record == null)
                     return canSkip ? extended_iterable_1.SKIP : record;
+                // Record-level RBAC (#1241): enforced here because `record` is now the final, materialized
+                // record — a caching table's source revalidation (above) may have replaced the local copy the
+                // query filters evaluated. Fail closed on the record actually being returned.
+                if (recordGuard && !recordGuard(record))
+                    return canSkip ? extended_iterable_1.SKIP : undefined;
                 if (select && !(select[0] === '*' && select.length === 1)) {
                     let promises;
                     const selectAttribute = (attribute, callback) => {
@@ -3033,6 +3158,9 @@ function makeTable(options) {
             // snapshot:false, which catches any commits that land during yield points; dropping in the
             // listener avoids duplicate delivery.
             let dropDuringReplay = false;
+            // Coalescing guards for the reload re-snapshot (harper-pro#495), driven from the listener below.
+            let reloadResnapshotRunning = false;
+            let reloadResnapshotPending = false;
             const thisId = requestTargetToId(request) ?? null; // treat undefined and null as the root
             const subscription = (0, transactionBroadcast_ts_1.addSubscription)(TableResource, thisId, function (id, auditRecord, localTime, beginTxn) {
                 if (dropDuringReplay)
@@ -3045,9 +3173,17 @@ function makeTable(options) {
                         // TODO: Do we want to have a limit to how far out-of-order we are willing to send?
                         value = auditRecord.getValue?.(primaryStore, getFullRecord);
                     }
-                    else if (type !== 'end_txn' && type !== 'reload') {
-                        // 'reload' is a whole-table marker with a null id and no record (harper-pro#489); pass it
-                        // through verbatim so subscribers re-read the table, skipping the per-record lookup below.
+                    else if (type === 'reload') {
+                        // Whole-table marker with a null id and no record (harper-pro#489): a copyApply base copy
+                        // back-filled rows with no per-row audit events. For a user table, re-deliver the current
+                        // scope as 'put's so MQTT/SSE/WS subscribers recover the snapshotted records, and do NOT
+                        // forward the bare marker (harper-pro#495). System-DB subscribers (knownNodes etc.) instead
+                        // get the raw marker and run their own bespoke whole-table rescan.
+                        if (databaseName !== 'system')
+                            return scheduleReloadResnapshot();
+                        // system DB: fall through to forward the bare 'reload' event verbatim.
+                    }
+                    else if (type !== 'end_txn') {
                         // these are events that indicate that the primary record has changed. I believe we always want to simply
                         // send the latest value. Note that it is fine to synchronously access these records, they should have just
                         // been written, so are fresh in memory.
@@ -3327,6 +3463,89 @@ function makeTable(options) {
                 }
                 subscription.send(event);
             }
+            // #region reload re-snapshot (harper-pro#495)
+            // A copyApply base copy back-fills rows as snapshots with NO per-row audit entries, so the live
+            // listener above never fires for them and an already-connected subscriber would miss them until
+            // the next direct write. After the copy, a whole-table 'reload' marker is delivered here (id=null).
+            // For a user table we react by re-delivering the subscription's current scope as ordinary 'put'
+            // events — so EVERY consumer that funnels through subscribe() (MQTT, SSE, WS) recovers the records
+            // uniformly, with no per-protocol handling. System-DB reloads are NOT re-snapshotted: their
+            // subscribers (knownNodes peer-discovery, hdb_certificate CA install) run a bespoke whole-table
+            // rescan off the raw marker, which a per-row re-emit cannot express (it can't drop stale rows).
+            // Yields the latest committed value (snapshot:false) and skips tombstones, mirroring the
+            // omitCurrent initial-snapshot scan.
+            async function* currentScopeRecords() {
+                const isCollection = request.isCollection ?? thisId == null;
+                if (isCollection) {
+                    let sinceYield = 0;
+                    for (const { key: id, value, version, localTime, size } of primaryStore.getRange({
+                        start: thisId ?? false,
+                        end: thisId == null ? undefined : [thisId, ordered_binary_1.MAXIMUM_KEY],
+                        versions: true,
+                        snapshot: false, // no need for a snapshot, just want the latest data
+                    })) {
+                        if (++sinceYield >= REPLAY_YIELD_INTERVAL) {
+                            sinceYield = 0;
+                            await rest();
+                        }
+                        if (!value)
+                            continue; // skip tombstones
+                        yield { id, localTime, value, version, type: 'put', size };
+                    }
+                }
+                else {
+                    const entry = primaryStore.getEntry(thisId);
+                    if (entry?.value)
+                        yield { id: thisId, ...entry, type: 'put' };
+                }
+            }
+            // Drain the current scope into the subscription with the same back-pressure as the live path.
+            // Coalesced: a marker that arrives while a re-snapshot is running just re-arms it once more (so
+            // markers for several tables, or a marker landing mid-scan, are not lost), and we never run two
+            // scans concurrently. The first thing it does is `await rest()` (a setImmediate macrotask), so the
+            // scan never executes inside the synchronous broadcast listener — which on the same-thread
+            // aftercommit path holds an inter-thread lock that must not span event-loop turns.
+            async function runReloadResnapshot() {
+                reloadResnapshotRunning = true;
+                try {
+                    await rest(); // defer off the broadcast listener's stack before scanning
+                    while (reloadResnapshotPending) {
+                        reloadResnapshotPending = false;
+                        // Subscription.end() nulls `subscriptions`; bail the moment it closes — before, between,
+                        // or mid-scan — so we never scan + send into a dead queue. pending is already cleared, so
+                        // the finally re-arm won't re-loop.
+                        if (!subscription.subscriptions)
+                            return;
+                        for await (const record of currentScopeRecords()) {
+                            if (!subscription.subscriptions)
+                                return;
+                            send(record);
+                            if (subscription.queue?.length > EVENT_HIGH_WATER_MARK) {
+                                if ((await subscription.waitForDrain()) === false)
+                                    return;
+                            }
+                        }
+                    }
+                }
+                catch (error) {
+                    harper_logger_ts_1.default.error?.('Error in reload re-snapshot:', error);
+                }
+                finally {
+                    reloadResnapshotRunning = false;
+                    // A marker that landed after the last pending-check but before we cleared the flag would
+                    // otherwise be dropped — re-arm if so (unless the subscription has since closed).
+                    if (subscription.subscriptions && reloadResnapshotPending)
+                        scheduleReloadResnapshot();
+                }
+            }
+            function scheduleReloadResnapshot() {
+                if (!subscription.subscriptions)
+                    return;
+                reloadResnapshotPending = true;
+                if (!reloadResnapshotRunning)
+                    runReloadResnapshot();
+            }
+            // #endregion
             return subscription;
         }
         /**
@@ -3820,7 +4039,7 @@ function makeTable(options) {
                                             hasPromises = true;
                                         // for now, we shouldn't be getting promises until rocksdb
                                         if (TableResource.loadAsInstance === false)
-                                            Object.freeze(returnEntry ? value?.value : value);
+                                            freezeRecord(returnEntry ? value?.value : value);
                                         return value;
                                     });
                                     return relationship.filterMissing
@@ -3836,7 +4055,7 @@ function makeTable(options) {
                                 });
                                 // for now, we shouldn't be getting promises until rocksdb
                                 if (TableResource.loadAsInstance === false)
-                                    Object.freeze(returnEntry ? value?.value : value);
+                                    freezeRecord(returnEntry ? value?.value : value);
                                 return value;
                             };
                             attribute.set = (object, related) => {
@@ -4213,7 +4432,7 @@ function makeTable(options) {
             // we need to freeze entry records to ensure the integrity of the cache;
             // but we only do this when users have opted into loadAsInstance/freezeRecords to avoid back-compat
             // issues
-            Object.freeze(entry?.value);
+            freezeRecord(entry?.value);
             if (entry?.residencyId &&
                 entry.metadataFlags & exports.INVALIDATED &&
                 sourceLoad &&
@@ -4337,6 +4556,12 @@ function makeTable(options) {
             return table;
         }
     }
+    function setLoadedFromSource(target, loadedFromSource) {
+        // cache disposition is a per-get result, recorded on the RequestTarget of the get (#1576)
+        // target may be a primitive id on instance-API calls, which can't hold the flag
+        if (target && typeof target === 'object')
+            target.loadedFromSource = loadedFromSource;
+    }
     function ensureLoadedFromSource(source, id, entry, context, resource, target) {
         if (context?.onlyIfCached) {
             if (!entry?.value)
@@ -4575,8 +4800,7 @@ function makeTable(options) {
                 whenResolved(getFromSource(source, id, primaryStore.getEntry(id), context, target));
             else {
                 // served from cache after waiting for another request to resolve
-                if (target)
-                    target.loadedFromSource = false;
+                setLoadedFromSource(target, false);
                 whenResolved(entry);
             }
         };
@@ -4590,8 +4814,7 @@ function makeTable(options) {
             });
         }
         // lock acquired — this request will actually load from source
-        if (target)
-            target.loadedFromSource = true;
+        setLoadedFromSource(target, true);
         const existingRecord = existingEntry?.value;
         // it is important to remember that this is _NOT_ part of the current transaction; nothing is changing
         // with the canonical data, we are simply fulfilling our local copy of the canonical data, but still don't