@coasys/ad4m 0.13.0-test-model-layer → 0.13.0-test-flows-1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/lib/index.cjs +817 -65
  2. package/lib/index.js +814 -66
  3. package/lib/src/ai/AIClient.d.ts +13 -0
  4. package/lib/src/ai/AIClient.js +15 -0
  5. package/lib/src/ai/AITypes.d.ts +5 -0
  6. package/lib/src/index.js +2 -0
  7. package/lib/src/model/Ad4mModel.d.ts +6 -1
  8. package/lib/src/model/Ad4mModel.js +41 -6
  9. package/lib/src/model/ModelQueryBuilder.d.ts +47 -3
  10. package/lib/src/model/ModelQueryBuilder.js +97 -6
  11. package/lib/src/model/query-common.d.ts +10 -1
  12. package/lib/src/model/query-common.js +16 -0
  13. package/lib/src/model/query-sparql.d.ts +11 -0
  14. package/lib/src/model/query-sparql.js +93 -1
  15. package/lib/src/model/query-utils.js +16 -0
  16. package/lib/src/model/shacl-gen.js +12 -0
  17. package/lib/src/model/types.d.ts +320 -3
  18. package/lib/src/model/types.js +9 -0
  19. package/lib/src/perspectives/AutoProcessor.d.ts +8 -0
  20. package/lib/src/perspectives/FlowInstance.d.ts +176 -12
  21. package/lib/src/perspectives/FlowInstance.js +77 -13
  22. package/lib/src/perspectives/FlowModels.d.ts +40 -9
  23. package/lib/src/perspectives/FlowModels.js +59 -13
  24. package/lib/src/perspectives/PerspectiveClient.d.ts +18 -0
  25. package/lib/src/perspectives/PerspectiveClient.js +30 -0
  26. package/lib/src/perspectives/PerspectiveProxy.d.ts +69 -2
  27. package/lib/src/perspectives/PerspectiveProxy.js +157 -7
  28. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +55 -5
  29. package/lib/src/perspectives/WakerSubscriptionManager.js +183 -8
  30. package/lib/src/shacl/SHACLFlow.d.ts +43 -0
  31. package/package.json +1 -1
  32. package/src/ai/AIClient.ts +16 -0
  33. package/src/ai/AITypes.ts +5 -0
  34. package/src/index.ts +2 -0
  35. package/src/model/Ad4mModel.test.ts +442 -0
  36. package/src/model/Ad4mModel.ts +39 -7
  37. package/src/model/ModelQueryBuilder.ts +101 -10
  38. package/src/model/query-common.ts +20 -1
  39. package/src/model/query-sparql.test.ts +115 -0
  40. package/src/model/query-sparql.ts +97 -1
  41. package/src/model/query-utils.ts +18 -0
  42. package/src/model/relation-filtering.test.ts +7 -0
  43. package/src/model/shacl-gen.ts +12 -0
  44. package/src/model/shacl-roundtrip.test.ts +71 -0
  45. package/src/model/types-typed-query.test.ts +42 -0
  46. package/src/model/types.ts +316 -6
  47. package/src/perspectives/AutoProcessor.ts +8 -0
  48. package/src/perspectives/FlowInstance.ts +194 -13
  49. package/src/perspectives/FlowModels.ts +53 -13
  50. package/src/perspectives/PerspectiveClient.ts +62 -0
  51. package/src/perspectives/PerspectiveProxy.test.ts +272 -0
  52. package/src/perspectives/PerspectiveProxy.ts +163 -7
  53. package/src/perspectives/WakerSubscriptionManager.test.ts +199 -0
  54. package/src/perspectives/WakerSubscriptionManager.ts +197 -9
  55. package/src/shacl/SHACLFlow.ts +44 -0
