@dereekb/openrouter 14.1.0 → 14.3.0

package/README.md

@@ -46,6 +46,79 @@ one run onto another's history.
 Short calls skip all of it: `callModelForPrompt(...)` runs inline and returns the result with no
 document.
 
+## Managing prompts
+
+There is deliberately no Angular UI for prompt authoring. Declaring the CRUD is what makes every prompt
+operation reachable over a consuming app's existing callModel surface — its CLI and the callModel MCP —
+instead of requiring a screen.
+
+| Operation | What it does |
+|---|---|
+| `openRouterPrompt.read` | The prompt plus **the version it actually serves**. |
+| `openRouterPrompt.query` | Page the collection, optionally filtered by lifecycle state. |
+| `openRouterPrompt.update` | Metadata, lifecycle state, and which version is active. |
+| `openRouterPromptVersion.create` | Publish a version. Allocates its number and locks the one it succeeds. |
+| `openRouterPromptVersion.update` | Edit the head version in place. Refuses a locked one. |
+
+A prompt has no `create`: it comes into existence server-side from a seed against an
+`OpenRouterPromptDefinition` the app already ships. Seeding is not CRUD either — exposing it would hand
+any admin a button that rewrites prompt pointers.
+
+**Prefer `read` over `model-get`.** Both models are registered model services, so either document is
+fetchable by key, but the prompt document holds only pointers (`av`, `lv`) and none of what the prompt
+says. Following them by hand means addressing the version subcollection at a zero-padded id, and still
+misses the definition fallback. `read` resolves, and reports `source: 'store' | 'definition'` so the
+precedence rule is observable rather than rederived:
+
+| Store state | Served | `source` |
+|---|---|---|
+| No prompt document | Code definition | `definition` |
+| Stored `activeVersion` **≥** the definition's declared version | Store | `store` |
+| Stored `activeVersion` **<** the definition's declared version | Code definition | `definition` |
+
+### Access
+
+Prompts are operational configuration, not secrets — nothing here is encrypted, and reads are
+**admin-only** rather than server-only. An admin who can edit a prompt has to be able to read back what
+they wrote, which is why neither model carries `@dbxModelServerOnly`: that tag is copied onto the
+generated CLI/MCP manifest, so a consuming app cannot override it, and the CLI would refuse the read
+locally before choosing a transport.
+
+A consuming app that wants these closed does so in the two places that actually refuse a read, and must
+do **both** — they mirror each other, and `dbx_model_server_only_validate_app` reports the drift when
+they disagree:
+
+1. omit the `orp` / `orpv` match blocks from `firestore.rules`, and
+2. set `serverOnly: true` on the model's `firebaseModelServiceFactory`.
+
+An app that leaves them open grants the read to system admins:
+
+```
+match /orp/{openRouterPrompt} {
+  allow read: if userClaimsIsSysAdmin();
+
+  match /orpv/{openRouterPromptVersion} {
+    allow read: if userClaimsIsSysAdmin();
+  }
+}
+
+// the model API addresses a version through the collection GROUP, which the nested match does not cover
+match /{path=**}/orpv/{openRouterPromptVersion} {
+  allow read: if userClaimsIsSysAdmin();
+}
+```
+
+`orrt` (`OpenRouterRunTask`) is readable by a system admin too — it is the execution record an operator
+reaches for when a run fails, and its `msg` field carrying the model's raw input and output is the
+reason to read it. It is granted `read` ALONE, on both transports: the sweep owns every write (claim,
+lease, state transition), so a client write would move a task out from under the sweep executing it.
+
+```
+match /orrt/{openRouterRunTask} {
+  allow read: if userClaimsIsSysAdmin();
+}
+```
+
 ## Files and PDFs
 
 There is no upload step. A run task stores the **GCS object path** (`fp`) and nothing else — never a

package/firebase/index.esm.js

@@ -1,5 +1,5 @@
 import { MS_IN_DAY } from '@dereekb/util';
-import { firestoreModelIdentity, snapshotConverterFunctions, optionalFirestoreArray, firestoreNumber, optionalFirestoreNumber, firestoreEnum, optionalFirestoreString, firestoreString, optionalFirestoreDate, firestoreDate, optionalFirestoreBoolean, optionalFirestorePassthroughJsonField, firestoreArray, AbstractFirestoreDocument, AbstractFirestoreDocumentWithParent, inferredTargetModelParamsType, callModelFirebaseFunctionMapFactory, where, whereDateIsOnOrBefore, orderBy, limit } from '@dereekb/firebase';
+import { firestoreModelIdentity, snapshotConverterFunctions, optionalFirestoreArray, firestoreNumber, optionalFirestoreNumber, firestoreEnum, optionalFirestoreString, firestoreString, optionalFirestoreDate, firestoreDate, optionalFirestoreBoolean, optionalFirestoreJsonStringField, firestoreArray, AbstractFirestoreDocument, AbstractFirestoreDocumentWithParent, inferredTargetModelParamsType, callModelFirebaseFunctionMapFactory, where, whereDateIsOnOrBefore, orderBy, limit } from '@dereekb/firebase';
 import { type } from 'arktype';
 import { clearable } from '@dereekb/model';
 
