@coasys/ad4m 0.13.0-test-inverse-relations → 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 (39) hide show
  1. package/lib/index.cjs +409 -43
  2. package/lib/index.js +409 -44
  3. package/lib/src/ai/AITypes.d.ts +5 -0
  4. package/lib/src/index.js +2 -0
  5. package/lib/src/model/Ad4mModel.d.ts +6 -1
  6. package/lib/src/model/Ad4mModel.js +31 -4
  7. package/lib/src/model/ModelQueryBuilder.d.ts +47 -3
  8. package/lib/src/model/ModelQueryBuilder.js +95 -14
  9. package/lib/src/model/query-sparql.d.ts +11 -0
  10. package/lib/src/model/query-sparql.js +74 -6
  11. package/lib/src/model/query-utils.js +16 -0
  12. package/lib/src/model/types.d.ts +237 -10
  13. package/lib/src/perspectives/FlowInstance.d.ts +150 -4
  14. package/lib/src/perspectives/FlowInstance.js +44 -3
  15. package/lib/src/perspectives/FlowModels.d.ts +33 -8
  16. package/lib/src/perspectives/FlowModels.js +51 -11
  17. package/lib/src/perspectives/PerspectiveClient.d.ts +11 -9
  18. package/lib/src/perspectives/PerspectiveClient.js +18 -0
  19. package/lib/src/perspectives/PerspectiveProxy.d.ts +40 -1
  20. package/lib/src/perspectives/PerspectiveProxy.js +79 -5
  21. package/lib/src/shacl/SHACLFlow.d.ts +43 -0
  22. package/package.json +1 -1
  23. package/src/ai/AITypes.ts +5 -0
  24. package/src/index.ts +2 -0
  25. package/src/model/Ad4mModel.test.ts +381 -18
  26. package/src/model/Ad4mModel.ts +29 -5
  27. package/src/model/ModelQueryBuilder.ts +99 -18
  28. package/src/model/query-sparql.test.ts +115 -0
  29. package/src/model/query-sparql.ts +75 -6
  30. package/src/model/query-utils.ts +18 -0
  31. package/src/model/relation-filtering.test.ts +7 -0
  32. package/src/model/types-typed-query.test.ts +42 -0
  33. package/src/model/types.ts +228 -13
  34. package/src/perspectives/FlowInstance.ts +159 -4
  35. package/src/perspectives/FlowModels.ts +45 -11
  36. package/src/perspectives/PerspectiveClient.ts +44 -10
  37. package/src/perspectives/PerspectiveProxy.test.ts +118 -0
  38. package/src/perspectives/PerspectiveProxy.ts +81 -4
  39. package/src/shacl/SHACLFlow.ts +44 -0
package/lib/index.cjs CHANGED
@@ -3999,7 +3999,7 @@ var __classPrivateFieldGet$a = (undefined && undefined.__classPrivateFieldGet) |
3999
3999
  if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
4000
4000
  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
4001
4001
  };
4002
- var _QuerySubscriptionProxy_instances, _QuerySubscriptionProxy_uuid, _QuerySubscriptionProxy_subscriptionId, _QuerySubscriptionProxy_client, _QuerySubscriptionProxy_callbacks, _QuerySubscriptionProxy_keepaliveTimer, _QuerySubscriptionProxy_unsubscribe, _QuerySubscriptionProxy_reconnectUnsub, _QuerySubscriptionProxy_latestResult, _QuerySubscriptionProxy_disposed, _QuerySubscriptionProxy_initialized, _QuerySubscriptionProxy_initResolve, _QuerySubscriptionProxy_initReject, _QuerySubscriptionProxy_initTimeoutId, _QuerySubscriptionProxy_query, _QuerySubscriptionProxy_generation, _QuerySubscriptionProxy_deliverResult, _QuerySubscriptionProxy_startKeepalive, _QuerySubscriptionProxy_notifyCallbacks, _PerspectiveProxy_handle, _PerspectiveProxy_client, _PerspectiveProxy_perspectiveLinkAddedCallbacks, _PerspectiveProxy_perspectiveLinkRemovedCallbacks, _PerspectiveProxy_perspectiveLinkUpdatedCallbacks, _PerspectiveProxy_perspectiveSyncStateChangeCallbacks, _PerspectiveProxy_ensuredSubjectClasses;
4002
+ var _QuerySubscriptionProxy_instances, _QuerySubscriptionProxy_uuid, _QuerySubscriptionProxy_subscriptionId, _QuerySubscriptionProxy_client, _QuerySubscriptionProxy_callbacks, _QuerySubscriptionProxy_keepaliveTimer, _QuerySubscriptionProxy_unsubscribe, _QuerySubscriptionProxy_reconnectUnsub, _QuerySubscriptionProxy_latestResult, _QuerySubscriptionProxy_disposed, _QuerySubscriptionProxy_initialized, _QuerySubscriptionProxy_initResolve, _QuerySubscriptionProxy_initReject, _QuerySubscriptionProxy_initTimeoutId, _QuerySubscriptionProxy_query, _QuerySubscriptionProxy_generation, _QuerySubscriptionProxy_deliverResult, _QuerySubscriptionProxy_startKeepalive, _QuerySubscriptionProxy_notifyCallbacks, _PerspectiveProxy_handle, _PerspectiveProxy_client, _PerspectiveProxy_perspectiveLinkAddedCallbacks, _PerspectiveProxy_perspectiveLinkRemovedCallbacks, _PerspectiveProxy_perspectiveLinkUpdatedCallbacks, _PerspectiveProxy_perspectiveSyncStateChangeCallbacks, _PerspectiveProxy_ensuredSubjectClasses, _PerspectiveProxy_overlaysInFlight;
4003
4003
  /** Extract namespace prefix from a URI (everything up to and including the last / or #) */
