API Reference
classes
Shaclflow

@coasys/ad4m / Exports / SHACLFlow

Class: SHACLFlow

SHACL Flow - represents a state machine for AD4M expressions

Flows define:

  • Which expressions can enter the flow (via inputTypes)
  • What states exist and their per-state guards (via requires)
  • How to transition between states (via transitions + consensus rules)

State lives on the on-graph FlowInstanceRecord.currentState and is read/written through the FlowInstance wrapper class (start / findAll) — see design doc §4.3/§5.

Example

const todoFlow = new SHACLFlow('todo://TODO', 'todo://');
 
// Any expression can become a TODO
todoFlow.inputTypes = ['any'];
 
todoFlow.addState({ name: 'ready', value: 0 });
todoFlow.addState({ name: 'doing', value: 0.5 });
todoFlow.addState({ name: 'done',  value: 1 });
 
todoFlow.addTransition({
  actionName: 'Start',
  fromState: 'ready',
  toState: 'doing',
  actions: [],
});
 
// Register on the perspective and mint an instance on a subject.
await perspective.addFlow('TODO', todoFlow);
const instance = await FlowInstance.start(perspective, 'TODO', 'expr://123');

Table of contents

Constructors

Properties

Accessors

Methods

Constructors

constructor

• new SHACLFlow(name, namespace)

Create a new SHACL Flow

Parameters

NameTypeDescription
namestringFlow name (e.g., "TODO")
namespacestringNamespace for URIs (e.g., "todo://")

Defined in

core/src/shacl/SHACLFlow.ts:494 (opens in a new tab)

Properties

_states

• Private _states: FlowState[] = []

States in this flow.

