@coasys/ad4m / Exports / ModelQuery
Interface: ModelQuery
A model-level query — the shape a flow's requires guard evaluates
against the perspective's current class-instance graph. Deliberately
higher-level than raw links so guards talk about subject classes, not
the underlying triples.
See design doc §3 principle 2 ("Guards talk about models, not raw graph")
and §4.1 for the full field spec. Template variables allowed inside
where string values: $flow.base, $flow.uri (alias:
$flow.instance), $did — the engine substitutes at evaluation time.
Table of contents
Properties
Properties
className
• className: string
Subject-class URI to search for.
Defined in
core/src/shacl/SHACLFlow.ts:53 (opens in a new tab)
count
• Optional count: Object
Cardinality constraint on matching instances. Default { min: 1 } —
at least one match required to satisfy the guard.
Type declaration
| Name | Type |
|---|---|
max? | number |
min? | number |
Defined in
core/src/shacl/SHACLFlow.ts:63 (opens in a new tab)
didProperty
• Optional didProperty: string
When this query is used as a ConsensusRule.fromRole, names the
property on the matched instance that carries a DID. Design doc §7.2
Shape 1 (instance-carries-DID): engine runs the query, then extracts
didProperty from each result to build the eligible-DID set.
Shape 2 (instance-is-per-DID, using $did templating in where)
omits didProperty — the engine iterates candidate DIDs and treats
a non-empty result set as "this DID matches."
Ignored when the query is used as a state guard (requires) or
background context.
Defined in
core/src/shacl/SHACLFlow.ts:93 (opens in a new tab)
linkedTo
• Optional linkedTo: "flow" | "base" | { to: "flow" | "base" ; via: string }
Scope the query to instances linked from a flow anchor. The anchor
(base subject or flow instance URI) is the source of the link and
the matched item is the target: linkedTo: "base" finds items
where the base subject links TO them via the default predicate
ad4m://has_child.
"base" / "flow" use ad4m://has_child; the object form
{ via, to } names a custom predicate (e.g.
{ via: "ns://about", to: "flow" }).
For the reverse direction (matched instance → anchor), use
where: { about: "$flow.base" } instead — linkedTo cannot
express that direction.
Defined in
core/src/shacl/SHACLFlow.ts:79 (opens in a new tab)
or
• Optional or: ModelQuery[]
OR-compose a role expression across multiple ModelQueries. Semantics:
a DID counts if it appears in the result of ANY branch (design §7.3
multi-role hybrid example — "either reviewer OR admin"). Branches
can carry their own didProperty / where, but NOT linkedTo
(which must be on the outer query — linkedTo on a branch is
rejected at translation time).
Every branch must use the same className as the outer query and
cannot declare its own count — the outer query's class and
cardinality apply to the combined result set.
A ModelQuery with a non-empty or array acts as a composition node;
its own className / where etc. still count as an additional
branch (union with the array). Empty or unset = no composition.
Intentionally scoped to or for v1 — and / not fall out of the
same mechanism and can land later without a schema break (design
§7.4). Ignored when the query is used as a state guard or context.
Defined in
core/src/shacl/SHACLFlow.ts:114 (opens in a new tab)
producedByFlow
• Optional producedByFlow: ProducedByFlow
When this query is used as a ConsensusRule.fromRole, require each
matched instance to be a valid output of a completed run of another
flow, and date the grant from that run's quorum instead of from an
assignment link.
The same name and the same check as the model-query filter
where: { producedByFlow }: a receipt filed under flow's index must
verify against this replica's own flow definitions, be for flow, have
settled into state, and name this instance (as this query's
className) among its outputs. Each replica checks this against its
own graph; the read-set carries only the resulting grant date.
Two things to know before configuring one:
- An instance no verified receipt produced is simply not a member. There is no fallback to the assignment link — if there were, writing that link would grant the role and this gate would be decorative.
- A granted role is not un-granted by undoing the flow. Retracting
a settling vote moves the live flow back; the receipt keeps
verifying. The only un-grant is a new signed
ad4m://flow/role_grant_revokedtombstone on the instance, from an author this query's ownwhere.authoraccepts — so a query with no author condition can be revoked by anyone, and one naming an author who is not around cannot be revoked at all.
Ignored when the query is used as a state guard (requires) or
background context.
Defined in
core/src/shacl/SHACLFlow.ts:143 (opens in a new tab)
where
• Optional where: Object
Per-property conditions (all must match — AND semantics inside one ModelQuery, same as AND semantics across an array of ModelQueries).
Index signature
▪ [prop: string]: PropertyCondition | string