4004
4004
  function extractNamespaceFromUri(uri) {
4005
4005
  const hashIdx = uri.lastIndexOf('#');
@@ -4491,6 +4491,10 @@ class PerspectiveProxy {
4491
4491
  _PerspectiveProxy_perspectiveLinkUpdatedCallbacks.set(this, void 0);
4492
4492
  _PerspectiveProxy_perspectiveSyncStateChangeCallbacks.set(this, void 0);
4493
4493
  _PerspectiveProxy_ensuredSubjectClasses.set(this, new Set()
4494
+ /** The `interpretationOverlays()` RPC currently in flight, shared by concurrent callers. */
4495
+ );
4496
+ /** The `interpretationOverlays()` RPC currently in flight, shared by concurrent callers. */
4497
+ _PerspectiveProxy_overlaysInFlight.set(this, null
4494
4498
  /**
4495
4499
  * Creates a new PerspectiveProxy instance.
4496
4500
  * Note: Don't create this directly, use ad4m.perspective.add() instead.
@@ -4705,9 +4709,28 @@ class PerspectiveProxy {
4705
4709
  /**
4706
4710
  * Pending interpretation overlays on this perspective — LLM suggestions the
4707
4711
  * §4 divergence gate staged rather than applied, awaiting human accept/reject.
4712
+ *
4713
+ * Concurrent callers share one in-flight RPC. Nothing is kept after it
4714
+ * settles, so every call made after that fetches from the executor again.
4715
+ * {@link acceptInterpretation} and {@link rejectInterpretation} detach the
4716
+ * in-flight RPC, so a read issued after they resolve never joins a read
4717
+ * that started before the write.
4718
+ * Each caller gets its own copy of the array.
4708
4719
  */
4709
4720
  async interpretationOverlays() {
4710
- return await __classPrivateFieldGet$a(this, _PerspectiveProxy_client, "f").interpretationOverlays(__classPrivateFieldGet$a(this, _PerspectiveProxy_handle, "f").uuid);
4721
+ if (__classPrivateFieldGet$a(this, _PerspectiveProxy_overlaysInFlight, "f")) {
4722
+ return [...(await __classPrivateFieldGet$a(this, _PerspectiveProxy_overlaysInFlight, "f"))];
4723
+ }
4724
+ const pending = __classPrivateFieldGet$a(this, _PerspectiveProxy_client, "f").interpretationOverlays(__classPrivateFieldGet$a(this, _PerspectiveProxy_handle, "f").uuid);
4725
+ __classPrivateFieldSet$a(this, _PerspectiveProxy_overlaysInFlight, pending, "f");
4726
+ try {
4727
+ return [...(await pending)];
4728
+ }
4729
+ finally {
4730
+ if (__classPrivateFieldGet$a(this, _PerspectiveProxy_overlaysInFlight, "f") === pending) {
4731
+ __classPrivateFieldSet$a(this, _PerspectiveProxy_overlaysInFlight, null, "f");
4732
+ }
4733
+ }
4711
4734
  }
4712
4735
  /**
4713
4736
  * Accept an interpretation overlay's suggestion(s): the LLM's staged value
@@ -4715,7 +4738,13 @@ class PerspectiveProxy {
4715
4738
  * `property` to accept a single predicate; omit it for the whole base.
4716
4739
  */
4717
4740
  async acceptInterpretation(base, property) {
4718
- return await __classPrivateFieldGet$a(this, _PerspectiveProxy_client, "f").acceptInterpretation(__classPrivateFieldGet$a(this, _PerspectiveProxy_handle, "f").uuid, base, property);
4741
+ try {
4742
+ return await __classPrivateFieldGet$a(this, _PerspectiveProxy_client, "f").acceptInterpretation(__classPrivateFieldGet$a(this, _PerspectiveProxy_handle, "f").uuid, base, property);
4743
+ }
4744
+ finally {
4745
+ // A read already in flight may predate this write; later callers must not join it.
4746
+ __classPrivateFieldSet$a(this, _PerspectiveProxy_overlaysInFlight, null, "f");
4747
+ }
4719
4748
  }
4720
4749
  /**
4721
4750
  * Reject an interpretation overlay's suggestion(s). Omit `property` to reject
@@ -4723,7 +4752,23 @@ class PerspectiveProxy {
4723
4752
  * rejected `update` drops the overlay and keeps the real value.
4724
4753
  */
4725
4754
  async rejectInterpretation(base, property) {
4726
- return await __classPrivateFieldGet$a(this, _PerspectiveProxy_client, "f").rejectInterpretation(__classPrivateFieldGet$a(this, _PerspectiveProxy_handle, "f").uuid, base, property);
4755
+ try {
4756
+ return await __classPrivateFieldGet$a(this, _PerspectiveProxy_client, "f").rejectInterpretation(__classPrivateFieldGet$a(this, _PerspectiveProxy_handle, "f").uuid, base, property);
4757
+ }
4758
+ finally {
4759
+ // A read already in flight may predate this write; later callers must not join it.
4760
+ __classPrivateFieldSet$a(this, _PerspectiveProxy_overlaysInFlight, null, "f");
4761
+ }
4762
+ }
4763
+ /**
4764
+ * `outputs` names the instances a run produces, as `{ className, id }`
4765
+ * pairs, for a transition into a terminal state. The proposal signs a
4766
+ * hash over their content, and a receipt for the run can only speak for
4767
+ * exactly these instances, as they stood at completion. Naming outputs
4768
+ * for a non-terminal state is refused.
4769
+ */
4770
+ async proposeFlowTransition(instanceUri, toState, rationale, outputs) {
4771
+ return await __classPrivateFieldGet$a(this, _PerspectiveProxy_client, "f").proposeFlowTransition(__classPrivateFieldGet$a(this, _PerspectiveProxy_handle, "f").uuid, instanceUri, toState, rationale, outputs);
4727
4772
  }
4728
4773
  async acceptFlowProposal(proposalUri) {
4729
4774
  return await __classPrivateFieldGet$a(this, _PerspectiveProxy_client, "f").acceptFlowProposal(__classPrivateFieldGet$a(this, _PerspectiveProxy_handle, "f").uuid, proposalUri);
@@ -4732,6 +4777,35 @@ class PerspectiveProxy {
4732
4777
  async rejectFlowProposal(proposalUri) {
4733
4778
  return await __classPrivateFieldGet$a(this, _PerspectiveProxy_client, "f").rejectFlowProposal(__classPrivateFieldGet$a(this, _PerspectiveProxy_handle, "f").uuid, proposalUri);
4734
4779
  }
4780
+ /**
4781
+ * Re-decide a flow receipt under this perspective's own flow catalogue.
4782
+ * The verdict is three-way — see {@link FlowReceiptVerdict}: branch on
4783
+ * `outcome`, never on a boolean you derive from it.
4784
+ */
4785
+ async verifyFlowReceipt(receipt) {
4786
+ return await __classPrivateFieldGet$a(this, _PerspectiveProxy_client, "f").verifyFlowReceipt(__classPrivateFieldGet$a(this, _PerspectiveProxy_handle, "f").uuid, receipt);
4787
+ }
4788
+ /**
4789
+ * Which instances are, as they stand, valid outputs of `flow`?
4790
+ *
4791
+ * Backed by receipt verification executor-side (see
4792
+ * {@link FlowValidOutput}); an instance without a verifying receipt, or
4793
+ * edited since its run completed, is not listed. The same predicate is
4794
+ * available as a model-query filter:
4795
+ * `where: { producedByFlow: { flow, state? } }`.
4796
+ *
4797
+ * Rejects — never resolves to `[]` — when the flow is not on this
4798
+ * perspective, or when it carries more receipt candidates than the
4799
+ * executor's per-flow budget (256): "could not read every receipt" is not
4800
+ * "no valid outputs". The filter rejects the same way.
4801
+ */
4802
+ async flowValidOutputs(flow, state) {
4803
+ return await __classPrivateFieldGet$a(this, _PerspectiveProxy_client, "f").flowValidOutputs(__classPrivateFieldGet$a(this, _PerspectiveProxy_handle, "f").uuid, flow, state);
4804
+ }
4805
+ /** Mint and store the receipt for a completed flow run. */
4806
+ async mintFlowReceipt(instanceUri) {
4807
+ return await __classPrivateFieldGet$a(this, _PerspectiveProxy_client, "f").mintFlowReceipt(__classPrivateFieldGet$a(this, _PerspectiveProxy_handle, "f").uuid, instanceUri);
4808
+ }
4735
4809
  /** Subscribe to this perspective's auto-processor step signals. */
4736
4810
  async addAutoProcessorEventListener(cb) {
4737
4811
  return await __classPrivateFieldGet$a(this, _PerspectiveProxy_client, "f").addAutoProcessorEventListener(__classPrivateFieldGet$a(this, _PerspectiveProxy_handle, "f").uuid, cb);
@@ -6359,7 +6433,7 @@ class PerspectiveProxy {
6359
6433
  return subscriptionProxy;
6360
6434
  }
6361
6435
  }
6362
- _PerspectiveProxy_handle = new WeakMap(), _PerspectiveProxy_client = new WeakMap(), _PerspectiveProxy_perspectiveLinkAddedCallbacks = new WeakMap(), _PerspectiveProxy_perspectiveLinkRemovedCallbacks = new WeakMap(), _PerspectiveProxy_perspectiveLinkUpdatedCallbacks = new WeakMap(), _PerspectiveProxy_perspectiveSyncStateChangeCallbacks = new WeakMap(), _PerspectiveProxy_ensuredSubjectClasses = new WeakMap();
6436
+ _PerspectiveProxy_handle = new WeakMap(), _PerspectiveProxy_client = new WeakMap(), _PerspectiveProxy_perspectiveLinkAddedCallbacks = new WeakMap(), _PerspectiveProxy_perspectiveLinkRemovedCallbacks = new WeakMap(), _PerspectiveProxy_perspectiveLinkUpdatedCallbacks = new WeakMap(), _PerspectiveProxy_perspectiveSyncStateChangeCallbacks = new WeakMap(), _PerspectiveProxy_ensuredSubjectClasses = new WeakMap(), _PerspectiveProxy_overlaysInFlight = new WeakMap();
6363
6437
 
6364
6438
  var __classPrivateFieldSet$9 = (undefined && undefined.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
6365
6439
  if (kind === "m") throw new TypeError("Private method is not writable");
@@ -6651,6 +6725,9 @@ class PerspectiveClient {
6651
6725
  async rejectInterpretation(uuid, base, property) {
6652
6726
  return __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").call('perspective.rejectInterpretation', { uuid, base, property });
6653
6727
  }
6728
+ async proposeFlowTransition(uuid, instanceUri, toState, rationale, outputs) {
6729
+ return __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").call('perspective.proposeFlowTransition', { uuid, instanceUri, toState, rationale, outputs });
6730
+ }
6654
6731
  async acceptFlowProposal(uuid, proposalUri) {
6655
6732
  return __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").call('perspective.acceptFlowProposal', { uuid, proposalUri });
6656
6733
  }
@@ -6663,6 +6740,21 @@ class PerspectiveClient {
6663
6740
  const result = await __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").call('perspective.rejectFlowProposal', { uuid, proposalUri });
6664
6741
  return result.retractedLinks;
6665
6742
  }
6743
+ /** Re-decide a flow receipt under this perspective's own flow catalogue. */
6744
+ async verifyFlowReceipt(uuid, receipt) {
6745
+ return __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").call('perspective.verifyFlowReceipt', { uuid, receipt });
6746
+ }
6747
+ /** The instances that are, as they stand, valid outputs of `flow`
6748
+ * (optionally: of runs settled into terminal state `state`). */
6749
+ async flowValidOutputs(uuid, flow, state) {
6750
+ return __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").call('perspective.flowValidOutputs', { uuid, flow, state });
6751
+ }
6752
+ /** Mint and store the receipt for a completed flow run. Fails while the
6753
+ * run has not settled into a terminal state, and when an output's
6754
+ * content no longer matches what the quorum committed to. */
6755
+ async mintFlowReceipt(uuid, instanceUri) {
6756
+ return __classPrivateFieldGet$9(this, _PerspectiveClient_apiClient, "f").call('perspective.mintFlowReceipt', { uuid, instanceUri });
6757
+ }
6666
6758
  /**
6667
6759
  * Subscribe to auto-processor step signals. `cb` fires for every
6668
6760
  * `auto-processor-event` on `uuid` (BatchReady → Claimed/BackedOff/… →
@@ -15604,6 +15696,68 @@ function hasJsOnlyWhereFilters(metadata, allRelationsMetadata, where) {
15604
15696
  }
15605
15697
  return false;
15606
15698
  }
15699
+ /**
15700
+ * Prepare a `where` for this client-side SPARQL builder: unwrap `{ eq: X }`
15701
+ * to the bare `X`, and refuse a per-link `author`.
15702
+ *
15703
+ * A per-link `author` (nested, `{ agent: { eq: X, author: A } }`, or a
15704
+ * top-level `author` beside link-backed property or relation conditions) is
15705
+ * answered by the executor, which joins each matched link's reifier (#1114). This builder
15706
+ * has no such join, and treating the author as instance-level here would
15707
+ * answer a different, wider question. `findAll()`/`count()` answer it.
15708
+ */
15709
+ function normalizeWhereForSparql(metadata, where) {
15710
+ if (!where)
15711
+ return where;
15712
+ assertNoPerLinkAuthor(metadata, where);
15713
+ const out = {};
15714
+ for (const [key, condition] of Object.entries(where)) {
15715
+ out[key] = unwrapEq(key, condition);
15716
+ }
15717
+ return out;
15718
+ }
15719
+ function isOpsObject(condition) {
15720
+ return typeof condition === "object" && condition !== null && !Array.isArray(condition);
15721
+ }
15722
+ function unwrapEq(key, condition) {
15723
+ if (key === "OR" || key === "AND" || key === "NOT" || !isOpsObject(condition) || condition.eq === undefined) {
15724
+ return condition;
15725
+ }
15726
+ if (Object.keys(condition).some((k) => k !== "eq")) {
15727
+ throw new Error(`where.${key}: \`eq\` cannot be combined with another operator`);
15728
+ }
15729
+ return condition.eq;
15730
+ }
15731
+ function assertNoPerLinkAuthor(metadata, where) {
15732
+ const refuse = (what) => {
15733
+ throw new Error(`buildSPARQLQuery: ${what} is a per-link \`author\`, which the executor answers by ` +
15734
+ "checking who wrote each matched link. This client-side SPARQL builder cannot express " +
15735
+ "it. Use the model query path (findAll/count).");
15736
+ };
15737
+ // A property or a relation with a predicate, as the executor's `is_link_leaf`.
15738
+ const linkBacked = (key) => {
15739
+ const field = metadata.properties[key] ?? metadata.relations?.[key];
15740
+ return !!field && !!field.predicate && !field.getter;
15741
+ };
15742
+ for (const [key, condition] of Object.entries(where)) {
15743
+ if (key === "OR" || key === "AND") {
15744
+ for (const branch of condition ?? [])
15745
+ assertNoPerLinkAuthor(metadata, branch);
15746
+ }
15747
+ else if (key === "NOT") {
15748
+ if (condition)
15749
+ assertNoPerLinkAuthor(metadata, condition);
15750
+ }
15751
+ else if (key === "author") {
15752
+ const sibling = Object.keys(where).find((k) => k !== "author" && linkBacked(k));
15753
+ if (sibling)
15754
+ refuse(`\`author\` beside \`${sibling}\``);
15755
+ }
15756
+ else if (isOpsObject(condition) && condition.author !== undefined) {
15757
+ refuse(`\`${key}.author\``);
15758
+ }
15759
+ }
15760
+ }
15607
15761
  /**
15608
15762
  * Check whether a string value is a well-formed absolute IRI that can be
15609
15763
  * stored verbatim as a link target (raw `NamedNode`) instead of being
@@ -15777,20 +15931,26 @@ function mapPropertyToSPARQLVar(propertyName, metadata) {
15777
15931
  function buildSPARQLQuery(metadata, allRelationsMetadata, query, modelClass) {
15778
15932
  const joinPatterns = [];
15779
15933
  const filterExpressions = [];
15934
+ query = { ...query, where: normalizeWhereForSparql(metadata, query.where) };
15780
15935
  // Parent filter — direct triple pattern
15781
15936
  if (query.parent) {
15782
15937
  const parentPredicate = resolveParentPredicate(query.parent, modelClass);
15783
15938
  if (isTraverseScope(query.parent)) {
15784
- const { ids, transitive, direction, limitPerAnchor } = query.parent;
15785
- // `limitPerAnchor` is applied by the executor between selecting ids and
15786
- // hydrating them, which is a shape this path does not have — it builds one
15787
- // query and reads the rows. Refused rather than ignored: quietly returning
15788
- // every reply where five per parent were asked for is a wrong answer that
15789
- // looks like a right one.
15939
+ const { ids, transitive, direction, limitPerAnchor, levels } = query.parent;
15940
+ // `limitPerAnchor` and `levels` are applied by the executor between
15941
+ // selecting ids and hydrating them, which is a shape this path does not
15942
+ // have — it builds one query and reads the rows. Refused rather than
15943
+ // ignored: quietly returning every reply where five per parent were
15944
+ // asked for — or one unbounded level where a walk was asked for — is a
15945
+ // wrong answer that looks like a right one.
15790
15946
  if (limitPerAnchor !== undefined) {
15791
15947
  throw new Error('buildSPARQLQuery: limitPerAnchor is applied by the executor between query phases and ' +
15792
15948
  'has no equivalent here. Use the model query path for per-anchor limits.');
15793
15949
  }
15950
+ if (levels !== undefined) {
15951
+ throw new Error('buildSPARQLQuery: levels is walked by the executor between query phases and ' +
15952
+ 'has no equivalent here. Use the model query path for level walks.');
15953
+ }
15794
15954
  const anchors = (Array.isArray(ids) ? ids : [ids]).map(iri).join(' ');
15795
15955
  const path = transitive ? '+' : '';
15796
15956
  joinPatterns.push(`
@@ -16301,6 +16461,23 @@ class ModelQueryBuilder {
16301
16461
  this.queryParams.properties = properties;
16302
16462
  return this;
16303
16463
  }
16464
+ /**
16465
+ * Asks for the individual links behind each instance — author, timestamp
16466
+ * and proof per link — under `instance.__links`. See `Query.links`.
16467
+ *
16468
+ * @param keys - Property / relation names, or absolute predicate IRIs
16469
+ * @returns The query builder for chaining
16470
+ *
16471
+ * @example
16472
+ * ```typescript
16473
+ * const [post] = await Post.query(perspective).links(["comments"]).get();
16474
+ * post.__links!.comments.map((l) => l.timestamp); // when each comment was attached
16475
+ * ```
16476
+ */
16477
+ links(keys) {
16478
+ this.queryParams.links = keys;
16479
+ return this;
16480
+ }
16304
16481
  /**
16305
16482
  * Controls whether SPARQL property getters are evaluated during hydration.
16306
16483
  *
@@ -16323,6 +16500,42 @@ class ModelQueryBuilder {
16323
16500
  this.queryParams.deepQuery = enabled;
16324
16501
  return this;
16325
16502
  }
16503
+ /**
16504
+ * Reads instances as they exist in links of one status only.
16505
+ *
16506
+ * `'shared'` leaves out every Local link, both from the values returned and
16507
+ * from what decides which instances are returned. Use it when the data is
16508
+ * shown to another user. `'local'` is the converse: it returns only
16509
+ * instances flagged in a Local link, so a Local note on a card flagged only
16510
+ * in a Shared link is read without `linkStatus`, not under `'local'`.
16511
+ * See {@link Query.linkStatus}.
16512
+ *
16513
+ * @param status - `'shared'` or `'local'`
16514
+ * @returns The query builder for chaining
16515
+ *
16516
+ * @example
16517
+ * ```typescript
16518
+ * const cards = await Card.query(perspective).linkStatus('shared').get();
16519
+ * ```
16520
+ */
16521
+ linkStatus(status) {
16522
+ this.queryParams.linkStatus = status;
16523
+ return this;
16524
+ }
16525
+ /**
16526
+ * Also hydrate from links whose signature did not verify.
16527
+ *
16528
+ * Off by default: the executor withholds unverified links. Turn it on only
16529
+ * to *display* an unverified claim, never for data you act on. See
16530
+ * {@link Query.includeUnverified}.
16531
+ *
16532
+ * @param enabled - Whether to include unverified links (default: true)
16533
+ * @returns The query builder for chaining
16534
+ */
16535
+ includeUnverified(enabled = true) {
16536
+ this.queryParams.includeUnverified = enabled;
16537
+ return this;
16538
+ }
16326
16539
  /**
16327
16540
  * Specifies which relations to eager-load (hydrate into model instances).
16328
16541
  *
@@ -16735,28 +16948,56 @@ class ModelQueryBuilder {
16735
16948
  offset: pageSize * (pageNumber - 1),
16736
16949
  count: true,
16737
16950
  };
16738
- // Each server dispatch triggers an independent async re-fetch, and those
16739
- // re-fetches resolve in completion order, not dispatch order. A re-fetch
16740
- // dispatched *before* a write committed can resolve *after* the re-fetch
16741
- // that saw the write, silently rolling the consumer back to a stale page —
16742
- // and no later dispatch ever corrects it. The generation counter drops any
16743
- // fetch that is no longer the newest one started; the newest fetch always
16744
- // delivers, so the callback is monotone in dispatch order.
16745
- let fetchGeneration = 0;
16951
+ // One read in flight. A dispatch while a read is running sets `pending`
16952
+ // so a fetch always completes after the last dispatch. The generation
16953
+ // counter from #1020 dropped superseded fetches, but ordered them by
16954
+ // start time rather than by how fresh the data they read was — two
16955
+ // back-to-back dispatches could keep the fetch that saw 1 model and
16956
+ // drop the one that saw 2, after which the server has nothing further
16957
+ // to say (issue #1051 / CI: "Paginate callback did not see second model save").
16958
+ // After dispose() no read starts and no result is delivered, including
16959
+ // a read that was already in flight when dispose() ran.
16960
+ let disposed = false;
16961
+ let fetching = false;
16962
+ let pending = false;
16963
+ let coalesced = 0;
16746
16964
  const processResults = async () => {
16747
- const generation = ++fetchGeneration;
16748
- const { results, totalCount } = await ctor.executeModelQuery(this.perspective, paginatedQuery, this.modelClassName);
16749
- if (generation !== fetchGeneration) {
16750
- console.debug(`[ModelQueryBuilder.paginateSubscribe] Dropping stale re-fetch result (generation ${generation}, newest ${fetchGeneration})`);
16965
+ if (disposed)
16966
+ return;
16967
+ if (fetching) {
16968
+ pending = true;
16969
+ coalesced++;
16751
16970
  return;
16752
16971
  }
16753
- callback({ results, totalCount, pageSize, pageNumber });
16972
+ fetching = true;
16973
+ try {
16974
+ const { results, totalCount } = await ctor.executeModelQuery(this.perspective, paginatedQuery, this.modelClassName);
16975
+ if (!disposed)
16976
+ callback({ results, totalCount, pageSize, pageNumber });
16977
+ }
16978
+ finally {
16979
+ fetching = false;
16980
+ if (pending) {
16981
+ const dispatches = coalesced;
16982
+ pending = false;
16983
+ coalesced = 0;
16984
+ // Whether a trailing fetch actually starts is decided by the entry
16985
+ // guard at the top of processResults, which returns when disposed.
16986
+ // Log only what that guard will let through, or the dispose path
16987
+ // announces a fetch it then drops.
16988
+ if (!disposed) {
16989
+ console.debug(`[ModelQueryBuilder.paginateSubscribe] ${dispatches} dispatch(es) during read for ${subscriptionId}, coalesced into one trailing fetch`);
16990
+ }
16991
+ // Detached from the caller's promise: needs its own handler, or a
16992
+ // rejection here is unhandled.
16993
+ processResults().catch(e => console.error('Paginate subscription error:', e));
16994
+ }
16995
+ }
16754
16996
  };
16755
16997
  const unsubscribe = this.perspective.client.subscribeToQueryUpdates(subscriptionId, (rawResult) => {
16756
16998
  console.debug(`[ModelQueryBuilder.paginateSubscribe] Update received for ${subscriptionId}, re-fetching paginated data...`);
16757
16999
  processResults().catch(e => console.error('Paginate subscription error:', e));
16758
17000
  });
16759
- let disposed = false;
16760
17001
  let keepaliveTimer;
16761
17002
  let resubscribeAttempts = 0;
16762
17003
  const MAX_RESUBSCRIBE_ATTEMPTS = 5;
@@ -17724,12 +17965,33 @@ class Ad4mModel {
17724
17965
  const queryInput = {};
17725
17966
  if (query.parent) {
17726
17967
  const parentPredicate = resolveParentPredicate(query.parent, this);
17727
- // A traversal is forwarded as it was written: the executor reads `ids`,
17968
+ // A traversal keeps its own shape on the wire: the executor reads `ids`,
17728
17969
  // and flattening it to one `id` here is how a request for a whole level
17729
17970
  // would quietly become a request for one parent's children.
17730
- queryInput.parent = isTraverseScope(query.parent)
17731
- ? { ...query.parent, predicate: parentPredicate }
17732
- : { id: query.parent.id, predicate: parentPredicate };
17971
+ //
17972
+ // Its fields are named rather than spread, because `model` — the class
17973
+ // itself — is how the scope may name its predicate, and that is a
17974
+ // constructor, not something to put in a query variable. The predicate is
17975
+ // resolved above; what travels is the result.
17976
+ if (isTraverseScope(query.parent)) {
17977
+ const t = query.parent;
17978
+ const traverse = {
17979
+ ids: t.ids,
17980
+ predicate: parentPredicate,
17981
+ };
17982
+ if (t.transitive !== undefined)
17983
+ traverse.transitive = t.transitive;
17984
+ if (t.direction !== undefined)
17985
+ traverse.direction = t.direction;
17986
+ if (t.limitPerAnchor !== undefined)
17987
+ traverse.limitPerAnchor = t.limitPerAnchor;
17988
+ if (t.levels !== undefined)
17989
+ traverse.levels = t.levels;
17990
+ queryInput.parent = traverse;
17991
+ }
17992
+ else {
17993
+ queryInput.parent = { id: query.parent.id, predicate: parentPredicate };
17994
+ }
17733
17995
  }
17734
17996
  if (query.properties)
17735
17997
  queryInput.properties = query.properties;
@@ -17791,7 +18053,13 @@ class Ad4mModel {
17791
18053
  queryInput.limit = query.limit;
17792
18054
  if (query.count !== undefined)
17793
18055
  queryInput.count = query.count;
18056
+ if (query.links)
18057
+ queryInput.links = query.links;
17794
18058
  queryInput.deepQuery = query.deepQuery ?? true;
18059
+ if (query.linkStatus != null)
18060
+ queryInput.linkStatus = query.linkStatus;
18061
+ if (query.includeUnverified !== undefined)
18062
+ queryInput.includeUnverified = query.includeUnverified;
17795
18063
  // Conformance getters, where filters, and target shapes for includes
17796
18064
  // are all resolved by the executor from the perspective's SHACL triples
17797
18065
  // — no client-side pre-computation is needed any more.
@@ -19318,14 +19586,14 @@ exports.InterpretationOverlay = __decorate$1([
19318
19586
  * Querying:
19319
19587
  * const pending = await FlowTransitionProposal.findAll(perspective);
19320
19588
  *
19321
- * Slice 5/7 of the flow-implementation arc (design doc §4.2). The Rust
19322
- * engine does not yet mint these — that lands with the consensus firing
19323
- * work in a later PR arc. This class defines the on-graph shape so:
19324
- * - clients can build UI over proposals immediately (Deliberation demo);
19325
- * - the SDNA-parity test locks TS/Rust drift the moment the JSON exists
19326
- * (`rust-executor/src/perspectives/hardwired_sdna/flow_transition_proposal.json`);
19327
- * - the engine can start writing into this shape when consensus lands
19328
- * without touching the client-side surface.
19589
+ * Slice 5/7 of the flow-implementation arc (design doc §4.2). The Rust engine
19590
+ * mints these as of #987 — see `flow_classes.rs` (`mint_proposal`, URIs at
19591
+ * `ad4m://flow/proposal/{id}`) — and reads them back in
19592
+ * `flow_instance/atom.rs`. A UI mints or joins them through
19593
+ * `FlowInstance.proposeTransition`. This class is the client-side mirror:
19594
+ * - clients build UI over proposals without knowing the raw link predicates;
19595
+ * - the SDNA-parity test locks TS/Rust drift against
19596
+ * `rust-executor/src/perspectives/hardwired_sdna/flow_transition_proposal.json`.
19329
19597
  */
19330
19598
  var __decorate = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
19331
19599
  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -19339,9 +19607,12 @@ var __metadata = (undefined && undefined.__metadata) || function (k, v) {
19339
19607
  // ── FlowTransitionProposal ──────────────────────────────────────────────────
19340
19608
  // Mirrors the Rust hardwired `flow_transition_proposal.json` SDNA (once wired
19341
19609
  // on the engine side; see file header). One node per proposed transition; the
19342
- // URI is `ad4m://flow/proposal/<uuid>` when the engine mints it, but the class
19343
- // carries no URI-format constraint — apps constructing proposals directly may
19344
- // choose any URI they can defend as unique.
19610
+ // URI the engine mints is `ad4m://flow/proposal/<hash>` — the content address
19611
+ // of the proposer-signed fields under the `nonce` (#1108). The class carries
19612
+ // no URI-format constraint, but a proposal whose URI is not that content
19613
+ // address (including any app-chosen URI) is not engine-visible: co-signatures
19614
+ // name the URI, so the engine only counts proposals whose URI commits to
19615
+ // their fields.
19345
19616
  exports.FlowTransitionProposal = class FlowTransitionProposal extends Ad4mModel {
19346
19617
  constructor() {
19347
19618
  super(...arguments);
@@ -19374,6 +19645,31 @@ exports.FlowTransitionProposal = class FlowTransitionProposal extends Ad4mModel
19374
19645
  * no rich-object type; the engine parses it back into a map.
19375
19646
  */
19376
19647
  this.evidenceHashes = "";
19648
+ /**
19649
+ * The instances the proposer names as the run's outputs. Written only on
19650
+ * a proposal into a terminal state; one link per output, ordering not
19651
+ * significant. Each entry is the canonical JSON text of a
19652
+ * `{ className, id }` pair (`FlowOutputRef`); `JSON.parse` it to read one.
19653
+ */
19654
+ this.outputs = [];
19655
+ /**
19656
+ * SHA-256 (hex) over the named outputs' content (each instance as
19657
+ * `model_query` returns it through its class), signed by the proposer
19658
+ * next to the evidence seal. Co-signers load the outputs and recompute it
19659
+ * before voting, and a flow receipt's output preimages must hash to it.
19660
+ * Empty on a proposal into a non-terminal state.
19661
+ */
19662
+ this.outputsHash = "";
19663
+ /**
19664
+ * The proposer's uniqueness salt for this proposal's content-addressed
19665
+ * URI (`ad4m://flow/proposal/<hash>`; the hash covers the instance, the
19666
+ * edge, the seal, the outputs commitment, the proposer DID and this
19667
+ * nonce). The engine writes a UUID. A proposal without one — or whose URI
19668
+ * does not match its own signed fields — is not engine-visible:
19669
+ * co-signatures name the URI, so the URI must commit to what they sign
19670
+ * (#1108).
19671
+ */
19672
+ this.nonce = "";
19377
19673
  // "When was this proposal written?" is answered by `Ad4mModel`'s built-in
19378
19674
  // `createdAt`, synthesized on hydration from the earliest link timestamp
19379
19675
  // of the proposal's own links (all written together during create_subject).
@@ -19403,6 +19699,18 @@ __decorate([
19403
19699
  Property({ through: "ad4m://flow/evidence_hashes", required: true }),
19404
19700
  __metadata("design:type", String)
19405
19701
  ], exports.FlowTransitionProposal.prototype, "evidenceHashes", void 0);
19702
+ __decorate([
19703
+ HasMany({ through: "ad4m://flow/output", datatype: "xsd:string" }),
19704
+ __metadata("design:type", Array)
19705
+ ], exports.FlowTransitionProposal.prototype, "outputs", void 0);
19706
+ __decorate([
19707
+ Property({ through: "ad4m://flow/outputs_hash" }),
19708
+ __metadata("design:type", String)
19709
+ ], exports.FlowTransitionProposal.prototype, "outputsHash", void 0);
19710
+ __decorate([
19711
+ Property({ through: "ad4m://flow/nonce" }),
19712
+ __metadata("design:type", String)
19713
+ ], exports.FlowTransitionProposal.prototype, "nonce", void 0);
19406
19714
  __decorate([
19407
19715
  Optional({ through: "ad4m://flow/run_uri" }),
19408
19716
  __metadata("design:type", String)
@@ -19529,10 +19837,23 @@ exports.FlowInstanceRecord = __decorate([
19529
19837
  * present now, withdrawing a vote that had settled an edge moves the
19530
19838
  * flow back to where it stood before it.
19531
19839
  *
19840
+ * - `proposeTransition()` — the manual write path: propose an edge as this
19841
+ * agent, or co-sign the equivalent proposal another agent already opened.
19842
+ * Its `FlowProposeResult` is what tells queued from no-op from stalled.
19843
+ *
19532
19844
  * Still absent (rather than shipped as `throw new Error("not yet")`
19533
- * stubs): `proposeTransition`, `fireAction`, and the subscriptions
19534
- * (`onStateChange`, `onProposalAdded`, `onProposalResolved`) — they land
19535
- * with the manual-proposal and subscription-topic slices.
19845
+ * stubs): `fireAction`, and the subscriptions (`onStateChange`,
19846
+ * `onProposalAdded`, `onProposalResolved`) — they land with the
19847
+ * subscription-topic slice.
19848
+ *
19849
+ * ## The guard-free rule
19850
+ *
19851
+ * A state with no `requires` guard is **never** proposed by the engine, on
19852
+ * any replica, ever — `flow_evaluator`'s auto-proposal composer skips it by
19853
+ * design. Nothing in the graph implies a human started work; they said so.
19854
+ * So states like "in progress" and "in review" only ever advance through
19855
+ * `proposeTransition`. This is a permanent contract, not a gap: wire the
19856
+ * button, or the instance sits there.
19536
19857
  */
19537
19858
  /**
19538
19859
  * Extract the flow's human-readable name from its canonical URI.
@@ -19838,6 +20159,34 @@ class FlowInstance {
19838
20159
  where: { flowInstance: this.uri },
19839
20160
  });
19840
20161
  }
20162
+ /**
20163
+ * Propose a flow transition for this instance, as the calling agent.
20164
+ *
20165
+ * The executor evaluates the guard on its own replica, seals the evidence,
20166
+ * and either writes a new proposal or — when an equivalent one is already
20167
+ * open, i.e. another agent pressed the same button first — co-signs that
20168
+ * one. When the resulting vote reaches the target state's
20169
+ * `consensusRule.n`, the transition fires in the same call.
20170
+ *
20171
+ * How to read the result — fired vs. queued vs. no-op vs. stalled — is
20172
+ * documented on {@link FlowProposeResult} itself.
20173
+ *
20174
+ * `outputs` names the instances the run produces, as `{ className, id }`
20175
+ * pairs, for a transition into a terminal state. The proposal signs a hash
20176
+ * over their content, every co-signer recomputes it on its own replica,
20177
+ * and a receipt for the run speaks for exactly these instances as they
20178
+ * stood at completion.
20179
+ *
20180
+ * Throws when `toState` is not reachable from the derived state, when the
20181
+ * target state carries a `requires` guard that is not currently satisfied
20182
+ * on this replica, when the instance is already contested, when `outputs`
20183
+ * is given for a non-terminal state or names something that is not an
20184
+ * instance of its class, or
20185
+ * when an open proposal on the same edge names different outputs.
20186
+ */
20187
+ async proposeTransition(toState, rationale, outputs) {
20188
+ return this.perspective.proposeFlowTransition(this.uri, toState, rationale, outputs);
20189
+ }
19841
20190
  async acceptProposal(proposal) {
19842
20191
  const uri = typeof proposal === "string" ? proposal : proposal.id;
19843
20192
  return this.perspective.acceptFlowProposal(uri);
@@ -20470,6 +20819,22 @@ function formatQueryValue(value) {
20470
20819
  * @returns A single SPARQL condition string
20471
20820
  */
20472
20821
  function buildWhereCondition(predicate, condition, opts) {
20822
+ // `{ eq: X }` is the bare `X`. A nested `author` is a per-link condition
20823
+ // the executor answers in model queries; a getter's SPARQL has no reifier
20824
+ // join to answer it with, so it is refused rather than dropped (#1114).
20825
+ if (typeof condition === 'object' && condition !== null && !Array.isArray(condition)) {
20826
+ const ops = condition;
20827
+ if (ops.author !== undefined) {
20828
+ throw new Error(`buildWhereCondition: a nested \`author\` on <${predicate}> is a per-link condition ` +
20829
+ 'that only the model query path can answer');
20830
+ }
20831
+ if (ops.eq !== undefined) {
20832
+ if (Object.keys(ops).some((k) => k !== 'eq')) {
20833
+ throw new Error(`buildWhereCondition: \`eq\` on <${predicate}> cannot be combined with another operator`);
20834
+ }
20835
+ condition = ops.eq;
20836
+ }
20837
+ }
20473
20838
  const escapedPredicate = escapeQueryString(predicate);
20474
20839
  // For deterministic-literal properties, values are stored as typed
20475
20840
  // literals like `"X"^^xsd:string` (or the legacy `<literal:string:VALUE>`
@@ -20906,6 +21271,7 @@ exports.looksLikeUri = looksLikeUri;
20906
21271
  exports.normalizeNamespaceString = normalizeNamespaceString;
20907
21272
  exports.normalizeSchemaType = normalizeSchemaType;
20908
21273
  exports.normalizeValue = normalizeValue;
21274
+ exports.normalizeWhereForSparql = normalizeWhereForSparql;
20909
21275
  exports.parseExprUrl = parseExprUrl;
20910
21276
  exports.parseLit = parseLit;
20911
21277
  exports.parseLitBoolean = parseLitBoolean;