@@ -6,6 +6,19 @@ export declare class AIClient {
6
6
  constructor(baseUrl: string, token?: string, subscribe?: boolean, sharedApiClient?: ApiClient);
7
7
  private serializeModelInput;
8
8
  getModels(): Promise<Model[]>;
9
+ /**
10
+ * Ask a remote endpoint which models it serves, before adding one.
11
+ *
12
+ * Takes the credentials of a model that does not exist yet — a settings
13
+ * form is being filled in and wants the list to pick from. Rejects when
14
+ * the endpoint is unreachable or the key is refused, which makes this the
15
+ * credential check too: without it a bad key surfaces later as a failed
16
+ * completion carrying an error from a different layer.
17
+ *
18
+ * `apiType` defaults to the OpenAI shape, which is what every endpoint
19
+ * that is not Anthropic speaks.
20
+ */
21
+ discoverModels(baseUrl: string, apiKey?: string, apiType?: string): Promise<string[]>;
9
22
  addModel(model: ModelInput): Promise<string>;
10
23
  updateModel(modelId: string, model: ModelInput): Promise<boolean>;
11
24
  removeModel(modelId: string): Promise<boolean>;
@@ -32,6 +32,21 @@ export class AIClient {
32
32
  async getModels() {
33
33
  return __classPrivateFieldGet(this, _AIClient_apiClient, "f").call('ai.models');
34
34
  }
35
+ /**
36
+ * Ask a remote endpoint which models it serves, before adding one.
37
+ *
38
+ * Takes the credentials of a model that does not exist yet — a settings
39
+ * form is being filled in and wants the list to pick from. Rejects when
40
+ * the endpoint is unreachable or the key is refused, which makes this the
41
+ * credential check too: without it a bad key surfaces later as a failed
42
+ * completion carrying an error from a different layer.
43
+ *
44
+ * `apiType` defaults to the OpenAI shape, which is what every endpoint
45
+ * that is not Anthropic speaks.
46
+ */
47
+ async discoverModels(baseUrl, apiKey, apiType) {
48
+ return __classPrivateFieldGet(this, _AIClient_apiClient, "f").call('ai.discoverModels', { baseUrl, apiKey, apiType });
49
+ }
35
50
  async addModel(model) {
36
51
  return __classPrivateFieldGet(this, _AIClient_apiClient, "f").call('ai.addModel', { model: this.serializeModelInput(model) });
37
52
  }
@@ -3,6 +3,9 @@ export declare class ModelApi {
3
3
  apiKey: string;
4
4
  model: string;
5
5
  apiType: String;
6
+ /** Optional ceiling for the provider's context window (tokens).
7
+ * Read by the Ollama provider to bound num_ctx / KV-cache VRAM. */
8
+ maxNumCtx?: number;
6
9
  }
7
10
  export declare class TokenizerSource {
8
11
  repo: string;
@@ -28,6 +31,8 @@ export declare class ModelApiInput {
28
31
  apiKey: string;
29
32
  model: string;
30
33
  apiType: string;
34
+ /** Optional ceiling for the provider's context window (tokens). */
35
+ maxNumCtx?: number;
31
36
  }
32
37
  export declare class TokenizerSourceInput {
33
38
  repo: string;
package/lib/src/index.js CHANGED
@@ -19,6 +19,8 @@ export * from "./perspectives/PerspectiveProxy";
19
19
  export * from "./perspectives/AutoProcessor";
20
20
  export * from "./perspectives/InterpretationModels";
21
21
  export * from "./perspectives/FlowModels";
22
+ // Also exports FlowFireOutcome / FlowProposeResult, the result shapes of the
23
+ // flow write API — they live beside the `proposeTransition()` surface.
22
24
  export * from "./perspectives/FlowInstance";
23
25
  export * from "./perspectives/SparqlBindings";
24
26
  export * from "./perspectives/WakerSubscriptionManager";
@@ -3,7 +3,7 @@ import { CallOptions } from "../apiClient";
3
3
  import type { SHACLShape } from "../shacl/SHACLShape";
4
4
  import type { JSONSchema, JSONSchemaToModelOptions } from "./json-schema";
5
5
  import { ModelQueryBuilder } from "./ModelQueryBuilder";
6
- import type { Scope, IncludeMap, Query, GetOptions, ResultsWithTotalCount, PaginationResult, ModelMetadata, TypedQuery, IncludeExtras, IncludeOf } from "./types";
6
+ import type { Scope, IncludeMap, Query, GetOptions, ResultsWithTotalCount, PaginationResult, ModelMetadata, TypedQuery, IncludeExtras, IncludeOf, LinksMap } from "./types";
7
7
  /**
8
8
  * Base class for defining data models in AD4M.
9
9
  *
@@ -123,6 +123,11 @@ export declare class Ad4mModel {
123
123
  author: string;
124
124
  createdAt: any;
125
125
  updatedAt: any;
126
+ /**
127
+ * Per-link rows for the entries asked for with `Query.links`, keyed as they
128
+ * were asked. Absent when the query did not ask for any.
129
+ */
130
+ __links?: LinksMap;
126
131
  /**
127
132
  * Backwards compatibility alias for createdAt.
128
133
  * @deprecated Use createdAt instead. This will be removed in a future version.
@@ -2,11 +2,12 @@ import { Link } from "../links/Links";
2
2
  import { LinkQuery } from "../perspectives/LinkQuery";
3
3
  import { makeRandomId } from "./util";
4
4
  import { getPropertiesMetadata, getRelationsMetadata, setPropertyRegistryEntry, setRelationRegistryEntry, Model } from "./decorators";
5
- import { resolveParentPredicate } from "./query-common";
5
+ import { requireSingleParent, resolveParentPredicate } from "./query-common";
6
6
  import { isArrayType, determinePredicate, determineNamespace, buildModelFromJSONSchema } from "./json-schema";
7
7
  import { buildSPARQLQuery, valueToLiteralIri, effectiveLiteralStorage } from "./query-sparql";
8
8
  import { ModelQueryBuilder } from "./ModelQueryBuilder";
9
9
  import { normalizeValue, } from "./hydration";
10
+ import { isTraverseScope } from "./types";
10
11
  // ---------------------------------------------------------------------------
11
12
  // Helpers for Rust-side include resolution
12
13
  // ---------------------------------------------------------------------------
@@ -895,7 +896,33 @@ export class Ad4mModel {
895
896
  const queryInput = {};
896
897
  if (query.parent) {
897
898
  const parentPredicate = resolveParentPredicate(query.parent, this);
898
- queryInput.parent = { id: query.parent.id, predicate: parentPredicate };
899
+ // A traversal keeps its own shape on the wire: the executor reads `ids`,
900
+ // and flattening it to one `id` here is how a request for a whole level
901
+ // would quietly become a request for one parent's children.
902
+ //
903
+ // Its fields are named rather than spread, because `model` — the class
904
+ // itself — is how the scope may name its predicate, and that is a
905
+ // constructor, not something to put in a query variable. The predicate is
906
+ // resolved above; what travels is the result.
907
+ if (isTraverseScope(query.parent)) {
908
+ const t = query.parent;
909
+ const traverse = {
910
+ ids: t.ids,
911
+ predicate: parentPredicate,
912
+ };
913
+ if (t.transitive !== undefined)
914
+ traverse.transitive = t.transitive;
915
+ if (t.direction !== undefined)
916
+ traverse.direction = t.direction;
917
+ if (t.limitPerAnchor !== undefined)
918
+ traverse.limitPerAnchor = t.limitPerAnchor;
919
+ if (t.levels !== undefined)
920
+ traverse.levels = t.levels;
921
+ queryInput.parent = traverse;
922
+ }
923
+ else {
924
+ queryInput.parent = { id: query.parent.id, predicate: parentPredicate };
925
+ }
899
926
  }
900
927
  if (query.properties)
901
928
  queryInput.properties = query.properties;
@@ -957,7 +984,13 @@ export class Ad4mModel {
957
984
  queryInput.limit = query.limit;
958
985
  if (query.count !== undefined)
959
986
  queryInput.count = query.count;
987
+ if (query.links)
988
+ queryInput.links = query.links;
960
989
  queryInput.deepQuery = query.deepQuery ?? true;
990
+ if (query.linkStatus != null)
991
+ queryInput.linkStatus = query.linkStatus;
992
+ if (query.includeUnverified !== undefined)
993
+ queryInput.includeUnverified = query.includeUnverified;
961
994
  // Conformance getters, where filters, and target shapes for includes
962
995
  // are all resolved by the executor from the perspective's SHACL triples
963
996
  // — no client-side pre-computation is needed any more.
@@ -1667,9 +1700,10 @@ export class Ad4mModel {
1667
1700
  if (options?.parent && !options?.batchId) {
1668
1701
  const batchId = await perspective.createBatch();
1669
1702
  await instance.save(batchId);
1670
- const predicate = resolveParentPredicate(options.parent, this);
1703
+ const parent = requireSingleParent(options.parent);
1704
+ const predicate = resolveParentPredicate(parent, this);
1671
1705
  const link = new Link({
1672
- source: options.parent.id,
1706
+ source: parent.id,
1673
1707
  predicate,
1674
1708
  target: instance.id,
1675
1709
  });
@@ -1683,9 +1717,10 @@ export class Ad4mModel {
1683
1717
  await instance.save(options?.batchId);
1684
1718
  // Create parent → child link if a parent scope was provided
1685
1719
  if (options?.parent) {
1686
- const predicate = resolveParentPredicate(options.parent, this);
1720
+ const parent = requireSingleParent(options.parent);
1721
+ const predicate = resolveParentPredicate(parent, this);
1687
1722
  const link = new Link({
1688
- source: options.parent.id,
1723
+ source: parent.id,
1689
1724
  predicate,
1690
1725
  target: instance.id,
1691
1726
  });
@@ -5,8 +5,8 @@
5
5
  * running them once or subscribing to real-time updates.
6
6
  */
7
7
  import type { Ad4mModel } from "./Ad4mModel";
8
- import type { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
9
- import type { Query, PaginationResult, TypedWhere, TypedOrder, TypedIncludeMap, PropertyKeysOf } from "./types";
8
+ import type { LinkStatus, PerspectiveProxy } from "../perspectives/PerspectiveProxy";
9
+ import type { Query, PaginationResult, TypedQueryWhere, TypedOrder, TypedIncludeMap, PropertyKeysOf } from "./types";
10
10
  /** Query builder for Ad4mModel queries.
11
11
  * Allows building queries with a fluent interface and either running them once
12
12
  * or subscribing to updates.
@@ -63,7 +63,7 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
63
63
  * })
64
64
  * ```
65
65
  */
66
- where(conditions: TypedWhere<T>): ModelQueryBuilder<T>;
66
+ where(conditions: TypedQueryWhere<T>): ModelQueryBuilder<T>;
67
67
  /**
68
68
  * Sets the order for the query results.
69
69
  *
@@ -157,6 +157,20 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
157
157
  * ```
158
158
  */
159
159
  properties(properties: PropertyKeysOf<T>[] | string[]): ModelQueryBuilder<T>;
160
+ /**
161
+ * Asks for the individual links behind each instance — author, timestamp
162
+ * and proof per link — under `instance.__links`. See `Query.links`.
163
+ *
164
+ * @param keys - Property / relation names, or absolute predicate IRIs
165
+ * @returns The query builder for chaining
166
+ *
167
+ * @example
168
+ * ```typescript
169
+ * const [post] = await Post.query(perspective).links(["comments"]).get();
170
+ * post.__links!.comments.map((l) => l.timestamp); // when each comment was attached
171
+ * ```
172
+ */
173
+ links(keys: string[]): ModelQueryBuilder<T>;
160
174
  /**
161
175
  * Controls whether SPARQL property getters are evaluated during hydration.
162
176
  *
@@ -176,6 +190,36 @@ export declare class ModelQueryBuilder<T extends Ad4mModel> {
176
190
  * ```
177
191
  */
178
192
  deepQuery(enabled?: boolean): ModelQueryBuilder<T>;
193
+ /**
194
+ * Reads instances as they exist in links of one status only.
195
+ *
196
+ * `'shared'` leaves out every Local link, both from the values returned and
197
+ * from what decides which instances are returned. Use it when the data is
198
+ * shown to another user. `'local'` is the converse: it returns only
199
+ * instances flagged in a Local link, so a Local note on a card flagged only
200
+ * in a Shared link is read without `linkStatus`, not under `'local'`.
201
+ * See {@link Query.linkStatus}.
202
+ *
203
+ * @param status - `'shared'` or `'local'`
204
+ * @returns The query builder for chaining
205
+ *
206
+ * @example
207
+ * ```typescript
208
+ * const cards = await Card.query(perspective).linkStatus('shared').get();
209
+ * ```
210
+ */
211
+ linkStatus(status: LinkStatus): ModelQueryBuilder<T>;
212
+ /**
213
+ * Also hydrate from links whose signature did not verify.
214
+ *
215
+ * Off by default: the executor withholds unverified links. Turn it on only
216
+ * to *display* an unverified claim, never for data you act on. See
217
+ * {@link Query.includeUnverified}.
218
+ *
219
+ * @param enabled - Whether to include unverified links (default: true)
220
+ * @returns The query builder for chaining
221
+ */
222
+ includeUnverified(enabled?: boolean): ModelQueryBuilder<T>;
179
223
  /**
180
224
  * Specifies which relations to eager-load (hydrate into model instances).
181
225
  *
@@ -200,6 +200,23 @@ export class ModelQueryBuilder {
200
200
  this.queryParams.properties = properties;
201
201
  return this;
202
202
  }
203
+ /**
204
+ * Asks for the individual links behind each instance — author, timestamp
205
+ * and proof per link — under `instance.__links`. See `Query.links`.
206
+ *
207
+ * @param keys - Property / relation names, or absolute predicate IRIs
208
+ * @returns The query builder for chaining
209
+ *
210
+ * @example
211
+ * ```typescript
212
+ * const [post] = await Post.query(perspective).links(["comments"]).get();
213
+ * post.__links!.comments.map((l) => l.timestamp); // when each comment was attached
214
+ * ```
215
+ */
216
+ links(keys) {
217
+ this.queryParams.links = keys;
218
+ return this;
219
+ }
203
220
  /**
204
221
  * Controls whether SPARQL property getters are evaluated during hydration.
205
222
  *
@@ -222,6 +239,42 @@ export class ModelQueryBuilder {
222
239
  this.queryParams.deepQuery = enabled;
223
240
  return this;
224
241
  }
242
+ /**
243
+ * Reads instances as they exist in links of one status only.
244
+ *
245
+ * `'shared'` leaves out every Local link, both from the values returned and
246
+ * from what decides which instances are returned. Use it when the data is
247
+ * shown to another user. `'local'` is the converse: it returns only
248
+ * instances flagged in a Local link, so a Local note on a card flagged only
249
+ * in a Shared link is read without `linkStatus`, not under `'local'`.
250
+ * See {@link Query.linkStatus}.
251
+ *
252
+ * @param status - `'shared'` or `'local'`
253
+ * @returns The query builder for chaining
254
+ *
255
+ * @example
256
+ * ```typescript
257
+ * const cards = await Card.query(perspective).linkStatus('shared').get();
258
+ * ```
259
+ */
260
+ linkStatus(status) {
261
+ this.queryParams.linkStatus = status;
262
+ return this;
263
+ }
264
+ /**
265
+ * Also hydrate from links whose signature did not verify.
266
+ *
267
+ * Off by default: the executor withholds unverified links. Turn it on only
268
+ * to *display* an unverified claim, never for data you act on. See
269
+ * {@link Query.includeUnverified}.
270
+ *
271
+ * @param enabled - Whether to include unverified links (default: true)
272
+ * @returns The query builder for chaining
273
+ */
274
+ includeUnverified(enabled = true) {
275
+ this.queryParams.includeUnverified = enabled;
276
+ return this;
277
+ }
225
278
  /**
226
279
  * Specifies which relations to eager-load (hydrate into model instances).
227
280
  *
@@ -362,13 +415,10 @@ export class ModelQueryBuilder {
362
415
  const unsubscribe = this.perspective.client.subscribeToQueryUpdates(subscriptionId, (rawResult) => {
363
416
  try {
364
417
  const results = parseResults(rawResult);
365
- console.debug(`[ModelQueryBuilder.subscribe] Update received for ${subscriptionId}: ${results.length} instances`);
366
418
  const fp = buildFingerprint(results);
367
419
  if (fp === lastResultFingerprint) {
368
- console.debug(`[ModelQueryBuilder.subscribe] Fingerprint unchanged, skipping callback`);
369
420
  return;
370
421
  }
371
- console.debug(`[ModelQueryBuilder.subscribe] Fingerprint changed, calling callback with ${results.length} results`);
372
422
  lastResultFingerprint = fp;
373
423
  callback(results);
374
424
  }
@@ -637,15 +687,56 @@ export class ModelQueryBuilder {
637
687
  offset: pageSize * (pageNumber - 1),
638
688
  count: true,
639
689
  };
690
+ // One read in flight. A dispatch while a read is running sets `pending`
691
+ // so a fetch always completes after the last dispatch. The generation
692
+ // counter from #1020 dropped superseded fetches, but ordered them by
693
+ // start time rather than by how fresh the data they read was — two
694
+ // back-to-back dispatches could keep the fetch that saw 1 model and
695
+ // drop the one that saw 2, after which the server has nothing further
696
+ // to say (issue #1051 / CI: "Paginate callback did not see second model save").
697
+ // After dispose() no read starts and no result is delivered, including
698
+ // a read that was already in flight when dispose() ran.
699
+ let disposed = false;
700
+ let fetching = false;
701
+ let pending = false;
702
+ let coalesced = 0;
640
703
  const processResults = async () => {
641
- const { results, totalCount } = await ctor.executeModelQuery(this.perspective, paginatedQuery, this.modelClassName);
642
- callback({ results, totalCount, pageSize, pageNumber });
704
+ if (disposed)
705
+ return;
706
+ if (fetching) {
707
+ pending = true;
708
+ coalesced++;
709
+ return;
710
+ }
711
+ fetching = true;
712
+ try {
713
+ const { results, totalCount } = await ctor.executeModelQuery(this.perspective, paginatedQuery, this.modelClassName);
714
+ if (!disposed)
715
+ callback({ results, totalCount, pageSize, pageNumber });
716
+ }
717
+ finally {
718
+ fetching = false;
719
+ if (pending) {
720
+ const dispatches = coalesced;
721
+ pending = false;
722
+ coalesced = 0;
723
+ // Whether a trailing fetch actually starts is decided by the entry
724
+ // guard at the top of processResults, which returns when disposed.
725
+ // Log only what that guard will let through, or the dispose path
726
+ // announces a fetch it then drops.
727
+ if (!disposed) {
728
+ console.debug(`[ModelQueryBuilder.paginateSubscribe] ${dispatches} dispatch(es) during read for ${subscriptionId}, coalesced into one trailing fetch`);
729
+ }
730
+ // Detached from the caller's promise: needs its own handler, or a
731
+ // rejection here is unhandled.
732
+ processResults().catch(e => console.error('Paginate subscription error:', e));
733
+ }
734
+ }
643
735
  };
644
736
  const unsubscribe = this.perspective.client.subscribeToQueryUpdates(subscriptionId, (rawResult) => {
645
737
  console.debug(`[ModelQueryBuilder.paginateSubscribe] Update received for ${subscriptionId}, re-fetching paginated data...`);
646
738
  processResults().catch(e => console.error('Paginate subscription error:', e));
647
739
  });
648
- let disposed = false;
649
740
  let keepaliveTimer;
650
741
  let resubscribeAttempts = 0;
651
742
  const MAX_RESUBSCRIBE_ATTEMPTS = 5;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Shared query helpers used by both the Prolog and SPARQL query pipelines.
3
3
  */
4
- import type { Scope } from "./types";
4
+ import type { Scope, TraverseScope } from "./types";
5
5
  /**
6
6
  * Resolves the predicate for a parent query.
7
7
  *
@@ -11,4 +11,13 @@ import type { Scope } from "./types";
11
11
  * - With `field`: direct key lookup
12
12
  * - Without `field`: scan for a relation whose `target()` matches `childCtor`
13
13
  */
14
+ /**
15
+ * Narrow a scope to the one-parent forms, for the paths that write a link.
16
+ *
17
+ * A traversal describes a read outward from several anchors. Creating a record
18
+ * "under" one would have to pick which, and nothing in the scope says — so this
19
+ * refuses rather than guessing at the first of the list. The executor's write
20
+ * scopes refuse it for the same reason.
21
+ */
22
+ export declare function requireSingleParent(parent: Scope): Exclude<Scope, TraverseScope>;
14
23
  export declare function resolveParentPredicate(parent: Scope, childCtor: Function): string;
@@ -1,6 +1,7 @@
1
1
  /**
2
2
  * Shared query helpers used by both the Prolog and SPARQL query pipelines.
3
3
  */
4
+ import { isTraverseScope } from "./types";
4
5
  import { getRelationsMetadata } from "./decorators";
5
6
  /**
6
7
  * Resolves the predicate for a parent query.
@@ -11,6 +12,21 @@ import { getRelationsMetadata } from "./decorators";
11
12
  * - With `field`: direct key lookup
12
13
  * - Without `field`: scan for a relation whose `target()` matches `childCtor`
13
14
  */
15
+ /**
16
+ * Narrow a scope to the one-parent forms, for the paths that write a link.
17
+ *
18
+ * A traversal describes a read outward from several anchors. Creating a record
19
+ * "under" one would have to pick which, and nothing in the scope says — so this
20
+ * refuses rather than guessing at the first of the list. The executor's write
21
+ * scopes refuse it for the same reason.
22
+ */
23
+ export function requireSingleParent(parent) {
24
+ if (isTraverseScope(parent)) {
25
+ throw new Error('parent(): a traverse scope describes a read and names no single parent to write under. ' +
26
+ 'Use { id, predicate } or { model, id } when creating a record under a parent.');
27
+ }
28
+ return parent;
29
+ }
14
30
  export function resolveParentPredicate(parent, childCtor) {
15
31
  // Raw form — explicit predicate
16
32
  if ('predicate' in parent)
@@ -27,6 +27,17 @@ import type { Where, Query, ModelMetadata } from "./types";
27
27
  * potentially discarding matches beyond the LIMIT.
28
28
  */
29
29
  export declare function hasJsOnlyWhereFilters(metadata: ModelMetadata, allRelationsMetadata: Record<string, RelationMetadataEntry>, where?: Where): boolean;
30
+ /**
31
+ * Prepare a `where` for this client-side SPARQL builder: unwrap `{ eq: X }`
32
+ * to the bare `X`, and refuse a per-link `author`.
33
+ *
34
+ * A per-link `author` (nested, `{ agent: { eq: X, author: A } }`, or a
35
+ * top-level `author` beside link-backed property or relation conditions) is
36
+ * answered by the executor, which joins each matched link's reifier (#1114). This builder
37
+ * has no such join, and treating the author as instance-level here would
38
+ * answer a different, wider question. `findAll()`/`count()` answer it.
39
+ */
40
+ export declare function normalizeWhereForSparql(metadata: ModelMetadata, where?: Where): Where | undefined;
30
41
  /**
31
42
  * Check whether a string value is a well-formed absolute IRI that can be
32
43
  * stored verbatim as a link target (raw `NamedNode`) instead of being
@@ -12,6 +12,7 @@
12
12
  */
13
13
  import { Literal } from "../Literal";
14
14
  import { resolveParentPredicate } from "./query-common";
15
+ import { isTraverseScope } from "./types";
15
16
  /**
16
17
  * Check whether a `where` clause contains filters that cannot be pushed down
17
18
  * to SPARQL and must be evaluated in JS after hydration.
@@ -69,6 +70,68 @@ export function hasJsOnlyWhereFilters(metadata, allRelationsMetadata, where) {
69
70
  }
70
71
  return false;
71
72
  }
73
+ /**
74
+ * Prepare a `where` for this client-side SPARQL builder: unwrap `{ eq: X }`
75
+ * to the bare `X`, and refuse a per-link `author`.
76
+ *
77
+ * A per-link `author` (nested, `{ agent: { eq: X, author: A } }`, or a
78
+ * top-level `author` beside link-backed property or relation conditions) is
79
+ * answered by the executor, which joins each matched link's reifier (#1114). This builder
80
+ * has no such join, and treating the author as instance-level here would
81
+ * answer a different, wider question. `findAll()`/`count()` answer it.
82
+ */
83
+ export function normalizeWhereForSparql(metadata, where) {
84
+ if (!where)
85
+ return where;
86
+ assertNoPerLinkAuthor(metadata, where);
87
+ const out = {};
88
+ for (const [key, condition] of Object.entries(where)) {
89
+ out[key] = unwrapEq(key, condition);
90
+ }
91
+ return out;
92
+ }
93
+ function isOpsObject(condition) {
94
+ return typeof condition === "object" && condition !== null && !Array.isArray(condition);
95
+ }
96
+ function unwrapEq(key, condition) {
97
+ if (key === "OR" || key === "AND" || key === "NOT" || !isOpsObject(condition) || condition.eq === undefined) {
98
+ return condition;
99
+ }
100
+ if (Object.keys(condition).some((k) => k !== "eq")) {
101
+ throw new Error(`where.${key}: \`eq\` cannot be combined with another operator`);
102
+ }
103
+ return condition.eq;
104
+ }
105
+ function assertNoPerLinkAuthor(metadata, where) {
106
+ const refuse = (what) => {
107
+ throw new Error(`buildSPARQLQuery: ${what} is a per-link \`author\`, which the executor answers by ` +
108
+ "checking who wrote each matched link. This client-side SPARQL builder cannot express " +
109
+ "it. Use the model query path (findAll/count).");
110
+ };
111
+ // A property or a relation with a predicate, as the executor's `is_link_leaf`.
112
+ const linkBacked = (key) => {
113
+ const field = metadata.properties[key] ?? metadata.relations?.[key];
114
+ return !!field && !!field.predicate && !field.getter;
115
+ };
116
+ for (const [key, condition] of Object.entries(where)) {
117
+ if (key === "OR" || key === "AND") {
118
+ for (const branch of condition ?? [])
119
+ assertNoPerLinkAuthor(metadata, branch);
120
+ }
121
+ else if (key === "NOT") {
122
+ if (condition)
123
+ assertNoPerLinkAuthor(metadata, condition);
124
+ }
125
+ else if (key === "author") {
126
+ const sibling = Object.keys(where).find((k) => k !== "author" && linkBacked(k));
127
+ if (sibling)
128
+ refuse(`\`author\` beside \`${sibling}\``);
129
+ }
130
+ else if (isOpsObject(condition) && condition.author !== undefined) {
131
+ refuse(`\`${key}.author\``);
132
+ }
133
+ }
134
+ }
72
135
  /**
73
136
  * Check whether a string value is a well-formed absolute IRI that can be
74
137
  * stored verbatim as a link target (raw `NamedNode`) instead of being
@@ -242,11 +305,40 @@ function mapPropertyToSPARQLVar(propertyName, metadata) {
242
305
  export function buildSPARQLQuery(metadata, allRelationsMetadata, query, modelClass) {
243
306
  const joinPatterns = [];
244
307
  const filterExpressions = [];
308
+ query = { ...query, where: normalizeWhereForSparql(metadata, query.where) };
245
309
  // Parent filter — direct triple pattern
246
310
  if (query.parent) {
247
311
  const parentPredicate = resolveParentPredicate(query.parent, modelClass);
248
- joinPatterns.push(`
312
+ if (isTraverseScope(query.parent)) {
313
+ const { ids, transitive, direction, limitPerAnchor, levels } = query.parent;
314
+ // `limitPerAnchor` and `levels` are applied by the executor between
315
+ // selecting ids and hydrating them, which is a shape this path does not
316
+ // have — it builds one query and reads the rows. Refused rather than
317
+ // ignored: quietly returning every reply where five per parent were
318
+ // asked for — or one unbounded level where a walk was asked for — is a
319
+ // wrong answer that looks like a right one.
320
+ if (limitPerAnchor !== undefined) {
321
+ throw new Error('buildSPARQLQuery: limitPerAnchor is applied by the executor between query phases and ' +
322
+ 'has no equivalent here. Use the model query path for per-anchor limits.');
323
+ }
324
+ if (levels !== undefined) {
325
+ throw new Error('buildSPARQLQuery: levels is walked by the executor between query phases and ' +
326
+ 'has no equivalent here. Use the model query path for level walks.');
327
+ }
328
+ const anchors = (Array.isArray(ids) ? ids : [ids]).map(iri).join(' ');
329
+ const path = transitive ? '+' : '';
330
+ joinPatterns.push(`
331
+ VALUES ?_anchor { ${anchors} }`);
332
+ joinPatterns.push(direction === 'in'
333
+ ? `
334
+ ?source ${iri(parentPredicate)}${path} ?_anchor .`
335
+ : `
336
+ ?_anchor ${iri(parentPredicate)}${path} ?source .`);
337
+ }
338
+ else {
339
+ joinPatterns.push(`
249
340
  ${iri(query.parent.id)} ${iri(parentPredicate)} ?source .`);
341
+ }
250
342
  }
251
343
  // Required property JOIN patterns — direct triple patterns
252
344
  let hasConformance = false;
@@ -55,6 +55,22 @@ export function formatQueryValue(value) {
55
55
  * @returns A single SPARQL condition string
56
56
  */
57
57
  export function buildWhereCondition(predicate, condition, opts) {
58
+ // `{ eq: X }` is the bare `X`. A nested `author` is a per-link condition
59
+ // the executor answers in model queries; a getter's SPARQL has no reifier
60
+ // join to answer it with, so it is refused rather than dropped (#1114).
61
+ if (typeof condition === 'object' && condition !== null && !Array.isArray(condition)) {
62
+ const ops = condition;
63
+ if (ops.author !== undefined) {
64
+ throw new Error(`buildWhereCondition: a nested \`author\` on <${predicate}> is a per-link condition ` +
65
+ 'that only the model query path can answer');
66
+ }
67
+ if (ops.eq !== undefined) {
68
+ if (Object.keys(ops).some((k) => k !== 'eq')) {
69
+ throw new Error(`buildWhereCondition: \`eq\` on <${predicate}> cannot be combined with another operator`);
70
+ }
71
+ condition = ops.eq;
72
+ }
73
+ }
58
74
  const escapedPredicate = escapeQueryString(predicate);
59
75
  // For deterministic-literal properties, values are stored as typed
60
76
  // literals like `"X"^^xsd:string` (or the legacy `<literal:string:VALUE>`
@@ -100,6 +100,18 @@ interpretationHint) {
100
100
  const propMeta = properties[propName];
101
101
  if (!propMeta.through)
102
102
  continue; // Skip properties without predicates
103
+ // `@BelongsToOne`/`@BelongsToMany` register in both maps: the relation
104
+ // registry describes the edge, and `applyPropertyMetadata` marks the
105
+ // accessor read-only so the non-owning side gets no setter. Both loops
106
+ // then emitted a shape for it, so an inverse relation appeared twice in
107
+ // the generated SHACL — once thinly, from here, and once with its target
108
+ // class, polymorphism and ordering, from the relation loop below.
109
+ //
110
+ // The relation loop is the complete description, so this one stands
111
+ // aside. Skipping by presence in the relation map rather than by kind
112
+ // keeps it right for any future decorator that registers in both.
113
+ if (allRelationsMeta[propName])
114
+ continue;
103
115
  const propShape = {
104
116
  name: propName,
105
117
  path: propMeta.through,