@coasys/ad4m 0.13.0-test-interpretation-1 → 0.13.0-test-interpretation-2
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 +449 -149
- package/lib/index.js +447 -150
- package/lib/src/Literal.js +8 -0
- package/lib/src/generated/api/RunInterpretationRequest.d.ts +16 -0
- package/lib/src/model/Ad4mModel.d.ts +28 -11
- package/lib/src/model/Ad4mModel.js +57 -35
- package/lib/src/model/ModelQueryBuilder.js +2 -2
- package/lib/src/model/decorators.d.ts +52 -8
- package/lib/src/model/decorators.js +18 -8
- package/lib/src/model/json-schema.js +7 -21
- package/lib/src/model/query-common.d.ts +2 -2
- package/lib/src/model/query-sparql.d.ts +62 -0
- package/lib/src/model/query-sparql.js +78 -15
- package/lib/src/model/query-utils.d.ts +7 -2
- package/lib/src/model/query-utils.js +21 -11
- package/lib/src/model/shacl-gen.js +44 -15
- package/lib/src/model/types.d.ts +23 -8
- package/lib/src/perspectives/AutoProcessor.d.ts +132 -2
- package/lib/src/perspectives/InterpretationModels.d.ts +51 -3
- package/lib/src/perspectives/InterpretationModels.js +64 -26
- package/lib/src/perspectives/PerspectiveClient.d.ts +22 -2
- package/lib/src/perspectives/PerspectiveClient.js +35 -3
- package/lib/src/perspectives/PerspectiveProxy.d.ts +9 -1
- package/lib/src/perspectives/PerspectiveProxy.js +24 -14
- package/lib/src/perspectives/SparqlBindings.d.ts +24 -3
- package/lib/src/perspectives/SparqlBindings.js +57 -6
- package/lib/src/shacl/SHACLShape.d.ts +11 -3
- package/lib/src/shacl/SHACLShape.js +13 -1
- package/lib/src/shacl/index.d.ts +1 -1
- package/lib/src/shacl/index.js +1 -1
- package/package.json +2 -2
- package/src/Literal.ts +7 -0
- package/src/generated/api/RunInterpretationRequest.ts +19 -3
- package/src/model/Ad4mModel.test.ts +84 -22
- package/src/model/Ad4mModel.ts +61 -41
- package/src/model/ModelQueryBuilder.ts +2 -2
- package/src/model/decorators.ts +62 -9
- package/src/model/json-schema.ts +10 -25
- package/src/model/query-common.ts +2 -2
- package/src/model/query-sparql.test.ts +114 -13
- package/src/model/query-sparql.ts +83 -14
- package/src/model/query-utils.ts +22 -12
- package/src/model/shacl-gen.ts +42 -13
- package/src/model/shacl-roundtrip.test.ts +4 -2
- package/src/model/types.ts +23 -8
- package/src/perspectives/AutoProcessor.ts +133 -1
- package/src/perspectives/InterpretationModels.ts +103 -21
- package/src/perspectives/PerspectiveClient.ts +50 -4
- package/src/perspectives/PerspectiveProxy.ts +37 -21
- package/src/perspectives/SparqlBindings.test.ts +134 -0
- package/src/perspectives/SparqlBindings.ts +57 -6
- package/src/shacl/SHACLShape.test.ts +30 -4
- package/src/shacl/SHACLShape.ts +28 -6
- package/src/shacl/index.ts +1 -1
|
@@ -27,6 +27,68 @@ import type { Where, Query, ModelMetadata } from "./types";
|
|
|
27
27
|
* potentially discarding matches beyond the LIMIT.
|
|
28
28
|
*/
|
|
29
29
|
export declare function hasJsOnlyWhereFilters(metadata: ModelMetadata, allRelationsMetadata: Record<string, RelationMetadataEntry>, where?: Where): boolean;
|
|
30
|
+
/**
|
|
31
|
+
* Check whether a string value is a well-formed absolute IRI that can be
|
|
32
|
+
* stored verbatim as a link target (raw `NamedNode`) instead of being
|
|
33
|
+
* wrapped in a `literal:string:*` URI.
|
|
34
|
+
*
|
|
35
|
+
* This mirrors the Rust `is_safe_iri_target` /
|
|
36
|
+
* `looks_like_absolute_iri` predicate in
|
|
37
|
+
* `rust-executor/src/perspectives/model_query/utils.rs` and is
|
|
38
|
+
* **load-bearing**: a value that returns `true` here MUST also be safely
|
|
39
|
+
* queryable on the Rust side (`validate_iri` gate on the SPARQL
|
|
40
|
+
* `UNION { ?s <pred> <val> }` IRI arm), otherwise scheme-lookalike prose
|
|
41
|
+
* such as `"Note: buy milk"`, `"Re: standup"`, `"TODO: fix this"` slips
|
|
42
|
+
* through the write regex, is stored as an invalid `NamedNode`, and
|
|
43
|
+
* becomes a silent no-match on read.
|
|
44
|
+
*
|
|
45
|
+
* Fast-path scheme check (`^[a-zA-Z][a-zA-Z0-9+\-._]*:`) followed by the
|
|
46
|
+
* same rejection set the Rust `validate_iri` applies: any Unicode
|
|
47
|
+
* whitespace, C0/C1 control chars, and the SPARQL-breaking characters
|
|
48
|
+
* `< > { } "`.
|
|
49
|
+
*/
|
|
50
|
+
export declare function looksLikeUri(value: string): boolean;
|
|
51
|
+
/**
|
|
52
|
+
* Convert a JS value to its literal: IRI form, matching how the Rust executor
|
|
53
|
+
* stores property values in the default deterministic-literal path
|
|
54
|
+
* (`resolveLanguage` unset). Strings that already look like URIs are returned
|
|
55
|
+
* as-is.
|
|
56
|
+
*
|
|
57
|
+
* Exported so write-side helpers (e.g. `Ad4mModel.setProperty`'s literal
|
|
58
|
+
* resolve path) can keep their on-disk form aligned with what
|
|
59
|
+
* `queryToSPARQL()` filters against — otherwise the same value can be
|
|
60
|
+
* stored as `<literal:string:https%3A...>` from one path while WHERE
|
|
61
|
+
* builders probe `<https://example.com>` from the other.
|
|
62
|
+
*
|
|
63
|
+
* The object/array arm mirrors Rust's `Literal::from_json` in
|
|
64
|
+
* `perspective_instance.rs::resolve_property_value` (which routes
|
|
65
|
+
* `Value::Object | Value::Array` through JSON encoding). Without it, JS
|
|
66
|
+
* would fall through to `String(value)` and turn `{a: 1}` into
|
|
67
|
+
* `"[object Object]"` and `[1, 2, 3]` into `"1,2,3"` before wrapping.
|
|
68
|
+
*/
|
|
69
|
+
export declare function valueToLiteralIri(value: any): string;
|
|
70
|
+
/** How a property's value is stored / resolved. */
|
|
71
|
+
export type LiteralStorageMode = {
|
|
72
|
+
kind: "deterministic";
|
|
73
|
+
} | {
|
|
74
|
+
kind: "envelope";
|
|
75
|
+
} | {
|
|
76
|
+
kind: "custom";
|
|
77
|
+
language: string;
|
|
78
|
+
};
|
|
79
|
+
/**
|
|
80
|
+
* Derive the effective storage mode from a property's explicit options.
|
|
81
|
+
* `resolveLanguage` is the sole selector and is NOT defaulted at the
|
|
82
|
+
* decorator level:
|
|
83
|
+
* - unset → deterministic typed literal (the perf default
|
|
84
|
+
* for a plain `@Property()`)
|
|
85
|
+
* - `"literal"` → signed envelope on the built-in literal language
|
|
86
|
+
* (per-value provenance, e.g. Flux message bodies)
|
|
87
|
+
* - `<custom address>` → signed expression on that custom language
|
|
88
|
+
*/
|
|
89
|
+
export declare function effectiveLiteralStorage(meta: {
|
|
90
|
+
resolveLanguage?: string;
|
|
91
|
+
}): LiteralStorageMode;
|
|
30
92
|
/**
|
|
31
93
|
* Format a value as a SPARQL string literal (double-quoted).
|
|
32
94
|
*/
|
|
@@ -70,17 +70,54 @@ export function hasJsOnlyWhereFilters(metadata, allRelationsMetadata, where) {
|
|
|
70
70
|
return false;
|
|
71
71
|
}
|
|
72
72
|
/**
|
|
73
|
-
* Check
|
|
73
|
+
* Check whether a string value is a well-formed absolute IRI that can be
|
|
74
|
+
* stored verbatim as a link target (raw `NamedNode`) instead of being
|
|
75
|
+
* wrapped in a `literal:string:*` URI.
|
|
76
|
+
*
|
|
77
|
+
* This mirrors the Rust `is_safe_iri_target` /
|
|
78
|
+
* `looks_like_absolute_iri` predicate in
|
|
79
|
+
* `rust-executor/src/perspectives/model_query/utils.rs` and is
|
|
80
|
+
* **load-bearing**: a value that returns `true` here MUST also be safely
|
|
81
|
+
* queryable on the Rust side (`validate_iri` gate on the SPARQL
|
|
82
|
+
* `UNION { ?s <pred> <val> }` IRI arm), otherwise scheme-lookalike prose
|
|
83
|
+
* such as `"Note: buy milk"`, `"Re: standup"`, `"TODO: fix this"` slips
|
|
84
|
+
* through the write regex, is stored as an invalid `NamedNode`, and
|
|
85
|
+
* becomes a silent no-match on read.
|
|
86
|
+
*
|
|
87
|
+
* Fast-path scheme check (`^[a-zA-Z][a-zA-Z0-9+\-._]*:`) followed by the
|
|
88
|
+
* same rejection set the Rust `validate_iri` applies: any Unicode
|
|
89
|
+
* whitespace, C0/C1 control chars, and the SPARQL-breaking characters
|
|
90
|
+
* `< > { } "`.
|
|
74
91
|
*/
|
|
75
|
-
function looksLikeUri(value) {
|
|
76
|
-
|
|
92
|
+
export function looksLikeUri(value) {
|
|
93
|
+
if (!/^[a-zA-Z][a-zA-Z0-9+\-._]*:/.test(value))
|
|
94
|
+
return false;
|
|
95
|
+
// Reject anything the Rust-side `validate_iri` rejects so the two
|
|
96
|
+
// predicates stay in sync. `\s` covers ASCII whitespace *and*
|
|
97
|
+
// U+00A0/other Unicode whitespace under the default JS regex semantics.
|
|
98
|
+
if (/[\s<>{}"\u0000-\u001F\u007F-\u009F]/.test(value))
|
|
99
|
+
return false;
|
|
100
|
+
return true;
|
|
77
101
|
}
|
|
78
102
|
/**
|
|
79
103
|
* Convert a JS value to its literal: IRI form, matching how the Rust executor
|
|
80
|
-
* stores property values
|
|
81
|
-
* Strings that already look like URIs are returned
|
|
104
|
+
* stores property values in the default deterministic-literal path
|
|
105
|
+
* (`resolveLanguage` unset). Strings that already look like URIs are returned
|
|
106
|
+
* as-is.
|
|
107
|
+
*
|
|
108
|
+
* Exported so write-side helpers (e.g. `Ad4mModel.setProperty`'s literal
|
|
109
|
+
* resolve path) can keep their on-disk form aligned with what
|
|
110
|
+
* `queryToSPARQL()` filters against — otherwise the same value can be
|
|
111
|
+
* stored as `<literal:string:https%3A...>` from one path while WHERE
|
|
112
|
+
* builders probe `<https://example.com>` from the other.
|
|
113
|
+
*
|
|
114
|
+
* The object/array arm mirrors Rust's `Literal::from_json` in
|
|
115
|
+
* `perspective_instance.rs::resolve_property_value` (which routes
|
|
116
|
+
* `Value::Object | Value::Array` through JSON encoding). Without it, JS
|
|
117
|
+
* would fall through to `String(value)` and turn `{a: 1}` into
|
|
118
|
+
* `"[object Object]"` and `[1, 2, 3]` into `"1,2,3"` before wrapping.
|
|
82
119
|
*/
|
|
83
|
-
function valueToLiteralIri(value) {
|
|
120
|
+
export function valueToLiteralIri(value) {
|
|
84
121
|
if (typeof value === 'string') {
|
|
85
122
|
if (looksLikeUri(value))
|
|
86
123
|
return value;
|
|
@@ -92,22 +129,48 @@ function valueToLiteralIri(value) {
|
|
|
92
129
|
if (typeof value === 'boolean') {
|
|
93
130
|
return Literal.from(value).toUrl();
|
|
94
131
|
}
|
|
132
|
+
// Objects and arrays: route through Literal.from so we emit
|
|
133
|
+
// `literal:json:*` (mirrors Rust `Literal::from_json`). Without this
|
|
134
|
+
// arm we fall through to `String(value)` which turns objects into
|
|
135
|
+
// `"[object Object]"` and arrays into `"1,2"` — silently storing the
|
|
136
|
+
// wrong shape and breaking equality filters (`findAll({ where:
|
|
137
|
+
// { config: {...} } })` would match against `"[object Object]"`).
|
|
138
|
+
// The `value !== null` guard preserves the historical fallthrough for
|
|
139
|
+
// `null` (→ `literal:string:null`), since `Literal.from(null).toUrl()`
|
|
140
|
+
// throws on the empty-literal check.
|
|
141
|
+
if (value !== null && typeof value === 'object') {
|
|
142
|
+
return Literal.from(value).toUrl();
|
|
143
|
+
}
|
|
95
144
|
return Literal.from(String(value)).toUrl();
|
|
96
145
|
}
|
|
97
146
|
/**
|
|
98
|
-
*
|
|
99
|
-
*
|
|
100
|
-
*
|
|
101
|
-
*
|
|
147
|
+
* Derive the effective storage mode from a property's explicit options.
|
|
148
|
+
* `resolveLanguage` is the sole selector and is NOT defaulted at the
|
|
149
|
+
* decorator level:
|
|
150
|
+
* - unset → deterministic typed literal (the perf default
|
|
151
|
+
* for a plain `@Property()`)
|
|
152
|
+
* - `"literal"` → signed envelope on the built-in literal language
|
|
153
|
+
* (per-value provenance, e.g. Flux message bodies)
|
|
154
|
+
* - `<custom address>` → signed expression on that custom language
|
|
155
|
+
*/
|
|
156
|
+
export function effectiveLiteralStorage(meta) {
|
|
157
|
+
const lang = meta.resolveLanguage;
|
|
158
|
+
if (lang === undefined)
|
|
159
|
+
return { kind: "deterministic" };
|
|
160
|
+
if (lang === "literal")
|
|
161
|
+
return { kind: "envelope" };
|
|
162
|
+
return { kind: "custom", language: lang };
|
|
163
|
+
}
|
|
164
|
+
/**
|
|
165
|
+
* Determine if a property stores values as deterministic literal: IRIs (so WHERE
|
|
166
|
+
* filters can match typed literals directly). Envelope / custom-language
|
|
167
|
+
* properties resolve through expressions, and flag properties store raw URIs —
|
|
168
|
+
* none is a deterministic literal.
|
|
102
169
|
*/
|
|
103
170
|
function isLiteralStoredProperty(propMeta) {
|
|
104
171
|
if (propMeta.flag)
|
|
105
172
|
return false;
|
|
106
|
-
|
|
107
|
-
if (propMeta.resolveLanguage && propMeta.resolveLanguage !== "literal")
|
|
108
|
-
return false;
|
|
109
|
-
// Everything else (resolveLanguage === "literal" or undefined) stores as literal: URIs
|
|
110
|
-
return true;
|
|
173
|
+
return effectiveLiteralStorage(propMeta).kind === "deterministic";
|
|
111
174
|
}
|
|
112
175
|
/**
|
|
113
176
|
* Escape a string for use as a SPARQL string literal.
|
|
@@ -25,11 +25,16 @@ export declare function formatQueryValue(value: any): string;
|
|
|
25
25
|
*
|
|
26
26
|
* @param predicate - The predicate URI for the property
|
|
27
27
|
* @param condition - The Where condition value
|
|
28
|
-
* @param opts - Optional settings
|
|
28
|
+
* @param opts - Optional settings. `isDeterministicLiteral` (default
|
|
29
|
+
* `true`) selects the direct typed-literal WHERE path.
|
|
30
|
+
* Set to `false` when the property stores a signed
|
|
31
|
+
* envelope (`resolveLanguage: "literal"`) or a
|
|
32
|
+
* custom-language expression — the envelope path unwraps
|
|
33
|
+
* with `parse_literal` before comparing.
|
|
29
34
|
* @returns A single SPARQL condition string
|
|
30
35
|
*/
|
|
31
36
|
export declare function buildWhereCondition(predicate: string, condition: WhereCondition, opts?: {
|
|
32
|
-
|
|
37
|
+
isDeterministicLiteral?: boolean;
|
|
33
38
|
varIndex?: number;
|
|
34
39
|
}): string;
|
|
35
40
|
/**
|
|
@@ -46,16 +46,21 @@ export function formatQueryValue(value) {
|
|
|
46
46
|
*
|
|
47
47
|
* @param predicate - The predicate URI for the property
|
|
48
48
|
* @param condition - The Where condition value
|
|
49
|
-
* @param opts - Optional settings
|
|
49
|
+
* @param opts - Optional settings. `isDeterministicLiteral` (default
|
|
50
|
+
* `true`) selects the direct typed-literal WHERE path.
|
|
51
|
+
* Set to `false` when the property stores a signed
|
|
52
|
+
* envelope (`resolveLanguage: "literal"`) or a
|
|
53
|
+
* custom-language expression — the envelope path unwraps
|
|
54
|
+
* with `parse_literal` before comparing.
|
|
50
55
|
* @returns A single SPARQL condition string
|
|
51
56
|
*/
|
|
52
57
|
export function buildWhereCondition(predicate, condition, opts) {
|
|
53
58
|
const escapedPredicate = escapeQueryString(predicate);
|
|
54
|
-
// For literal
|
|
55
|
-
//
|
|
56
|
-
// For
|
|
57
|
-
//
|
|
58
|
-
const isLiteral =
|
|
59
|
+
// For deterministic-literal properties, values are stored as typed
|
|
60
|
+
// literals like `"X"^^xsd:string` (or the legacy `<literal:string:VALUE>`
|
|
61
|
+
// IRI form). For envelope / custom-language properties the target is a
|
|
62
|
+
// signed expression URI; comparisons need to unwrap via `parse_literal`.
|
|
63
|
+
const isLiteral = opts?.isDeterministicLiteral !== false;
|
|
59
64
|
const varSuffix = opts?.varIndex ?? 0;
|
|
60
65
|
function formatValue(v) {
|
|
61
66
|
if (typeof v === 'string') {
|
|
@@ -164,23 +169,28 @@ export function compileWhereClause(where, metadata) {
|
|
|
164
169
|
if (['id', 'author', 'timestamp'].includes(propertyName))
|
|
165
170
|
continue;
|
|
166
171
|
let predicate;
|
|
167
|
-
|
|
172
|
+
// Storage mode is derived from `resolveLanguage` alone:
|
|
173
|
+
// - undefined → deterministic typed literal (fast POS-index path)
|
|
174
|
+
// - "literal" → signed envelope on the literal language
|
|
175
|
+
// - custom address → expression on that custom language
|
|
176
|
+
// Envelope and custom-language properties both need the `parse_literal`
|
|
177
|
+
// unwrap path, so we treat any `resolveLanguage`-carrying property as
|
|
178
|
+
// non-deterministic here.
|
|
179
|
+
let isDeterministicLiteral;
|
|
168
180
|
if (metadata) {
|
|
169
181
|
const propMeta = metadata.properties[propertyName];
|
|
170
182
|
if (propMeta) {
|
|
171
183
|
predicate = propMeta.predicate;
|
|
172
|
-
|
|
184
|
+
isDeterministicLiteral = propMeta.resolveLanguage === undefined;
|
|
173
185
|
}
|
|
174
186
|
else {
|
|
175
|
-
// Property not found in metadata — treat name as raw predicate URI
|
|
176
187
|
predicate = propertyName;
|
|
177
188
|
}
|
|
178
189
|
}
|
|
179
190
|
else {
|
|
180
|
-
// No metadata — treat name as raw predicate URI
|
|
181
191
|
predicate = propertyName;
|
|
182
192
|
}
|
|
183
|
-
const cond = buildWhereCondition(predicate, condition, {
|
|
193
|
+
const cond = buildWhereCondition(predicate, condition, { isDeterministicLiteral, varIndex: conditions.length });
|
|
184
194
|
if (cond) {
|
|
185
195
|
conditions.push(cond);
|
|
186
196
|
}
|
|
@@ -104,20 +104,38 @@ interpretationHint) {
|
|
|
104
104
|
name: propName,
|
|
105
105
|
path: propMeta.through,
|
|
106
106
|
};
|
|
107
|
-
// Determine datatype from
|
|
108
|
-
|
|
109
|
-
|
|
107
|
+
// Determine datatype from JS field value type; the resolve* options
|
|
108
|
+
// control storage mode (deterministic vs envelope), not scalar type.
|
|
109
|
+
// A value stored on the literal language (deterministic or envelope,
|
|
110
|
+
// i.e. resolveLanguage unset or "literal") gets a string datatype when
|
|
111
|
+
// no initial value pins a more specific type. A custom resolveLanguage
|
|
112
|
+
// yields an expression URI, not a literal.
|
|
113
|
+
//
|
|
114
|
+
// Skip auto-datatype for properties with a custom `getter` — those
|
|
115
|
+
// typically return URIs (e.g. `@Optional({ getter: "SELECT ?target ..." })`
|
|
116
|
+
// that hops through a link to another instance's URI). Autosetting
|
|
117
|
+
// `sh:datatype xsd:string` there would trip the hydration decode gate
|
|
118
|
+
// and silently transform `literal:string:<hex>` URIs into their inner
|
|
119
|
+
// plain-string form on read. Users who want a getter to return literal
|
|
120
|
+
// values can opt in explicitly by setting `datatype` on the property
|
|
121
|
+
// options (handled below).
|
|
122
|
+
if (propMeta.datatype) {
|
|
123
|
+
// Explicit opt-in from PropertyOptions always wins over inference.
|
|
124
|
+
propShape.datatype = propMeta.datatype;
|
|
110
125
|
}
|
|
111
|
-
else
|
|
112
|
-
const
|
|
113
|
-
if (
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
126
|
+
else {
|
|
127
|
+
const isLiteral = propMeta.resolveLanguage === undefined || propMeta.resolveLanguage === "literal";
|
|
128
|
+
if ((propMeta.initial !== undefined || isLiteral) && !propMeta.getter) {
|
|
129
|
+
const initialType = typeof obj[propName];
|
|
130
|
+
if (initialType === "number") {
|
|
131
|
+
propShape.datatype = "xsd://integer";
|
|
132
|
+
}
|
|
133
|
+
else if (initialType === "boolean") {
|
|
134
|
+
propShape.datatype = "xsd://boolean";
|
|
135
|
+
}
|
|
136
|
+
else if (initialType === "string" || isLiteral) {
|
|
137
|
+
propShape.datatype = "xsd://string";
|
|
138
|
+
}
|
|
121
139
|
}
|
|
122
140
|
}
|
|
123
141
|
// Cardinality constraints
|
|
@@ -219,8 +237,19 @@ interpretationHint) {
|
|
|
219
237
|
name: relName,
|
|
220
238
|
path: synthesizedPath,
|
|
221
239
|
};
|
|
222
|
-
//
|
|
223
|
-
|
|
240
|
+
// A relation with a declared `datatype` holds encoded literal
|
|
241
|
+
// values (e.g. `HasMany<string>` with `datatype: "xsd:string"`).
|
|
242
|
+
// Everything else is a URI relation pointing at another
|
|
243
|
+
// instance. The executor uses `sh:datatype` on hydration to
|
|
244
|
+
// decide whether to decode `literal:<type>:<value>` wire form
|
|
245
|
+
// (yes for literals, no for URIs).
|
|
246
|
+
if (relMeta.datatype) {
|
|
247
|
+
relShape.datatype = relMeta.datatype;
|
|
248
|
+
relShape.nodeKind = 'Literal';
|
|
249
|
+
}
|
|
250
|
+
else {
|
|
251
|
+
relShape.nodeKind = 'IRI';
|
|
252
|
+
}
|
|
224
253
|
// Encode relation kind so the executor can derive direction and
|
|
225
254
|
// scalar-vs-collection rendering without consulting the JS class.
|
|
226
255
|
relShape.relationKind = relMeta.kind;
|
package/lib/src/model/types.d.ts
CHANGED
|
@@ -32,15 +32,25 @@ export type Order = {
|
|
|
32
32
|
[propertyName: string]: "ASC" | "DESC";
|
|
33
33
|
};
|
|
34
34
|
/**
|
|
35
|
-
*
|
|
35
|
+
* A named subgraph scope: a parent node + linking predicate.
|
|
36
36
|
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
37
|
+
* Reusable across contexts that need to identify "the subtree under node X
|
|
38
|
+
* linked via predicate P": query-time filtering as a `parent` filter on a
|
|
39
|
+
* `ModelQuery` (the "all Messages belonging to Channel X" case) AND
|
|
40
|
+
* AutoProcessor's `existingScope` / `mintScope` fields — the former
|
|
41
|
+
* constrains dedup lookups; the latter turns each new mint into a child
|
|
42
|
+
* link under the given node.
|
|
43
|
+
*
|
|
44
|
+
* **Model form** (preferred for parent-filter queries) — predicate
|
|
45
|
+
* auto-resolved from the parent model's relation metadata. Use `field` to
|
|
46
|
+
* disambiguate when the parent has multiple relations targeting the same
|
|
47
|
+
* child class. AutoProcessor `mintScope` requires the **Raw form** because
|
|
48
|
+
* only Raw carries an explicit linking predicate; `Model` scopes have no
|
|
49
|
+
* predicate to write.
|
|
40
50
|
*
|
|
41
51
|
* **Raw form** — explicit predicate string, no metadata lookup.
|
|
42
52
|
*/
|
|
43
|
-
export type
|
|
53
|
+
export type Scope = {
|
|
44
54
|
model: typeof Ad4mModel;
|
|
45
55
|
id: string;
|
|
46
56
|
field?: string;
|
|
@@ -113,7 +123,7 @@ export interface IncludeProjection {
|
|
|
113
123
|
export declare function isIncludeProjection(val: unknown): val is IncludeProjection;
|
|
114
124
|
export type Query = {
|
|
115
125
|
/** Filter to instances that are the target of a link from a given parent. */
|
|
116
|
-
parent?:
|
|
126
|
+
parent?: Scope;
|
|
117
127
|
properties?: string[];
|
|
118
128
|
include?: IncludeMap;
|
|
119
129
|
/**
|
|
@@ -272,7 +282,7 @@ export type IncludeExtras<T extends Ad4mModel, I> = I extends Record<string, any
|
|
|
272
282
|
} ? (R extends RelationKeysOf<T> ? RelatedModel<T, R>[] : never) : unknown;
|
|
273
283
|
} : unknown;
|
|
274
284
|
type StrictTypedQuery<T extends Ad4mModel> = {
|
|
275
|
-
parent?:
|
|
285
|
+
parent?: Scope;
|
|
276
286
|
properties?: PropertyKeysOf<T>[];
|
|
277
287
|
include?: TypedIncludeMap<T>;
|
|
278
288
|
includeAll?: boolean;
|
|
@@ -323,7 +333,12 @@ export interface PropertyMetadata {
|
|
|
323
333
|
readOnly: boolean;
|
|
324
334
|
/** Initial value if specified */
|
|
325
335
|
initial?: string;
|
|
326
|
-
/**
|
|
336
|
+
/** Sole selector of storage mode:
|
|
337
|
+
* - unset → deterministic typed literal (fast POS-index
|
|
338
|
+
* path, the default for a plain `@Property()`)
|
|
339
|
+
* - `"literal"` → signed envelope on the built-in literal language
|
|
340
|
+
* - `<custom address>` → expression on that custom language
|
|
341
|
+
*/
|
|
327
342
|
resolveLanguage?: string;
|
|
328
343
|
/** Custom Prolog getter code */
|
|
329
344
|
prologGetter?: string;
|
|
@@ -1,5 +1,55 @@
|
|
|
1
|
-
/**
|
|
2
|
-
|
|
1
|
+
/**
|
|
2
|
+
* Raw form of `Scope` (parent node + linking predicate) — the only variant
|
|
3
|
+
* the WebSocket auto-processor config accepts. `Scope`'s model form
|
|
4
|
+
* (`{ model: typeof Ad4mModel, id, field? }`) references a JS class
|
|
5
|
+
* constructor, which JSON.stringify silently drops, so the executor would
|
|
6
|
+
* receive `{ id }` and the scope would be unresolvable. Client callers who
|
|
7
|
+
* hold a model class should resolve its predicate via
|
|
8
|
+
* `ModelQueryBuilder.buildParentScope()` first and pass the result here.
|
|
9
|
+
*/
|
|
10
|
+
export type RawScope = {
|
|
11
|
+
id: string;
|
|
12
|
+
predicate: string;
|
|
13
|
+
};
|
|
14
|
+
/**
|
|
15
|
+
* One step in an auto-processor pass (serde camelCase of the Rust enum).
|
|
16
|
+
*
|
|
17
|
+
* ## Lifecycle (winning peer, emitDebugEvents: true)
|
|
18
|
+
*
|
|
19
|
+
* A pass on the winning executor emits, in order:
|
|
20
|
+
*
|
|
21
|
+
* 1. `batchReady` — debounced batch reached threshold, pass starting
|
|
22
|
+
* 2. `claimed` — this executor won the `try_claim`
|
|
23
|
+
* 3. `gatheringTranscript` — pulling the batch's transcript turns
|
|
24
|
+
* 4. `runningInterpretation` — about to invoke the LLM
|
|
25
|
+
* 5. `llmRequestSent` — prompt built + dispatched; carries `llmInput`
|
|
26
|
+
* (only when `emitDebugEvents: true`)
|
|
27
|
+
* 6. `llmResponseReceived` — LLM response arrived; carries `llmOutput`
|
|
28
|
+
* (only when `emitDebugEvents: true`) — the UI
|
|
29
|
+
* can render "waiting on LLM" between steps 5-6
|
|
30
|
+
* 7. `processed` — pass complete; carries `bases[]` (new/updated
|
|
31
|
+
* instance URIs)
|
|
32
|
+
*
|
|
33
|
+
* ## Lifecycle (losing peer, or short-circuit)
|
|
34
|
+
*
|
|
35
|
+
* - `batchReady` → `backedOff` — another peer claimed the batch first
|
|
36
|
+
* - `batchReady` → `awaitingAuthor` — no author of the batch is online
|
|
37
|
+
* - `batchReady` → `notCandidate` — this peer stood down for an earlier author
|
|
38
|
+
* - `claimed` → `shapesMissing` — a configured class shape hasn't synced
|
|
39
|
+
* - `claimed` → `emptyTranscript` — the batch drained empty
|
|
40
|
+
*
|
|
41
|
+
* ## Payload fields per step
|
|
42
|
+
*
|
|
43
|
+
* All steps carry `perspectiveUuid`, `processorId`, `agentDid`, `itemIds[]`.
|
|
44
|
+
* Additional payload:
|
|
45
|
+
*
|
|
46
|
+
* - `backedOff`, `notCandidate` → `detail` = holder / elected-author DID
|
|
47
|
+
* - `shapesMissing` → `detail` = comma-joined missing class URIs
|
|
48
|
+
* - `llmRequestSent` → `llmInput` = raw prompt
|
|
49
|
+
* - `llmResponseReceived` → `llmOutput` = raw LLM response
|
|
50
|
+
* - `processed` → `bases[]` = new/updated instance URIs
|
|
51
|
+
*/
|
|
52
|
+
export type AutoProcessorStep = "batchReady" | "claimed" | "backedOff" | "awaitingAuthor" | "notCandidate" | "gatheringTranscript" | "runningInterpretation" | "llmRequestSent" | "llmResponseReceived" | "processed" | "shapesMissing" | "emptyTranscript";
|
|
3
53
|
/** A single step-signal from one auto-processor pass on one perspective. */
|
|
4
54
|
export interface AutoProcessorEvent {
|
|
5
55
|
type: "auto-processor-event";
|
|
@@ -14,6 +64,44 @@ export interface AutoProcessorEvent {
|
|
|
14
64
|
bases: string[];
|
|
15
65
|
/** Free-form context for the step (a holder/elected DID, an error, …). */
|
|
16
66
|
detail?: string;
|
|
67
|
+
/** Raw LLM prompt this pass fed the model. Present ONLY on
|
|
68
|
+
* `llmRequestSent` events, and only when the processor was configured
|
|
69
|
+
* with `emitDebugEvents: true`. Never carried on `processed`. */
|
|
70
|
+
llmInput?: string;
|
|
71
|
+
/** Raw LLM response this pass received. Present ONLY on
|
|
72
|
+
* `llmResponseReceived` events, and only when the processor was
|
|
73
|
+
* configured with `emitDebugEvents: true`. Never carried on `processed`. */
|
|
74
|
+
llmOutput?: string;
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* Coarse-grained phase of a neighbourhood-state event.
|
|
78
|
+
*
|
|
79
|
+
* `claimed` — this executor just started a pass.
|
|
80
|
+
* `finished` — the pass completed successfully.
|
|
81
|
+
* `abandoned` — the pass short-circuited (missing shape / empty batch /
|
|
82
|
+
* error); the claim will TTL-expire.
|
|
83
|
+
*/
|
|
84
|
+
export type NeighbourhoodPhase = "claimed" | "finished" | "abandoned";
|
|
85
|
+
/**
|
|
86
|
+
* `auto-processor-neighbourhood-state` — perspective-scoped observability
|
|
87
|
+
* event. Fires when THIS executor claims, finishes, or abandons a batch.
|
|
88
|
+
* Anyone with perspective read access sees it, so a UI can render "someone
|
|
89
|
+
* is auto-processing this" without receiving the batch payload or LLM I/O.
|
|
90
|
+
*
|
|
91
|
+
* Cross-executor visibility (peer's claim reaching us via Holochain sync) is
|
|
92
|
+
* NOT covered here; consumers who need that subscribe to `link-added` and
|
|
93
|
+
* filter for the `has_claim` predicate on the shared perspective.
|
|
94
|
+
*/
|
|
95
|
+
export interface AutoProcessorNeighbourhoodStateEvent {
|
|
96
|
+
type: "auto-processor-neighbourhood-state";
|
|
97
|
+
perspectiveUuid: string;
|
|
98
|
+
processorId: string;
|
|
99
|
+
/** DID that claimed the batch — the pass owner's DID. */
|
|
100
|
+
claimantDid: string;
|
|
101
|
+
/** SHA-256 hex of the batch's item-id set — merge `claimed` + `finished`
|
|
102
|
+
* for the same key to render a single row in a UI. */
|
|
103
|
+
batchKey: string;
|
|
104
|
+
phase: NeighbourhoodPhase;
|
|
17
105
|
}
|
|
18
106
|
/** Configuration for `perspective.addAutoProcessor` (everything but `uuid`). */
|
|
19
107
|
export interface AddAutoProcessorConfig {
|
|
@@ -69,6 +157,48 @@ export interface AddAutoProcessorConfig {
|
|
|
69
157
|
* runs.
|
|
70
158
|
*/
|
|
71
159
|
sourceWindowMs?: number;
|
|
160
|
+
/**
|
|
161
|
+
* Optional parent-scope filter for the dedup lookup: when set, only
|
|
162
|
+
* existing instances of the interpretation classes that live under this
|
|
163
|
+
* scope are candidates for upsert. Omit for the whole-perspective dedup
|
|
164
|
+
* set (pre-scope behaviour). Raw form only — see `RawScope`.
|
|
165
|
+
*/
|
|
166
|
+
existingScope?: RawScope;
|
|
167
|
+
/**
|
|
168
|
+
* Optional parent-scope target for newly minted instances: when set,
|
|
169
|
+
* every base URI the pass CREATES is additionally linked as a child of
|
|
170
|
+
* `mintScope.id` via the scope's predicate — turning the SoA-tree
|
|
171
|
+
* "children live under this node" pattern from a URI-prefix convention
|
|
172
|
+
* into an actual graph edge. Upserts of pre-existing instances are NOT
|
|
173
|
+
* linked (would multi-parent unrelated graph state). Raw form only —
|
|
174
|
+
* see `RawScope`; the Rust watcher rejects `Model` scopes at runtime.
|
|
175
|
+
*/
|
|
176
|
+
mintScope?: RawScope;
|
|
177
|
+
/**
|
|
178
|
+
* Persist the raw LLM prompt + response on the pass's `InterpretationRun`
|
|
179
|
+
* (`debugPrompt` / `debugResponse`) so a UI can look them up post-hoc.
|
|
180
|
+
* Independent of `emitDebugEvents` — Nico's PR #903 split so a caller
|
|
181
|
+
* can persist without emitting mid-pass events (retrospective inspection
|
|
182
|
+
* only) or emit without persisting (live observability, no graph-sync
|
|
183
|
+
* payload). Default `false` — LLM I/O is 10s of KB per pass and every
|
|
184
|
+
* enabled peer syncs it.
|
|
185
|
+
*/
|
|
186
|
+
persistDebug?: boolean;
|
|
187
|
+
/**
|
|
188
|
+
* Emit `LlmRequestSent` and `LlmResponseReceived` `auto-processor-event`s
|
|
189
|
+
* mid-pass, so a subscribed UI can render "waiting on LLM" between
|
|
190
|
+
* prompt-send and response-receive. See `persistDebug` for the split
|
|
191
|
+
* rationale. Default `false`.
|
|
192
|
+
*/
|
|
193
|
+
emitDebugEvents?: boolean;
|
|
194
|
+
/**
|
|
195
|
+
* Legacy backwards-compat alias — pre-split callers set `debugMode` as a
|
|
196
|
+
* single coupled flag. When present and both `persistDebug` +
|
|
197
|
+
* `emitDebugEvents` are absent, its value is expanded to both. The two
|
|
198
|
+
* specific fields take precedence when present. Prefer the split fields;
|
|
199
|
+
* this alias is retained so pre-split clients still work.
|
|
200
|
+
*/
|
|
201
|
+
debugMode?: boolean;
|
|
72
202
|
}
|
|
73
203
|
/**
|
|
74
204
|
* Raw REST-API response shape for a pending interpretation overlay.
|
|
@@ -16,7 +16,6 @@
|
|
|
16
16
|
*/
|
|
17
17
|
import { Ad4mModel } from "../model/Ad4mModel";
|
|
18
18
|
export declare class AutoProcessorConfig extends Ad4mModel {
|
|
19
|
-
type: string;
|
|
20
19
|
/** Unique processor id — the dedup key for auto-processor instances. */
|
|
21
20
|
processorId: string;
|
|
22
21
|
/** SPARQL SELECT that gathers source items each pass. */
|
|
@@ -39,9 +38,50 @@ export declare class AutoProcessorConfig extends Ad4mModel {
|
|
|
39
38
|
sourceWindowMs?: string;
|
|
40
39
|
/** Serialised `DedupStrategy` JSON (absent = NormalizedString). */
|
|
41
40
|
dedupStrategy?: string;
|
|
41
|
+
/**
|
|
42
|
+
* Serialised `Scope` JSON (absent = whole-perspective dedup set).
|
|
43
|
+
* Constrains the existing-instance lookup to the subtree rooted at
|
|
44
|
+
* `Scope.id` linked via `Scope.predicate` — the SoA-tree "existing items
|
|
45
|
+
* live under THIS project node" pattern. Stored as an opaque JSON blob
|
|
46
|
+
* because SHACL properties carry no rich-object type-check; the Rust
|
|
47
|
+
* watcher parses it back into `Scope`.
|
|
48
|
+
*/
|
|
49
|
+
existingScope?: string;
|
|
50
|
+
/**
|
|
51
|
+
* Serialised `Scope` JSON (absent = mint sites are unlinked). When set,
|
|
52
|
+
* every freshly created base URI gets an additional `Scope.id
|
|
53
|
+
* --Scope.predicate--> new-uri` link written into the perspective, so
|
|
54
|
+
* mints become first-class children of the target scope. Must be the
|
|
55
|
+
* `Raw` form of `Scope`; `Model` scopes carry no linking predicate.
|
|
56
|
+
*/
|
|
57
|
+
mintScope?: string;
|
|
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.
|
|
66
|
+
*/
|
|
67
|
+
debugMode?: string;
|
|
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"`.
|
|
81
|
+
*/
|
|
82
|
+
emitDebugEvents?: string;
|
|
42
83
|
}
|
|
43
84
|
export declare class InterpretationRun extends Ad4mModel {
|
|
44
|
-
type: string;
|
|
45
85
|
/** UUID for this run — the dedup key across run nodes. */
|
|
46
86
|
runId: string;
|
|
47
87
|
/** LLM model id used for this run. */
|
|
@@ -55,9 +95,17 @@ export declare class InterpretationRun extends Ad4mModel {
|
|
|
55
95
|
/**
|
|
56
96
|
* Source item IDs consumed by this pass.
|
|
57
97
|
* Stored as multiple links with the same predicate; the processed-turn
|
|
58
|
-
* cursor uses these to avoid re-interpreting a turn.
|
|
98
|
+
* cursor uses these to avoid re-interpreting a turn. Values are plain
|
|
99
|
+
* strings (turn hex), so the property opts into `sh:datatype`-gated
|
|
100
|
+
* literal decoding on hydration.
|
|
59
101
|
*/
|
|
60
102
|
sources: string[];
|
|
103
|
+
/** 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. */
|
|
106
|
+
debugPrompt?: string;
|
|
107
|
+
/** Raw LLM response this pass received. Same rules as `debugPrompt`. */
|
|
108
|
+
debugResponse?: string;
|
|
61
109
|
}
|
|
62
110
|
export declare class InterpretationOverlay extends Ad4mModel {
|
|
63
111
|
/**
|