@_linked/server 2.25.0 → 3.1.0

package/lib/esm/utils/queryPlane.d.ts

@@ -1,3 +1,4 @@
+import type { ShapeCatalog } from '@_linked/core/utils/ShapeCatalog';
 import { type QueryOperation } from '@_linked/server-utils/utils/QueryAccess';
 /**
  * Whether DSL-JSON carries a query-context reference (`{"@ctx": name}`) in any
@@ -7,9 +8,34 @@ import { type QueryOperation } from '@_linked/server-utils/utils/QueryAccess';
  */
 export declare function containsContextRef(json: unknown): boolean;
 /**
- * A rehydrated query builder from the DSL-JSON a client sent. The result is
- * what the store runs, so the access check and the store see the same query.
- * A body that is not a query answers 400.
+ * Supplies the shape catalog a generic query request is decoded in, from the
+ * DSL-JSON the client sent (the request context is available through the
+ * host's own means, e.g. `getCallContext`). `undefined` means the global
+ * shape registry.
+ */
+export type QueryCatalogResolver = (query: unknown) => ShapeCatalog | undefined | Promise<ShapeCatalog | undefined>;
+/**
+ * Set (or, with `undefined`, clear) the host's catalog resolver for the
+ * generic query endpoints. Without one, every query decodes in the global
+ * shape registry.
+ */
+export declare function setQueryCatalogResolver(resolver: QueryCatalogResolver | undefined): void;
+/**
+ * The catalog `query` is decoded in: the host resolver's answer, or
+ * `undefined` (the global registry) without a resolver. A live builder already
+ * carries its catalog, so the resolver is not asked for it.
+ *
+ * A `ServerCallError` the resolver throws is passed on as is (the host chose
+ * the status); any other failure is logged and answers 500.
+ */
+export declare function resolveQueryCatalog(query: unknown): Promise<ShapeCatalog | undefined>;
+/**
+ * A rehydrated query builder from the DSL-JSON a client sent, decoded in
+ * `catalog` (`undefined`: the global registry, whatever catalog is active;
+ * see `resolveQueryCatalog`). The builder keeps that catalog, so
+ * the access-check lowering and the store's lowering both resolve against it.
+ * The result is what the store runs, so the access check and the store see
+ * the same query. A body that is not a query answers 400.
  *
  * A query-context reference (`{"@ctx": "user"}`) also answers 400. Core
  * resolves one at lowering time against a process-wide context map, which on a
@@ -19,11 +45,11 @@ export declare function containsContextRef(json: unknown): boolean;
  * names its nodes by id.
  *
  * Without context references, lowering a rehydrated builder is a pure function
- * of the builder (closed and never mutated after `fromJSON`) and the shape
- * registry: the IR `authorizeGenericQuery` checks is the IR the store lowers
+ * of the builder (closed and never mutated after `fromJSON`) and its shape
+ * catalog: the IR `authorizeGenericQuery` checks is the IR the store lowers
  * from the same builder.
  */
-export declare function toQueryBuilder(query: any): any;
+export declare function toQueryBuilder(query: unknown, catalog?: ShapeCatalog): any;
 /** The lowered IR of a query, or `undefined` when it cannot be lowered (refused). */
 export declare function lowerForAccessCheck(builder: any): unknown;
 /**

package/lib/esm/utils/queryPlane.js

@@ -10,6 +10,10 @@
  * module turns the incoming query into the builder the store runs and the IR
  * the rules read.
  *
+ * The host can supply the shape catalog a request's query is decoded in
+ * (`setQueryCatalogResolver`), so one server can resolve the same shape IRI
+ * differently per request (for example per project branch).
+ *
  * INTERIM: that per-store access model needs to be revised and rethought from
  * the ground up (see QueryAccess).
  */
@@ -47,10 +51,51 @@ export function containsContextRef(json) {
     }
     return false;
 }
+let queryCatalogResolver;
+/**
+ * Set (or, with `undefined`, clear) the host's catalog resolver for the
+ * generic query endpoints. Without one, every query decodes in the global
+ * shape registry.
+ */
+export function setQueryCatalogResolver(resolver) {
+    queryCatalogResolver = resolver;
+}
+/** A live builder passed by backend code (never a plain object from JSON). */
+function isLiveBuilder(query) {
+    return (!!query &&
+        typeof query === 'object' &&
+        Object.getPrototypeOf(query) !== Object.prototype &&
+        typeof query.__queryKind === 'string');
+}
+/**
+ * The catalog `query` is decoded in: the host resolver's answer, or
+ * `undefined` (the global registry) without a resolver. A live builder already
+ * carries its catalog, so the resolver is not asked for it.
+ *
+ * A `ServerCallError` the resolver throws is passed on as is (the host chose
+ * the status); any other failure is logged and answers 500.
+ */
+export async function resolveQueryCatalog(query) {
+    const resolver = queryCatalogResolver;
+    if (!resolver || isLiveBuilder(query))
+        return undefined;
+    try {
+        return await resolver(query);
+    }
+    catch (error) {
+        if (ServerCallError.is(error))
+            throw error;
+        console.error('[queryPlane] the shape catalog resolver failed:', error);
+        throw new ServerCallError(500, 'Shape catalog unavailable');
+    }
+}
 /**
- * A rehydrated query builder from the DSL-JSON a client sent. The result is
- * what the store runs, so the access check and the store see the same query.
- * A body that is not a query answers 400.
+ * A rehydrated query builder from the DSL-JSON a client sent, decoded in
+ * `catalog` (`undefined`: the global registry, whatever catalog is active;
+ * see `resolveQueryCatalog`). The builder keeps that catalog, so
+ * the access-check lowering and the store's lowering both resolve against it.
+ * The result is what the store runs, so the access check and the store see
+ * the same query. A body that is not a query answers 400.
  *
  * A query-context reference (`{"@ctx": "user"}`) also answers 400. Core
  * resolves one at lowering time against a process-wide context map, which on a
@@ -60,23 +105,18 @@ export function containsContextRef(json) {
  * names its nodes by id.
  *
  * Without context references, lowering a rehydrated builder is a pure function
- * of the builder (closed and never mutated after `fromJSON`) and the shape
- * registry: the IR `authorizeGenericQuery` checks is the IR the store lowers
+ * of the builder (closed and never mutated after `fromJSON`) and its shape
+ * catalog: the IR `authorizeGenericQuery` checks is the IR the store lowers
  * from the same builder.
  */