Ordering convention (James PR #929 R9): the array is stored sorted ascending by value. states[0] is the initial state — the one start mints a fresh instance into. A flow author who wants a specific state as the entry point must give it the lowest value in the set. fromLinks enforces this sort, so link-order on the graph never dictates the initial state.

Defined in

core/src/shacl/SHACLFlow.ts:484 (opens in a new tab)

_transitions

• Private _transitions: FlowTransition[] = []

Transitions between states

Defined in

core/src/shacl/SHACLFlow.ts:487 (opens in a new tab)

consensusRule

• Optional consensusRule: ConsensusRule

Flow-level consensus rule. Two roles:

  • Default for state transitions — when a FlowState doesn't declare its own consensusRule, transitions into it fall back to this rule.
  • Zero-state flow completion — for actions-as-flows (a flow with no FlowStates), this is the rule the engine checks the moment outputTypes are satisfied. E.g. a Like flow declares { n: 1 } and completes on the first author.

Design doc §4.1: terminal condition for stateless flows. Unset = engine default of { n: 1 } applies at both layers.

Defined in

core/src/shacl/SHACLFlow.ts:472 (opens in a new tab)

context

• Optional context: ModelQuery[]

Optional background queries pulled into the LLM prompt as CONTEXT (not evidence).

Design doc §4.1: engine evaluates each ModelQuery and threads matches into the prompt so the LLM can reason with them, but matches do NOT count toward requires guards on states. Same ModelQuery[] shape and template-variable rules as FlowState.requires. Empty / unset = no context queries.

Defined in

core/src/shacl/SHACLFlow.ts:457 (opens in a new tab)

creationHint

• Optional creationHint: string

Optional English hint for AI-driven flow-spawn: when should the interpretation engine mint a new instance of this flow (as opposed to advancing an existing one)?

Design doc §4.1: analogous to interpretationHint on subject classes — steers the LLM's up-front extraction pass. Distinct from interpretationHint on the flow, which describes what the flow is. Example (Delivery Flow): "Spawn when someone commits to a concrete, actionable task."

Defined in

core/src/shacl/SHACLFlow.ts:445 (opens in a new tab)

inputTypes

• inputTypes: string[] = []

Subject-class URIs the flow accepts as its base expression.

Design doc §4.1: a flow's typed input. When an expression whose class matches any URI in this array enters scope, the flow-spawn engine considers it a candidate base. Superseded the older link-level flowable: LinkPattern primitive — model-level matching by subject class instead of link matching. Empty array = flow declares no typed input. The "any" sentinel is accepted as a wildcard for tests and legacy flows.

Defined in

core/src/shacl/SHACLFlow.ts:418 (opens in a new tab)

interpretationHint

• Optional interpretationHint: string

Top-level natural-language description of what the flow is about — used by AI-driven state suggestion (suggestFlowState) to frame the state hints. Optional; states' own interpretationHints are what actually discriminate. Example (Deliberation Flow): "Tracks a group deliberation from an initial proposal to a shared understanding — through voicing perspectives, surfacing tension, and finding overlap."

Defined in

core/src/shacl/SHACLFlow.ts:405 (opens in a new tab)

name

• name: string

Flow name (e.g., "TODO")

Defined in

core/src/shacl/SHACLFlow.ts:391 (opens in a new tab)

namespace

• namespace: string

Namespace for generated URIs

Defined in

core/src/shacl/SHACLFlow.ts:394 (opens in a new tab)

outputTypes

• outputTypes: string[] = []

Subject-class URIs the flow must produce (linked to the base) for a run to count as complete.

Design doc §4.1: a flow's typed output. Two jobs: (a) documentation for stateful flows — records what a completed run leaves in the graph; (b) terminal condition for zero-state flows — a flow with no FlowStates completes when at least one instance of each outputTypes entry exists in scope and is linked to the base, and consensusRule fires. This is what makes "Like" a first-class flow with no state machine.

Defined in

core/src/shacl/SHACLFlow.ts:432 (opens in a new tab)

FLOW_LEVEL_PREDICATES

▪ Static Readonly FLOW_LEVEL_PREDICATES: readonly string[]

Every predicate toLinks writes from the flow's own URI. The flow's URI also carries links the definition does not own (a receipt index, for one), so replacing a definition removes only these from it. Keep in step with toLinks.

Defined in

core/src/shacl/SHACLFlow.ts:355 (opens in a new tab)

STATE_AND_TRANSITION_PREDICATES

▪ Static Readonly STATE_AND_TRANSITION_PREDICATES: readonly string[]

Every predicate toLinks writes from a state's or a transition's URI, plus the retired ad4m://stateCheck, so a re-add still clears it from an older definition. These URIs can carry links the definition does not own too (an app's label on a state, for one), so replacing a definition removes only these from them. Keep in step with toLinks.

Defined in

core/src/shacl/SHACLFlow.ts:375 (opens in a new tab)

Accessors

flowUri

• get flowUri(): string

Get the flow shape URI

Returns

string

Defined in

core/src/shacl/SHACLFlow.ts:528 (opens in a new tab)

states

• get states(): FlowState[]

Get all states

Returns

FlowState[]

Defined in

core/src/shacl/SHACLFlow.ts:500 (opens in a new tab)

transitions

• get transitions(): FlowTransition[]

Get all transitions

Returns

FlowTransition[]

Defined in

core/src/shacl/SHACLFlow.ts:505 (opens in a new tab)

Methods

addState

▸ addState(state): void

Add a state to the flow

Parameters

NameTypeDescription
stateFlowStateState definition

Returns

void

Defined in

core/src/shacl/SHACLFlow.ts:513 (opens in a new tab)

addTransition

▸ addTransition(transition): void

Add a transition to the flow

Parameters

NameTypeDescription
transitionFlowTransitionTransition definition

Returns

void

Defined in

core/src/shacl/SHACLFlow.ts:521 (opens in a new tab)

stateUri

▸ stateUri(stateName): string

Get a state URI

Parameters

NameType
stateNamestring

Returns

string

Defined in

core/src/shacl/SHACLFlow.ts:535 (opens in a new tab)

toJSON

▸ toJSON(): object

Convert to JSON representation

Returns

object

Defined in

core/src/shacl/SHACLFlow.ts:1081 (opens in a new tab)

toLinks

▸ toLinks(): Link[]

Serialize the flow to AD4M links These links can be stored in a perspective and queried via SPARQL

Returns

Link[]

Array of Link objects representing the flow

Defined in

core/src/shacl/SHACLFlow.ts:556 (opens in a new tab)

transitionUri

▸ transitionUri(fromState, toState, actionName): string

Get a transition URI: {namespace}{name}.transition/{from}/{to}/{action}. Each part is RFC 3986-encoded, so the URI is unique per transition. The executor's flow writer (parse_flow_to_links) builds the same URI.

Parameters

NameType
fromStatestring
toStatestring
actionNamestring

Returns

string

Defined in

core/src/shacl/SHACLFlow.ts:544 (opens in a new tab)

fromJSON

▸ Static fromJSON(json): SHACLFlow

Create from JSON representation

Parameters

NameType
jsonany

Returns

SHACLFlow

Defined in

core/src/shacl/SHACLFlow.ts:1113 (opens in a new tab)

fromLinks

▸ Static fromLinks(links, flowUri): SHACLFlow

Reconstruct a SHACLFlow from links

Parameters

NameTypeDescription
linksLink[]Array of links containing the flow definition
flowUristringThe URI of the flow to reconstruct

Returns

SHACLFlow

Reconstructed SHACLFlow

Defined in

core/src/shacl/SHACLFlow.ts:773 (opens in a new tab)

SentmessageShaclshape