@coasys/ad4m 0.13.0-test-interpretation-2 → 0.13.0-test-model-layer

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 (254) hide show
  1. package/lib/index.cjs +1982 -498
  2. package/lib/index.js +1982 -499
  3. package/lib/src/ai/AIClient.js +6 -3
  4. package/lib/src/apiClient.d.ts +40 -4
  5. package/lib/src/apiClient.js +149 -9
  6. package/lib/src/index.d.ts +3 -1
  7. package/lib/src/index.js +2 -0
  8. package/lib/src/model/Ad4mModel.d.ts +6 -5
  9. package/lib/src/model/Ad4mModel.js +246 -29
  10. package/lib/src/model/Ad4mModel.test.js +480 -735
  11. package/lib/src/model/decorators.d.ts +147 -4
  12. package/lib/src/model/decorators.js +70 -24
  13. package/lib/src/model/model-manifest.d.ts +41 -0
  14. package/lib/src/model/model-manifest.js +11 -0
  15. package/lib/src/model/query-sparql.test.js +92 -10
  16. package/lib/src/model/shacl-gen.js +33 -0
  17. package/lib/src/model/types.d.ts +9 -0
  18. package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +33 -33
  19. package/lib/src/perspectives/AutoProcessor.d.ts +90 -24
  20. package/lib/src/perspectives/FlowInstance.d.ts +187 -0
  21. package/lib/src/perspectives/FlowInstance.js +336 -0
  22. package/lib/src/perspectives/FlowModels.d.ts +94 -0
  23. package/lib/src/perspectives/FlowModels.js +182 -0
  24. package/lib/src/perspectives/InterpretationModels.d.ts +12 -22
  25. package/lib/src/perspectives/InterpretationModels.js +2 -6
  26. package/lib/src/perspectives/PerspectiveClient.d.ts +68 -7
  27. package/lib/src/perspectives/PerspectiveClient.js +105 -10
  28. package/lib/src/perspectives/PerspectiveProxy.d.ts +142 -57
  29. package/lib/src/perspectives/PerspectiveProxy.js +388 -274
  30. package/lib/src/shacl/SHACLFlow.d.ts +273 -47
  31. package/lib/src/shacl/SHACLFlow.js +397 -88
  32. package/lib/src/shacl/SHACLShape.d.ts +8 -0
  33. package/lib/src/shacl/SHACLShape.js +17 -0
  34. package/lib/src/shacl/SHACLShape.test.js +82 -0
  35. package/package.json +2 -2
  36. package/src/ai/AIClient.ts +6 -3
  37. package/src/apiClient.test.ts +227 -0
  38. package/src/apiClient.ts +185 -9
  39. package/src/index.ts +3 -1
  40. package/src/model/Ad4mModel.test.ts +645 -0
  41. package/src/model/Ad4mModel.ts +245 -26
  42. package/src/model/decorators.ts +216 -35
  43. package/src/model/relation-filtering.test.ts +70 -20
  44. package/src/model/shacl-gen.ts +36 -0
  45. package/src/model/shacl-roundtrip.test.ts +130 -0
  46. package/src/model/types.ts +7 -0
  47. package/src/perspectives/AutoProcessor.ts +94 -24
  48. package/src/perspectives/FlowInstance.ts +369 -0
  49. package/src/perspectives/FlowModels.ts +157 -0
  50. package/src/perspectives/InterpretationModels.ts +13 -25
  51. package/src/perspectives/PerspectiveClient.test.ts +67 -6
  52. package/src/perspectives/PerspectiveClient.ts +142 -12
  53. package/src/perspectives/PerspectiveProxy.test.ts +406 -0
  54. package/src/perspectives/PerspectiveProxy.ts +459 -289
  55. package/src/perspectives/shacl-rpc.test.ts +258 -0
  56. package/src/shacl/SHACLFlow.test.ts +762 -35
  57. package/src/shacl/SHACLFlow.ts +680 -112
  58. package/src/shacl/SHACLShape.ts +31 -0
  59. package/lib/src/generated/rest/AIModelLoadingStatus.d.ts +0 -7
  60. package/lib/src/generated/rest/AIModelLoadingStatus.js +0 -2
  61. package/lib/src/generated/rest/AddAgentInfosRequest.d.ts +0 -3
  62. package/lib/src/generated/rest/AddAgentInfosRequest.js +0 -2
  63. package/lib/src/generated/rest/AddLinkExpressionRequest.d.ts +0 -6
  64. package/lib/src/generated/rest/AddLinkExpressionRequest.js +0 -1
  65. package/lib/src/generated/rest/AddLinkRequest.d.ts +0 -6
  66. package/lib/src/generated/rest/AddLinkRequest.js +0 -1
  67. package/lib/src/generated/rest/AddLinksBulkRequest.d.ts +0 -6
  68. package/lib/src/generated/rest/AddLinksBulkRequest.js +0 -1
  69. package/lib/src/generated/rest/AddSdnaRequest.d.ts +0 -6
  70. package/lib/src/generated/rest/AddSdnaRequest.js +0 -2
  71. package/lib/src/generated/rest/ApplyTemplateRequest.d.ts +0 -4
  72. package/lib/src/generated/rest/ApplyTemplateRequest.js +0 -2
  73. package/lib/src/generated/rest/AuthInfoInput.d.ts +0 -10
  74. package/lib/src/generated/rest/AuthInfoInput.js +0 -1
  75. package/lib/src/generated/rest/BroadcastRequest.d.ts +0 -6
  76. package/lib/src/generated/rest/BroadcastRequest.js +0 -1
  77. package/lib/src/generated/rest/CapabilityInput.d.ts +0 -5
  78. package/lib/src/generated/rest/CapabilityInput.js +0 -1
  79. package/lib/src/generated/rest/CommitBatchRequest.d.ts +0 -3
  80. package/lib/src/generated/rest/CommitBatchRequest.js +0 -2
  81. package/lib/src/generated/rest/ComputeLogEntry.d.ts +0 -9
  82. package/lib/src/generated/rest/ComputeLogEntry.js +0 -2
  83. package/lib/src/generated/rest/CreateExpressionRequest.d.ts +0 -4
  84. package/lib/src/generated/rest/CreateExpressionRequest.js +0 -2
  85. package/lib/src/generated/rest/CreatePerspectiveRequest.d.ts +0 -3
  86. package/lib/src/generated/rest/CreatePerspectiveRequest.js +0 -2
  87. package/lib/src/generated/rest/CreateSubjectRequest.d.ts +0 -6
  88. package/lib/src/generated/rest/CreateSubjectRequest.js +0 -2
  89. package/lib/src/generated/rest/CreateUserRequest.d.ts +0 -4
  90. package/lib/src/generated/rest/CreateUserRequest.js +0 -2
  91. package/lib/src/generated/rest/CreateUserResponse.d.ts +0 -5
  92. package/lib/src/generated/rest/CreateUserResponse.js +0 -2
  93. package/lib/src/generated/rest/DecoratedExpressionProof.d.ts +0 -6
  94. package/lib/src/generated/rest/DecoratedExpressionProof.js +0 -2
  95. package/lib/src/generated/rest/DecoratedLinkExpression.d.ts +0 -10
  96. package/lib/src/generated/rest/DecoratedLinkExpression.js +0 -1
  97. package/lib/src/generated/rest/DisposeQueryRequest.d.ts +0 -3
  98. package/lib/src/generated/rest/DisposeQueryRequest.js +0 -2
  99. package/lib/src/generated/rest/EmailTestRequest.d.ts +0 -6
  100. package/lib/src/generated/rest/EmailTestRequest.js +0 -2
  101. package/lib/src/generated/rest/EmbedRequest.d.ts +0 -4
  102. package/lib/src/generated/rest/EmbedRequest.js +0 -2
  103. package/lib/src/generated/rest/EntanglementProofInput.d.ts +0 -6
  104. package/lib/src/generated/rest/EntanglementProofInput.js +0 -2
  105. package/lib/src/generated/rest/EntanglementProofPreflightRequest.d.ts +0 -4
  106. package/lib/src/generated/rest/EntanglementProofPreflightRequest.js +0 -2
  107. package/lib/src/generated/rest/ExecuteCommandsRequest.d.ts +0 -4
  108. package/lib/src/generated/rest/ExecuteCommandsRequest.js +0 -2
  109. package/lib/src/generated/rest/ExportRequest.d.ts +0 -5
  110. package/lib/src/generated/rest/ExportRequest.js +0 -2
  111. package/lib/src/generated/rest/ExpressionManyRequest.d.ts +0 -3
  112. package/lib/src/generated/rest/ExpressionManyRequest.js +0 -2
  113. package/lib/src/generated/rest/ExpressionProof.d.ts +0 -4
  114. package/lib/src/generated/rest/ExpressionProof.js +0 -2
  115. package/lib/src/generated/rest/ExpressionProofInput.d.ts +0 -6
  116. package/lib/src/generated/rest/ExpressionProofInput.js +0 -2
  117. package/lib/src/generated/rest/FriendSendMessageRequest.d.ts +0 -3
  118. package/lib/src/generated/rest/FriendSendMessageRequest.js +0 -2
  119. package/lib/src/generated/rest/FriendsListRequest.d.ts +0 -3
  120. package/lib/src/generated/rest/FriendsListRequest.js +0 -2
  121. package/lib/src/generated/rest/GenerateAgentRequest.d.ts +0 -3
  122. package/lib/src/generated/rest/GenerateAgentRequest.js +0 -2
  123. package/lib/src/generated/rest/GenerateJwtRequest.d.ts +0 -4
  124. package/lib/src/generated/rest/GenerateJwtRequest.js +0 -2
  125. package/lib/src/generated/rest/GetSubjectDataRequest.d.ts +0 -4
  126. package/lib/src/generated/rest/GetSubjectDataRequest.js +0 -2
  127. package/lib/src/generated/rest/HostingInfoResponse.d.ts +0 -5
  128. package/lib/src/generated/rest/HostingInfoResponse.js +0 -2
  129. package/lib/src/generated/rest/HostingWalletResponse.d.ts +0 -4
  130. package/lib/src/generated/rest/HostingWalletResponse.js +0 -2
  131. package/lib/src/generated/rest/ImportAgentRequest.d.ts +0 -6
  132. package/lib/src/generated/rest/ImportAgentRequest.js +0 -2
  133. package/lib/src/generated/rest/ImportRequest.d.ts +0 -4
  134. package/lib/src/generated/rest/ImportRequest.js +0 -2
  135. package/lib/src/generated/rest/JoinNeighbourhoodRequest.d.ts +0 -3
  136. package/lib/src/generated/rest/JoinNeighbourhoodRequest.js +0 -2
  137. package/lib/src/generated/rest/KeepAliveQueryRequest.d.ts +0 -3
  138. package/lib/src/generated/rest/KeepAliveQueryRequest.js +0 -2
  139. package/lib/src/generated/rest/LanguageMetaInput.d.ts +0 -6
  140. package/lib/src/generated/rest/LanguageMetaInput.js +0 -2
  141. package/lib/src/generated/rest/Link.d.ts +0 -5
  142. package/lib/src/generated/rest/Link.js +0 -2
  143. package/lib/src/generated/rest/LinkExpression.d.ts +0 -10
  144. package/lib/src/generated/rest/LinkExpression.js +0 -1
  145. package/lib/src/generated/rest/LinkExpressionInput.d.ts +0 -10
  146. package/lib/src/generated/rest/LinkExpressionInput.js +0 -1
  147. package/lib/src/generated/rest/LinkInput.d.ts +0 -5
  148. package/lib/src/generated/rest/LinkInput.js +0 -2
  149. package/lib/src/generated/rest/LinkLanguageTemplatesRequest.d.ts +0 -3
  150. package/lib/src/generated/rest/LinkLanguageTemplatesRequest.js +0 -2
  151. package/lib/src/generated/rest/LinkMutationRequest.d.ts +0 -12
  152. package/lib/src/generated/rest/LinkMutationRequest.js +0 -1
  153. package/lib/src/generated/rest/LinkMutationResponse.d.ts +0 -9
  154. package/lib/src/generated/rest/LinkMutationResponse.js +0 -1
  155. package/lib/src/generated/rest/LinkMutations.d.ts +0 -6
  156. package/lib/src/generated/rest/LinkMutations.js +0 -1
  157. package/lib/src/generated/rest/LinkMutationsRequest.d.ts +0 -5
  158. package/lib/src/generated/rest/LinkMutationsRequest.js +0 -1
  159. package/lib/src/generated/rest/LinkStatus.d.ts +0 -1
  160. package/lib/src/generated/rest/LinkStatus.js +0 -2
  161. package/lib/src/generated/rest/LinkUpdateInput.d.ts +0 -5
  162. package/lib/src/generated/rest/LinkUpdateInput.js +0 -1
  163. package/lib/src/generated/rest/LockAgentRequest.d.ts +0 -3
  164. package/lib/src/generated/rest/LockAgentRequest.js +0 -2
  165. package/lib/src/generated/rest/LoginUserRequest.d.ts +0 -5
  166. package/lib/src/generated/rest/LoginUserRequest.js +0 -2
  167. package/lib/src/generated/rest/ModelType.d.ts +0 -1
  168. package/lib/src/generated/rest/ModelType.js +0 -2
  169. package/lib/src/generated/rest/NotificationGrantRequest.d.ts +0 -3
  170. package/lib/src/generated/rest/NotificationGrantRequest.js +0 -2
  171. package/lib/src/generated/rest/NotificationInput.d.ts +0 -10
  172. package/lib/src/generated/rest/NotificationInput.js +0 -2
  173. package/lib/src/generated/rest/OpenLinkRequest.d.ts +0 -3
  174. package/lib/src/generated/rest/OpenLinkRequest.js +0 -2
  175. package/lib/src/generated/rest/PermitCapabilityRequest.d.ts +0 -3
  176. package/lib/src/generated/rest/PermitCapabilityRequest.js +0 -2
  177. package/lib/src/generated/rest/PerspectiveInput.d.ts +0 -4
  178. package/lib/src/generated/rest/PerspectiveInput.js +0 -1
  179. package/lib/src/generated/rest/PromptRequest.d.ts +0 -4
  180. package/lib/src/generated/rest/PromptRequest.js +0 -2
  181. package/lib/src/generated/rest/PublicPerspectiveInput.d.ts +0 -4
  182. package/lib/src/generated/rest/PublicPerspectiveInput.js +0 -1
  183. package/lib/src/generated/rest/PublishLanguageRequest.d.ts +0 -5
  184. package/lib/src/generated/rest/PublishLanguageRequest.js +0 -1
  185. package/lib/src/generated/rest/PublishNeighbourhoodRequest.d.ts +0 -6
  186. package/lib/src/generated/rest/PublishNeighbourhoodRequest.js +0 -1
  187. package/lib/src/generated/rest/QueryRequest.d.ts +0 -7
  188. package/lib/src/generated/rest/QueryRequest.js +0 -2
  189. package/lib/src/generated/rest/RemoveLinkRequest.d.ts +0 -5
  190. package/lib/src/generated/rest/RemoveLinkRequest.js +0 -1
  191. package/lib/src/generated/rest/RemoveLinksBulkRequest.d.ts +0 -5
  192. package/lib/src/generated/rest/RemoveLinksBulkRequest.js +0 -1
  193. package/lib/src/generated/rest/RequestCapabilityRequest.d.ts +0 -4
  194. package/lib/src/generated/rest/RequestCapabilityRequest.js +0 -1
  195. package/lib/src/generated/rest/RequestPaymentRequest.d.ts +0 -3
  196. package/lib/src/generated/rest/RequestPaymentRequest.js +0 -2
  197. package/lib/src/generated/rest/RequestVerificationRequest.d.ts +0 -4
  198. package/lib/src/generated/rest/RequestVerificationRequest.js +0 -2
  199. package/lib/src/generated/rest/ResourceInput.d.ts +0 -4
  200. package/lib/src/generated/rest/ResourceInput.js +0 -2
  201. package/lib/src/generated/rest/SetDefaultModelRequest.d.ts +0 -4
  202. package/lib/src/generated/rest/SetDefaultModelRequest.js +0 -1
  203. package/lib/src/generated/rest/SetFreeHostingEnabledRequest.d.ts +0 -3
  204. package/lib/src/generated/rest/SetFreeHostingEnabledRequest.js +0 -2
  205. package/lib/src/generated/rest/SetHotWalletAddressRequest.d.ts +0 -3
  206. package/lib/src/generated/rest/SetHotWalletAddressRequest.js +0 -2
  207. package/lib/src/generated/rest/SetMultiUserRequest.d.ts +0 -3
  208. package/lib/src/generated/rest/SetMultiUserRequest.js +0 -2
  209. package/lib/src/generated/rest/SetOnlineStatusRequest.d.ts +0 -5
  210. package/lib/src/generated/rest/SetOnlineStatusRequest.js +0 -1
  211. package/lib/src/generated/rest/SetStatusRequest.d.ts +0 -3
  212. package/lib/src/generated/rest/SetStatusRequest.js +0 -2
  213. package/lib/src/generated/rest/SetUserFreeAccessRequest.d.ts +0 -4
  214. package/lib/src/generated/rest/SetUserFreeAccessRequest.js +0 -2
  215. package/lib/src/generated/rest/SignMessageRequest.d.ts +0 -3
  216. package/lib/src/generated/rest/SignMessageRequest.js +0 -2
  217. package/lib/src/generated/rest/SignalRequest.d.ts +0 -6
  218. package/lib/src/generated/rest/SignalRequest.js +0 -1
  219. package/lib/src/generated/rest/SubscribeQueryRequest.d.ts +0 -3
  220. package/lib/src/generated/rest/SubscribeQueryRequest.js +0 -2
  221. package/lib/src/generated/rest/SubscribeQueryResponse.d.ts +0 -4
  222. package/lib/src/generated/rest/SubscribeQueryResponse.js +0 -2
  223. package/lib/src/generated/rest/TrustedAgentsRequest.d.ts +0 -3
  224. package/lib/src/generated/rest/TrustedAgentsRequest.js +0 -2
  225. package/lib/src/generated/rest/UnlockAgentRequest.d.ts +0 -4
  226. package/lib/src/generated/rest/UnlockAgentRequest.js +0 -2
  227. package/lib/src/generated/rest/UpdateLinkRequest.d.ts +0 -7
  228. package/lib/src/generated/rest/UpdateLinkRequest.js +0 -1
  229. package/lib/src/generated/rest/UpdatePerspectiveRequest.d.ts +0 -3
  230. package/lib/src/generated/rest/UpdatePerspectiveRequest.js +0 -2
  231. package/lib/src/generated/rest/UpdateProfileRequest.d.ts +0 -5
  232. package/lib/src/generated/rest/UpdateProfileRequest.js +0 -1
  233. package/lib/src/generated/rest/UserStatistics.d.ts +0 -9
  234. package/lib/src/generated/rest/UserStatistics.js +0 -2
  235. package/lib/src/generated/rest/VerificationRequestResult.d.ts +0 -6
  236. package/lib/src/generated/rest/VerificationRequestResult.js +0 -2
  237. package/lib/src/generated/rest/VerifyEmailRequest.d.ts +0 -6
  238. package/lib/src/generated/rest/VerifyEmailRequest.js +0 -2
  239. package/lib/src/generated/rest/VerifySignatureRequest.d.ts +0 -5
  240. package/lib/src/generated/rest/VerifySignatureRequest.js +0 -2
  241. package/lib/src/generated/rest/WriteSettingsRequest.d.ts +0 -3
  242. package/lib/src/generated/rest/WriteSettingsRequest.js +0 -2
  243. package/lib/src/generated/rest/index.d.ts +0 -73
  244. package/lib/src/generated/rest/index.js +0 -8
  245. package/lib/src/generated/rest/routes.d.ts +0 -587
  246. package/lib/src/generated/rest/routes.js +0 -3
  247. package/lib/src/model/query-surreal.d.ts +0 -44
  248. package/lib/src/model/query-surreal.js +0 -249
  249. package/lib/src/model/surreal-utils.d.ts +0 -42
  250. package/lib/src/model/surreal-utils.js +0 -128
  251. package/lib/src/perspectives/PerspectiveProxy.test.d.ts +0 -1
  252. package/lib/src/perspectives/PerspectiveProxy.test.js +0 -34
  253. package/lib/src/restClient.d.ts +0 -52
  254. package/lib/src/restClient.js +0 -227