@@ -213,7 +213,7 @@ var openRouterPromptVersionConverter = snapshotConverterFunctions({
         m: optionalFirestoreArray({
             dontStoreIfEmpty: true
         }),
-        c: optionalFirestorePassthroughJsonField(),
+        c: optionalFirestoreJsonStringField(),
         nt: optionalFirestoreString(),
         by: optionalFirestoreString(),
         lk: optionalFirestoreBoolean()
@@ -390,15 +390,15 @@ var openRouterRunTaskConverter = snapshotConverterFunctions({
         fa: optionalFirestoreArray({
             dontStoreIfEmpty: true
         }),
-        co: optionalFirestorePassthroughJsonField(),
+        co: optionalFirestoreJsonStringField(),
         o: optionalFirestoreString(),
-        j: optionalFirestorePassthroughJsonField(),
+        j: optionalFirestoreJsonStringField(),
         gi: optionalFirestoreArray({
             filterUnique: true,
             dontStoreIfEmpty: true
         }),
-        u: optionalFirestorePassthroughJsonField(),
-        e: optionalFirestorePassthroughJsonField(),
+        u: optionalFirestoreJsonStringField(),
+        e: optionalFirestoreJsonStringField(),
         msg: optionalFirestoreArray({
             dontStoreIfEmpty: true
         }),
@@ -494,12 +494,16 @@ var updateOpenRouterPromptVersionParamsType = /* @__PURE__ */ inferredTargetMode
     'config?': clearable('object'),
     'notes?': clearable('string')
 }));
+var readOpenRouterPromptParamsType = /* @__PURE__ */ inferredTargetModelParamsType.merge(type({
+    'version?': 'number'
+}));
 var readOpenRouterRunTaskParamsType = /* @__PURE__ */ type({
     key: 'string >= 1'
 });
 var OPENROUTER_PROMPT_FUNCTION_TYPE_CONFIG_MAP = {};
 var OPENROUTER_PROMPT_MODEL_CRUD_FUNCTIONS_CONFIG = {
     openRouterPrompt: [
+        'read',
         'update',
         'query'
     ],
@@ -615,4 +619,4 @@ var OPENROUTER_PROMPT_MODEL_CRUD_FUNCTIONS_CONFIG = {
     ];
 }
 
-export { OPENROUTER_PROMPT_FUNCTION_TYPE_CONFIG_MAP, OPENROUTER_PROMPT_MODEL_CRUD_FUNCTIONS_CONFIG, OPENROUTER_PROMPT_VERSION_ID_DIGITS, OPENROUTER_RUN_TASK_CLAIMABLE_STATES, OPENROUTER_RUN_TASK_MAX_AGE, OPENROUTER_RUN_TASK_TERMINAL_STATES, OpenRouterPromptDocument, OpenRouterPromptModelFunctions, OpenRouterPromptState, OpenRouterPromptVersionDocument, OpenRouterRunTaskDocument, OpenRouterRunTaskState, createOpenRouterPromptVersionParamsType, isOpenRouterRunTaskStateTerminal, openRouterPromptCollectionReference, openRouterPromptConverter, openRouterPromptFirestoreCollection, openRouterPromptIdentity, openRouterPromptModelFunctionMap, openRouterPromptVersionCollectionReference, openRouterPromptVersionCollectionReferenceFactory, openRouterPromptVersionConverter, openRouterPromptVersionDocumentId, openRouterPromptVersionFirestoreCollectionFactory, openRouterPromptVersionFirestoreCollectionGroup, openRouterPromptVersionId, openRouterPromptVersionIdentity, openRouterPromptVersionMessageParamsType, openRouterPromptVersionNumberFromId, openRouterPromptsWithStateQuery, openRouterResolvedPromptForVersion, openRouterRunTaskCollectionReference, openRouterRunTaskConverter, openRouterRunTaskFirestoreCollection, openRouterRunTaskIdentity, openRouterRunTasksExpiredQuery, openRouterRunTasksReclaimableQuery, openRouterRunTasksRunnableQuery, readOpenRouterRunTaskParamsType, updateOpenRouterPromptParamsType, updateOpenRouterPromptVersionParamsType };
+export { OPENROUTER_PROMPT_FUNCTION_TYPE_CONFIG_MAP, OPENROUTER_PROMPT_MODEL_CRUD_FUNCTIONS_CONFIG, OPENROUTER_PROMPT_VERSION_ID_DIGITS, OPENROUTER_RUN_TASK_CLAIMABLE_STATES, OPENROUTER_RUN_TASK_MAX_AGE, OPENROUTER_RUN_TASK_TERMINAL_STATES, OpenRouterPromptDocument, OpenRouterPromptModelFunctions, OpenRouterPromptState, OpenRouterPromptVersionDocument, OpenRouterRunTaskDocument, OpenRouterRunTaskState, createOpenRouterPromptVersionParamsType, isOpenRouterRunTaskStateTerminal, openRouterPromptCollectionReference, openRouterPromptConverter, openRouterPromptFirestoreCollection, openRouterPromptIdentity, openRouterPromptModelFunctionMap, openRouterPromptVersionCollectionReference, openRouterPromptVersionCollectionReferenceFactory, openRouterPromptVersionConverter, openRouterPromptVersionDocumentId, openRouterPromptVersionFirestoreCollectionFactory, openRouterPromptVersionFirestoreCollectionGroup, openRouterPromptVersionId, openRouterPromptVersionIdentity, openRouterPromptVersionMessageParamsType, openRouterPromptVersionNumberFromId, openRouterPromptsWithStateQuery, openRouterResolvedPromptForVersion, openRouterRunTaskCollectionReference, openRouterRunTaskConverter, openRouterRunTaskFirestoreCollection, openRouterRunTaskIdentity, openRouterRunTasksExpiredQuery, openRouterRunTasksReclaimableQuery, openRouterRunTasksRunnableQuery, readOpenRouterPromptParamsType, readOpenRouterRunTaskParamsType, updateOpenRouterPromptParamsType, updateOpenRouterPromptVersionParamsType };

package/firebase/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@dereekb/openrouter/firebase",
-  "version": "14.1.0",
+  "version": "14.3.0",
+  "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "14.1.0",
-    "@dereekb/firebase": "14.1.0",
-    "@dereekb/model": "14.1.0",
-    "@dereekb/openrouter": "14.1.0",
-    "@dereekb/rxjs": "14.1.0",
-    "@dereekb/util": "14.1.0",
+    "@dereekb/date": "14.3.0",
+    "@dereekb/firebase": "14.3.0",
+    "@dereekb/model": "14.3.0",
+    "@dereekb/openrouter": "14.3.0",
+    "@dereekb/rxjs": "14.3.0",
+    "@dereekb/util": "14.3.0",
     "arktype": "^2.2.0"
   },
   "exports": {

package/firebase/src/lib/openrouter.api.d.ts

@@ -1,7 +1,7 @@
 import { type Type } from 'arktype';
 import { type FirebaseFunctionTypeConfigMap, type FirestoreModelKey, type InferredTargetModelParams, type ModelFirebaseCreateFunction, type ModelFirebaseCrudFunction, type ModelFirebaseCrudFunctionConfigMap, type ModelFirebaseFunctionMap, type ModelFirebaseQueryFunction, type OnCallCreateModelResult, type OnCallQueryModelRequestParams, type OnCallQueryModelResult } from '@dereekb/firebase';
 import { type Maybe } from '@dereekb/util';
-import { type OpenRouterPromptVersionNumber } from '@dereekb/openrouter';
+import { type OpenRouterPromptResolutionSource, type OpenRouterPromptVersionNumber, type OpenRouterResolvedPrompt } from '@dereekb/openrouter';
 import { type OpenRouterPrompt, type OpenRouterPromptState, type OpenRouterPromptTypes } from './openrouter.model';
 /**
  * Parameters for updating an {@link OpenRouterPrompt}'s metadata and lifecycle state.
@@ -160,6 +160,64 @@ export interface QueryOpenRouterPromptsParams extends OnCallQueryModelRequestPar
      */
     readonly state?: Maybe<OpenRouterPromptState>;
 }
