@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.
- package/lib/index.cjs +1982 -498
- package/lib/index.js +1982 -499
- package/lib/src/ai/AIClient.js +6 -3
- package/lib/src/apiClient.d.ts +40 -4
- package/lib/src/apiClient.js +149 -9
- package/lib/src/index.d.ts +3 -1
- package/lib/src/index.js +2 -0
- package/lib/src/model/Ad4mModel.d.ts +6 -5
- package/lib/src/model/Ad4mModel.js +246 -29
- package/lib/src/model/Ad4mModel.test.js +480 -735
- package/lib/src/model/decorators.d.ts +147 -4
- package/lib/src/model/decorators.js +70 -24
- package/lib/src/model/model-manifest.d.ts +41 -0
- package/lib/src/model/model-manifest.js +11 -0
- package/lib/src/model/query-sparql.test.js +92 -10
- package/lib/src/model/shacl-gen.js +33 -0
- package/lib/src/model/types.d.ts +9 -0
- package/lib/src/neighbourhood/NeighbourhoodProxy.test.js +33 -33
- package/lib/src/perspectives/AutoProcessor.d.ts +90 -24
- package/lib/src/perspectives/FlowInstance.d.ts +187 -0
- package/lib/src/perspectives/FlowInstance.js +336 -0
- package/lib/src/perspectives/FlowModels.d.ts +94 -0
- package/lib/src/perspectives/FlowModels.js +182 -0
- package/lib/src/perspectives/InterpretationModels.d.ts +12 -22
- package/lib/src/perspectives/InterpretationModels.js +2 -6
- package/lib/src/perspectives/PerspectiveClient.d.ts +68 -7
- package/lib/src/perspectives/PerspectiveClient.js +105 -10
- package/lib/src/perspectives/PerspectiveProxy.d.ts +142 -57
- package/lib/src/perspectives/PerspectiveProxy.js +388 -274
- package/lib/src/shacl/SHACLFlow.d.ts +273 -47
- package/lib/src/shacl/SHACLFlow.js +397 -88
- package/lib/src/shacl/SHACLShape.d.ts +8 -0
- package/lib/src/shacl/SHACLShape.js +17 -0
- package/lib/src/shacl/SHACLShape.test.js +82 -0
- package/package.json +2 -2
- package/src/ai/AIClient.ts +6 -3
- package/src/apiClient.test.ts +227 -0
- package/src/apiClient.ts +185 -9
- package/src/index.ts +3 -1
- package/src/model/Ad4mModel.test.ts +645 -0
- package/src/model/Ad4mModel.ts +245 -26
- package/src/model/decorators.ts +216 -35
- package/src/model/relation-filtering.test.ts +70 -20
- package/src/model/shacl-gen.ts +36 -0
- package/src/model/shacl-roundtrip.test.ts +130 -0
- package/src/model/types.ts +7 -0
- package/src/perspectives/AutoProcessor.ts +94 -24
- package/src/perspectives/FlowInstance.ts +369 -0
- package/src/perspectives/FlowModels.ts +157 -0
- package/src/perspectives/InterpretationModels.ts +13 -25
- package/src/perspectives/PerspectiveClient.test.ts +67 -6
- package/src/perspectives/PerspectiveClient.ts +142 -12
- package/src/perspectives/PerspectiveProxy.test.ts +406 -0
- package/src/perspectives/PerspectiveProxy.ts +459 -289
- package/src/perspectives/shacl-rpc.test.ts +258 -0
- package/src/shacl/SHACLFlow.test.ts +762 -35
- package/src/shacl/SHACLFlow.ts +680 -112
- package/src/shacl/SHACLShape.ts +31 -0
- package/lib/src/generated/rest/AIModelLoadingStatus.d.ts +0 -7
- package/lib/src/generated/rest/AIModelLoadingStatus.js +0 -2
- package/lib/src/generated/rest/AddAgentInfosRequest.d.ts +0 -3
- package/lib/src/generated/rest/AddAgentInfosRequest.js +0 -2
- package/lib/src/generated/rest/AddLinkExpressionRequest.d.ts +0 -6
- package/lib/src/generated/rest/AddLinkExpressionRequest.js +0 -1
- package/lib/src/generated/rest/AddLinkRequest.d.ts +0 -6
- package/lib/src/generated/rest/AddLinkRequest.js +0 -1
- package/lib/src/generated/rest/AddLinksBulkRequest.d.ts +0 -6
- package/lib/src/generated/rest/AddLinksBulkRequest.js +0 -1
- package/lib/src/generated/rest/AddSdnaRequest.d.ts +0 -6
- package/lib/src/generated/rest/AddSdnaRequest.js +0 -2
- package/lib/src/generated/rest/ApplyTemplateRequest.d.ts +0 -4
- package/lib/src/generated/rest/ApplyTemplateRequest.js +0 -2
- package/lib/src/generated/rest/AuthInfoInput.d.ts +0 -10
- package/lib/src/generated/rest/AuthInfoInput.js +0 -1
- package/lib/src/generated/rest/BroadcastRequest.d.ts +0 -6
- package/lib/src/generated/rest/BroadcastRequest.js +0 -1
- package/lib/src/generated/rest/CapabilityInput.d.ts +0 -5
- package/lib/src/generated/rest/CapabilityInput.js +0 -1
- package/lib/src/generated/rest/CommitBatchRequest.d.ts +0 -3
- package/lib/src/generated/rest/CommitBatchRequest.js +0 -2
- package/lib/src/generated/rest/ComputeLogEntry.d.ts +0 -9
- package/lib/src/generated/rest/ComputeLogEntry.js +0 -2
- package/lib/src/generated/rest/CreateExpressionRequest.d.ts +0 -4
- package/lib/src/generated/rest/CreateExpressionRequest.js +0 -2
- package/lib/src/generated/rest/CreatePerspectiveRequest.d.ts +0 -3
- package/lib/src/generated/rest/CreatePerspectiveRequest.js +0 -2
- package/lib/src/generated/rest/CreateSubjectRequest.d.ts +0 -6
- package/lib/src/generated/rest/CreateSubjectRequest.js +0 -2
- package/lib/src/generated/rest/CreateUserRequest.d.ts +0 -4
- package/lib/src/generated/rest/CreateUserRequest.js +0 -2
- package/lib/src/generated/rest/CreateUserResponse.d.ts +0 -5
- package/lib/src/generated/rest/CreateUserResponse.js +0 -2
- package/lib/src/generated/rest/DecoratedExpressionProof.d.ts +0 -6
- package/lib/src/generated/rest/DecoratedExpressionProof.js +0 -2
- package/lib/src/generated/rest/DecoratedLinkExpression.d.ts +0 -10
- package/lib/src/generated/rest/DecoratedLinkExpression.js +0 -1
- package/lib/src/generated/rest/DisposeQueryRequest.d.ts +0 -3
- package/lib/src/generated/rest/DisposeQueryRequest.js +0 -2
- package/lib/src/generated/rest/EmailTestRequest.d.ts +0 -6
- package/lib/src/generated/rest/EmailTestRequest.js +0 -2
- package/lib/src/generated/rest/EmbedRequest.d.ts +0 -4
- package/lib/src/generated/rest/EmbedRequest.js +0 -2
- package/lib/src/generated/rest/EntanglementProofInput.d.ts +0 -6
- package/lib/src/generated/rest/EntanglementProofInput.js +0 -2
- package/lib/src/generated/rest/EntanglementProofPreflightRequest.d.ts +0 -4
- package/lib/src/generated/rest/EntanglementProofPreflightRequest.js +0 -2
- package/lib/src/generated/rest/ExecuteCommandsRequest.d.ts +0 -4
- package/lib/src/generated/rest/ExecuteCommandsRequest.js +0 -2
- package/lib/src/generated/rest/ExportRequest.d.ts +0 -5
- package/lib/src/generated/rest/ExportRequest.js +0 -2
- package/lib/src/generated/rest/ExpressionManyRequest.d.ts +0 -3
- package/lib/src/generated/rest/ExpressionManyRequest.js +0 -2
- package/lib/src/generated/rest/ExpressionProof.d.ts +0 -4
- package/lib/src/generated/rest/ExpressionProof.js +0 -2
- package/lib/src/generated/rest/ExpressionProofInput.d.ts +0 -6
- package/lib/src/generated/rest/ExpressionProofInput.js +0 -2
- package/lib/src/generated/rest/FriendSendMessageRequest.d.ts +0 -3
- package/lib/src/generated/rest/FriendSendMessageRequest.js +0 -2
- package/lib/src/generated/rest/FriendsListRequest.d.ts +0 -3
- package/lib/src/generated/rest/FriendsListRequest.js +0 -2
- package/lib/src/generated/rest/GenerateAgentRequest.d.ts +0 -3
- package/lib/src/generated/rest/GenerateAgentRequest.js +0 -2
- package/lib/src/generated/rest/GenerateJwtRequest.d.ts +0 -4
- package/lib/src/generated/rest/GenerateJwtRequest.js +0 -2
- package/lib/src/generated/rest/GetSubjectDataRequest.d.ts +0 -4
- package/lib/src/generated/rest/GetSubjectDataRequest.js +0 -2
- package/lib/src/generated/rest/HostingInfoResponse.d.ts +0 -5
- package/lib/src/generated/rest/HostingInfoResponse.js +0 -2
- package/lib/src/generated/rest/HostingWalletResponse.d.ts +0 -4
- package/lib/src/generated/rest/HostingWalletResponse.js +0 -2
- package/lib/src/generated/rest/ImportAgentRequest.d.ts +0 -6
- package/lib/src/generated/rest/ImportAgentRequest.js +0 -2
- package/lib/src/generated/rest/ImportRequest.d.ts +0 -4
- package/lib/src/generated/rest/ImportRequest.js +0 -2
- package/lib/src/generated/rest/JoinNeighbourhoodRequest.d.ts +0 -3
- package/lib/src/generated/rest/JoinNeighbourhoodRequest.js +0 -2
- package/lib/src/generated/rest/KeepAliveQueryRequest.d.ts +0 -3
- package/lib/src/generated/rest/KeepAliveQueryRequest.js +0 -2
- package/lib/src/generated/rest/LanguageMetaInput.d.ts +0 -6
- package/lib/src/generated/rest/LanguageMetaInput.js +0 -2
- package/lib/src/generated/rest/Link.d.ts +0 -5
- package/lib/src/generated/rest/Link.js +0 -2
- package/lib/src/generated/rest/LinkExpression.d.ts +0 -10
- package/lib/src/generated/rest/LinkExpression.js +0 -1
- package/lib/src/generated/rest/LinkExpressionInput.d.ts +0 -10
- package/lib/src/generated/rest/LinkExpressionInput.js +0 -1
- package/lib/src/generated/rest/LinkInput.d.ts +0 -5
- package/lib/src/generated/rest/LinkInput.js +0 -2
- package/lib/src/generated/rest/LinkLanguageTemplatesRequest.d.ts +0 -3
- package/lib/src/generated/rest/LinkLanguageTemplatesRequest.js +0 -2
- package/lib/src/generated/rest/LinkMutationRequest.d.ts +0 -12
- package/lib/src/generated/rest/LinkMutationRequest.js +0 -1
- package/lib/src/generated/rest/LinkMutationResponse.d.ts +0 -9
- package/lib/src/generated/rest/LinkMutationResponse.js +0 -1
- package/lib/src/generated/rest/LinkMutations.d.ts +0 -6
- package/lib/src/generated/rest/LinkMutations.js +0 -1
- package/lib/src/generated/rest/LinkMutationsRequest.d.ts +0 -5
- package/lib/src/generated/rest/LinkMutationsRequest.js +0 -1
- package/lib/src/generated/rest/LinkStatus.d.ts +0 -1
- package/lib/src/generated/rest/LinkStatus.js +0 -2
- package/lib/src/generated/rest/LinkUpdateInput.d.ts +0 -5
- package/lib/src/generated/rest/LinkUpdateInput.js +0 -1
- package/lib/src/generated/rest/LockAgentRequest.d.ts +0 -3
- package/lib/src/generated/rest/LockAgentRequest.js +0 -2
- package/lib/src/generated/rest/LoginUserRequest.d.ts +0 -5
- package/lib/src/generated/rest/LoginUserRequest.js +0 -2
- package/lib/src/generated/rest/ModelType.d.ts +0 -1
- package/lib/src/generated/rest/ModelType.js +0 -2
- package/lib/src/generated/rest/NotificationGrantRequest.d.ts +0 -3
- package/lib/src/generated/rest/NotificationGrantRequest.js +0 -2
- package/lib/src/generated/rest/NotificationInput.d.ts +0 -10
- package/lib/src/generated/rest/NotificationInput.js +0 -2
- package/lib/src/generated/rest/OpenLinkRequest.d.ts +0 -3
- package/lib/src/generated/rest/OpenLinkRequest.js +0 -2
- package/lib/src/generated/rest/PermitCapabilityRequest.d.ts +0 -3
- package/lib/src/generated/rest/PermitCapabilityRequest.js +0 -2
- package/lib/src/generated/rest/PerspectiveInput.d.ts +0 -4
- package/lib/src/generated/rest/PerspectiveInput.js +0 -1
- package/lib/src/generated/rest/PromptRequest.d.ts +0 -4
- package/lib/src/generated/rest/PromptRequest.js +0 -2
- package/lib/src/generated/rest/PublicPerspectiveInput.d.ts +0 -4
- package/lib/src/generated/rest/PublicPerspectiveInput.js +0 -1
- package/lib/src/generated/rest/PublishLanguageRequest.d.ts +0 -5
- package/lib/src/generated/rest/PublishLanguageRequest.js +0 -1
- package/lib/src/generated/rest/PublishNeighbourhoodRequest.d.ts +0 -6
- package/lib/src/generated/rest/PublishNeighbourhoodRequest.js +0 -1
- package/lib/src/generated/rest/QueryRequest.d.ts +0 -7
- package/lib/src/generated/rest/QueryRequest.js +0 -2
- package/lib/src/generated/rest/RemoveLinkRequest.d.ts +0 -5
- package/lib/src/generated/rest/RemoveLinkRequest.js +0 -1
- package/lib/src/generated/rest/RemoveLinksBulkRequest.d.ts +0 -5
- package/lib/src/generated/rest/RemoveLinksBulkRequest.js +0 -1
- package/lib/src/generated/rest/RequestCapabilityRequest.d.ts +0 -4
- package/lib/src/generated/rest/RequestCapabilityRequest.js +0 -1
- package/lib/src/generated/rest/RequestPaymentRequest.d.ts +0 -3
- package/lib/src/generated/rest/RequestPaymentRequest.js +0 -2
- package/lib/src/generated/rest/RequestVerificationRequest.d.ts +0 -4
- package/lib/src/generated/rest/RequestVerificationRequest.js +0 -2
- package/lib/src/generated/rest/ResourceInput.d.ts +0 -4
- package/lib/src/generated/rest/ResourceInput.js +0 -2
- package/lib/src/generated/rest/SetDefaultModelRequest.d.ts +0 -4
- package/lib/src/generated/rest/SetDefaultModelRequest.js +0 -1
- package/lib/src/generated/rest/SetFreeHostingEnabledRequest.d.ts +0 -3
- package/lib/src/generated/rest/SetFreeHostingEnabledRequest.js +0 -2
- package/lib/src/generated/rest/SetHotWalletAddressRequest.d.ts +0 -3
- package/lib/src/generated/rest/SetHotWalletAddressRequest.js +0 -2
- package/lib/src/generated/rest/SetMultiUserRequest.d.ts +0 -3
- package/lib/src/generated/rest/SetMultiUserRequest.js +0 -2
- package/lib/src/generated/rest/SetOnlineStatusRequest.d.ts +0 -5
- package/lib/src/generated/rest/SetOnlineStatusRequest.js +0 -1
- package/lib/src/generated/rest/SetStatusRequest.d.ts +0 -3
- package/lib/src/generated/rest/SetStatusRequest.js +0 -2
- package/lib/src/generated/rest/SetUserFreeAccessRequest.d.ts +0 -4
- package/lib/src/generated/rest/SetUserFreeAccessRequest.js +0 -2
- package/lib/src/generated/rest/SignMessageRequest.d.ts +0 -3
- package/lib/src/generated/rest/SignMessageRequest.js +0 -2
- package/lib/src/generated/rest/SignalRequest.d.ts +0 -6
- package/lib/src/generated/rest/SignalRequest.js +0 -1
- package/lib/src/generated/rest/SubscribeQueryRequest.d.ts +0 -3
- package/lib/src/generated/rest/SubscribeQueryRequest.js +0 -2
- package/lib/src/generated/rest/SubscribeQueryResponse.d.ts +0 -4
- package/lib/src/generated/rest/SubscribeQueryResponse.js +0 -2
- package/lib/src/generated/rest/TrustedAgentsRequest.d.ts +0 -3
- package/lib/src/generated/rest/TrustedAgentsRequest.js +0 -2
- package/lib/src/generated/rest/UnlockAgentRequest.d.ts +0 -4
- package/lib/src/generated/rest/UnlockAgentRequest.js +0 -2
- package/lib/src/generated/rest/UpdateLinkRequest.d.ts +0 -7
- package/lib/src/generated/rest/UpdateLinkRequest.js +0 -1
- package/lib/src/generated/rest/UpdatePerspectiveRequest.d.ts +0 -3
- package/lib/src/generated/rest/UpdatePerspectiveRequest.js +0 -2
- package/lib/src/generated/rest/UpdateProfileRequest.d.ts +0 -5
- package/lib/src/generated/rest/UpdateProfileRequest.js +0 -1
- package/lib/src/generated/rest/UserStatistics.d.ts +0 -9
- package/lib/src/generated/rest/UserStatistics.js +0 -2
- package/lib/src/generated/rest/VerificationRequestResult.d.ts +0 -6
- package/lib/src/generated/rest/VerificationRequestResult.js +0 -2
- package/lib/src/generated/rest/VerifyEmailRequest.d.ts +0 -6
- package/lib/src/generated/rest/VerifyEmailRequest.js +0 -2
- package/lib/src/generated/rest/VerifySignatureRequest.d.ts +0 -5
- package/lib/src/generated/rest/VerifySignatureRequest.js +0 -2
- package/lib/src/generated/rest/WriteSettingsRequest.d.ts +0 -3
- package/lib/src/generated/rest/WriteSettingsRequest.js +0 -2
- package/lib/src/generated/rest/index.d.ts +0 -73
- package/lib/src/generated/rest/index.js +0 -8
- package/lib/src/generated/rest/routes.d.ts +0 -587
- package/lib/src/generated/rest/routes.js +0 -3
- package/lib/src/model/query-surreal.d.ts +0 -44
- package/lib/src/model/query-surreal.js +0 -249
- package/lib/src/model/surreal-utils.d.ts +0 -42
- package/lib/src/model/surreal-utils.js +0 -128
- package/lib/src/perspectives/PerspectiveProxy.test.d.ts +0 -1
- package/lib/src/perspectives/PerspectiveProxy.test.js +0 -34
- package/lib/src/restClient.d.ts +0 -52
- package/lib/src/restClient.js +0 -227
|
@@ -13,6 +13,134 @@ export interface LinkPattern {
|
|
|
13
13
|
/** Required target value to match */
|
|
14
14
|
target: string;
|
|
15
15
|
}
|
|
16
|
+
/**
|
|
17
|
+
* Per-property condition for a `ModelQuery`. String / number / boolean
|
|
18
|
+
* shorthands compile to an equality match; the object forms are the full
|
|
19
|
+
* shape a `ModelQuery` engine consumer will evaluate against a class
|
|
20
|
+
* instance's decoded property value.
|
|
21
|
+
*
|
|
22
|
+
* Only the shorthand + `equals` / `in` / `exists` / `matches` operators are
|
|
23
|
+
* declared in v1 (see design doc §4.1). More operators can land as
|
|
24
|
+
* additional variants without a schema break.
|
|
25
|
+
*/
|
|
26
|
+
export type PropertyCondition = string | number | boolean | {
|
|
27
|
+
equals: unknown;
|
|
28
|
+
} | {
|
|
29
|
+
in: unknown[];
|
|
30
|
+
} | {
|
|
31
|
+
exists: true;
|
|
32
|
+
} | {
|
|
33
|
+
matches: string;
|
|
34
|
+
};
|
|
35
|
+
/**
|
|
36
|
+
* A model-level query — the shape a flow's `requires` guard evaluates
|
|
37
|
+
* against the perspective's current class-instance graph. Deliberately
|
|
38
|
+
* higher-level than raw links so guards talk about subject classes, not
|
|
39
|
+
* the underlying triples.
|
|
40
|
+
*
|
|
41
|
+
* See design doc §3 principle 2 ("Guards talk about models, not raw graph")
|
|
42
|
+
* and §4.1 for the full field spec. Template variables allowed inside
|
|
43
|
+
* `where` string values: `$flow.base`, `$flow.uri` (alias:
|
|
44
|
+
* `$flow.instance`), `$did` — the engine substitutes at evaluation time.
|
|
45
|
+
*/
|
|
46
|
+
export interface ModelQuery {
|
|
47
|
+
/** Subject-class URI to search for. */
|
|
48
|
+
className: string;
|
|
49
|
+
/**
|
|
50
|
+
* Per-property conditions (all must match — AND semantics inside one
|
|
51
|
+
* ModelQuery, same as AND semantics across an array of ModelQueries).
|
|
52
|
+
*/
|
|
53
|
+
where?: {
|
|
54
|
+
[prop: string]: PropertyCondition | string;
|
|
55
|
+
};
|
|
56
|
+
/**
|
|
57
|
+
* Cardinality constraint on matching instances. Default `{ min: 1 }` —
|
|
58
|
+
* at least one match required to satisfy the guard.
|
|
59
|
+
*/
|
|
60
|
+
count?: {
|
|
61
|
+
min?: number;
|
|
62
|
+
max?: number;
|
|
63
|
+
};
|
|
64
|
+
/**
|
|
65
|
+
* Scope the query to instances linked from a flow anchor. The anchor
|
|
66
|
+
* (base subject or flow instance URI) is the **source** of the link and
|
|
67
|
+
* the matched item is the **target**: `linkedTo: "base"` finds items
|
|
68
|
+
* where the base subject links TO them via the default predicate
|
|
69
|
+
* `ad4m://has_child`.
|
|
70
|
+
*
|
|
71
|
+
* `"base"` / `"flow"` use `ad4m://has_child`; the object form
|
|
72
|
+
* `{ via, to }` names a custom predicate (e.g.
|
|
73
|
+
* `{ via: "ns://about", to: "flow" }`).
|
|
74
|
+
*
|
|
75
|
+
* For the reverse direction (matched instance → anchor), use
|
|
76
|
+
* `where: { about: "$flow.base" }` instead — `linkedTo` cannot
|
|
77
|
+
* express that direction.
|
|
78
|
+
*/
|
|
79
|
+
linkedTo?: "flow" | "base" | {
|
|
80
|
+
via: string;
|
|
81
|
+
to: "flow" | "base";
|
|
82
|
+
};
|
|
83
|
+
/**
|
|
84
|
+
* When this query is used as a `ConsensusRule.fromRole`, names the
|
|
85
|
+
* property on the matched instance that carries a DID. Design doc §7.2
|
|
86
|
+
* Shape 1 (instance-carries-DID): engine runs the query, then extracts
|
|
87
|
+
* `didProperty` from each result to build the eligible-DID set.
|
|
88
|
+
*
|
|
89
|
+
* Shape 2 (instance-is-per-DID, using `$did` templating in `where`)
|
|
90
|
+
* omits `didProperty` — the engine iterates candidate DIDs and treats
|
|
91
|
+
* a non-empty result set as "this DID matches."
|
|
92
|
+
*
|
|
93
|
+
* Ignored when the query is used as a state guard (`requires`) or
|
|
94
|
+
* background `context`.
|
|
95
|
+
*/
|
|
96
|
+
didProperty?: string;
|
|
97
|
+
/**
|
|
98
|
+
* OR-compose a role expression across multiple ModelQueries. Semantics:
|
|
99
|
+
* a DID counts if it appears in the result of ANY branch (design §7.3
|
|
100
|
+
* multi-role hybrid example — "either reviewer OR admin"). Branches
|
|
101
|
+
* can carry their own `didProperty` / `where`, but NOT `linkedTo`
|
|
102
|
+
* (which must be on the outer query — `linkedTo` on a branch is
|
|
103
|
+
* rejected at translation time).
|
|
104
|
+
*
|
|
105
|
+
* Every branch must use the same `className` as the outer query and
|
|
106
|
+
* cannot declare its own `count` — the outer query's class and
|
|
107
|
+
* cardinality apply to the combined result set.
|
|
108
|
+
*
|
|
109
|
+
* A ModelQuery with a non-empty `or` array acts as a composition node;
|
|
110
|
+
* its own `className` / `where` etc. still count as an additional
|
|
111
|
+
* branch (union with the array). Empty or unset = no composition.
|
|
112
|
+
*
|
|
113
|
+
* Intentionally scoped to `or` for v1 — `and` / `not` fall out of the
|
|
114
|
+
* same mechanism and can land later without a schema break (design
|
|
115
|
+
* §7.4). Ignored when the query is used as a state guard or context.
|
|
116
|
+
*/
|
|
117
|
+
or?: ModelQuery[];
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* Consensus rule for a flow-state transition (or a top-level zero-state
|
|
121
|
+
* flow's completion). Distinct DID counting with optional role
|
|
122
|
+
* restriction.
|
|
123
|
+
*
|
|
124
|
+
* Design doc §7:
|
|
125
|
+
* - `{ n: 1 }` — any agent's proposal advances (default).
|
|
126
|
+
* - `{ n: 2 }` — two distinct agents must agree.
|
|
127
|
+
* - `{ n, fromRole }` — only agents matching the role query count.
|
|
128
|
+
*
|
|
129
|
+
* `fromRole` reuses `ModelQuery` (design §7.2) so role definitions live
|
|
130
|
+
* entirely in the ontology — communities can invent roles like
|
|
131
|
+
* "Reviewer" / "Guardian" without any code change.
|
|
132
|
+
*/
|
|
133
|
+
export interface ConsensusRule {
|
|
134
|
+
/** Required count of distinct qualifying DIDs. */
|
|
135
|
+
n: number;
|
|
136
|
+
/**
|
|
137
|
+
* Optional role restriction. When set, only DIDs returned by the role
|
|
138
|
+
* query are counted. Two evaluation shapes (design §7.2):
|
|
139
|
+
* Shape 1 — `didProperty` present: run once, extract DIDs from matches.
|
|
140
|
+
* Shape 2 — `$did` templated in `where`: run per candidate.
|
|
141
|
+
*/
|
|
142
|
+
fromRole?: ModelQuery;
|
|
143
|
+
}
|
|
16
144
|
/**
|
|
17
145
|
* Flow State definition
|
|
18
146
|
* Represents a single state in the flow state machine
|
|
@@ -22,8 +150,54 @@ export interface FlowState {
|
|
|
22
150
|
name: string;
|
|
23
151
|
/** Numeric state value for ordering (e.g., 0, 0.5, 1) */
|
|
24
152
|
value: number;
|
|
25
|
-
/**
|
|
26
|
-
|
|
153
|
+
/**
|
|
154
|
+
* Natural-language description of what puts a flow instance IN this state.
|
|
155
|
+
* Used by AI-driven state suggestion (`suggestFlowState`) — the same
|
|
156
|
+
* pattern subject classes use for `interpretationHint`. When set, the LLM
|
|
157
|
+
* reads it alongside conversation content to suggest transitions.
|
|
158
|
+
*
|
|
159
|
+
* Example (Deliberation Flow, "Tension" state):
|
|
160
|
+
* "Participants have voiced opposing views or objections — there is a
|
|
161
|
+
* clear disagreement or unresolved conflict on the table."
|
|
162
|
+
*/
|
|
163
|
+
interpretationHint?: string;
|
|
164
|
+
/**
|
|
165
|
+
* Model-level guard: the state is satisfied when every ModelQuery in
|
|
166
|
+
* the array returns at least one match on committed graph state
|
|
167
|
+
* (overlays do NOT count as evidence — design §3 principle 5).
|
|
168
|
+
*
|
|
169
|
+
* Array semantics: AND — every entry must match. Empty / unset =
|
|
170
|
+
* no model-level guard.
|
|
171
|
+
*
|
|
172
|
+
* Design doc §4.1: "an array of queries, ALL must match; each query's
|
|
173
|
+
* matches become evidence."
|
|
174
|
+
*/
|
|
175
|
+
requires?: ModelQuery[];
|
|
176
|
+
/**
|
|
177
|
+
* Optional English hint for a targeted LLM confirmation before the
|
|
178
|
+
* engine declares the state entered. Distinct from
|
|
179
|
+
* `interpretationHint`, which frames the state semantically for the
|
|
180
|
+
* up-front extraction pass — `semanticCheck` is the "am I still
|
|
181
|
+
* confident?" pass the engine runs after `requires` matches, for
|
|
182
|
+
* states where structural presence isn't enough (e.g. tension
|
|
183
|
+
* resolution).
|
|
184
|
+
*
|
|
185
|
+
* Design doc §5 covers the LLM confirmation pass shape. Unset = no
|
|
186
|
+
* confirmation, `requires` matches directly imply state entered.
|
|
187
|
+
*/
|
|
188
|
+
semanticCheck?: string;
|
|
189
|
+
/**
|
|
190
|
+
* Per-state consensus rule override. When present, transitions INTO
|
|
191
|
+
* this state require the specified number of distinct qualifying DIDs
|
|
192
|
+
* (see `ConsensusRule`). Overrides the flow-level `consensusRule` if
|
|
193
|
+
* both are set; when neither is set, the runtime engine's default of
|
|
194
|
+
* `{ n: 1 }` applies (any single agent's action fires the transition).
|
|
195
|
+
*
|
|
196
|
+
* Design doc §4.1 (v3) — per-state override enables mixed-consensus
|
|
197
|
+
* flows where e.g. "Perspective" states need only one voice but the
|
|
198
|
+
* "Resolution" state requires a quorum.
|
|
199
|
+
*/
|
|
200
|
+
consensusRule?: ConsensusRule;
|
|
27
201
|
}
|
|
28
202
|
/**
|
|
29
203
|
* Flow Transition definition
|
|
@@ -39,65 +213,40 @@ export interface FlowTransition {
|
|
|
39
213
|
/** Actions to execute for this transition */
|
|
40
214
|
actions: AD4MAction[];
|
|
41
215
|
}
|
|
42
|
-
/**
|
|
43
|
-
* Flowable condition - determines which expressions can enter this flow
|
|
44
|
-
* "any" means all expressions can start this flow
|
|
45
|
-
* Otherwise, a link pattern to check
|
|
46
|
-
*/
|
|
47
|
-
export type FlowableCondition = "any" | LinkPattern;
|
|
48
216
|
/**
|
|
49
217
|
* SHACL Flow - represents a state machine for AD4M expressions
|
|
50
218
|
*
|
|
51
219
|
* Flows define:
|
|
52
|
-
* - Which expressions can enter the flow (
|
|
53
|
-
* - What states exist and
|
|
54
|
-
* - How to transition between states (via
|
|
220
|
+
* - Which expressions can enter the flow (via `inputTypes`)
|
|
221
|
+
* - What states exist and their per-state guards (via `requires`)
|
|
222
|
+
* - How to transition between states (via transitions + consensus rules)
|
|
223
|
+
*
|
|
224
|
+
* State lives on the on-graph `FlowInstanceRecord.currentState` and is
|
|
225
|
+
* read/written through the `FlowInstance` wrapper class
|
|
226
|
+
* ({@link FlowInstance.start} / {@link FlowInstance.findAll}) — see design
|
|
227
|
+
* doc §4.3/§5.
|
|
55
228
|
*
|
|
56
229
|
* @example
|
|
57
230
|
* ```typescript
|
|
58
231
|
* const todoFlow = new SHACLFlow('todo://TODO', 'todo://');
|
|
59
232
|
*
|
|
60
233
|
* // Any expression can become a TODO
|
|
61
|
-
* todoFlow.
|
|
234
|
+
* todoFlow.inputTypes = ['any'];
|
|
62
235
|
*
|
|
63
|
-
*
|
|
64
|
-
* todoFlow.addState({
|
|
65
|
-
*
|
|
66
|
-
* value: 0,
|
|
67
|
-
* stateCheck: { predicate: 'todo://state', target: 'todo://ready' }
|
|
68
|
-
* });
|
|
69
|
-
* todoFlow.addState({
|
|
70
|
-
* name: 'doing',
|
|
71
|
-
* value: 0.5,
|
|
72
|
-
* stateCheck: { predicate: 'todo://state', target: 'todo://doing' }
|
|
73
|
-
* });
|
|
74
|
-
* todoFlow.addState({
|
|
75
|
-
* name: 'done',
|
|
76
|
-
* value: 1,
|
|
77
|
-
* stateCheck: { predicate: 'todo://state', target: 'todo://done' }
|
|
78
|
-
* });
|
|
236
|
+
* todoFlow.addState({ name: 'ready', value: 0 });
|
|
237
|
+
* todoFlow.addState({ name: 'doing', value: 0.5 });
|
|
238
|
+
* todoFlow.addState({ name: 'done', value: 1 });
|
|
79
239
|
*
|
|
80
|
-
* // Define start action
|
|
81
|
-
* todoFlow.startAction = [{
|
|
82
|
-
* action: 'addLink',
|
|
83
|
-
* source: 'this',
|
|
84
|
-
* predicate: 'todo://state',
|
|
85
|
-
* target: 'todo://ready'
|
|
86
|
-
* }];
|
|
87
|
-
*
|
|
88
|
-
* // Define transitions
|
|
89
240
|
* todoFlow.addTransition({
|
|
90
241
|
* actionName: 'Start',
|
|
91
242
|
* fromState: 'ready',
|
|
92
243
|
* toState: 'doing',
|
|
93
|
-
* actions: [
|
|
94
|
-
* { action: 'addLink', source: 'this', predicate: 'todo://state', target: 'todo://doing' },
|
|
95
|
-
* { action: 'removeLink', source: 'this', predicate: 'todo://state', target: 'todo://ready' }
|
|
96
|
-
* ]
|
|
244
|
+
* actions: [],
|
|
97
245
|
* });
|
|
98
246
|
*
|
|
99
|
-
* //
|
|
247
|
+
* // Register on the perspective and mint an instance on a subject.
|
|
100
248
|
* await perspective.addFlow('TODO', todoFlow);
|
|
249
|
+
* const instance = await FlowInstance.start(perspective, 'TODO', 'expr://123');
|
|
101
250
|
* ```
|
|
102
251
|
*/
|
|
103
252
|
export declare class SHACLFlow {
|
|
@@ -105,11 +254,88 @@ export declare class SHACLFlow {
|
|
|
105
254
|
name: string;
|
|
106
255
|
/** Namespace for generated URIs */
|
|
107
256
|
namespace: string;
|
|
108
|
-
/**
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
257
|
+
/**
|
|
258
|
+
* Top-level natural-language description of what the flow is about — used
|
|
259
|
+
* by AI-driven state suggestion (`suggestFlowState`) to frame the state
|
|
260
|
+
* hints. Optional; states' own `interpretationHint`s are what actually
|
|
261
|
+
* discriminate. Example (Deliberation Flow):
|
|
262
|
+
* "Tracks a group deliberation from an initial proposal to a shared
|
|
263
|
+
* understanding — through voicing perspectives, surfacing tension, and
|
|
264
|
+
* finding overlap."
|
|
265
|
+
*/
|
|
266
|
+
interpretationHint?: string;
|
|
267
|
+
/**
|
|
268
|
+
* Subject-class URIs the flow accepts as its base expression.
|
|
269
|
+
*
|
|
270
|
+
* Design doc §4.1: a flow's *typed input*. When an
|
|
271
|
+
* expression whose class matches any URI in this array enters scope,
|
|
272
|
+
* the flow-spawn engine considers it a candidate base. Superseded
|
|
273
|
+
* the older link-level `flowable: LinkPattern` primitive — model-level
|
|
274
|
+
* matching by subject class instead of link matching. Empty array =
|
|
275
|
+
* flow declares no typed input. The `"any"` sentinel is accepted as
|
|
276
|
+
* a wildcard for tests and legacy flows.
|
|
277
|
+
*/
|
|
278
|
+
inputTypes: string[];
|
|
279
|
+
/**
|
|
280
|
+
* Subject-class URIs the flow must produce (linked to the base) for a
|
|
281
|
+
* run to count as complete.
|
|
282
|
+
*
|
|
283
|
+
* Design doc §4.1: a flow's *typed output*. Two jobs:
|
|
284
|
+
* (a) documentation for stateful flows — records what a completed run
|
|
285
|
+
* leaves in the graph; (b) **terminal condition** for zero-state flows —
|
|
286
|
+
* a flow with no `FlowState`s completes when at least one instance of
|
|
287
|
+
* each `outputTypes` entry exists in scope and is linked to the base,
|
|
288
|
+
* and `consensusRule` fires. This is what makes "Like" a first-class
|
|
289
|
+
* flow with no state machine.
|
|
290
|
+
*/
|
|
291
|
+
outputTypes: string[];
|
|
292
|
+
/**
|
|
293
|
+
* Optional English hint for AI-driven flow-spawn: when should the
|
|
294
|
+
* interpretation engine mint a new instance of this flow (as opposed
|
|
295
|
+
* to advancing an existing one)?
|
|
296
|
+
*
|
|
297
|
+
* Design doc §4.1: analogous to `interpretationHint` on subject
|
|
298
|
+
* classes — steers the LLM's up-front extraction pass. Distinct from
|
|
299
|
+
* `interpretationHint` on the flow, which describes what the flow *is*.
|
|
300
|
+
* Example (Delivery Flow): "Spawn when someone commits to a concrete,
|
|
301
|
+
* actionable task."
|
|
302
|
+
*/
|
|
303
|
+
creationHint?: string;
|
|
304
|
+
/**
|
|
305
|
+
* Optional background queries pulled into the LLM prompt as CONTEXT
|
|
306
|
+
* (not evidence).
|
|
307
|
+
*
|
|
308
|
+
* Design doc §4.1: engine evaluates each `ModelQuery` and threads
|
|
309
|
+
* matches into the prompt so the LLM can reason with them, but
|
|
310
|
+
* matches do NOT count toward `requires` guards on states. Same
|
|
311
|
+
* `ModelQuery[]` shape and template-variable rules as `FlowState.requires`.
|
|
312
|
+
* Empty / unset = no context queries.
|
|
313
|
+
*/
|
|
314
|
+
context?: ModelQuery[];
|
|
315
|
+
/**
|
|
316
|
+
* Flow-level consensus rule. Two roles:
|
|
317
|
+
* - **Default for state transitions** — when a `FlowState` doesn't
|
|
318
|
+
* declare its own `consensusRule`, transitions into it fall back
|
|
319
|
+
* to this rule.
|
|
320
|
+
* - **Zero-state flow completion** — for actions-as-flows (a flow
|
|
321
|
+
* with no `FlowState`s), this is the rule the engine checks the
|
|
322
|
+
* moment `outputTypes` are satisfied. E.g. a Like flow declares
|
|
323
|
+
* `{ n: 1 }` and completes on the first author.
|
|
324
|
+
*
|
|
325
|
+
* Design doc §4.1: terminal condition for stateless flows.
|
|
326
|
+
* Unset = engine default of `{ n: 1 }` applies at both layers.
|
|
327
|
+
*/
|
|
328
|
+
consensusRule?: ConsensusRule;
|
|
329
|
+
/**
|
|
330
|
+
* States in this flow.
|
|
331
|
+
*
|
|
332
|
+
* **Ordering convention (James PR #929 R9):** the array is stored sorted
|
|
333
|
+
* ascending by `value`. `states[0]` is the initial state — the one
|
|
334
|
+
* {@link FlowInstance.start} mints a fresh instance into. A flow author
|
|
335
|
+
* who wants a specific state as the entry point must give it the lowest
|
|
336
|
+
* `value` in the set. `fromLinks` enforces this sort, so link-order on
|
|
337
|
+
* the graph never dictates the initial state.
|
|
338
|
+
*/
|
|
113
339
|
private _states;
|
|
114
340
|
/** Transitions between states */
|
|
115
341
|
private _transitions;
|