@@ -0,0 +1,336 @@
1
+ /**
2
+ * `FlowInstance` — object-oriented wrapper for a running flow.
3
+ *
4
+ * Design authority: `docs/flow-interpretation-hints-design.md` §4.3.
5
+ *
6
+ * Wraps two on-graph objects:
7
+ *
8
+ * - `FlowInstanceRecord` — the raw @Model row minted by
9
+ * {@link FlowInstance.start}; carries `flow`, `subject`, `currentState`,
10
+ * and Ad4mModel's synthesised `createdAt`.
11
+ * - `SHACLFlow` — the flow definition the record is bound to. Held so
12
+ * `availableTransitions` / `currentState` object lookups don't require
13
+ * a per-call round-trip.
14
+ *
15
+ * Construct via the class factories — {@link FlowInstance.start} for the
16
+ * mint path and {@link FlowInstance.findAll} for the read path — rather
17
+ * than the `wrap` escape hatch, which exists for tests that already own
18
+ * a matched (record, shape) pair.
19
+ *
20
+ * # What's here vs. what's coming in §7 / slice 10.6
21
+ *
22
+ * Read surface (implemented today, PR #929):
23
+ * - `uri`, `subject`, `flowName`, `currentStateName`, `startedAtMillis`
24
+ * accessors.
25
+ * - `currentState` — resolves the `FlowState` on the shape whose name
26
+ * matches `record.currentState`.
27
+ * - `availableTransitions` — filters `shape.transitions` by `fromState`.
28
+ * - `proposals()` — queries `FlowTransitionProposal` records that
29
+ * target this instance's URI.
30
+ *
31
+ * Mutations + subscriptions (`proposeTransition`, `accept`, `reject`,
32
+ * `fireAction`, `onStateChange`, `onProposalAdded`, `onProposalResolved`)
33
+ * land with the consensus-engine slice (§4.3 / slice 10.6). Rather than
34
+ * ship them as `throw new Error("not yet")` stubs — which is a type-level
35
+ * lie the caller only discovers at runtime — they are simply absent from
36
+ * this class until the engine is wired.
37
+ */
38
+ import { Ad4mModel } from "../model/Ad4mModel";
39
+ import { FlowInstanceRecord, FlowTransitionProposal } from "./FlowModels";
40
+ /**
41
+ * Extract the flow's human-readable name from its canonical URI.
42
+ *
43
+ * `SHACLFlow.flowUri` is `${namespace}${name}Flow` (e.g.
44
+ * `coasys://DeliveryFlow`). This function strips the `Flow` suffix and
45
+ * everything before the last URI-segment separator (`/` or `#`), leaving
46
+ * the bare name. Returns `undefined` for URIs that don't match the
47
+ * `…{name}Flow` shape — a stale FlowInstanceRecord whose flow URI came
48
+ * from an older writer, for instance.
49
+ */
50
+ function flowNameFromUri(flowUri) {
51
+ if (!flowUri.endsWith("Flow"))
52
+ return undefined;
53
+ const withoutSuffix = flowUri.slice(0, -"Flow".length);
54
+ const sepIdx = Math.max(withoutSuffix.lastIndexOf("/"), withoutSuffix.lastIndexOf("#"));
55
+ if (sepIdx < 0)
56
+ return withoutSuffix || undefined;
57
+ const name = withoutSuffix.slice(sepIdx + 1);
58
+ return name || undefined;
59
+ }
60
+ export class FlowInstance {
61
+ /**
62
+ * Private constructor — construct via {@link FlowInstance.start} or
63
+ * {@link FlowInstance.findAll}. {@link FlowInstance.wrap} is the
64
+ * escape hatch for tests / direct construction cases.
65
+ */
66
+ constructor(perspective,
67
+ /** The flow definition this instance was minted against. */
68
+ shape,
69
+ /**
70
+ * The on-graph record — carries `flow`, `subject`, `currentState`
71
+ * and Ad4mModel's synthesised `createdAt`. Callers can reach into it
72
+ * for anything the wrapper doesn't expose directly, but should prefer
73
+ * the wrapper accessors so future refactors of the underlying shape
74
+ * don't ripple through their code.
75
+ */
76
+ record) {
77
+ this.perspective = perspective;
78
+ this.shape = shape;
79
+ this.record = record;
80
+ }
81
+ /**
82
+ * Escape hatch used by {@link FlowInstance.start} and
83
+ * {@link FlowInstance.findAll} — not meant for general use, but public
84
+ * so tests that already own a `FlowInstanceRecord + SHACLFlow` pair
85
+ * (e.g. from pre-populated fixtures) can build a wrapper without
86
+ * going through the mint path.
87
+ */
88
+ static wrap(perspective, shape, record) {
89
+ return new FlowInstance(perspective, shape, record);
90
+ }
91
+ /**
92
+ * Mint a new `FlowInstance` on the given perspective (design doc §4.3).
93
+ *
94
+ * Idempotently registers the hardwired `FlowInstanceRecord` +
95
+ * `FlowTransitionProposal` @Model classes on first call — the on-graph
96
+ * shape matches the Rust-side hardwired SDNA (parity-locked in
97
+ * `flow-instance.test.ts` / `flow-transition-proposal.test.ts`).
98
+ *
99
+ * The returned wrapper carries the parsed `SHACLFlow` alongside the
100
+ * on-graph record, so `currentState` / `availableTransitions` /
101
+ * `proposals` accessors work without further round-trips. The consensus
102
+ * engine (slice 10.6) will read the record's `currentState` when it
103
+ * fires transitions.
104
+ *
105
+ * @param perspective - The perspective the flow instance lives on
106
+ * @param flowName - Name of a `SHACLFlow` already registered on the perspective
107
+ * @param baseExpression - URI of the subject expression the flow runs on
108
+ * @throws When the flow is unknown or has zero declared states (zero-state
109
+ * flows fire via the forthcoming atomic-action path, §6.3).
110
+ */
111
+ static async start(perspective, flowName, baseExpression) {
112
+ const flow = await perspective.getFlow(flowName);
113
+ if (!flow)
114
+ throw `Flow "${flowName}" not found`;
115
+ if (flow.states.length === 0) {
116
+ throw `Flow "${flowName}" has no states — FlowInstance.start is for stateful flows only; zero-state flows fire via the forthcoming atomic-action path (§6.3)`;
117
+ }
118
+ // Register the hardwired runtime classes if this is the first flow
119
+ // instance on the perspective. registerAll is a single batched RPC and
120
+ // no-ops when both classes are already present.
121
+ await Ad4mModel.registerAll(perspective, [FlowInstanceRecord, FlowTransitionProposal]);
122
+ // Property keys must be the FlowInstanceRecord @Model field names —
123
+ // `subject` (not `baseExpression`, which collides with Ad4mModel's
124
+ // synthetic hydration field and would be silently shadowed on read).
125
+ // No explicit start-time field: Ad4mModel synthesises `createdAt` on
126
+ // hydration from the earliest link timestamp on the instance's URI.
127
+ // Convention: `SHACLFlow.states` is stored sorted ascending by `value`
128
+ // (enforced by `fromLinks`), so `states[0]` is the initial state. A
129
+ // flow author who wants a specific state as the entry point must give
130
+ // it the lowest `value` in the set.
131
+ //
132
+ // Store the flow's URI, not the bare name — see FlowInstanceRecord's
133
+ // docstring for the collision-across-modules argument (James PR #929 R5).
134
+ const record = await FlowInstanceRecord.create(perspective, {
135
+ flowUri: flow.flowUri,
136
+ subject: baseExpression,
137
+ currentState: flow.states[0].name,
138
+ });
139
+ return FlowInstance.wrap(perspective, flow, record);
140
+ }
141
+ /**
142
+ * Return every live `FlowInstance` on the perspective (design doc §4.3).
143
+ *
144
+ * Read-only path: never registers classes. On a perspective that has
145
+ * never minted a flow instance, the `FlowInstanceRecord` SHACL shape
146
+ * isn't installed yet — this returns `[]` in that case rather than
147
+ * mutating the perspective. Registration is the responsibility of
148
+ * {@link FlowInstance.start}, which is the write path. (Registering on
149
+ * a read would sync a write to every peer in the neighbourhood —
150
+ * exactly what a query must not do — James PR #929 R7.)
151
+ *
152
+ * Filter surface (all optional, all combinable):
153
+ * - **`flowName`** — narrows by flow-name discriminator (e.g. "Delivery")
154
+ * - **`subject`** — narrows by base-expression URI, i.e. "give me every
155
+ * flow running on THIS expression"
156
+ *
157
+ * Both filters translate to a single SHACL `where`-filter round-trip
158
+ * (no client-side filtering); combining them AND-joins server-side.
159
+ * The string-arg shape (`FlowInstance.findAll(p, "Delivery")`) is
160
+ * shorthand for `{ flowName: "Delivery" }`.
161
+ *
162
+ * Records whose `flow` value has no matching `SHACLFlow` on the
163
+ * perspective (e.g. the flow was unregistered) are silently skipped —
164
+ * the wrapper can't answer `currentState` / `availableTransitions`
165
+ * without the shape, and callers routinely iterate the returned array
166
+ * without null-checks.
167
+ *
168
+ * @example
169
+ * ```typescript
170
+ * const all = await FlowInstance.findAll(perspective);
171
+ * const deliveries = await FlowInstance.findAll(perspective, "Delivery");
172
+ * const onThisTask = await FlowInstance.findAll(perspective, {
173
+ * subject: "ad4m://task/1",
174
+ * });
175
+ * const deliveriesOnTask = await FlowInstance.findAll(perspective, {
176
+ * flowName: "Delivery",
177
+ * subject: "ad4m://task/1",
178
+ * });
179
+ * ```
180
+ */
181
+ static async findAll(perspective, filter) {
182
+ const { flowName, subject } = typeof filter === "string"
183
+ ? { flowName: filter, subject: undefined }
184
+ : { flowName: filter?.flowName, subject: filter?.subject };
185
+ // Filter surface accepts a flow *name* for ergonomics — resolve it to
186
+ // the canonical URI before the SHACL query, since the record stores
187
+ // the URI (James PR #929 R5). Unknown name → no matches (short-circuit
188
+ // with an empty result rather than issuing a bare-name query that
189
+ // would silently return nothing anyway).
190
+ const where = {};
191
+ if (flowName !== undefined) {
192
+ const flow = await perspective.getFlow(flowName);
193
+ if (!flow)
194
+ return [];
195
+ where.flowUri = flow.flowUri;
196
+ }
197
+ if (subject !== undefined)
198
+ where.subject = subject;
199
+ // "Shape not found" on a perspective that has never minted a flow
200
+ // instance is a no-op read, not an error — the executor throws for a
201
+ // missing SHACL shape and there is no side-effect-free way to ask
202
+ // "does this class exist". Return `[]` on that specific case; rethrow
203
+ // anything else so real infra failures don't get swallowed.
204
+ //
205
+ // Regex covers every message the executor + client stack raises for
206
+ // an unregistered class:
207
+ // "No SHACL shape stored for class 'FlowInstance'." (executor RPC)
208
+ // "Shape not found" (older Rust path)
209
+ // "class not registered" / "not registered" (TS Ad4mModel guard)
210
+ let records;
211
+ try {
212
+ records =
213
+ Object.keys(where).length > 0
214
+ ? await FlowInstanceRecord.findAll(perspective, { where })
215
+ : await FlowInstanceRecord.findAll(perspective);
216
+ }
217
+ catch (e) {
218
+ const msg = e instanceof Error ? e.message : String(e);
219
+ if (/no shacl shape stored|shape not found|class not registered|not registered/i.test(msg)) {
220
+ return [];
221
+ }
222
+ throw e;
223
+ }
224
+ // Pair each record with its parsed SHACLFlow. Cache lookups by
225
+ // flow-URI so `getFlow` fires at most once per distinct flow —
226
+ // matters when a perspective has hundreds of instances against
227
+ // one shape.
228
+ //
229
+ // The URI stored on the record is `${namespace}${name}Flow`
230
+ // (see SHACLFlow.flowUri) — recovering the name for `getFlow`
231
+ // means stripping the namespace + the `Flow` suffix. Records that
232
+ // don't parse this way are treated as stale and skipped.
233
+ const shapesByUri = new Map();
234
+ const wrappers = [];
235
+ for (const record of records) {
236
+ let shape = shapesByUri.get(record.flowUri);
237
+ if (!shape) {
238
+ const name = flowNameFromUri(record.flowUri);
239
+ if (!name)
240
+ continue;
241
+ const loaded = await perspective.getFlow(name);
242
+ if (!loaded || loaded.flowUri !== record.flowUri) {
243
+ // Stale record — the flow it references was unregistered,
244
+ // or a different flow now owns that name.
245
+ continue;
246
+ }
247
+ shape = loaded;
248
+ shapesByUri.set(record.flowUri, shape);
249
+ }
250
+ wrappers.push(FlowInstance.wrap(perspective, shape, record));
251
+ }
252
+ return wrappers;
253
+ }
254
+ // ── Read accessors ────────────────────────────────────────────────────
255
+ /**
256
+ * URI of the on-graph `FlowInstance` node — `ad4m://flow/instance/{id}`.
257
+ *
258
+ * Sourced from `Ad4mModel`'s synthesised `baseExpression`, which for
259
+ * `FlowInstanceRecord` *is* the instance's own URI (the value
260
+ * `FlowTransitionProposal.flowInstance` references).
261
+ */
262
+ get uri() {
263
+ return this.record.baseExpression;
264
+ }
265
+ /**
266
+ * URI of the base expression this flow runs on — matches the
267
+ * `SHACLFlow.inputTypes` that {@link PerspectiveProxy.availableFlows}
268
+ * would greenlight for this expression.
269
+ */
270
+ get subject() {
271
+ return this.record.subject;
272
+ }
273
+ /**
274
+ * Human-readable flow name — the display label. Sourced from the paired
275
+ * `SHACLFlow.name`, not from the record (which stores the URI as its
276
+ * canonical identity — see FlowInstanceRecord's docstring for why).
277
+ */
278
+ get flowName() {
279
+ return this.shape.name;
280
+ }
281
+ /** Flow URI — the on-graph discriminator, collision-free across modules. */
282
+ get flowUri() {
283
+ return this.record.flowUri;
284
+ }
285
+ /** Name of the state this instance is currently in. */
286
+ get currentStateName() {
287
+ return this.record.currentState;
288
+ }
289
+ /**
290
+ * ISO-8601 (epoch millis after Ad4mModel hydration) start time.
291
+ * Returns `undefined` when hydration didn't produce a `createdAt`
292
+ * — rare, but not fatal.
293
+ */
294
+ get startedAtMillis() {
295
+ const v = this.record.createdAt;
296
+ return typeof v === "number" ? v : undefined;
297
+ }
298
+ /**
299
+ * The `FlowState` object on the shape matching `currentStateName`.
300
+ * Throws when the record's state name is not declared on the flow —
301
+ * that's a "stale FlowInstance whose flow was edited under it" bug,
302
+ * not a silent-fail case.
303
+ */
304
+ get currentState() {
305
+ const s = this.shape.states.find((x) => x.name === this.currentStateName);
306
+ if (!s) {
307
+ throw new Error(`FlowInstance ${this.uri}: currentState "${this.currentStateName}" is not declared on flow "${this.flowName}". ` +
308
+ `Known states: ${this.shape.states.map((x) => x.name).join(", ") || "(none)"}`);
309
+ }
310
+ return s;
311
+ }
312
+ /**
313
+ * Every `FlowTransition` on the shape whose `fromState` matches
314
+ * `currentStateName`. Order preserved from the shape.
315
+ *
316
+ * Empty when the current state is terminal (no outgoing transitions).
317
+ */
318
+ get availableTransitions() {
319
+ return this.shape.transitions.filter((t) => t.fromState === this.currentStateName);
320
+ }
321
+ /**
322
+ * All `FlowTransitionProposal` records targeting this instance's URI.
323
+ *
324
+ * Uses the SDNA identity discriminator (`ad4m://flow/instance` predicate)
325
+ * for the where-filter — one SPARQL round-trip, no client-side
326
+ * filtering.
327
+ *
328
+ * Note: the consensus engine (slice 10.6) will start writing these; today
329
+ * they only exist when a client wrote one directly (or a test seeded one).
330
+ */
331
+ async proposals() {
332
+ return FlowTransitionProposal.findAll(this.perspective, {
333
+ where: { flowInstance: this.uri },
334
+ });
335
+ }
336
+ }
@@ -0,0 +1,94 @@
1
+ /**
2
+ * TypeScript @Model classes mirroring the Rust-side hardwired SDNA for the
3
+ * flow runtime. Apps can import these to query the perspective graph for
4
+ * pending flow-transition proposals without knowing the raw link predicates.
5
+ *
6
+ * Registration:
7
+ * await FlowTransitionProposal.register(perspective);
8
+ *
9
+ * Querying:
10
+ * const pending = await FlowTransitionProposal.findAll(perspective);
11
+ *
12
+ * Slice 5/7 of the flow-implementation arc (design doc §4.2). The Rust
13
+ * engine does not yet mint these — that lands with the consensus firing
14
+ * work in a later PR arc. This class defines the on-graph shape so:
15
+ * - clients can build UI over proposals immediately (Deliberation demo);
16
+ * - the SDNA-parity test locks TS/Rust drift the moment the JSON exists
17
+ * (`rust-executor/src/perspectives/hardwired_sdna/flow_transition_proposal.json`);
18
+ * - the engine can start writing into this shape when consensus lands
19
+ * without touching the client-side surface.
20
+ */
21
+ import { Ad4mModel } from "../model/Ad4mModel";
22
+ export declare class FlowTransitionProposal extends Ad4mModel {
23
+ /**
24
+ * URI of the running `FlowInstance` this proposal targets. First-declared
25
+ * property so `buildSHACL` derives the shape namespace from its `through`
26
+ * prefix — `ad4m://flow/instance` → `ad4m://` → target_class
27
+ * `ad4m://FlowTransitionProposal`. Also the identity predicate: the
28
+ * discriminator `findAll` uses to isolate proposal nodes.
29
+ */
30
+ flowInstance: string;
31
+ /** Name of the state the flow instance is currently in. */
32
+ fromState: string;
33
+ /** Name of the state the proposal wants to transition to. */
34
+ toState: string;
35
+ /** DID of the agent that issued the proposal. */
36
+ proposer: string;
37
+ /**
38
+ * URIs of instances offered as evidence that `toState.requires` is now
39
+ * satisfied. Multiple links, one per cited instance; ordering is not
40
+ * significant.
41
+ */
42
+ evidence: string[];
43
+ /**
44
+ * JSON blob: `{ [uri]: sha256_hex }` — one entry per evidence URI, hashing
45
+ * the canonicalized graph-visible properties (sorted by property URI,
46
+ * multi-values sorted lexicographically) at proposal time. Downstream
47
+ * verifiers use it to detect edits to cited instances after the proposal
48
+ * was written. Stored as an opaque string because SHACL properties carry
49
+ * no rich-object type; the engine parses it back into a map.
50
+ */
51
+ evidenceHashes: string;
52
+ /**
53
+ * URI of the `InterpretationRun` node that produced this proposal, when
54
+ * the proposal came from an LLM extraction pass. Absent when a human
55
+ * clicked "propose" in the UI or an external tool wrote the proposal
56
+ * directly.
57
+ */
58
+ runUri?: string;
59
+ /**
60
+ * Free-form human-readable justification. Optional — the LLM includes it
61
+ * when it wants to explain *why* the cited evidence satisfies the state's
62
+ * `requires`; the UI shows it to reviewers.
63
+ */
64
+ rationale?: string;
65
+ }
66
+ export declare class FlowInstanceRecord extends Ad4mModel {
67
+ /**
68
+ * URI of the `SHACLFlow` this instance runs — the flow's canonical
69
+ * identity, collision-free across social-DNA modules from different
70
+ * communities (bare names WILL collide once shared flows are adopted
71
+ * cross-team — James PR #929 R5). Sourced from `SHACLFlow.flowUri`
72
+ * (which is `${namespace}${name}Flow`, e.g. `coasys://DeliveryFlow`).
73
+ *
74
+ * First-declared property so `buildSHACL` derives the shape namespace
75
+ * from its `through` prefix — `ad4m://flow/flow_uri` → `ad4m://` →
76
+ * target_class `ad4m://FlowInstance`. Also the discriminator predicate
77
+ * `findAll` uses to isolate instance nodes.
78
+ *
79
+ * The human-readable flow name is still available on the paired
80
+ * `SHACLFlow` (via `perspective.getFlow(record.flowUri.split('/').pop()!.replace(/Flow$/,''))`,
81
+ * or more commonly via the `FlowInstance` wrapper's `flowName` getter).
82
+ */
83
+ flowUri: string;
84
+ /**
85
+ * URI of the subject expression this flow runs on.
86
+ * Named `subject` (not `baseExpression`) because `Ad4mModel` reserves
87
+ * `baseExpression` as a synthetic hydration field always set to the
88
+ * instance's own URI — a subclass property with that name is shadowed
89
+ * on read.
90
+ */
91
+ subject: string;
92
+ /** Name of the state the flow is currently in. */
93
+ currentState: string;
94
+ }
@@ -0,0 +1,182 @@
1
+ /**
2
+ * TypeScript @Model classes mirroring the Rust-side hardwired SDNA for the
3
+ * flow runtime. Apps can import these to query the perspective graph for
4
+ * pending flow-transition proposals without knowing the raw link predicates.
5
+ *
6
+ * Registration:
7
+ * await FlowTransitionProposal.register(perspective);
8
+ *
9
+ * Querying:
10
+ * const pending = await FlowTransitionProposal.findAll(perspective);
11
+ *
12
+ * Slice 5/7 of the flow-implementation arc (design doc §4.2). The Rust
13
+ * engine does not yet mint these — that lands with the consensus firing
14
+ * work in a later PR arc. This class defines the on-graph shape so:
15
+ * - clients can build UI over proposals immediately (Deliberation demo);
16
+ * - the SDNA-parity test locks TS/Rust drift the moment the JSON exists
17
+ * (`rust-executor/src/perspectives/hardwired_sdna/flow_transition_proposal.json`);
18
+ * - the engine can start writing into this shape when consensus lands
19
+ * without touching the client-side surface.
20
+ */
21
+ var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
22
+ var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
23
+ if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
24
+ else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
25
+ return c > 3 && r && Object.defineProperty(target, key, r), r;
26
+ };
27
+ var __metadata = (this && this.__metadata) || function (k, v) {
28
+ if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
29
+ };
30
+ import { Ad4mModel } from "../model/Ad4mModel";
31
+ import { HasMany, Optional, Property } from "../model/decorators";
32
+ import { Model } from "../model/decorators";
33
+ // ── FlowTransitionProposal ──────────────────────────────────────────────────
34
+ // Mirrors the Rust hardwired `flow_transition_proposal.json` SDNA (once wired
35
+ // on the engine side; see file header). One node per proposed transition; the
36
+ // URI is `ad4m://flow/proposal/<uuid>` when the engine mints it, but the class
37
+ // carries no URI-format constraint — apps constructing proposals directly may
38
+ // choose any URI they can defend as unique.
39
+ let FlowTransitionProposal = class FlowTransitionProposal extends Ad4mModel {
40
+ constructor() {
41
+ super(...arguments);
42
+ /**
43
+ * URI of the running `FlowInstance` this proposal targets. First-declared
44
+ * property so `buildSHACL` derives the shape namespace from its `through`
45
+ * prefix — `ad4m://flow/instance` → `ad4m://` → target_class
46
+ * `ad4m://FlowTransitionProposal`. Also the identity predicate: the
47
+ * discriminator `findAll` uses to isolate proposal nodes.
48
+ */
49
+ this.flowInstance = "";
50
+ /** Name of the state the flow instance is currently in. */
51
+ this.fromState = "";
52
+ /** Name of the state the proposal wants to transition to. */
53
+ this.toState = "";
54
+ /** DID of the agent that issued the proposal. */
55
+ this.proposer = "";
56
+ /**
57
+ * URIs of instances offered as evidence that `toState.requires` is now
58
+ * satisfied. Multiple links, one per cited instance; ordering is not
59
+ * significant.
60
+ */
61
+ this.evidence = [];
62
+ /**
63
+ * JSON blob: `{ [uri]: sha256_hex }` — one entry per evidence URI, hashing
64
+ * the canonicalized graph-visible properties (sorted by property URI,
65
+ * multi-values sorted lexicographically) at proposal time. Downstream
66
+ * verifiers use it to detect edits to cited instances after the proposal
67
+ * was written. Stored as an opaque string because SHACL properties carry
68
+ * no rich-object type; the engine parses it back into a map.
69
+ */
70
+ this.evidenceHashes = "";
71
+ // "When was this proposal written?" is answered by `Ad4mModel`'s built-in
72
+ // `createdAt`, synthesized on hydration from the earliest link timestamp
73
+ // of the proposal's own links (all written together during create_subject).
74
+ }
75
+ };
76
+ __decorate([
77
+ Property({ through: "ad4m://flow/instance", required: true, identity: true }),
78
+ __metadata("design:type", String)
79
+ ], FlowTransitionProposal.prototype, "flowInstance", void 0);
80
+ __decorate([
81
+ Property({ through: "ad4m://flow/from_state", required: true }),
82
+ __metadata("design:type", String)
83
+ ], FlowTransitionProposal.prototype, "fromState", void 0);
84
+ __decorate([
85
+ Property({ through: "ad4m://flow/to_state", required: true }),
86
+ __metadata("design:type", String)
87
+ ], FlowTransitionProposal.prototype, "toState", void 0);
88
+ __decorate([
89
+ Property({ through: "ad4m://flow/proposer", required: true }),
90
+ __metadata("design:type", String)
91
+ ], FlowTransitionProposal.prototype, "proposer", void 0);
92
+ __decorate([
93
+ HasMany({ through: "ad4m://flow/evidence", datatype: "xsd:string" }),
94
+ __metadata("design:type", Array)
95
+ ], FlowTransitionProposal.prototype, "evidence", void 0);
96
+ __decorate([
97
+ Property({ through: "ad4m://flow/evidence_hashes", required: true }),
98
+ __metadata("design:type", String)
99
+ ], FlowTransitionProposal.prototype, "evidenceHashes", void 0);
100
+ __decorate([
101
+ Optional({ through: "ad4m://flow/run_uri" }),
102
+ __metadata("design:type", String)
103
+ ], FlowTransitionProposal.prototype, "runUri", void 0);
104
+ __decorate([
105
+ Optional({ through: "ad4m://flow/rationale" }),
106
+ __metadata("design:type", String)
107
+ ], FlowTransitionProposal.prototype, "rationale", void 0);
108
+ FlowTransitionProposal = __decorate([
109
+ Model({ name: "FlowTransitionProposal" })
110
+ ], FlowTransitionProposal);
111
+ export { FlowTransitionProposal };
112
+ // ── FlowInstanceRecord ──────────────────────────────────────────────────────
113
+ // On-graph node minted by the engine when a flow is started on a specific
114
+ // base expression. Its URI is the value that `FlowTransitionProposal.flowInstance`
115
+ // references. Mirrors `rust-executor/src/perspectives/hardwired_sdna/flow_instance.json`.
116
+ //
117
+ // Design authority: `docs/flow-interpretation-hints-design.md` §4.3.
118
+ //
119
+ // This class is the raw on-graph record (@Model over the SDNA shape). The
120
+ // object-oriented handle callers work with is `FlowInstance` in
121
+ // `./FlowInstance.ts` — it wraps `FlowInstanceRecord + SHACLFlow definition`
122
+ // and exposes `currentState`, `availableTransitions`, `proposals`, etc.
123
+ // Renamed from `FlowInstance` → `FlowInstanceRecord` on 2026-08-27 per
124
+ // Nico's PR #929 review R2 (the `FlowInstance` name is reserved for the
125
+ // wrapper the design has always specified in §4.3).
126
+ //
127
+ // The SDNA name (`@Model({ name: "FlowInstance" })`) stays unchanged — that
128
+ // keys the on-graph class, not the TS export. Renaming the TS class only
129
+ // changes the JS import surface; the graph shape is identical, and Rust
130
+ // hardwired_sdna/flow_instance.json + all the parity tests still lock down
131
+ // the same `ad4m://FlowInstance` target class.
132
+ let FlowInstanceRecord = class FlowInstanceRecord extends Ad4mModel {
133
+ constructor() {
134
+ super(...arguments);
135
+ /**
136
+ * URI of the `SHACLFlow` this instance runs — the flow's canonical
137
+ * identity, collision-free across social-DNA modules from different
138
+ * communities (bare names WILL collide once shared flows are adopted
139
+ * cross-team — James PR #929 R5). Sourced from `SHACLFlow.flowUri`
140
+ * (which is `${namespace}${name}Flow`, e.g. `coasys://DeliveryFlow`).
141
+ *
142
+ * First-declared property so `buildSHACL` derives the shape namespace
143
+ * from its `through` prefix — `ad4m://flow/flow_uri` → `ad4m://` →
144
+ * target_class `ad4m://FlowInstance`. Also the discriminator predicate
145
+ * `findAll` uses to isolate instance nodes.
146
+ *
147
+ * The human-readable flow name is still available on the paired
148
+ * `SHACLFlow` (via `perspective.getFlow(record.flowUri.split('/').pop()!.replace(/Flow$/,''))`,
149
+ * or more commonly via the `FlowInstance` wrapper's `flowName` getter).
150
+ */
151
+ this.flowUri = "";
152
+ /**
153
+ * URI of the subject expression this flow runs on.
154
+ * Named `subject` (not `baseExpression`) because `Ad4mModel` reserves
155
+ * `baseExpression` as a synthetic hydration field always set to the
156
+ * instance's own URI — a subclass property with that name is shadowed
157
+ * on read.
158
+ */
159
+ this.subject = "";
160
+ /** Name of the state the flow is currently in. */
161
+ this.currentState = "";
162
+ // "When was this flow started?" is answered by `Ad4mModel`'s built-in
163
+ // `createdAt`, synthesized on hydration from the earliest link timestamp
164
+ // of the instance's own links (all written together during `mint_flow_instance`).
165
+ }
166
+ };
167
+ __decorate([
168
+ Property({ through: "ad4m://flow/flow_uri", required: true, identity: true }),
169
+ __metadata("design:type", String)
170
+ ], FlowInstanceRecord.prototype, "flowUri", void 0);
171
+ __decorate([
172
+ Property({ through: "ad4m://flow/base", required: true }),
173
+ __metadata("design:type", String)
174
+ ], FlowInstanceRecord.prototype, "subject", void 0);
175
+ __decorate([
176
+ Property({ through: "ad4m://flow/current_state", required: true }),
177
+ __metadata("design:type", String)
178
+ ], FlowInstanceRecord.prototype, "currentState", void 0);
179
+ FlowInstanceRecord = __decorate([
180
+ Model({ name: "FlowInstance" })
181
+ ], FlowInstanceRecord);
182
+ export { FlowInstanceRecord };
@@ -56,28 +56,19 @@ export declare class AutoProcessorConfig extends Ad4mModel {
56
56
  */
57
57
  mintScope?: string;
58
58
  /**
59
- * Legacy coupled debug knob (`"true"` / `"false"` string). Reserved as a
60
- * backwards-compat scalar: pre-split writes used it as the single flag
61
- * for both LLM I/O persistence AND mid-pass event emission. The Rust
62
- * loader still reads it as a fallback when the specific `persistDebug`
63
- * / `emitDebugEvents` fields are absent. New writes SHOULD prefer the
64
- * split fields (below); this alias is retained so a pre-split peer's
65
- * config still loads with the coupled behaviour it originally requested.
59
+ * Tool-call budget for the interpretation-pass harness. Absent (or `"0"`)
60
+ * = the original single-shot LLM path — one prompt, one parse, no tools.
61
+ * `"N"` (positive integer) = engage the tool-calling harness and let the
62
+ * LLM issue up to N tool calls per pass (query/list/get/propose_create/
63
+ * propose_link_child) before being forced to answer. Stored as a decimal
64
+ * string because SHACL properties carry no numeric type; the Rust
65
+ * watcher parses it back to `u32`.
66
66
  */
67
- debugMode?: string;
67
+ maxToolCalls?: string;
68
68
  /**
69
- * Persist the raw LLM prompt + response on the pass's `InterpretationRun`
70
- * (`debugPrompt` / `debugResponse`). Independent of `emitDebugEvents`
71
- * — Nico's PR #903 split. Absent = fall back to legacy `debugMode` (see
72
- * above); when both are absent, defaults to `"false"`.
73
- */
74
- persistDebug?: string;
75
- /**
76
- * Emit `LlmRequestSent` and `LlmResponseReceived` auto-processor events
77
- * mid-pass, so a subscribed UI can render "waiting on LLM" between
78
- * prompt-send and response-receive. Independent of `persistDebug`.
79
- * Absent = fall back to legacy `debugMode`; when both are absent,
80
- * defaults to `"false"`.
69
+ * Enable full debug observability: persists the raw LLM prompt + response
70
+ * on the pass's `InterpretationRun` AND emits `LlmRequestSent` /
71
+ * `LlmResponseReceived` mid-pass events. `"true"` / `"false"` string.
81
72
  */
82
73
  emitDebugEvents?: string;
83
74
  }
@@ -101,8 +92,7 @@ export declare class InterpretationRun extends Ad4mModel {
101
92
  */
102
93
  sources: string[];
103
94
  /** Raw LLM prompt this pass fed the model. Present only when the pass's
104
- * AutoProcessor had `persistDebug: true` (or the legacy `debugMode: true`
105
- * fallback). Absent by default. */
95
+ * AutoProcessor had `emitDebugEvents: true`. Absent by default. */
106
96
  debugPrompt?: string;
107
97
  /** Raw LLM response this pass received. Same rules as `debugPrompt`. */
108
98
  debugResponse?: string;