+/**
+ * Parameters for reading an {@link OpenRouterPrompt} together with the version it serves.
+ *
+ * @dbxModelApiParams
+ */
+export interface ReadOpenRouterPromptParams extends InferredTargetModelParams {
+    /**
+     * The version to read. Omit to read the version an unpinned caller is served right now.
+     */
+    readonly version?: Maybe<OpenRouterPromptVersionNumber>;
+}
+export declare const readOpenRouterPromptParamsType: Type<ReadOpenRouterPromptParams>;
+/**
+ * Result of reading a prompt.
+ *
+ * Returns the RESOLVED version rather than a stored document, because the stored document is not
+ * necessarily what the app serves: a code {@link OpenRouterPromptDefinition} stands in when the store
+ * cannot serve, or is behind it. Reading the two documents by key would answer "what is stored", which
+ * is a different — and, when they disagree, misleading — question from "what will run".
+ */
+export interface ReadOpenRouterPromptResult {
+    /**
+     * The stored prompt document, or null when the prompt exists only as a code definition.
+     *
+     * Null here alongside a populated {@link resolved} is the never-seeded case, not an error.
+     */
+    readonly prompt: Maybe<OpenRouterPrompt>;
+    /**
+     * The version that will actually be served — instructions, seed messages, and model config.
+     *
+     * This is the read the version model could not previously give back: a version could be written and
+     * never read, so an author edited a prompt blind.
+     */
+    readonly resolved: OpenRouterResolvedPrompt;
+    /**
+     * Which half of the resolution won: the stored version, or the code definition standing in for it.
+     *
+     * The one field that makes the precedence rule observable. A caller who published version 3 and is
+     * still being served version 4 from code sees `definition` here rather than having to rederive why.
+     */
+    readonly source: OpenRouterPromptResolutionSource;
+    /**
+     * Config problems that do not stop the prompt from being served.
+     *
+     * Same warnings a create or update returns, reported here so a prompt that was published before a
+     * validation rule existed still surfaces them on read.
+     */
+    readonly warnings: string[];
+    /**
+     * Config problems that make {@link resolved} unusable.
+     *
+     * Separate from {@link warnings}, and non-empty only in cases a create would have refused. A read
+     * still returns rather than throwing on them: the resolver rejects an invalid config only when it is
+     * configured with `rejectInvalidConfig`, so such a version CAN be the live one — and showing the
+     * caller the config that is breaking their calls is the entire point of the read.
+     */
+    readonly errors: string[];
+}
 /**
  * Parameters for reading an {@link OpenRouterRunTask}.
  *
@@ -190,14 +248,21 @@ export declare const OPENROUTER_PROMPT_FUNCTION_TYPE_CONFIG_MAP: FirebaseFunctio
  * appears — rather than as a specifier on the parent's update. Its `update` edits the latest version
  * in place and refuses a locked one, so iterating on a prompt does not mint a version per keystroke.
  *
- * Neither model declares a `read`: both are registered model services, so a stored prompt or one of its
- * versions is already fetchable by key through model-get.
+ * The prompt declares a `read` on top of model-get, because model-get answers a different question: it
+ * returns the stored DOCUMENT, which holds only pointers (`av`, `lv`) and none of what the prompt says.
+ * Following it by hand means reading the version subcollection at a zero-padded id the caller has to
+ * construct, and still leaves the code-definition fallback invisible. The `read` returns what will
+ * actually be served, and says which half of the resolution produced it.
+ *
+ * The VERSION declares no `read`: it is a registered model service, so a specific stored version is
+ * already fetchable by key through model-get, and the prompt's `read` covers the "what is live" case.
  *
  * `OpenRouterRunTask` is absent on purpose. A run task is written and drained entirely server-side, and
  * its `msg` field carries raw model input and output.
  */
 export type OpenRouterPromptModelCrudFunctionsConfig = {
     readonly openRouterPrompt: {
+        read: [ReadOpenRouterPromptParams, ReadOpenRouterPromptResult];
         update: UpdateOpenRouterPromptParams;
         query: [QueryOpenRouterPromptsParams, OnCallQueryModelResult<OpenRouterPrompt>];
     };
@@ -212,6 +277,7 @@ export declare const OPENROUTER_PROMPT_MODEL_CRUD_FUNCTIONS_CONFIG: ModelFirebas
  */
 export declare abstract class OpenRouterPromptModelFunctions implements ModelFirebaseFunctionMap<OpenRouterPromptFunctionTypeMap, OpenRouterPromptModelCrudFunctionsConfig> {
     abstract openRouterPrompt: {
+        readOpenRouterPrompt: ModelFirebaseCrudFunction<ReadOpenRouterPromptParams, ReadOpenRouterPromptResult>;
         updateOpenRouterPrompt: ModelFirebaseCrudFunction<UpdateOpenRouterPromptParams>;
         queryOpenRouterPrompt: ModelFirebaseQueryFunction<QueryOpenRouterPromptsParams, OnCallQueryModelResult<OpenRouterPrompt>>;
     };

package/firebase/src/lib/openrouter.model.d.ts

@@ -49,10 +49,20 @@ export declare enum OpenRouterPromptState {
  * The prompt document holds only identity and version pointers; everything servable lives on an
  * {@link OpenRouterPromptVersion}.
  *
+ * NOT `@dbxModelServerOnly`, deliberately. The tag means "no client may read this on any path", which
+ * a downstream app cannot override: it is copied onto the generated CLI/MCP manifest, so the CLI
+ * refuses the read locally before it picks a transport. That is right for the models that carry it —
+ * system plumbing tagged `@dbxModelRead system` — but a prompt is `@dbxModelRead admin-only` operational
+ * configuration, and an admin reading the configuration they are allowed to edit is the normal case.
+ * Nothing here is encrypted; `serverOnly` is an access posture, not confidentiality at rest.
+ *
+ * Server-only-ness is a PER-APP property anyway, because it follows from that app's `firestore.rules`.
+ * An app that wants these closed still closes them, in the two places that actually refuse a read:
+ * omit the `orp` match block, and set `serverOnly: true` on its `firebaseModelServiceFactory`.
+ *
  * @dbxModel
- * @dbxModelRead admin
+ * @dbxModelRead admin-only
  * @dbxModelUpdate admin
- * @dbxModelServerOnly
  */
 export interface OpenRouterPrompt {
     /**
@@ -169,9 +179,13 @@ export interface OpenRouterPromptVersionMessage {
  * iterated on without minting a version per keystroke — which does mean a run against the head can be
  * replayed against text that has since moved. Lock it by creating the next version.
  *
+ * NOT `@dbxModelServerOnly`, for the reason given on {@link OpenRouterPrompt} — and more so here, since
+ * this is the model that holds what a prompt actually SAYS. Tagging it meant an author could write a
+ * version and never read back what they wrote.
+ *
  * @dbxModel
- * @dbxModelRead admin
- * @dbxModelServerOnly
+ * @dbxModelRead admin-only
+ * @dbxModelUpdate admin
  */
 export interface OpenRouterPromptVersion {
     /**
@@ -201,10 +215,15 @@ export interface OpenRouterPromptVersion {
     /**
      * Model configuration.
      *
-     * Stored as PASSTHROUGH JSON, deliberately not a strict converter. OpenRouter's parameter surface
-     * moves fast, and a strict converter would silently drop any field it did not know about — turning
-     * every OpenRouter release into a config-corrupting event. `OpenRouterModelConfig` types it in
-     * TypeScript for autocomplete and call-time validation instead: strict types in code, loose storage.
+     * Stored as a JSON STRING, deliberately not a strict converter. OpenRouter's parameter surface moves
+     * fast, and a strict converter would silently drop any field it did not know about — turning every
+     * OpenRouter release into a config-corrupting event. `OpenRouterModelConfig` types it in TypeScript
+     * for autocomplete and call-time validation instead: strict types in code, loose storage.
+     *
+     * A string rather than a native Firestore map because this config carries a json schema, and a map
+     * cannot hold every legal one: Firestore forbids an array inside an array, so an array-valued `enum`,
+     * `const`, `default`, or `examples` fails the write outright rather than degrading. Serializing costs
+     * queryability on the config's interior, which nothing wants, and buys back the whole json type system.
      *
      * @dbxModelVariable config
      */
@@ -415,7 +434,7 @@ export interface OpenRouterRunTaskUnsentToolResult {
  * run reuses this document instead of queueing a duplicate.
  *
  * @dbxModel
- * @dbxModelRead admin
+ * @dbxModelRead admin-only
  * @dbxModelUpdate admin
  */
 export interface OpenRouterRunTask {

package/firebase-server/index.esm.js

@@ -1,8 +1,16 @@
 import { firestoreModelId, firestoreModelKeyParentKey, getDocumentSnapshotDataTuples } from '@dereekb/firebase';
 import { runAsyncTasksForValues, mergeObjects, KeyValueTypleValueFilter, concatArraysUnique, MS_IN_MINUTE, arrayToMap, expiringCachedGetter, filterMaybeArrayValues, filterUniqueValues, mergeArrays, addMilliseconds, filterUndefinedValues, randomNumberFactory, performTasksInParallel } from '@dereekb/util';
 import { validateOpenRouterModelConfig, openRouterPromptRequest, callModelForOpenRouterRequest, openRouterMessagesWithoutFileAttachmentData, openRouterMessagesWithFreshFileAttachments, openRouterInputMessages, openRouterFunctionCallOutputItems } from '@dereekb/openrouter';
-import { updateOpenRouterPromptParamsType, createOpenRouterPromptVersionParamsType, updateOpenRouterPromptVersionParamsType, OpenRouterPromptState, openRouterPromptVersionId, openRouterResolvedPromptForVersion, OpenRouterRunTaskState, openRouterRunTasksRunnableQuery, openRouterRunTasksReclaimableQuery, OPENROUTER_RUN_TASK_MAX_AGE, openRouterRunTasksExpiredQuery, isOpenRouterRunTaskStateTerminal } from '@dereekb/openrouter/firebase';
+import { updateOpenRouterPromptParamsType, readOpenRouterPromptParamsType, createOpenRouterPromptVersionParamsType, updateOpenRouterPromptVersionParamsType, OpenRouterPromptState, openRouterPromptVersionId, openRouterResolvedPromptForVersion, OpenRouterRunTaskState, openRouterRunTasksRunnableQuery, openRouterRunTasksReclaimableQuery, OPENROUTER_RUN_TASK_MAX_AGE, openRouterRunTasksExpiredQuery, isOpenRouterRunTaskStateTerminal } from '@dereekb/openrouter/firebase';
 
+function _array_like_to_array$2(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_with_holes$1(arr) {
+    if (Array.isArray(arr)) return arr;
+}
 function asyncGeneratorStep$8(gen, resolve, reject, _next, _throw, key, arg) {
     try {
         var info = gen[key](arg);
@@ -43,6 +51,33 @@ function _define_property$3(obj, key, value) {
     } else obj[key] = value;
     return obj;
 }
+function _iterable_to_array_limit$1(arr, i) {
+    var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"];
+    if (_i == null) return;
+    var _arr = [];
+    var _n = true;
+    var _d = false;
+    var _s, _e;
+    try {
+        for(_i = _i.call(arr); !(_n = (_s = _i.next()).done); _n = true){
+            _arr.push(_s.value);
+            if (i && _arr.length === i) break;
+        }
+    } catch (err) {
+        _d = true;
+        _e = err;
+    } finally{
+        try {
+            if (!_n && _i["return"] != null) _i["return"]();
+        } finally{
+            if (_d) throw _e;
+        }
+    }
+    return _arr;
+}
+function _non_iterable_rest$1() {
+    throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
 function _object_spread$2(target) {
     for(var i = 1; i < arguments.length; i++){
         var source = arguments[i] != null ? arguments[i] : {};
@@ -58,6 +93,9 @@ function _object_spread$2(target) {
     }
     return target;
 }
+function _sliced_to_array$1(arr, i) {
+    return _array_with_holes$1(arr) || _iterable_to_array_limit$1(arr, i) || _unsupported_iterable_to_array$2(arr, i) || _non_iterable_rest$1();
+}
 function _ts_generator$8(thisArg, body) {
     var f, y, t, _ = {
         label: 0,
@@ -157,13 +195,24 @@ function _ts_generator$8(thisArg, body) {
         };
     }
 }
+function _unsupported_iterable_to_array$2(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array$2(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$2(o, minLen);
+}
 /**
  * Server actions for managing prompts.
  *
- * The writes exist instead of an Angular UI: they reach the model API, and the existing callModel MCP
- * surface makes them callable without building a screen for it. Reads are absent because the prompt and
- * version model services already make both fetchable by key through model-get, and listing is the
- * model API's standard query operation over {@link openRouterPromptsWithStateQuery}.
+ * These exist instead of an Angular UI: they reach the model API, and the existing callModel MCP
+ * surface makes them callable without building a screen for it.
+ *
+ * The one read is {@link readOpenRouterPrompt}, which answers "what does this prompt serve right now".
+ * Fetching either document by key is already covered by model-get, and listing by the model API's
+ * standard query over {@link openRouterPromptsWithStateQuery}, so the read earns its place only by
+ * resolving — following the version pointer and the code-definition fallback that model-get cannot.
  */ var OpenRouterPromptServerActions = function OpenRouterPromptServerActions() {
     _class_call_check$3(this, OpenRouterPromptServerActions);
 };
@@ -174,6 +223,7 @@ function _ts_generator$8(thisArg, body) {
  * @returns The server actions.
  */ function openRouterPromptServerActions(context) {
     return {
+        readOpenRouterPrompt: readOpenRouterPromptFactory(context),
         createOpenRouterPrompt: createOpenRouterPromptFactory(context),
         updateOpenRouterPrompt: updateOpenRouterPromptFactory(context),
         createOpenRouterPromptVersion: createOpenRouterPromptVersionFactory(context),
@@ -332,6 +382,71 @@ function _ts_generator$8(thisArg, body) {
         })();
     });
 }
+/**
+ * Reads a prompt together with the version it actually serves.
+ *
+ * Goes through the prompt SERVICE rather than reading the two documents directly, so the answer is the
+ * one a dispatch would get — code definition included. Reading the documents here would reimplement the
+ * precedence rule in a second place, where it could drift from the resolver it is meant to describe.
+ *
+ * @param context - The actions context.
+ * @returns The read action.
+ */ function readOpenRouterPromptFactory(context) {
+    var firebaseServerActionTransformFunctionFactory = context.firebaseServerActionTransformFunctionFactory, openRouterPromptService = context.openRouterPromptService;
+    return firebaseServerActionTransformFunctionFactory(readOpenRouterPromptParamsType, function(params) {
+        return _async_to_generator$8(function() {
+            var version;
+            return _ts_generator$8(this, function(_state) {
+                version = params.version;
+                return [
+                    2,
+                    function(document) {
+                        return _async_to_generator$8(function() {
+                            var promptKey, _ref, prompt, resolution, resolved, source, validation, result;
+                            return _ts_generator$8(this, function(_state) {
+                                switch(_state.label){
+                                    case 0:
+                                        promptKey = document.id;
+                                        return [
+                                            4,
+                                            Promise.all([
+                                                openRouterPromptService.loadPrompt(promptKey),
+                                                openRouterPromptService.readPrompt({
+                                                    promptKey: promptKey,
+                                                    version: version
+                                                })
+                                            ])
+                                        ];
+                                    case 1:
+                                        _ref = _sliced_to_array$1.apply(void 0, [
+                                            _state.sent(),
+                                            2
+                                        ]), prompt = _ref[0], resolution = _ref[1];
+                                        resolved = resolution.resolved, source = resolution.source;
+                                        validation = validateOpenRouterModelConfig(resolved.config);
+                                        result = {
+                                            prompt: prompt !== null && prompt !== void 0 ? prompt : null,
+                                            resolved: resolved,
+                                            source: source,
+                                            // Both severities are reported rather than thrown. A create refuses an invalid config, but the
+                                            // resolver only refuses one when configured to, so an unusable config can already be live —
+                                            // and showing it is what the read is for.
+                                            warnings: validation.warnings,
+                                            errors: validation.errors
+                                        };
+                                        return [
+                                            2,
+                                            result
+                                        ];
+                                }
+                            });
+                        })();
+                    }
+                ];
+            });
+        })();
+    });
+}
 /**
  * Creates a new version, allocating its number inside the transaction, locking the version it succeeds,
  * and optionally promoting it.
@@ -1994,7 +2109,7 @@ function _wrap_native_super(Class) {
     }
     function resolveVersion(promptKey, inputVersion) {
         return _async_to_generator$4(function() {
-            var definition, promptDocument, prompt, storedActiveVersion, resolved, _tmp, validation;
+            var definition, promptDocument, prompt, storedActiveVersion, resolved, source, _tmp, validation;
             return _ts_generator$4(this, function(_state) {
                 switch(_state.label){
                     case 0:
@@ -2011,6 +2126,10 @@ function _wrap_native_super(Class) {
                         // A pinned caller is still allowed to read a draft/archived prompt: that is how a version is tested
                         // before promotion, and how a historical run is replayed after retirement.
                         storedActiveVersion = (prompt === null || prompt === void 0 ? void 0 : prompt.s) === OpenRouterPromptState.ACTIVE ? prompt.av : undefined;
+                        // Tracked alongside `resolved` rather than inferred from it afterwards: a definition and a stored
+                        // version that agree are indistinguishable by value, and the branch that picked one is the only
+                        // place that actually knows.
+                        source = 'store';
                         if (!(inputVersion != null)) return [
                             3,
                             5
@@ -2039,6 +2158,7 @@ function _wrap_native_super(Class) {
                         resolved = _tmp;
                         if (resolved == null && (definition === null || definition === void 0 ? void 0 : definition.version) === inputVersion) {
                             resolved = definition;
+                            source = 'definition';
                         }
                         return [
                             3,
@@ -2051,6 +2171,7 @@ function _wrap_native_super(Class) {
                         ];
                         // Unpinned, and code is either standing in for the store or ahead of it.
                         resolved = definition;
+                        source = 'definition';
                         return [
                             3,
                             8
@@ -2089,7 +2210,10 @@ function _wrap_native_super(Class) {
                         }
                         return [
                             2,
-                            resolved
+                            {
+                                resolved: resolved,
+                                source: source
+                            }
                         ];
                 }
             });
@@ -2098,7 +2222,7 @@ function _wrap_native_super(Class) {
     function cacheKey(promptKey, version) {
         return "".concat(promptKey, ":").concat(version !== null && version !== void 0 ? version : '_');
     }
-    function resolvePrompt(params) {
+    function readPrompt(params) {
         return _async_to_generator$4(function() {
             var promptKey, version, key, getter, load, result, e;
             return _ts_generator$4(this, function(_state) {
@@ -2155,6 +2279,26 @@ function _wrap_native_super(Class) {
             });
         })();
     }
+    function resolvePrompt(params) {
+        return _async_to_generator$4(function() {
+            return _ts_generator$4(this, function(_state) {
+                switch(_state.label){
+                    case 0:
+                        return [
+                            4,
+                            readPrompt(params)
+                        ];
+                    case 1:
+                        // Projection of readPrompt rather than a second resolution path, so both share the one cache entry
+                        // and cannot disagree about what is being served.
+                        return [
+                            2,
+                            _state.sent().resolved
+                        ];
+                }
+            });
+        })();
+    }
     function clearCachedPrompt(promptKey) {
         var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
         try {
@@ -2186,6 +2330,7 @@ function _wrap_native_super(Class) {
         loadPromptDefinitions: loadPromptDefinitions,
         loadPrompt: loadPrompt,
         resolvePrompt: resolvePrompt,
+        readPrompt: readPrompt,
         clearCachedPrompt: clearCachedPrompt
     };
 }
@@ -4413,4 +4558,4 @@ var randomSweepId = randomNumberFactory({
     })();
 }
 
-export { AbstractAppOpenRouterModule, DEFAULT_OPENROUTER_EXPIRATION_SWEEP_MAX_RUN_TIME, DEFAULT_OPENROUTER_EXPIRATION_SWEEP_PAGE_SIZE, DEFAULT_OPENROUTER_INLINE_FILE_CONTENT_TYPE, DEFAULT_OPENROUTER_LEASE_DURATION, DEFAULT_OPENROUTER_MAX_ATTEMPTS, DEFAULT_OPENROUTER_MAX_INLINE_FILE_SIZE_BYTES, DEFAULT_OPENROUTER_SIGNED_URL_TTL, DEFAULT_OPENROUTER_SWEEP_MAX_PARALLEL_TASKS, DEFAULT_OPENROUTER_SWEEP_MAX_RUN_TIME, DEFAULT_OPENROUTER_SWEEP_PAGE_SIZE, OPENROUTER_BROADCAST_RUN_TASK_KEY_ATTRIBUTES, OPENROUTER_MAX_EXPIRED_RUN_TASK_DELETE_PAGE_SIZE, OPENROUTER_PERMANENT_ERROR_STATUSES, OPENROUTER_PROMPT_CACHE_DURATION, OPENROUTER_PROMPT_SERVICE_TOKEN, OPENROUTER_RUN_TASK_SERVICE_TOKEN, OPENROUTER_SEED_PROMPTS_MAX_PARALLEL_UPDATES, OpenRouterPromptResolutionError, OpenRouterPromptServerActions, OpenRouterPromptService, OpenRouterRunTaskService, appOpenRouterModuleMetadata, callModelForPrompt, conversationStateForOpenRouterRunTask, conversationStatusForOpenRouterRunTaskState, createOpenRouterPromptFactory, createOpenRouterPromptVersionFactory, firestoreOpenRouterStateAccessor, handleOpenRouterRunTaskResultFactory, hasUnresolvedOpenRouterPendingToolCalls, isOpenRouterRunTaskClaimable, isRetryableOpenRouterError, mergeOpenRouterRunUsage, openRouterConversationValueForFirestore, openRouterDeferredToolResolutionsForRunTask, openRouterErrorCode, openRouterErrorMessage, openRouterFileAttachmentModeForConfig, openRouterFileAttachmentResolver, openRouterPromptServerActions, openRouterPromptService, openRouterRunTaskExpirationSweep, openRouterRunTaskKeyFromBroadcastAttributes, openRouterRunTaskOutcome, openRouterRunTaskService, openRouterRunTaskStateForConversationStatus, openRouterRunTaskSweep, openRouterRunTaskUpdateForConversationState, reconcileOpenRouterRunTaskFromBroadcast, seedOpenRouterPromptsFactory, updateOpenRouterPromptFactory, updateOpenRouterPromptVersionFactory };
+export { AbstractAppOpenRouterModule, DEFAULT_OPENROUTER_EXPIRATION_SWEEP_MAX_RUN_TIME, DEFAULT_OPENROUTER_EXPIRATION_SWEEP_PAGE_SIZE, DEFAULT_OPENROUTER_INLINE_FILE_CONTENT_TYPE, DEFAULT_OPENROUTER_LEASE_DURATION, DEFAULT_OPENROUTER_MAX_ATTEMPTS, DEFAULT_OPENROUTER_MAX_INLINE_FILE_SIZE_BYTES, DEFAULT_OPENROUTER_SIGNED_URL_TTL, DEFAULT_OPENROUTER_SWEEP_MAX_PARALLEL_TASKS, DEFAULT_OPENROUTER_SWEEP_MAX_RUN_TIME, DEFAULT_OPENROUTER_SWEEP_PAGE_SIZE, OPENROUTER_BROADCAST_RUN_TASK_KEY_ATTRIBUTES, OPENROUTER_MAX_EXPIRED_RUN_TASK_DELETE_PAGE_SIZE, OPENROUTER_PERMANENT_ERROR_STATUSES, OPENROUTER_PROMPT_CACHE_DURATION, OPENROUTER_PROMPT_SERVICE_TOKEN, OPENROUTER_RUN_TASK_SERVICE_TOKEN, OPENROUTER_SEED_PROMPTS_MAX_PARALLEL_UPDATES, OpenRouterPromptResolutionError, OpenRouterPromptServerActions, OpenRouterPromptService, OpenRouterRunTaskService, appOpenRouterModuleMetadata, callModelForPrompt, conversationStateForOpenRouterRunTask, conversationStatusForOpenRouterRunTaskState, createOpenRouterPromptFactory, createOpenRouterPromptVersionFactory, firestoreOpenRouterStateAccessor, handleOpenRouterRunTaskResultFactory, hasUnresolvedOpenRouterPendingToolCalls, isOpenRouterRunTaskClaimable, isRetryableOpenRouterError, mergeOpenRouterRunUsage, openRouterConversationValueForFirestore, openRouterDeferredToolResolutionsForRunTask, openRouterErrorCode, openRouterErrorMessage, openRouterFileAttachmentModeForConfig, openRouterFileAttachmentResolver, openRouterPromptServerActions, openRouterPromptService, openRouterRunTaskExpirationSweep, openRouterRunTaskKeyFromBroadcastAttributes, openRouterRunTaskOutcome, openRouterRunTaskService, openRouterRunTaskStateForConversationStatus, openRouterRunTaskSweep, openRouterRunTaskUpdateForConversationState, readOpenRouterPromptFactory, reconcileOpenRouterRunTaskFromBroadcast, seedOpenRouterPromptsFactory, updateOpenRouterPromptFactory, updateOpenRouterPromptVersionFactory };

package/firebase-server/package.json

@@ -1,17 +1,18 @@
 {
   "name": "@dereekb/openrouter/firebase-server",
-  "version": "14.1.0",
+  "version": "14.3.0",
+  "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "14.1.0",
-    "@dereekb/date": "14.1.0",
-    "@dereekb/firebase": "14.1.0",
-    "@dereekb/firebase-server": "14.1.0",
-    "@dereekb/model": "14.1.0",
-    "@dereekb/nestjs": "14.1.0",
-    "@dereekb/openrouter": "14.1.0",
-    "@dereekb/rxjs": "14.1.0",
-    "@dereekb/util": "14.1.0",
+    "@dereekb/analytics": "14.3.0",
+    "@dereekb/date": "14.3.0",
+    "@dereekb/firebase": "14.3.0",
+    "@dereekb/firebase-server": "14.3.0",
+    "@dereekb/model": "14.3.0",
+    "@dereekb/nestjs": "14.3.0",
+    "@dereekb/openrouter": "14.3.0",
+    "@dereekb/rxjs": "14.3.0",
+    "@dereekb/util": "14.3.0",
     "@nestjs/common": "^12.0.1",
     "@nestjs/config": "^12.0.0",
     "@openrouter/sdk": "^1.2.26",

package/firebase-server/src/lib/openrouter.action.server.d.ts

@@ -2,7 +2,7 @@ import { type FirebaseServerActionsContext } from '@dereekb/firebase-server';
 import { type FirestoreContextReference } from '@dereekb/firebase';
 import { type Maybe } from '@dereekb/util';
 import { type OpenRouterPromptKey } from '@dereekb/openrouter';
-import { type CreateOpenRouterPromptVersionParams, type CreateOpenRouterPromptVersionResult, type OpenRouterPromptDocument, type OpenRouterPromptFirestoreCollections, type OpenRouterPromptVersionDocument, type UpdateOpenRouterPromptParams, type UpdateOpenRouterPromptVersionParams, type UpdateOpenRouterPromptVersionResult } from '@dereekb/openrouter/firebase';
+import { type CreateOpenRouterPromptVersionParams, type CreateOpenRouterPromptVersionResult, type OpenRouterPromptDocument, type OpenRouterPromptFirestoreCollections, type OpenRouterPromptVersionDocument, type ReadOpenRouterPromptParams, type ReadOpenRouterPromptResult, type UpdateOpenRouterPromptParams, type UpdateOpenRouterPromptVersionParams, type UpdateOpenRouterPromptVersionResult } from '@dereekb/openrouter/firebase';
 import { type OpenRouterPromptService } from './openrouter.prompt.service';
 /**
  * Context required by the OpenRouter prompt server actions.
@@ -91,12 +91,16 @@ export interface SeedOpenRouterPromptsResult {
 /**
  * Server actions for managing prompts.
  *
- * The writes exist instead of an Angular UI: they reach the model API, and the existing callModel MCP
- * surface makes them callable without building a screen for it. Reads are absent because the prompt and
- * version model services already make both fetchable by key through model-get, and listing is the
- * model API's standard query operation over {@link openRouterPromptsWithStateQuery}.
+ * These exist instead of an Angular UI: they reach the model API, and the existing callModel MCP
+ * surface makes them callable without building a screen for it.
+ *
+ * The one read is {@link readOpenRouterPrompt}, which answers "what does this prompt serve right now".
+ * Fetching either document by key is already covered by model-get, and listing by the model API's
+ * standard query over {@link openRouterPromptsWithStateQuery}, so the read earns its place only by
+ * resolving — following the version pointer and the code-definition fallback that model-get cannot.
  */
 export declare abstract class OpenRouterPromptServerActions {
+    abstract readOpenRouterPrompt(params: ReadOpenRouterPromptParams): Promise<(document: OpenRouterPromptDocument) => Promise<ReadOpenRouterPromptResult>>;
     abstract createOpenRouterPrompt(params: CreateOpenRouterPromptParams): Promise<OpenRouterPromptDocument>;
     abstract updateOpenRouterPrompt(params: UpdateOpenRouterPromptParams): Promise<(document: OpenRouterPromptDocument) => Promise<OpenRouterPromptDocument>>;
     abstract createOpenRouterPromptVersion(params: CreateOpenRouterPromptVersionParams): Promise<(document: OpenRouterPromptDocument) => Promise<CreateOpenRouterPromptVersionResult>>;
@@ -131,6 +135,17 @@ export declare function createOpenRouterPromptFactory(context: OpenRouterPromptS
  * @returns The update action.
  */
 export declare function updateOpenRouterPromptFactory(context: OpenRouterPromptServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<UpdateOpenRouterPromptParams, (document: OpenRouterPromptDocument) => Promise<OpenRouterPromptDocument>, object, unknown>;
+/**
+ * Reads a prompt together with the version it actually serves.
+ *
+ * Goes through the prompt SERVICE rather than reading the two documents directly, so the answer is the
+ * one a dispatch would get — code definition included. Reading the documents here would reimplement the
+ * precedence rule in a second place, where it could drift from the resolver it is meant to describe.
+ *
+ * @param context - The actions context.
+ * @returns The read action.
+ */
+export declare function readOpenRouterPromptFactory(context: OpenRouterPromptServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<ReadOpenRouterPromptParams, (document: OpenRouterPromptDocument) => Promise<ReadOpenRouterPromptResult>, object, unknown>;
 /**
  * Creates a new version, allocating its number inside the transaction, locking the version it succeeds,
  * and optionally promoting it.

package/firebase-server/src/lib/openrouter.prompt.service.d.ts

@@ -1,5 +1,5 @@
 import { type Maybe, type Milliseconds } from '@dereekb/util';
-import { type OpenRouterPromptDefinition, type OpenRouterPromptKey, type OpenRouterPromptVersionNumber, type OpenRouterResolvedPrompt } from '@dereekb/openrouter';
+import { type OpenRouterPromptDefinition, type OpenRouterPromptKey, type OpenRouterPromptResolutionSource, type OpenRouterPromptVersionNumber, type OpenRouterResolvedPrompt } from '@dereekb/openrouter';
 import { type OpenRouterPrompt, type OpenRouterPromptFirestoreCollections } from '@dereekb/openrouter/firebase';
 /**
  * Error thrown when a prompt cannot be resolved.
@@ -22,6 +22,19 @@ export interface OpenRouterResolvePromptParams {
      */
     readonly version?: Maybe<OpenRouterPromptVersionNumber>;
 }
+/**
+ * A resolved prompt together with where it came from.
+ */
+export interface OpenRouterPromptResolution {
+    /**
+     * The version that will be served.
+     */
+    readonly resolved: OpenRouterResolvedPrompt;
+    /**
+     * Which half of the resolution produced {@link resolved}.
+     */
+    readonly source: OpenRouterPromptResolutionSource;
+}
 /**
  * Default time a resolved prompt is cached for.
  *
@@ -65,6 +78,17 @@ export declare abstract class OpenRouterPromptService {
      * @throws {OpenRouterPromptResolutionError} when the prompt, or the requested version, is not servable.
      */
     abstract resolvePrompt(params: OpenRouterResolvePromptParams): Promise<OpenRouterResolvedPrompt>;
+    /**
+     * Resolves a prompt and reports which half of the resolution served it.
+     *
+     * The same work {@link resolvePrompt} does, off the same cache — that one projects this result down
+     * to its `resolved` half. Separate rather than widening `resolvePrompt`'s return type because every
+     * dispatch path calls it on the hot path and wants the prompt, not a wrapper around it; the source is
+     * only interesting to a caller inspecting the prompt rather than running it.
+     *
+     * @throws {OpenRouterPromptResolutionError} when the prompt, or the requested version, is not servable.
+     */
+    abstract readPrompt(params: OpenRouterResolvePromptParams): Promise<OpenRouterPromptResolution>;
     /**
      * Drops any cached resolution for a prompt. Called after a publish/promote so the change is visible
      * immediately rather than after the cache expires.

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@dereekb/openrouter",
-  "version": "14.1.0",
+  "version": "14.3.0",
+  "sideEffects": false,
   "type": "module",
   "exports": {
     "./firebase": {
@@ -21,7 +22,7 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/util": "14.1.0",
+    "@dereekb/util": "14.3.0",
     "@openrouter/sdk": "^1.2.26"
   },
   "module": "./index.esm.js",

package/src/lib/openrouter.prompt.d.ts

@@ -47,6 +47,17 @@ export interface OpenRouterResolvedPrompt {
      */
     readonly config: OpenRouterModelConfig;
 }
+/**
+ * Which half of a prompt resolution served it: the stored version, or the code definition standing in
+ * for it.
+ *
+ * `definition` is not an error state — it is the normal answer for an environment that has never been
+ * seeded, and for one whose {@link OpenRouterPromptDefinition} has moved ahead of the store.
+ *
+ * Lives here rather than beside the resolver in `@dereekb/openrouter/firebase-server` because the read
+ * API returns it, and that API is declared client-side.
+ */
+export type OpenRouterPromptResolutionSource = 'store' | 'definition';
 /**
  * A prompt defined in CODE rather than published to Firestore.
  *