-export function toQueryBuilder(query) {
-    // A live builder passed by backend code (never a plain object from JSON).
-    if (query &&
-        typeof query === 'object' &&
-        Object.getPrototypeOf(query) !== Object.prototype &&
-        typeof query.__queryKind === 'string') {
+export function toQueryBuilder(query, catalog) {
+    if (isLiveBuilder(query))
         return query;
-    }
     if (containsContextRef(query)) {
         throw new ServerCallError(400, 'Query context references (@ctx) are not accepted by the generic query endpoints');
     }
     try {
-        const builder = fromJSON(query);
+        const builder = fromJSON(query, { catalog });
         if (!builder || typeof builder !== 'object')
             throw new Error('not a query');
         return builder;

package/lib/esm/utils/queryPlane.js.map

@@ -1 +1 @@
-{"version":3,"file":"queryPlane.js","sourceRoot":"","sources":["../../../src/utils/queryPlane.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Authorization for the generic query plane: the endpoints that run a query the\n * client built (`LincdServerBackendProvider.*Query` behind\n * `/call/@_linked/server/*Query`, and `LincdAPI` `post_*` behind `/api/*`).\n *\n * The rules are declared per store in the app's storage config\n * (`linked.backend.storage.js`) with `withAccess` from\n * `@_linked/server-utils/utils/QueryAccess`; see `checkQueryAccess` there for\n * how a query is mapped to stores and the order the checks apply in. This\n * module turns the incoming query into the builder the store runs and the IR\n * the rules read.\n *\n * INTERIM: that per-store access model needs to be revised and rethought from\n * the ground up (see QueryAccess).\n */\nimport { fromJSON } from '@_linked/core';\nimport { lower } from '@_linked/core/queries/lower';\nimport {\n  checkQueryAccess,\n  type QueryOperation,\n} from '@_linked/server-utils/utils/QueryAccess';\nimport { ServerCallError } from '@_linked/server-utils/utils/ServerCallError';\nimport { getRawQueriesMode } from './rawQueries.js';\nimport { getRpcExposureMode } from './rpcExposure.js';\n\n/** The DSL-JSON tag of a query-context reference (`CONTEXT_REF_KEY` in core). */\nconst CONTEXT_REF_KEY = '@ctx';\n\n/**\n * Whether DSL-JSON carries a query-context reference (`{\"@ctx\": name}`) in any\n * position: a select or count subject, an update target, a delete id, a\n * where-clause operand or a mutation field value. Every DSL-JSON decoder in\n * core reads a context reference from this one key.\n */\nexport function containsContextRef(json: unknown): boolean {\n  const seen = new Set<object>();\n  const stack: unknown[] = [json];\n  while (stack.length) {\n    const value = stack.pop();\n    if (!value || typeof value !== 'object' || seen.has(value)) continue;\n    seen.add(value);\n    if (Array.isArray(value)) {\n      for (const item of value) stack.push(item);\n      continue;\n    }\n    if (Object.prototype.hasOwnProperty.call(value, CONTEXT_REF_KEY)) return true;\n    for (const key of Object.keys(value)) stack.push((value as any)[key]);\n  }\n  return false;\n}\n\n/**\n * A rehydrated query builder from the DSL-JSON a client sent. The result is\n * what the store runs, so the access check and the store see the same query.\n * A body that is not a query answers 400.\n *\n * A query-context reference (`{\"@ctx\": \"user\"}`) also answers 400. Core\n * resolves one at lowering time against a process-wide context map, which on a\n * server holds whatever some code last set there, not the caller's identity,\n * and lowering runs twice (once for the access check, once in the store), so\n * the two could even resolve it differently. A query built from client JSON\n * names its nodes by id.\n *\n * Without context references, lowering a rehydrated builder is a pure function\n * of the builder (closed and never mutated after `fromJSON`) and the shape\n * registry: the IR `authorizeGenericQuery` checks is the IR the store lowers\n * from the same builder.\n */\nexport function toQueryBuilder(query: any): any {\n  // A live builder passed by backend code (never a plain object from JSON).\n  if (\n    query &&\n    typeof query === 'object' &&\n    Object.getPrototypeOf(query) !== Object.prototype &&\n    typeof query.__queryKind === 'string'\n  ) {\n    return query;\n  }\n  if (containsContextRef(query)) {\n    throw new ServerCallError(\n      400,\n      'Query context references (@ctx) are not accepted by the generic query endpoints'\n    );\n  }\n  try {\n    const builder = fromJSON(query);\n    if (!builder || typeof builder !== 'object') throw new Error('not a query');\n    return builder;\n  } catch {\n    throw new ServerCallError(400, 'Invalid query');\n  }\n}\n\n/** The lowered IR of a query, or `undefined` when it cannot be lowered (refused). */\nexport function lowerForAccessCheck(builder: any): unknown {\n  try {\n    return lower(builder);\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Check `builder` (rehydrated from `query` with `toQueryBuilder`) against the\n * store access rules. Throws a `ServerCallError` (400/401/403) when the current\n * call may not run it; the caller then hands the same builder to the store.\n *\n * Deliberately returns nothing: a query builder is a thenable, so resolving an\n * async function with one would run it.\n */\nexport async function authorizeGenericQuery(\n  operation: QueryOperation,\n  query: unknown,\n  builder: any,\n  endpoint: string\n): Promise<void> {\n  await checkQueryAccess({\n    operation,\n    query,\n    ir: lowerForAccessCheck(builder),\n    mode: getRpcExposureMode(),\n    endpoint,\n  });\n}\n\n/** Check a raw SPARQL query against the `rawQueries` setting (see utils/rawQueries). */\nexport async function authorizeRawQuery(query: unknown, endpoint: string): Promise<void> {\n  if (typeof query !== 'string') {\n    throw new ServerCallError(400, 'Invalid query');\n  }\n  await checkQueryAccess({\n    operation: 'select',\n    query,\n    ir: undefined,\n    raw: true,\n    rawQueries: getRawQueriesMode(),\n    mode: getRpcExposureMode(),\n    endpoint,\n  });\n}\n"]}
+{"version":3,"file":"queryPlane.js","sourceRoot":"","sources":["../../../src/utils/queryPlane.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAEpD,OAAO,EACL,gBAAgB,GAEjB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD,iFAAiF;AACjF,MAAM,eAAe,GAAG,MAAM,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAa;IAC9C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,KAAK,GAAc,CAAC,IAAI,CAAC,CAAC;IAChC,OAAO,KAAK,CAAC,MAAM,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;QAC1B,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,SAAS;QACrE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChB,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,KAAK,MAAM,IAAI,IAAI,KAAK;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3C,SAAS;QACX,CAAC;QACD,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,eAAe,CAAC;YAAE,OAAO,IAAI,CAAC;QAC9E,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,KAAK,CAAC,IAAI,CAAE,KAAa,CAAC,GAAG,CAAC,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAYD,IAAI,oBAAsD,CAAC;AAE3D;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAA0C;IAChF,oBAAoB,GAAG,QAAQ,CAAC;AAClC,CAAC;AAED,8EAA8E;AAC9E,SAAS,aAAa,CAAC,KAAU;IAC/B,OAAO,CACL,CAAC,CAAC,KAAK;QACP,OAAO,KAAK,KAAK,QAAQ;QACzB,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,SAAS;QACjD,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ,CACtC,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,KAAc;IACtD,MAAM,QAAQ,GAAG,oBAAoB,CAAC;IACtC,IAAI,CAAC,QAAQ,IAAI,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACxD,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,eAAe,CAAC,EAAE,CAAC,KAAK,CAAC;YAAE,MAAM,KAAK,CAAC;QAC3C,OAAO,CAAC,KAAK,CAAC,iDAAiD,EAAE,KAAK,CAAC,CAAC;QACxE,MAAM,IAAI,eAAe,CAAC,GAAG,EAAE,2BAA2B,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc,EAAE,OAAsB;IACnE,IAAI,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,eAAe,CACvB,GAAG,EACH,iFAAiF,CAClF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAY,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC;QAC5E,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,WAAM,CAAC;QACP,MAAM,IAAI,eAAe,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;IAClD,CAAC;AACH,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,mBAAmB,CAAC,OAAY;IAC9C,IAAI,CAAC;QACH,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;IAAC,WAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,SAAyB,EACzB,KAAc,EACd,OAAY,EACZ,QAAgB;IAEhB,MAAM,gBAAgB,CAAC;QACrB,SAAS;QACT,KAAK;QACL,EAAE,EAAE,mBAAmB,CAAC,OAAO,CAAC;QAChC,IAAI,EAAE,kBAAkB,EAAE;QAC1B,QAAQ;KACT,CAAC,CAAC;AACL,CAAC;AAED,wFAAwF;AACxF,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,KAAc,EAAE,QAAgB;IACtE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,eAAe,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,gBAAgB,CAAC;QACrB,SAAS,EAAE,QAAQ;QACnB,KAAK;QACL,EAAE,EAAE,SAAS;QACb,GAAG,EAAE,IAAI;QACT,UAAU,EAAE,iBAAiB,EAAE;QAC/B,IAAI,EAAE,kBAAkB,EAAE;QAC1B,QAAQ;KACT,CAAC,CAAC;AACL,CAAC","sourcesContent":["/**\n * Authorization for the generic query plane: the endpoints that run a query the\n * client built (`LincdServerBackendProvider.*Query` behind\n * `/call/@_linked/server/*Query`, and `LincdAPI` `post_*` behind `/api/*`).\n *\n * The rules are declared per store in the app's storage config\n * (`linked.backend.storage.js`) with `withAccess` from\n * `@_linked/server-utils/utils/QueryAccess`; see `checkQueryAccess` there for\n * how a query is mapped to stores and the order the checks apply in. This\n * module turns the incoming query into the builder the store runs and the IR\n * the rules read.\n *\n * The host can supply the shape catalog a request's query is decoded in\n * (`setQueryCatalogResolver`), so one server can resolve the same shape IRI\n * differently per request (for example per project branch).\n *\n * INTERIM: that per-store access model needs to be revised and rethought from\n * the ground up (see QueryAccess).\n */\nimport { fromJSON } from '@_linked/core';\nimport { lower } from '@_linked/core/queries/lower';\nimport type { ShapeCatalog } from '@_linked/core/utils/ShapeCatalog';\nimport {\n  checkQueryAccess,\n  type QueryOperation,\n} from '@_linked/server-utils/utils/QueryAccess';\nimport { ServerCallError } from '@_linked/server-utils/utils/ServerCallError';\nimport { getRawQueriesMode } from './rawQueries.js';\nimport { getRpcExposureMode } from './rpcExposure.js';\n\n/** The DSL-JSON tag of a query-context reference (`CONTEXT_REF_KEY` in core). */\nconst CONTEXT_REF_KEY = '@ctx';\n\n/**\n * Whether DSL-JSON carries a query-context reference (`{\"@ctx\": name}`) in any\n * position: a select or count subject, an update target, a delete id, a\n * where-clause operand or a mutation field value. Every DSL-JSON decoder in\n * core reads a context reference from this one key.\n */\nexport function containsContextRef(json: unknown): boolean {\n  const seen = new Set<object>();\n  const stack: unknown[] = [json];\n  while (stack.length) {\n    const value = stack.pop();\n    if (!value || typeof value !== 'object' || seen.has(value)) continue;\n    seen.add(value);\n    if (Array.isArray(value)) {\n      for (const item of value) stack.push(item);\n      continue;\n    }\n    if (Object.prototype.hasOwnProperty.call(value, CONTEXT_REF_KEY)) return true;\n    for (const key of Object.keys(value)) stack.push((value as any)[key]);\n  }\n  return false;\n}\n\n/**\n * Supplies the shape catalog a generic query request is decoded in, from the\n * DSL-JSON the client sent (the request context is available through the\n * host's own means, e.g. `getCallContext`). `undefined` means the global\n * shape registry.\n */\nexport type QueryCatalogResolver = (\n  query: unknown\n) => ShapeCatalog | undefined | Promise<ShapeCatalog | undefined>;\n\nlet queryCatalogResolver: QueryCatalogResolver | undefined;\n\n/**\n * Set (or, with `undefined`, clear) the host's catalog resolver for the\n * generic query endpoints. Without one, every query decodes in the global\n * shape registry.\n */\nexport function setQueryCatalogResolver(resolver: QueryCatalogResolver | undefined): void {\n  queryCatalogResolver = resolver;\n}\n\n/** A live builder passed by backend code (never a plain object from JSON). */\nfunction isLiveBuilder(query: any): boolean {\n  return (\n    !!query &&\n    typeof query === 'object' &&\n    Object.getPrototypeOf(query) !== Object.prototype &&\n    typeof query.__queryKind === 'string'\n  );\n}\n\n/**\n * The catalog `query` is decoded in: the host resolver's answer, or\n * `undefined` (the global registry) without a resolver. A live builder already\n * carries its catalog, so the resolver is not asked for it.\n *\n * A `ServerCallError` the resolver throws is passed on as is (the host chose\n * the status); any other failure is logged and answers 500.\n */\nexport async function resolveQueryCatalog(query: unknown): Promise<ShapeCatalog | undefined> {\n  const resolver = queryCatalogResolver;\n  if (!resolver || isLiveBuilder(query)) return undefined;\n  try {\n    return await resolver(query);\n  } catch (error) {\n    if (ServerCallError.is(error)) throw error;\n    console.error('[queryPlane] the shape catalog resolver failed:', error);\n    throw new ServerCallError(500, 'Shape catalog unavailable');\n  }\n}\n\n/**\n * A rehydrated query builder from the DSL-JSON a client sent, decoded in\n * `catalog` (`undefined`: the global registry, whatever catalog is active;\n * see `resolveQueryCatalog`). The builder keeps that catalog, so\n * the access-check lowering and the store's lowering both resolve against it.\n * The result is what the store runs, so the access check and the store see\n * the same query. A body that is not a query answers 400.\n *\n * A query-context reference (`{\"@ctx\": \"user\"}`) also answers 400. Core\n * resolves one at lowering time against a process-wide context map, which on a\n * server holds whatever some code last set there, not the caller's identity,\n * and lowering runs twice (once for the access check, once in the store), so\n * the two could even resolve it differently. A query built from client JSON\n * names its nodes by id.\n *\n * Without context references, lowering a rehydrated builder is a pure function\n * of the builder (closed and never mutated after `fromJSON`) and its shape\n * catalog: the IR `authorizeGenericQuery` checks is the IR the store lowers\n * from the same builder.\n */\nexport function toQueryBuilder(query: unknown, catalog?: ShapeCatalog): any {\n  if (isLiveBuilder(query)) return query;\n  if (containsContextRef(query)) {\n    throw new ServerCallError(\n      400,\n      'Query context references (@ctx) are not accepted by the generic query endpoints'\n    );\n  }\n  try {\n    const builder = fromJSON(query as any, { catalog });\n    if (!builder || typeof builder !== 'object') throw new Error('not a query');\n    return builder;\n  } catch {\n    throw new ServerCallError(400, 'Invalid query');\n  }\n}\n\n/** The lowered IR of a query, or `undefined` when it cannot be lowered (refused). */\nexport function lowerForAccessCheck(builder: any): unknown {\n  try {\n    return lower(builder);\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Check `builder` (rehydrated from `query` with `toQueryBuilder`) against the\n * store access rules. Throws a `ServerCallError` (400/401/403) when the current\n * call may not run it; the caller then hands the same builder to the store.\n *\n * Deliberately returns nothing: a query builder is a thenable, so resolving an\n * async function with one would run it.\n */\nexport async function authorizeGenericQuery(\n  operation: QueryOperation,\n  query: unknown,\n  builder: any,\n  endpoint: string\n): Promise<void> {\n  await checkQueryAccess({\n    operation,\n    query,\n    ir: lowerForAccessCheck(builder),\n    mode: getRpcExposureMode(),\n    endpoint,\n  });\n}\n\n/** Check a raw SPARQL query against the `rawQueries` setting (see utils/rawQueries). */\nexport async function authorizeRawQuery(query: unknown, endpoint: string): Promise<void> {\n  if (typeof query !== 'string') {\n    throw new ServerCallError(400, 'Invalid query');\n  }\n  await checkQueryAccess({\n    operation: 'select',\n    query,\n    ir: undefined,\n    raw: true,\n    rawQueries: getRawQueriesMode(),\n    mode: getRpcExposureMode(),\n    endpoint,\n  });\n}\n"]}

package/package.json

@@ -10,7 +10,7 @@
     "type": "git",
     "url": "git+https://github.com/linked-fw/server.git"
   },
-  "version": "2.25.0",
+  "version": "3.1.0",
   "packageManager": "npm@12.2.0",
   "linkedPackage": true,
   "type": "module",
@@ -39,7 +39,7 @@
   ],
   "dependencies": {
     "@_linked/cli": "^1.45.5",
-    "@_linked/core": "^2.28.0",
+    "@_linked/core": "^2.35.0",
     "@_linked/server-utils": "^1.12.0",
     "autoprefixer": "^10.4.18",
     "compression": "^1.7.4",

package/readme.md

@@ -20,8 +20,10 @@ If you want to further adjust the functionality of LincdServer yourself, either
   - [Gotchas](#gotchas)
   - [Error semantics](#error-semantics)
 - [Query stores](#query-stores)
-  - [BackendAPIStore](#backendapistore)
-  - [GatewayStore](#gatewaystore)
+  - [Without `url`](#without-url)
+  - [With `url`](#with-url)
+  - [`ping`](#ping)
+  - [Shape catalog per request](#shape-catalog-per-request)
 - [API-only servers (`server.apiOnly`)](#api-only-servers-serverapionly)
 - [Provider lifecycle and HMR](#provider-lifecycle-and-hmr)
   - [When a provider throws, and refusing to start](#when-a-provider-throws-and-refusing-to-start)
@@ -233,73 +235,113 @@ What the caller sees depends on how it calls:
 - **`Server.call` on the backend.** Here it calls the `LinkedServer` directly.
   - A provider method that throws always rejects.
   - An unmatched call resolves `undefined` by default and rejects with a 501 `ServerCallError` when `rejectOnError` is set.
-- **`BackendAPIStore`.** It always uses `rejectOnError`, so a failed query rejects with the status and message. A successful call resolves with whatever the provider returned, `undefined` included.
+- **`RemoteDataset` without `url`.** It always uses `rejectOnError`, so a failed query rejects with the status and message. A successful call resolves with whatever the provider returned, `undefined` included.
 
 ## Query stores
 
-Two `IDataset` implementations in this package forward Linked Queries over HTTP instead of
-answering them. Both ship `query.toJSON()` and resolve with the plain JSON rows the other side
-returns; neither offers raw SPARQL (`rawQuery`), dataset administration or a change feed.
+`RemoteDataset` is an `IDataset` whose Linked Queries are answered by a linked server instead of
+by the store itself. It ships `query.toJSON()` and resolves with the plain JSON the server
+returns; it offers no raw SPARQL (`rawQuery`), dataset administration or change feed.
 
-| | `BackendAPIStore` | `GatewayStore` |
+Export path `@_linked/server/shapes/quadstores/RemoteDataset` (named export `RemoteDataset`, so
+`loadStores` resolves it by the last path segment). One class, two forms:
+
+| | no `url` | with `url` |
 | --- | --- | --- |
-| Runs in | the browser (or any client of this package's `/call` routes) | a backend process |
-| Sends to | this app's own backend, through `Server.call` (`/call/<package>/<method>`) | a gateway of another service: `POST {endpoint}/query` |
-| Authenticated by | the user's session | a bearer credential the gateway issued to this process |
-| Who picks the dataset | the backend's `LinkedStorage` | the gateway, from the credential |
+| Answered by | this app's own backend | a remote data server, e.g. a host's gateway |
+| Sends through | `Server.call`'s package form (`/call/@_linked/server/<method>`); on a backend, `Server`'s local shortcut | `globalThis.fetch` to `{url}/call/@_linked/server/<method>`, never `Server` |
+| Authenticated by | the user's session | `Authorization: Bearer <token>` |
+| `init()` | resolves at once | posts `ping`, throws a typed error when the server cannot be used |
+| Typical config | `linked.frontend.datasets.json` | `linked.backend.datasets.json` |
+
+```typescript
+export interface RemoteDatasetConfig {
+  url?: string;   // data server base, e.g. http://localhost:4040/gateway; routes are appended
+  token?: string; // sent as Authorization: Bearer <token> when set and url is set
+  name?: string;  // id = ${DATA_ROOT}/backend-api-store/<name>; does not affect routing
+  id?: string;
+}
+```
 
-### BackendAPIStore
+`new RemoteDataset('main')` is the `name` form.
 
-Export path `@_linked/server/shapes/quadstores/BackendAPIStore`. Selected in
-`linked.frontend.datasets.json`; `config` may carry a `name` or `id`, neither of which affects
-routing. Its error semantics are under [Error semantics](#error-semantics).
+### Without `url`
 
-### GatewayStore
+Every query is `Server.call(packageName, { method, rejectOnError: true }, query.toJSON())`, and
+this package's generic provider answers it from the backend's `LinkedStorage`. Its error
+semantics are under [Error semantics](#error-semantics). `token` is ignored.
 
-Export path `@_linked/server/shapes/quadstores/GatewayStore` (named export `GatewayStore`, so
-`loadStores` resolves it by the last path segment). It is for a backend whose data lives behind
-a gateway run by the host that started it — for example an app process started by Create Now,
-whose queries go to CN's gateway so that branch forks, authorization and audit apply to app
-traffic.
+### With `url`
 
 ```json
 {
   "datasets": {
-    "gateway": {
-      "store": "@_linked/server/shapes/quadstores/GatewayStore",
-      "config": { "endpoint": "${CN_EG_GATEWAY:-}", "credential": "${CN_APP_SERVICE_SECRET:-}" }
+    "appData": {
+      "store": "@_linked/server/shapes/quadstores/RemoteDataset",
+      "config": { "url": "${DATA_SERVER_URL:-}", "token": "${DATA_SERVER_TOKEN:-}" }
     }
   }
 }
 ```
 
+- Each method posts `{"args": [<query.toJSON()>]}` to `{url}/call/@_linked/server/<method>`
+  (`selectQuery`, which also carries counts, `askQuery`, `updateQuery`, `createQuery`,
+  `deleteQuery`) with `Content-Type` and `Accept` set to `application/json` and, when `token` is
+  non-empty, `Authorization: Bearer <token>`. It resolves the parsed body; `null` is a valid
+  result. No other headers are sent and nothing is retried, so a write is never applied twice.
+- Trailing slashes are trimmed from `url`. A `url` that is present but empty (an unset
+  `${DATA_SERVER_URL:-}`) never falls back to the no-url form: `init()` and every method throw
+  `RemoteDatasetUnreachableError` with `url: ''`.
+- `init()` posts `{"args": []}` to `{url}/call/@_linked/server/ping`. A success is memoized; after
+  a failure the next `init()` asks again. `LinkedStorage.setDefaultDataset` does not await
+  `init()`, so a boot that must fail loudly awaits it itself before registering the store.
+- Errors, each carrying `url` (the base), `status` (0 when no HTTP answer came back) and `code`
+  (the error body's `code`, when the server sent one). Messages name the url and the method,
+  never the token.
+
+  | Answer | Error |
+  | --- | --- |
+  | no HTTP answer | `RemoteDatasetUnreachableError` (status 0) |
+  | 401 or 403 | `RemoteDatasetUnauthorizedError` |
+  | on `ping` only: 404, 501, 502, 503, 504, or a body that is not JSON | `RemoteDatasetUnreachableError` |
+  | any other non-2xx | `RemoteDatasetError` |
+
+  `RemoteDatasetUnreachableError` and `RemoteDatasetUnauthorizedError` extend
+  `RemoteDatasetError`, which extends `Error`; match them with `instanceof`.
+
+### `ping`
+
+`POST /call/@_linked/server/ping` (a `public` method of this package's generic provider) reads
+nothing, changes nothing and answers `{ "ok": true }`. A plain linked server has no token
+concept; a host that serves the wire with tokens checks the token itself and answers 401 for a
+refused one.
+
+### Shape catalog per request
+
+The generic query endpoints (`/call/@_linked/server/*Query` and `/api/*`) rebuild the client's
+DSL-JSON with core's `fromJSON`. By default it decodes against the global shape registry. A
+host that serves several shape sets at once (for example one per project branch) supplies a
+`ShapeCatalog` (from `@_linked/core`) per request:
+
 ```typescript
-export interface GatewayStoreConfig {
-  endpoint: string;   // base URL of the gateway, routes are appended: `${endpoint}/query`, `${endpoint}/health`
-  credential: string; // sent as `Authorization: Bearer <credential>`
-  fetch?: typeof fetch; // transport override, default `globalThis.fetch`
-}
+import { setQueryCatalogResolver } from '@_linked/server/utils/queryPlane';
+
+// query: the DSL-JSON the client sent. Read the request itself through getCallContext().
+setQueryCatalogResolver(async (query) => catalogForThisRequest(query));
 ```
 
-- The constructor throws at once when `endpoint` or `credential` is empty. The `:-` defaults in
-  the JSON keep `parseDatasetsConfig` from throwing when the variables are unset; a storage file
-  instantiates the alias only when the host set them (the presence of `CN_EG_GATEWAY` is the
-  mode switch; `CN_APP_SERVICE_SECRET` is injected into the process environment, never written
-  to `.env`).
-- `init()` is `GET {endpoint}/health` and resolves with the gateway's answer
-  (`{projectId, branchName, dataset}`). It throws `GatewayUnreachableError` when the gateway
-  cannot be reached or refuses the credential. `LinkedStorage.setDefaultDataset` does not await
-  `init()`, so a boot that must fail loudly awaits `init()` itself before registering the store.
-  Calling it again is harmless.
-- Every query method posts `{ "v": 1, "op": "select" | "ask" | "update" | "create" | "delete", "query": <query.toJSON()> }`
-  and resolves with the body's `result`. A count arrives through `selectQuery` with `op: "select"`
-  (the gateway dispatches on the query's own `op`). Nothing about the project, branch or actor is
-  in the body: the credential decides all three.
-- Errors: a network failure and a `401` reject with `GatewayUnreachableError` (`status` 0 or 401);
-  any other non-2xx answer rejects with `GatewayStoreError`, whose `code` is the body's `code`
-  (`bad-request`, `wire-version`, `unknown-shape`, `refused`, `fork-failed`, `query-failed`),
-  else `http-<status>`, with the parsed body on `body`. `GatewayUnreachableError extends
-  GatewayStoreError`.
+- The resolver is called once per request, before the query is decoded. `undefined` means the
+  global registry. With no resolver set, behaviour is unchanged.
+- The builder keeps the catalog it was decoded in, so the access check (`withAccess` rules) and
+  the store lower the query against the same shapes. A shape the catalog does not hold answers
+  `400 Invalid query`.
+- A resolver that throws a `ServerCallError` answers with its status and message. Any other
+  throw is logged and answers `500 {"error": "Shape catalog unavailable"}`.
+- A live builder passed in by backend code already carries its catalog; the resolver is not
+  called for it.
+- `setQueryCatalogResolver(undefined)` removes the resolver. `resolveQueryCatalog(query)` and
+  `toQueryBuilder(query, catalog)` are exported for hosts that serve the same wire on their own
+  routes.
 
 ## API-only servers (`server.apiOnly`)
 

package/lib/esm/shapes/quadstores/BackendAPIStore.d.ts

@@ -1,58 +0,0 @@
-import type { IDataset } from '@_linked/core/interfaces/IDataset';
-import type { SelectQuery } from '@_linked/core/queries/SelectQuery';
-import type { AskQuery } from '@_linked/core/queries/AskQuery';
-import type { UpdateQuery } from '@_linked/core/queries/UpdateQuery';
-import type { CreateQuery } from '@_linked/core/queries/CreateQuery';
-import type { DeleteQuery, DeleteResponse } from '@_linked/core/queries/DeleteQuery';
-import type { SelectResult, UpdateResult, CreateResult } from '@_linked/core/queries/IntermediateRepresentation';
-/**
- * Constructor argument for `new BackendAPIStore(config)`. Per the
- * docs/backlog/016-ejection-export-flow.md spec — a single JSON object
- * passed verbatim from linked.{frontend,backend}.datasets.json's `config`.
- */
-export interface BackendAPIStoreConfig {
-    /** Stable name; becomes the suffix of the store URI: ${DATA_ROOT}/backend-api-store/<name>. */
-    name?: string;
-    /** Or pass a fully-qualified URI directly. */
-    id?: string;
-}
-/**
- * Frontend-side store that routes all queries to the backend via `Server.call()`.
- * The backend's generic provider for this package executes them against the real store.
- *
- * A store is not a Shape. This class used to `extends Shape` and carry `@linkedShape`
- * with a `targetClass`, purely so that `Server.call(this, …)` could address it: the
- * transport derived the target from `shape instanceof Shape && shape.id` (the instance)
- * and `shapeClass.shape.id` (the class). Neither carried any meaning — the backend
- * provider never read the store it was handed, and query routing is decided by the
- * QUERY's shape, not the store's.
- *
- * It now uses `Server.call`'s package form instead, which addresses the backend by
- * package name and sends no shape fields at all. That removes the last reason for this
- * class to be a Shape, and with it the `new (providerShapeClass)({id})` the backend had
- * to perform to rebuild a store instance nobody used.
- */
-export declare class BackendAPIStore implements IDataset {
-    /**
-     * Kept so the config form is still accepted and a store can be named, but it is no
-     * longer an addressing mechanism — nothing transmits or resolves it. Retained because
-     * `linked.{frontend,backend}.datasets.json` may still pass `name`/`id`.
-     */
-    readonly id?: string;
-    constructor(config?: BackendAPIStoreConfig | string | {
-        id?: string;
-    });
-    init(): Promise<void>;
-    selectQuery(query: SelectQuery): Promise<SelectResult>;
-    askQuery(query: AskQuery): Promise<boolean>;
-    updateQuery(query: UpdateQuery): Promise<UpdateResult>;
-    createQuery(query: CreateQuery): Promise<CreateResult>;
-    deleteQuery(query: DeleteQuery): Promise<DeleteResponse>;
-    /**
-     * Opts in to `rejectOnError`, so a failed call (HTTP error status, or no
-     * provider on the backend) rejects with a `ServerCallError` carrying the
-     * status and the server's message instead of reading as an empty result.
-     * Whatever a successful call returns, `undefined` included, resolves as is.
-     */
-    private callBackend;
-}

package/lib/esm/shapes/quadstores/BackendAPIStore.js

@@ -1,71 +0,0 @@
-import { packageName } from '../../package.js';
-import { Server } from '@_linked/server-utils/utils/Server';
-/**
- * Frontend-side store that routes all queries to the backend via `Server.call()`.
- * The backend's generic provider for this package executes them against the real store.
- *
- * A store is not a Shape. This class used to `extends Shape` and carry `@linkedShape`
- * with a `targetClass`, purely so that `Server.call(this, …)` could address it: the
- * transport derived the target from `shape instanceof Shape && shape.id` (the instance)
- * and `shapeClass.shape.id` (the class). Neither carried any meaning — the backend
- * provider never read the store it was handed, and query routing is decided by the
- * QUERY's shape, not the store's.
- *
- * It now uses `Server.call`'s package form instead, which addresses the backend by
- * package name and sends no shape fields at all. That removes the last reason for this
- * class to be a Shape, and with it the `new (providerShapeClass)({id})` the backend had
- * to perform to rebuild a store instance nobody used.
- */
-export class BackendAPIStore {
-    constructor(config) {
-        if (!config)
-            return;
-        if (typeof config === 'string') {
-            this.id = `${process.env.DATA_ROOT}/backend-api-store/${config}`;
-            return;
-        }
-        if (config.id) {
-            this.id = config.id;
-            return;
-        }
-        if (config.name) {
-            const name = config.name;
-            this.id = `${process.env.DATA_ROOT}/backend-api-store/${name}`;
-        }
-    }
-    async init() {
-        // No initialization needed — queries are routed to the backend
-    }
-    // Queries serialize to DSL-JSON for the wire (core 2.10.0 contract flip): the
-    // live (closed) query can't cross Server.call as-is, so we ship `toJSON()` and
-    // the BackendAPIStoreProvider rehydrates with `fromJSON()` on the backend.
-    selectQuery(query) {
-        return this.callBackend('selectQuery', query.toJSON());
-    }
-    askQuery(query) {
-        return this.callBackend('askQuery', query.toJSON());
-    }
-    updateQuery(query) {
-        return this.callBackend('updateQuery', query.toJSON());
-    }
-    createQuery(query) {
-        return this.callBackend('createQuery', query.toJSON());
-    }
-    deleteQuery(query) {
-        return this.callBackend('deleteQuery', query.toJSON());
-    }
-    /**
-     * Opts in to `rejectOnError`, so a failed call (HTTP error status, or no
-     * provider on the backend) rejects with a `ServerCallError` carrying the
-     * status and the server's message instead of reading as an empty result.
-     * Whatever a successful call returns, `undefined` included, resolves as is.
-     */
-    callBackend(method, json) {
-        // The PACKAGE form, not the shape form. It posts to
-        // `/call/<packageName>/<method>` with a body of `{args}` only — no `shapeURI`,
-        // no `instanceNode` — and the backend answers from this package's generic
-        // provider without resolving or instantiating any Shape.
-        return Server.call(packageName, { method, rejectOnError: true }, json);
-    }
-}
-//# sourceMappingURL=BackendAPIStore.js.map

package/lib/esm/shapes/quadstores/BackendAPIStore.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"BackendAPIStore.js","sourceRoot":"","sources":["../../../../src/shapes/quadstores/BackendAPIStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,oCAAoC,CAAC;AA4B5D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,eAAe;IAQ1B,YAAY,MAAyD;QACnE,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC/B,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,sBAAsB,MAAM,EAAE,CAAC;YACjE,OAAO;QACT,CAAC;QACD,IAAK,MAAgC,CAAC,EAAE,EAAE,CAAC;YACzC,IAAI,CAAC,EAAE,GAAI,MAAgC,CAAC,EAAG,CAAC;YAChD,OAAO;QACT,CAAC;QACD,IAAK,MAAgC,CAAC,IAAI,EAAE,CAAC;YAC3C,MAAM,IAAI,GAAI,MAAgC,CAAC,IAAK,CAAC;YACrD,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,sBAAsB,IAAI,EAAE,CAAC;QACjE,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI;QACR,+DAA+D;IACjE,CAAC;IAED,8EAA8E;IAC9E,+EAA+E;IAC/E,2EAA2E;IAC3E,WAAW,CAAC,KAAkB;QAC5B,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,QAAQ,CAAC,KAAe;QACtB,OAAO,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,WAAW,CAAC,KAAkB;QAC5B,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,WAAW,CAAC,KAAkB;QAC5B,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,WAAW,CAAC,KAAkB;QAC5B,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,CAAC;IAED;;;;;OAKG;IACK,WAAW,CAAI,MAAc,EAAE,IAAa;QAClD,oDAAoD;QACpD,+EAA+E;QAC/E,0EAA0E;QAC1E,yDAAyD;QACzD,OAAO,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACzE,CAAC;CACF","sourcesContent":["import { packageName } from '../../package.js';\nimport { Server } from '@_linked/server-utils/utils/Server';\nimport type { IDataset } from '@_linked/core/interfaces/IDataset';\nimport type { SelectQuery } from '@_linked/core/queries/SelectQuery';\nimport type { AskQuery } from '@_linked/core/queries/AskQuery';\nimport type { UpdateQuery } from '@_linked/core/queries/UpdateQuery';\nimport type { CreateQuery } from '@_linked/core/queries/CreateQuery';\nimport type {\n  DeleteQuery,\n  DeleteResponse,\n} from '@_linked/core/queries/DeleteQuery';\nimport type {\n  SelectResult,\n  UpdateResult,\n  CreateResult,\n} from '@_linked/core/queries/IntermediateRepresentation';\n\n/**\n * Constructor argument for `new BackendAPIStore(config)`. Per the\n * docs/backlog/016-ejection-export-flow.md spec — a single JSON object\n * passed verbatim from linked.{frontend,backend}.datasets.json's `config`.\n */\nexport interface BackendAPIStoreConfig {\n  /** Stable name; becomes the suffix of the store URI: ${DATA_ROOT}/backend-api-store/<name>. */\n  name?: string;\n  /** Or pass a fully-qualified URI directly. */\n  id?: string;\n}\n\n/**\n * Frontend-side store that routes all queries to the backend via `Server.call()`.\n * The backend's generic provider for this package executes them against the real store.\n *\n * A store is not a Shape. This class used to `extends Shape` and carry `@linkedShape`\n * with a `targetClass`, purely so that `Server.call(this, …)` could address it: the\n * transport derived the target from `shape instanceof Shape && shape.id` (the instance)\n * and `shapeClass.shape.id` (the class). Neither carried any meaning — the backend\n * provider never read the store it was handed, and query routing is decided by the\n * QUERY's shape, not the store's.\n *\n * It now uses `Server.call`'s package form instead, which addresses the backend by\n * package name and sends no shape fields at all. That removes the last reason for this\n * class to be a Shape, and with it the `new (providerShapeClass)({id})` the backend had\n * to perform to rebuild a store instance nobody used.\n */\nexport class BackendAPIStore implements IDataset {\n  /**\n   * Kept so the config form is still accepted and a store can be named, but it is no\n   * longer an addressing mechanism — nothing transmits or resolves it. Retained because\n   * `linked.{frontend,backend}.datasets.json` may still pass `name`/`id`.\n   */\n  readonly id?: string;\n\n  constructor(config?: BackendAPIStoreConfig | string | { id?: string }) {\n    if (!config) return;\n    if (typeof config === 'string') {\n      this.id = `${process.env.DATA_ROOT}/backend-api-store/${config}`;\n      return;\n    }\n    if ((config as BackendAPIStoreConfig).id) {\n      this.id = (config as BackendAPIStoreConfig).id!;\n      return;\n    }\n    if ((config as BackendAPIStoreConfig).name) {\n      const name = (config as BackendAPIStoreConfig).name!;\n      this.id = `${process.env.DATA_ROOT}/backend-api-store/${name}`;\n    }\n  }\n\n  async init(): Promise<void> {\n    // No initialization needed — queries are routed to the backend\n  }\n\n  // Queries serialize to DSL-JSON for the wire (core 2.10.0 contract flip): the\n  // live (closed) query can't cross Server.call as-is, so we ship `toJSON()` and\n  // the BackendAPIStoreProvider rehydrates with `fromJSON()` on the backend.\n  selectQuery(query: SelectQuery): Promise<SelectResult> {\n    return this.callBackend('selectQuery', query.toJSON());\n  }\n\n  askQuery(query: AskQuery): Promise<boolean> {\n    return this.callBackend('askQuery', query.toJSON());\n  }\n\n  updateQuery(query: UpdateQuery): Promise<UpdateResult> {\n    return this.callBackend('updateQuery', query.toJSON());\n  }\n\n  createQuery(query: CreateQuery): Promise<CreateResult> {\n    return this.callBackend('createQuery', query.toJSON());\n  }\n\n  deleteQuery(query: DeleteQuery): Promise<DeleteResponse> {\n    return this.callBackend('deleteQuery', query.toJSON());\n  }\n\n  /**\n   * Opts in to `rejectOnError`, so a failed call (HTTP error status, or no\n   * provider on the backend) rejects with a `ServerCallError` carrying the\n   * status and the server's message instead of reading as an empty result.\n   * Whatever a successful call returns, `undefined` included, resolves as is.\n   */\n  private callBackend<T>(method: string, json: unknown): Promise<T> {\n    // The PACKAGE form, not the shape form. It posts to\n    // `/call/<packageName>/<method>` with a body of `{args}` only — no `shapeURI`,\n    // no `instanceNode` — and the backend answers from this package's generic\n    // provider without resolving or instantiating any Shape.\n    return Server.call(packageName, { method, rejectOnError: true }, json);\n  }\n}\n"]}

package/lib/esm/shapes/quadstores/GatewayStore.d.ts

@@ -1,85 +0,0 @@
-import type { IDataset } from '@_linked/core/interfaces/IDataset';
-import type { SelectQuery } from '@_linked/core/queries/SelectQuery';
-import type { CountQuery } from '@_linked/core/queries/CountQuery';
-import type { AskQuery } from '@_linked/core/queries/AskQuery';
-import type { UpdateQuery } from '@_linked/core/queries/UpdateQuery';
-import type { CreateQuery } from '@_linked/core/queries/CreateQuery';
-import type { DeleteQuery, DeleteResponse } from '@_linked/core/queries/DeleteQuery';
-import type { SelectResult, UpdateResult, CreateResult } from '@_linked/core/queries/IntermediateRepresentation';
-/**
- * Constructor argument for `new GatewayStore(config)` — the `config` object of a
- * `linked.backend.datasets.json` entry, passed verbatim by `loadStores`.
- */
-export interface GatewayStoreConfig {
-    /** Base URL of the gateway, e.g. `http://localhost:4040/gateway`. Routes are appended to it. */
-    endpoint: string;
-    /** The bearer credential the gateway issued to this process. */
-    credential: string;
-    /** Transport override; defaults to `globalThis.fetch`. */
-    fetch?: typeof fetch;
-}
-/** The op names on the wire; each is the `IDataset` method the store was called on. */
-export type GatewayOp = 'select' | 'ask' | 'update' | 'create' | 'delete';
-/** The wire version this store speaks. The gateway refuses any other with `code: "wire-version"`. */
-export declare const GATEWAY_WIRE_VERSION = 1;
-/**
- * A non-2xx answer from the gateway. `code` is the body's `code` when the gateway sent one
- * (`bad-request`, `wire-version`, `unknown-shape`, `refused`, `fork-failed`, `query-failed`),
- * else a generic one; `body` is the parsed response when it was JSON.
- */
-export declare class GatewayStoreError extends Error {
-    readonly status: number;
-    readonly code: string;
-    readonly body?: unknown;
-    constructor(message: string, status: number, code: string, body?: unknown);
-}
-/**
- * The gateway could not be used at all: the request never got an HTTP answer (network error,
- * `status` 0), or the gateway refused the credential (401). Thrown by `init()` and by every
- * query method; a process that gets this at boot should stop rather than carry on without data.
- */
-export declare class GatewayUnreachableError extends GatewayStoreError {
-}
-/** What `GET {endpoint}/health` answers with a valid credential. */
-export interface GatewayHealth {
-    projectId: string;
-    branchName: string;
-    dataset: string;
-}
-/**
- * An {@link IDataset} that forwards every Linked Query to a gateway over HTTP and returns
- * the gateway's result as is.
- *
- * Each query method posts `{v, op, query: query.toJSON()}` to `POST {endpoint}/query` with
- * `Authorization: Bearer <credential>` and resolves with the body's `result` — the same plain
- * JSON rows `BackendAPIStore` returns. The gateway decides which dataset the query runs on
- * from the credential; the store carries no project, branch or actor.
- *
- * Unlike `BackendAPIStore` it does not go through `Server.call` and has no dependency on
- * the process's own HTTP server: it is meant for a backend whose data lives behind another
- * service, selected from `linked.backend.datasets.json` by the host that started it.
- *
- * The store offers no raw SPARQL (`rawQuery`), no dataset administration and no change feed.
- */
-export declare class GatewayStore implements IDataset {
-    readonly endpoint: string;
-    private readonly credential;
-    private readonly fetchImpl;
-    constructor(config: GatewayStoreConfig);
-    /**
-     * Checks the gateway answers for this credential: `GET {endpoint}/health`. Resolves with the
-     * gateway's answer; throws {@link GatewayUnreachableError} when the gateway cannot be reached
-     * or refuses the credential. Safe to call more than once; it changes nothing on either side.
-     *
-     * `LinkedStorage.setDefaultDataset` calls `init()` without awaiting it, so a boot that must
-     * fail loudly awaits `init()` itself before registering the store.
-     */
-    init(): Promise<GatewayHealth>;
-    selectQuery(query: SelectQuery | CountQuery): Promise<SelectResult | number>;
-    askQuery(query: AskQuery): Promise<boolean>;
-    updateQuery(query: UpdateQuery): Promise<UpdateResult>;
-    createQuery(query: CreateQuery): Promise<CreateResult>;
-    deleteQuery(query: DeleteQuery): Promise<DeleteResponse>;
-    private send;
-    private request;
-}