@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
package/src/model/decorators.ts
CHANGED
|
@@ -57,6 +57,21 @@ export interface RelationMetadataEntry {
|
|
|
57
57
|
* instances — those pass through byte-for-byte.
|
|
58
58
|
*/
|
|
59
59
|
datatype?: string;
|
|
60
|
+
/** Hydrate targets as the class each one actually is — see `RelationOptions.polymorphic`. */
|
|
61
|
+
polymorphic?: boolean;
|
|
62
|
+
/** Model classes this relation's polymorphic results can be constructed as. */
|
|
63
|
+
instantiateAs?: () => Ad4mModelLike[];
|
|
64
|
+
/** CRDT ordering config — see `RelationOptions.ordering`. */
|
|
65
|
+
ordering?: { strategy: 'linkedList' };
|
|
66
|
+
/**
|
|
67
|
+
* Natural-language hint describing what this relation MEANS semantically.
|
|
68
|
+
* Emitted as an `ad4m://interpretation_hint` link on the SHACL property
|
|
69
|
+
* node; read back by the Rust harness and rendered into the
|
|
70
|
+
* `_propose_link_child` tool's `predicate` field description. Mirror of
|
|
71
|
+
* the same field on `RelationOptions` (the decorator arg); this is the
|
|
72
|
+
* memoized registry copy.
|
|
73
|
+
*/
|
|
74
|
+
interpretationHint?: string;
|
|
60
75
|
}
|
|
61
76
|
|
|
62
77
|
/** Registry of property metadata keyed by constructor → { propName → metadata } */
|
|
@@ -806,15 +821,34 @@ export interface RelationOptions {
|
|
|
806
821
|
*/
|
|
807
822
|
through?: string;
|
|
808
823
|
/** The target model class (use a thunk to avoid circular-dependency issues). Optional for untyped string relations.
|
|
809
|
-
*
|
|
824
|
+
* Combines with `getter`, where it names the class the traversal's values hydrate into. */
|
|
810
825
|
target?: () => Ad4mModelLike;
|
|
811
826
|
/**
|
|
812
827
|
* Custom getter to resolve the relation values. Use this for custom graph traversals.
|
|
813
828
|
* The expression can reference 'Base' which will be replaced with the instance's base expression.
|
|
814
829
|
* Example: "SELECT ?target WHERE { ?target <flux://has_reply> <Base> . }"
|
|
815
830
|
*
|
|
816
|
-
* Mutually exclusive with `through`
|
|
817
|
-
*
|
|
831
|
+
* Mutually exclusive with `through` — a getter replaces link-based resolution,
|
|
832
|
+
* so there is no predicate to add to or remove from. When `getter` is provided
|
|
833
|
+
* the relation is read-only (no adder/remover actions are generated).
|
|
834
|
+
*
|
|
835
|
+
* **Combines with `target`**, which names the class the traversal's values
|
|
836
|
+
* hydrate into — without it `include` has no shape to resolve and the relation
|
|
837
|
+
* can only return bare URIs. Also combines with `where`, applied as a
|
|
838
|
+
* post-getter filter against the target class.
|
|
839
|
+
*
|
|
840
|
+
* @example Traversing a reified edge — a connection stored as a record rather
|
|
841
|
+
* than a predicate, so no `through` can express it:
|
|
842
|
+
* ```typescript
|
|
843
|
+
* @HasMany({
|
|
844
|
+
* getter: `SELECT ?target WHERE {
|
|
845
|
+
* ?citation <paper://cites_from> <Base> .
|
|
846
|
+
* ?citation <paper://cites_to> ?target .
|
|
847
|
+
* }`,
|
|
848
|
+
* target: () => Paper,
|
|
849
|
+
* })
|
|
850
|
+
* cited: Paper[] = [];
|
|
851
|
+
* ```
|
|
818
852
|
*/
|
|
819
853
|
getter?: string;
|
|
820
854
|
/** Whether the link is stored locally (not shared on the network) */
|
|
@@ -835,7 +869,8 @@ export interface RelationOptions {
|
|
|
835
869
|
* auto-derived from the target shape (flags + required properties).
|
|
836
870
|
* Providing `where` overrides this auto-derivation.
|
|
837
871
|
*
|
|
838
|
-
* Mutually exclusive with `
|
|
872
|
+
* Mutually exclusive with `filter: false`. Combines with `getter`, where it
|
|
873
|
+
* is applied as a post-getter filter against the target class.
|
|
839
874
|
*
|
|
840
875
|
* @example
|
|
841
876
|
* ```typescript
|
|
@@ -861,6 +896,110 @@ export interface RelationOptions {
|
|
|
861
896
|
* ```
|
|
862
897
|
*/
|
|
863
898
|
datatype?: string;
|
|
899
|
+
/**
|
|
900
|
+
* Hydrate each target as the class it actually **is**, rather than as the
|
|
901
|
+
* class this relation declares.
|
|
902
|
+
*
|
|
903
|
+
* A heterogeneous relation has no single right target. Declaring the base
|
|
904
|
+
* class loses every subclass property — the executor hydrates against the
|
|
905
|
+
* shape it is given, so an `ImagePost` read as a `Post` arrives with its own
|
|
906
|
+
* fields simply absent, not merely mislabelled. Declaring nothing leaves
|
|
907
|
+
* `include` with no shape to resolve at all.
|
|
908
|
+
*
|
|
909
|
+
* With this set, the targets are classified, grouped by concrete class, and
|
|
910
|
+
* hydrated against their own shapes — one query per distinct class present,
|
|
911
|
+
* not per instance.
|
|
912
|
+
*
|
|
913
|
+
* Pair with `instantiateAs` so the results become instances of the right
|
|
914
|
+
* model class rather than plain objects.
|
|
915
|
+
*
|
|
916
|
+
* @example
|
|
917
|
+
* ```typescript
|
|
918
|
+
* @HasMany({
|
|
919
|
+
* through: "we://children",
|
|
920
|
+
* polymorphic: true,
|
|
921
|
+
* instantiateAs: () => [TextBlock, ImageBlock],
|
|
922
|
+
* })
|
|
923
|
+
* children: Post[] = [];
|
|
924
|
+
* ```
|
|
925
|
+
*/
|
|
926
|
+
polymorphic?: boolean;
|
|
927
|
+
/**
|
|
928
|
+
* The model classes a `polymorphic` result may be constructed as.
|
|
929
|
+
*
|
|
930
|
+
* Classification happens in the executor, structurally — there is no
|
|
931
|
+
* `rdf:type` triple to read, so a target's class is derived from the flags
|
|
932
|
+
* and required properties it carries. What cannot cross the wire is the
|
|
933
|
+
* TypeScript constructor, so this names the classes this side can build.
|
|
934
|
+
* `@Model` already records each class's name on the class itself, so the
|
|
935
|
+
* name → class mapping is derived from the list rather than restated
|
|
936
|
+
* alongside it.
|
|
937
|
+
*
|
|
938
|
+
* **This is advisory, not a constraint.** It never narrows what the query
|
|
939
|
+
* returns and never excludes a target: a class missing from the list arrives
|
|
940
|
+
* as plain JSON carrying its class name, so partial knowledge degrades
|
|
941
|
+
* instead of failing. Declaring what this call site can *construct* is a
|
|
942
|
+
* different statement from declaring what the relation may *contain* — a
|
|
943
|
+
* heterogeneous relation is open by definition, and a list that silently
|
|
944
|
+
* dropped unrecognised members would defeat the point of reading it
|
|
945
|
+
* polymorphically at all. Constraining a read to particular classes belongs
|
|
946
|
+
* in the query, not here.
|
|
947
|
+
*
|
|
948
|
+
* A thunk rather than an array, for the same reason `target` is one: it is
|
|
949
|
+
* evaluated at query time, so a class defined later in a circular import
|
|
950
|
+
* graph still resolves.
|
|
951
|
+
*/
|
|
952
|
+
instantiateAs?: () => Ad4mModelLike[];
|
|
953
|
+
/**
|
|
954
|
+
* Give this collection a user-controlled order that survives concurrent edits.
|
|
955
|
+
*
|
|
956
|
+
* A `@HasMany` is a set of links, and hydration sorts them by link timestamp.
|
|
957
|
+
* That is right for an append-only collection — a transcript, a message
|
|
958
|
+
* thread — where timestamp order *is* the order. It cannot express a sequence
|
|
959
|
+
* somebody chose: a kanban column, a playlist, the blocks of a post.
|
|
960
|
+
*
|
|
961
|
+
* **Declaration only, for now.** Setting this emits `ad4m://ordering` on the
|
|
962
|
+
* property shape, where the executor reads it back — but no read or write
|
|
963
|
+
* path acts on it yet, so a relation declaring it still hydrates by link
|
|
964
|
+
* timestamp exactly as one that does not. Wiring save and hydration to the
|
|
965
|
+
* declaration is the next change; nothing about how you write the relation
|
|
966
|
+
* will change when it lands — assign the array in the order you want and
|
|
967
|
+
* save.
|
|
968
|
+
*
|
|
969
|
+
* Ordering is declared in the type system, rather than passed per query, so
|
|
970
|
+
* that *every* writer gets it once it is wired: the ORM, MCP agents, raw
|
|
971
|
+
* WS-RPC callers, another app sharing the neighbourhood. Implemented
|
|
972
|
+
* client-side it would order only what this client wrote.
|
|
973
|
+
*
|
|
974
|
+
* @example
|
|
975
|
+
* ```typescript
|
|
976
|
+
* @HasMany(() => Task, {
|
|
977
|
+
* through: "kanban://has_task",
|
|
978
|
+
* ordering: { strategy: "linkedList" },
|
|
979
|
+
* })
|
|
980
|
+
* tasks: Task[] = [];
|
|
981
|
+
* ```
|
|
982
|
+
*/
|
|
983
|
+
ordering?: { strategy: 'linkedList' };
|
|
984
|
+
/**
|
|
985
|
+
* Natural-language hint describing what this relation MEANS semantically —
|
|
986
|
+
* the sentence-level rationale for when to use it, not just its structural
|
|
987
|
+
* shape. Emitted as an `ad4m://interpretation_hint` link on the SHACL
|
|
988
|
+
* property node; read back by the Rust harness (`ClassProposeShape.
|
|
989
|
+
* relations[N].hint`) and rendered into the `_propose_link_child` tool's
|
|
990
|
+
* `predicate` field description so the LLM knows which relation applies
|
|
991
|
+
* to which situation instead of guessing from the predicate name alone.
|
|
992
|
+
*
|
|
993
|
+
* @example
|
|
994
|
+
* ```typescript
|
|
995
|
+
* @HasMany(() => Belief, {
|
|
996
|
+
* through: "ns://basedOn",
|
|
997
|
+
* interpretationHint: "The prior beliefs this intention derives from.",
|
|
998
|
+
* })
|
|
999
|
+
* basedOn: Belief[] = [];
|
|
1000
|
+
* ```
|
|
1001
|
+
*/
|
|
1002
|
+
interpretationHint?: string;
|
|
864
1003
|
}
|
|
865
1004
|
|
|
866
1005
|
/**
|
|
@@ -895,7 +1034,16 @@ function resolveRelationArgs(
|
|
|
895
1034
|
? { ...(second || {}), target: first }
|
|
896
1035
|
: first;
|
|
897
1036
|
|
|
898
|
-
//
|
|
1037
|
+
// `where` and `filter: false` contradict each other on every relation,
|
|
1038
|
+
// getter-backed ones included — checked before the getter path returns.
|
|
1039
|
+
if (opts.where && opts.filter === false) {
|
|
1040
|
+
throw new Error(
|
|
1041
|
+
'Relation decorator: `where` and `filter: false` are contradictory. ' +
|
|
1042
|
+
'`where` adds filtering constraints; `filter: false` disables filtering.'
|
|
1043
|
+
);
|
|
1044
|
+
}
|
|
1045
|
+
|
|
1046
|
+
// getter is mutually exclusive with through
|
|
899
1047
|
if (opts.getter) {
|
|
900
1048
|
if (opts.through) {
|
|
901
1049
|
throw new Error(
|
|
@@ -904,19 +1052,38 @@ function resolveRelationArgs(
|
|
|
904
1052
|
'(with optional `target`) for standard link-based relations.'
|
|
905
1053
|
);
|
|
906
1054
|
}
|
|
907
|
-
|
|
908
|
-
|
|
909
|
-
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
|
|
1055
|
+
// `target` and `where` are NOT mutually exclusive with `getter`.
|
|
1056
|
+
//
|
|
1057
|
+
// `target` does two separable jobs: it auto-derives a conformance
|
|
1058
|
+
// getter, and it names the class the relation's values hydrate into.
|
|
1059
|
+
// Only the first conflicts with an explicit getter, and `buildSHACL`
|
|
1060
|
+
// already resolves that on its own — an explicit getter wins the getter
|
|
1061
|
+
// slot, while `sh:class` / `ad4m:targetClassName` are emitted from
|
|
1062
|
+
// `target` independently.
|
|
1063
|
+
//
|
|
1064
|
+
// Refusing the pair cost the one thing a custom getter is for. A getter
|
|
1065
|
+
// expresses a traversal the link-shaped DSL cannot — most usefully
|
|
1066
|
+
// through a reified edge, where the connection is a record rather than
|
|
1067
|
+
// a predicate:
|
|
1068
|
+
//
|
|
1069
|
+
// @HasMany({
|
|
1070
|
+
// getter: "SELECT ?target WHERE { \
|
|
1071
|
+
// ?citation <paper://cites_from> <Base> . \
|
|
1072
|
+
// ?citation <paper://cites_to> ?target . }",
|
|
1073
|
+
// target: () => Paper,
|
|
1074
|
+
// })
|
|
1075
|
+
// cited: Paper[] = [];
|
|
1076
|
+
//
|
|
1077
|
+
// Without `target` the relation has no target class, so `include` on it
|
|
1078
|
+
// resolves a shape named "" and fails — leaving a traversal that can
|
|
1079
|
+
// only ever return bare URIs. With it, the values hydrate like any other
|
|
1080
|
+
// relation, because getters are evaluated before include resolution.
|
|
1081
|
+
//
|
|
1082
|
+
// `where` is the same story: the executor applies post-getter where
|
|
1083
|
+
// filters specifically to getter-backed relations
|
|
1084
|
+
// (`apply_where_filter_to_relation`), and emitting `wherePredicates`
|
|
1085
|
+
// needs `target` to resolve the target's metadata — so the runtime is
|
|
1086
|
+
// built for all three together and only this check said otherwise.
|
|
920
1087
|
return opts;
|
|
921
1088
|
}
|
|
922
1089
|
|
|
@@ -925,16 +1092,6 @@ function resolveRelationArgs(
|
|
|
925
1092
|
opts.through = 'ad4m://has_child';
|
|
926
1093
|
}
|
|
927
1094
|
|
|
928
|
-
// where validation
|
|
929
|
-
if (opts.where) {
|
|
930
|
-
if (opts.filter === false) {
|
|
931
|
-
throw new Error(
|
|
932
|
-
'Relation decorator: `where` and `filter: false` are contradictory. ' +
|
|
933
|
-
'`where` adds filtering constraints; `filter: false` disables filtering.'
|
|
934
|
-
);
|
|
935
|
-
}
|
|
936
|
-
}
|
|
937
|
-
|
|
938
1095
|
return opts;
|
|
939
1096
|
}
|
|
940
1097
|
|
|
@@ -988,6 +1145,10 @@ export function HasMany(
|
|
|
988
1145
|
...(opts.filter !== undefined && { filter: opts.filter }),
|
|
989
1146
|
...(opts.where && { where: opts.where }),
|
|
990
1147
|
...(opts.datatype && { datatype: opts.datatype }),
|
|
1148
|
+
...(opts.polymorphic && { polymorphic: opts.polymorphic }),
|
|
1149
|
+
...(opts.instantiateAs && { instantiateAs: opts.instantiateAs }),
|
|
1150
|
+
...(opts.ordering && { ordering: opts.ordering }),
|
|
1151
|
+
...(opts.interpretationHint && { interpretationHint: opts.interpretationHint }),
|
|
991
1152
|
};
|
|
992
1153
|
|
|
993
1154
|
const relKey = key as string;
|
|
@@ -1052,6 +1213,10 @@ export function HasOne(
|
|
|
1052
1213
|
...(opts.filter !== undefined && { filter: opts.filter }),
|
|
1053
1214
|
...(opts.where && { where: opts.where }),
|
|
1054
1215
|
...(opts.datatype && { datatype: opts.datatype }),
|
|
1216
|
+
...(opts.polymorphic && { polymorphic: opts.polymorphic }),
|
|
1217
|
+
...(opts.instantiateAs && { instantiateAs: opts.instantiateAs }),
|
|
1218
|
+
...(opts.ordering && { ordering: opts.ordering }),
|
|
1219
|
+
...(opts.interpretationHint && { interpretationHint: opts.interpretationHint }),
|
|
1055
1220
|
};
|
|
1056
1221
|
|
|
1057
1222
|
const relKey = key as string;
|
|
@@ -1063,15 +1228,23 @@ export function HasOne(
|
|
|
1063
1228
|
local: opts.local,
|
|
1064
1229
|
})(target, key);
|
|
1065
1230
|
|
|
1066
|
-
// Add prototype methods for add/remove/set (mirroring @HasMany)
|
|
1067
|
-
|
|
1068
|
-
|
|
1231
|
+
// Add prototype methods for add/remove/set (mirroring @HasMany).
|
|
1232
|
+
//
|
|
1233
|
+
// `batchId` is part of that mirroring: without it a to-one link
|
|
1234
|
+
// cannot join a write group, so anything that creates a record and
|
|
1235
|
+
// then points it at something has to commit twice and every
|
|
1236
|
+
// subscriber sees the state in between — a record whose to-one
|
|
1237
|
+
// relation is still empty. Anything rendering from a subscription
|
|
1238
|
+
// therefore has a frame in which the record exists and points at
|
|
1239
|
+
// nothing.
|
|
1240
|
+
(target as any)[`add${capitalize(relKey)}`] = async function(this: any, arg: any, batchId?: string) {
|
|
1241
|
+
return (this as any).addRelationValue(relKey, arg, batchId);
|
|
1069
1242
|
};
|
|
1070
|
-
(target as any)[`remove${capitalize(relKey)}`] = async function(this: any, arg: any) {
|
|
1071
|
-
return (this as any).removeRelationValue(relKey, arg);
|
|
1243
|
+
(target as any)[`remove${capitalize(relKey)}`] = async function(this: any, arg: any, batchId?: string) {
|
|
1244
|
+
return (this as any).removeRelationValue(relKey, arg, batchId);
|
|
1072
1245
|
};
|
|
1073
|
-
(target as any)[`set${capitalize(relKey)}`] = async function(this: any, arg: any) {
|
|
1074
|
-
return (this as any).setRelationValues(relKey, arg);
|
|
1246
|
+
(target as any)[`set${capitalize(relKey)}`] = async function(this: any, arg: any, batchId?: string) {
|
|
1247
|
+
return (this as any).setRelationValues(relKey, arg, batchId);
|
|
1075
1248
|
};
|
|
1076
1249
|
} else {
|
|
1077
1250
|
Object.defineProperty(target, relKey, { configurable: true, writable: true });
|
|
@@ -1123,6 +1296,10 @@ export function BelongsToOne(
|
|
|
1123
1296
|
...(opts.filter !== undefined && { filter: opts.filter }),
|
|
1124
1297
|
...(opts.where && { where: opts.where }),
|
|
1125
1298
|
...(opts.datatype && { datatype: opts.datatype }),
|
|
1299
|
+
...(opts.polymorphic && { polymorphic: opts.polymorphic }),
|
|
1300
|
+
...(opts.instantiateAs && { instantiateAs: opts.instantiateAs }),
|
|
1301
|
+
...(opts.ordering && { ordering: opts.ordering }),
|
|
1302
|
+
...(opts.interpretationHint && { interpretationHint: opts.interpretationHint }),
|
|
1126
1303
|
};
|
|
1127
1304
|
|
|
1128
1305
|
if (opts.through) {
|
|
@@ -1182,6 +1359,10 @@ export function BelongsToMany(
|
|
|
1182
1359
|
...(opts.filter !== undefined && { filter: opts.filter }),
|
|
1183
1360
|
...(opts.where && { where: opts.where }),
|
|
1184
1361
|
...(opts.datatype && { datatype: opts.datatype }),
|
|
1362
|
+
...(opts.polymorphic && { polymorphic: opts.polymorphic }),
|
|
1363
|
+
...(opts.instantiateAs && { instantiateAs: opts.instantiateAs }),
|
|
1364
|
+
...(opts.ordering && { ordering: opts.ordering }),
|
|
1365
|
+
...(opts.interpretationHint && { interpretationHint: opts.interpretationHint }),
|
|
1185
1366
|
};
|
|
1186
1367
|
|
|
1187
1368
|
// @BelongsToMany is the inverse/read-only side — do NOT generate add*/remove*/set*
|
|
@@ -394,17 +394,44 @@ describe("Ad4mModel.getModelMetadata() relation filtering fields", () => {
|
|
|
394
394
|
// ============================================================================
|
|
395
395
|
|
|
396
396
|
describe("Relation decorator validation", () => {
|
|
397
|
-
it("
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
}
|
|
405
|
-
|
|
406
|
-
}
|
|
407
|
-
|
|
397
|
+
it("accepts getter together with target, and keeps the getter verbatim", () => {
|
|
398
|
+
// `target` does two separable jobs — derive a conformance getter, and name
|
|
399
|
+
// the class values hydrate into. Only the first conflicts with an explicit
|
|
400
|
+
// getter, so the pair is legal and the explicit getter wins.
|
|
401
|
+
@Model({ name: "GetterWithTarget" })
|
|
402
|
+
class GetterWithTarget extends Ad4mModel {
|
|
403
|
+
@HasMany({
|
|
404
|
+
getter: "SELECT ?target WHERE { ?rel <we://src> <Base> . ?rel <we://tgt> ?target . }",
|
|
405
|
+
target: () => FlaggedTarget,
|
|
406
|
+
})
|
|
407
|
+
items: string[] = [];
|
|
408
|
+
}
|
|
409
|
+
|
|
410
|
+
const { shape } = (GetterWithTarget as any).generateSHACL();
|
|
411
|
+
const rel = shape.properties.find((p: any) => p.name === "items");
|
|
412
|
+
|
|
413
|
+
expect(rel.getter).toBe(
|
|
414
|
+
"SELECT ?target WHERE { ?rel <we://src> <Base> . ?rel <we://tgt> ?target . }"
|
|
415
|
+
);
|
|
416
|
+
});
|
|
417
|
+
|
|
418
|
+
it("emits sh:class for a getter relation, so include has a shape to resolve", () => {
|
|
419
|
+
// Without a target class the executor resolves a shape named "" and the
|
|
420
|
+
// include fails — which is what made a custom traversal able to return only
|
|
421
|
+
// bare URIs.
|
|
422
|
+
@Model({ name: "GetterWithTargetClass" })
|
|
423
|
+
class GetterWithTargetClass extends Ad4mModel {
|
|
424
|
+
@HasMany({
|
|
425
|
+
getter: "SELECT ?target WHERE { ?target ?p <Base> . }",
|
|
426
|
+
target: () => FlaggedTarget,
|
|
427
|
+
})
|
|
428
|
+
items: string[] = [];
|
|
429
|
+
}
|
|
430
|
+
|
|
431
|
+
const { shape } = (GetterWithTargetClass as any).generateSHACL();
|
|
432
|
+
const rel = shape.properties.find((p: any) => p.name === "items");
|
|
433
|
+
|
|
434
|
+
expect(rel.targetClassName).toBe("FlaggedTarget");
|
|
408
435
|
});
|
|
409
436
|
|
|
410
437
|
it("should throw if both getter and through are provided", () => {
|
|
@@ -556,25 +583,48 @@ describe("sh:class target shape reference", () => {
|
|
|
556
583
|
// ============================================================================
|
|
557
584
|
|
|
558
585
|
describe("where clause validation", () => {
|
|
559
|
-
it("
|
|
586
|
+
it("accepts where alongside a getter, as a post-getter filter", () => {
|
|
587
|
+
// The executor applies where filters specifically to getter-backed
|
|
588
|
+
// relations (`apply_where_filter_to_relation`), so the runtime was built
|
|
589
|
+
// for this pairing; only the decorator refused it.
|
|
590
|
+
@Model({ name: "WhereWithGetter" })
|
|
591
|
+
class WhereWithGetter extends Ad4mModel {
|
|
592
|
+
@HasMany({
|
|
593
|
+
where: { status: "active" },
|
|
594
|
+
getter: "SELECT ?target WHERE { ?target ?p <Base> . }",
|
|
595
|
+
target: () => FlaggedTarget,
|
|
596
|
+
})
|
|
597
|
+
items: string[] = [];
|
|
598
|
+
}
|
|
599
|
+
|
|
600
|
+
const { shape } = (WhereWithGetter as any).generateSHACL();
|
|
601
|
+
const rel = shape.properties.find((p: any) => p.name === "items");
|
|
602
|
+
|
|
603
|
+
expect(rel.whereFilter).toEqual({ status: "active" });
|
|
604
|
+
expect(rel.getter).toBe("SELECT ?target WHERE { ?target ?p <Base> . }");
|
|
605
|
+
});
|
|
606
|
+
|
|
607
|
+
it("should throw if both where and filter:false are provided", () => {
|
|
560
608
|
expect(() => {
|
|
561
|
-
@Model({ name: "
|
|
609
|
+
@Model({ name: "InvalidWhereFilterFalse" })
|
|
562
610
|
class _Invalid extends Ad4mModel {
|
|
563
|
-
@HasMany({
|
|
611
|
+
@HasMany(() => FlaggedTarget, {
|
|
612
|
+
through: "test://pred",
|
|
564
613
|
where: { status: "active" },
|
|
565
|
-
|
|
614
|
+
filter: false,
|
|
566
615
|
})
|
|
567
616
|
items: string[] = [];
|
|
568
617
|
}
|
|
569
|
-
}).toThrow(/where.*
|
|
618
|
+
}).toThrow(/where.*filter.*contradictory/i);
|
|
570
619
|
});
|
|
571
620
|
|
|
572
|
-
it("should throw if both where and filter:false are provided", () => {
|
|
621
|
+
it("should throw if both where and filter:false are provided on a getter relation", () => {
|
|
573
622
|
expect(() => {
|
|
574
|
-
@Model({ name: "
|
|
623
|
+
@Model({ name: "InvalidGetterWhereFilterFalse" })
|
|
575
624
|
class _Invalid extends Ad4mModel {
|
|
576
|
-
@HasMany(
|
|
577
|
-
|
|
625
|
+
@HasMany({
|
|
626
|
+
getter: "SELECT ?target WHERE { ?target ?p <Base> . }",
|
|
627
|
+
target: () => FlaggedTarget,
|
|
578
628
|
where: { status: "active" },
|
|
579
629
|
filter: false,
|
|
580
630
|
})
|
package/src/model/shacl-gen.ts
CHANGED
|
@@ -309,11 +309,27 @@ export function buildSHACL(
|
|
|
309
309
|
relShape.filter = false;
|
|
310
310
|
}
|
|
311
311
|
|
|
312
|
+
// Ordering is declared in the type system so the executor can act on it
|
|
313
|
+
// for every writer, not just this client.
|
|
314
|
+
if (relMeta.ordering) {
|
|
315
|
+
relShape.ordering = relMeta.ordering.strategy;
|
|
316
|
+
}
|
|
317
|
+
|
|
312
318
|
// AD4M-specific metadata
|
|
313
319
|
if (relMeta.local !== undefined) {
|
|
314
320
|
relShape.local = relMeta.local;
|
|
315
321
|
}
|
|
316
322
|
|
|
323
|
+
// Per-relation interpretation hint — sentence-level meaning that
|
|
324
|
+
// steers the harness LLM's `_propose_link_child` `predicate` field
|
|
325
|
+
// description. Read back on the Rust side by
|
|
326
|
+
// `ShaclProperty.interpretation_hint` and rendered into the tool
|
|
327
|
+
// schema alongside the predicate URI enum (so `basedOn` reads
|
|
328
|
+
// "prior beliefs this intention derives from", not just "some link").
|
|
329
|
+
if (relMeta.interpretationHint) {
|
|
330
|
+
relShape.interpretationHint = relMeta.interpretationHint;
|
|
331
|
+
}
|
|
332
|
+
|
|
317
333
|
// Adder / Remover actions — only meaningful for relations backed
|
|
318
334
|
// by a real link predicate. Getter-only relations are read-only.
|
|
319
335
|
if (relMeta.predicate) {
|
|
@@ -455,6 +471,26 @@ export function buildSHACL(
|
|
|
455
471
|
shape.addProperty(relShape);
|
|
456
472
|
}
|
|
457
473
|
|
|
474
|
+
// ── Ordering links ─────────────────────────────────────────────────
|
|
475
|
+
// Ordering entries are stored on the *parent*, under one shared predicate,
|
|
476
|
+
// so that reconstruction needs no extra query: they arrive with the
|
|
477
|
+
// instance's own links. That only works if the instance query asks for them,
|
|
478
|
+
// and it builds its predicate filter from the shape's declared paths — so a
|
|
479
|
+
// class owning any ordered collection has to declare the predicate, or the
|
|
480
|
+
// very links the ordering depends on are filtered out of the read that needs
|
|
481
|
+
// them.
|
|
482
|
+
//
|
|
483
|
+
// One entry covers every ordered relation on the class; each entry names the
|
|
484
|
+
// relation it belongs to.
|
|
485
|
+
const hasOrderedRelation = Object.values(allRelationsMeta).some((m) => m.ordering);
|
|
486
|
+
if (hasOrderedRelation) {
|
|
487
|
+
shape.addProperty({
|
|
488
|
+
name: '_collectionOrder',
|
|
489
|
+
path: 'ad4m://collection_order',
|
|
490
|
+
nodeKind: 'IRI',
|
|
491
|
+
});
|
|
492
|
+
}
|
|
493
|
+
|
|
458
494
|
// Always set constructor and destructor actions on the shape, even
|
|
459
495
|
// when empty. An empty array serialises to `literal:string:[]`
|
|
460
496
|
// which the Rust executor parses as a valid (no-op) command list,
|
|
@@ -17,6 +17,7 @@ import {
|
|
|
17
17
|
BelongsToOne,
|
|
18
18
|
BelongsToMany,
|
|
19
19
|
} from "./decorators";
|
|
20
|
+
import { SHACLShape } from "../shacl/SHACLShape";
|
|
20
21
|
|
|
21
22
|
function flatten(
|
|
22
23
|
shape: any,
|
|
@@ -234,6 +235,59 @@ describe("Decorators → SHACL writer round-trip", () => {
|
|
|
234
235
|
).toBeUndefined();
|
|
235
236
|
});
|
|
236
237
|
|
|
238
|
+
it("emits ad4m://interpretation_hint on relation properties", () => {
|
|
239
|
+
// Relation-level interpretation hints (RelationOptions.interpretationHint)
|
|
240
|
+
// are read by the Rust harness's `ShaclProperty.interpretation_hint` and
|
|
241
|
+
// rendered into the `_propose_link_child` predicate-field description so
|
|
242
|
+
// the LLM knows what each relation MEANS semantically, not just that it
|
|
243
|
+
// exists. Regression against the follow-up-branch scope creep: pulled
|
|
244
|
+
// into PR #911 per Nico's 2026-08-24 ask.
|
|
245
|
+
@Model({ name: "Intention" })
|
|
246
|
+
class Intention extends Ad4mModel {
|
|
247
|
+
@Property({
|
|
248
|
+
through: "ns://title",
|
|
249
|
+
required: true,
|
|
250
|
+
interpretationHint: "Imperative statement of intent.",
|
|
251
|
+
})
|
|
252
|
+
title: string = "";
|
|
253
|
+
|
|
254
|
+
@HasMany(() => Belief, {
|
|
255
|
+
through: "ns://basedOn",
|
|
256
|
+
interpretationHint:
|
|
257
|
+
"The prior beliefs this intention derives from.",
|
|
258
|
+
})
|
|
259
|
+
basedOn: Belief[] = [];
|
|
260
|
+
|
|
261
|
+
@HasMany(() => Belief, { through: "ns://contradicts" })
|
|
262
|
+
contradicts: Belief[] = [];
|
|
263
|
+
}
|
|
264
|
+
@Model({ name: "Belief" })
|
|
265
|
+
class Belief extends Ad4mModel {
|
|
266
|
+
@Property({ through: "ns://title", required: true }) title: string = "";
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
const { shape } = Intention.generateSHACL();
|
|
270
|
+
const links = flatten(shape);
|
|
271
|
+
|
|
272
|
+
// Named relation with a hint → link present on the relation's property
|
|
273
|
+
// node with the hint text.
|
|
274
|
+
expect(
|
|
275
|
+
findLinkTarget(links, "ns://Intention.basedOn", "ad4m://interpretation_hint"),
|
|
276
|
+
).toBe(
|
|
277
|
+
"literal:string:The prior beliefs this intention derives from.",
|
|
278
|
+
);
|
|
279
|
+
|
|
280
|
+
// Named relation WITHOUT a hint → no interpretation_hint link (the
|
|
281
|
+
// scalar-property "no hint = no link" path is what relations follow too).
|
|
282
|
+
expect(
|
|
283
|
+
findLinkTarget(
|
|
284
|
+
links,
|
|
285
|
+
"ns://Intention.contradicts",
|
|
286
|
+
"ad4m://interpretation_hint",
|
|
287
|
+
),
|
|
288
|
+
).toBeUndefined();
|
|
289
|
+
});
|
|
290
|
+
|
|
237
291
|
it("round-trips interpretationHint through toJSON/fromJSON", () => {
|
|
238
292
|
@Model({
|
|
239
293
|
name: "Task",
|
|
@@ -272,4 +326,80 @@ describe("Decorators → SHACL writer round-trip", () => {
|
|
|
272
326
|
"Imperative summary of the work.",
|
|
273
327
|
);
|
|
274
328
|
});
|
|
329
|
+
|
|
330
|
+
it("round-trips ordering through toLinks/fromLinks", () => {
|
|
331
|
+
@Model({ name: "OrderedItem" })
|
|
332
|
+
class OrderedItem extends Ad4mModel {}
|
|
333
|
+
|
|
334
|
+
@Model({ name: "OrderedHolder" })
|
|
335
|
+
class OrderedHolder extends Ad4mModel {
|
|
336
|
+
@HasMany({
|
|
337
|
+
through: "ns://ordered",
|
|
338
|
+
target: () => OrderedItem,
|
|
339
|
+
ordering: { strategy: "linkedList" },
|
|
340
|
+
})
|
|
341
|
+
ordered: string[] = [];
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
const { shape } = OrderedHolder.generateSHACL();
|
|
345
|
+
const links = shape.toLinks();
|
|
346
|
+
|
|
347
|
+
// Pin the wire format itself. `ordering` is the one relation field the
|
|
348
|
+
// read path recovers by stripping a prefix off the target rather than by
|
|
349
|
+
// parsing a typed literal, so a change to how the writer spells it would
|
|
350
|
+
// otherwise surface as the executor silently seeing no strategy.
|
|
351
|
+
expect(
|
|
352
|
+
findLinkTarget(
|
|
353
|
+
flatten(shape),
|
|
354
|
+
"ns://OrderedHolder.ordered",
|
|
355
|
+
"ad4m://ordering",
|
|
356
|
+
),
|
|
357
|
+
).toBe("literal:string:linkedList");
|
|
358
|
+
|
|
359
|
+
const rebuilt = SHACLShape.fromLinks(links, shape.nodeShapeUri);
|
|
360
|
+
const rebuiltProp = rebuilt.properties.find(
|
|
361
|
+
(p: any) => p.name === "ordered",
|
|
362
|
+
);
|
|
363
|
+
expect(rebuiltProp?.ordering).toBe("linkedList");
|
|
364
|
+
});
|
|
365
|
+
|
|
366
|
+
it("round-trips ordering through toJSON/fromJSON", () => {
|
|
367
|
+
@Model({ name: "JsonOrderedItem" })
|
|
368
|
+
class JsonOrderedItem extends Ad4mModel {}
|
|
369
|
+
|
|
370
|
+
@Model({ name: "JsonOrderedHolder" })
|
|
371
|
+
class JsonOrderedHolder extends Ad4mModel {
|
|
372
|
+
@HasMany({
|
|
373
|
+
through: "ns://ordered",
|
|
374
|
+
target: () => JsonOrderedItem,
|
|
375
|
+
ordering: { strategy: "linkedList" },
|
|
376
|
+
})
|
|
377
|
+
ordered: string[] = [];
|
|
378
|
+
|
|
379
|
+
@HasMany({ through: "ns://plain", target: () => JsonOrderedItem })
|
|
380
|
+
plain: string[] = [];
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
const { shape } = JsonOrderedHolder.generateSHACL();
|
|
384
|
+
|
|
385
|
+
// `toJSON` — not `toLinks` — is what `ensureSubjectClass` ships to the
|
|
386
|
+
// backend, which turns it into the `ad4m://ordering` link the executor
|
|
387
|
+
// reads the strategy back from. A declaration dropped here is inert
|
|
388
|
+
// end to end however faithfully `toLinks` spells it: the setter writes
|
|
389
|
+
// no ordering entries and hydration never reorders.
|
|
390
|
+
const json: any = shape.toJSON();
|
|
391
|
+
const orderedProp = json.properties.find((p: any) => p.name === "ordered");
|
|
392
|
+
expect(orderedProp?.ordering).toBe("linkedList");
|
|
393
|
+
|
|
394
|
+
const plainProp = json.properties.find((p: any) => p.name === "plain");
|
|
395
|
+
expect(plainProp?.ordering).toBeUndefined();
|
|
396
|
+
|
|
397
|
+
const rebuilt = SHACLShape.fromJSON(json);
|
|
398
|
+
expect(
|
|
399
|
+
rebuilt.properties.find((p: any) => p.name === "ordered")?.ordering,
|
|
400
|
+
).toBe("linkedList");
|
|
401
|
+
expect(
|
|
402
|
+
rebuilt.properties.find((p: any) => p.name === "plain")?.ordering,
|
|
403
|
+
).toBeUndefined();
|
|
404
|
+
});
|
|
275
405
|
});
|
package/src/model/types.ts
CHANGED
|
@@ -447,6 +447,13 @@ export interface RelationMetadata {
|
|
|
447
447
|
local?: boolean;
|
|
448
448
|
/** Link direction: 'forward' for HasMany/HasOne, 'reverse' for BelongsToMany/BelongsToOne */
|
|
449
449
|
direction?: 'forward' | 'reverse';
|
|
450
|
+
/**
|
|
451
|
+
* CRDT ordering config, when this collection has a user-controlled order.
|
|
452
|
+
*
|
|
453
|
+
* Its presence is what makes a reorder count as a change: for an ordered
|
|
454
|
+
* relation the sequence *is* the state, where an unordered one is a set.
|
|
455
|
+
*/
|
|
456
|
+
ordering?: { strategy: 'linkedList' };
|
|
450
457
|
/** Target model class thunk for hydration and type filtering */
|
|
451
458
|
target?: () => any;
|
|
452
459
|
/**
|