@coasys/ad4m / Exports / FlowInstance

Class: FlowInstance

Table of contents

Constructors

• constructor

Properties

• perspective
• record
• shape

Accessors

• availableTransitions
• currentState
• currentStateName
• flowName
• flowUri
• startedAtMillis
• subject
• uri

Methods

• acceptProposal
• proposals
• proposeTransition
• rejectProposal
• findAll
• start
• wrap

Constructors

constructor

• Private new FlowInstance(perspective, shape, record)

Private constructor — construct via start or findAll. wrap is the escape hatch for tests / direct construction cases.

Parameters

Defined in

core/src/perspectives/FlowInstance.ts:207 (opens in a new tab)

Properties

perspective

• Private Readonly perspective: PerspectiveProxy

Defined in

core/src/perspectives/FlowInstance.ts:208 (opens in a new tab)

record

• Readonly record: FlowInstanceRecord

The on-graph record — carries flow, subject, currentState and Ad4mModel's synthesised createdAt. Callers can reach into it for anything the wrapper doesn't expose directly, but should prefer the wrapper accessors so future refactors of the underlying shape don't ripple through their code.

Defined in

core/src/perspectives/FlowInstance.ts:218 (opens in a new tab)

shape

• Readonly shape: SHACLFlow

The flow definition this instance was minted against.

Defined in

core/src/perspectives/FlowInstance.ts:210 (opens in a new tab)

Accessors

availableTransitions

• get availableTransitions(): FlowTransition[]

Every FlowTransition on the shape whose fromState matches currentStateName. Order preserved from the shape.

Empty when the current state is terminal (no outgoing transitions).

Returns

FlowTransition[]

Defined in

core/src/perspectives/FlowInstance.ts:516 (opens in a new tab)

currentState

• get currentState(): FlowState

The FlowState object on the shape matching currentStateName. Throws when the record's state name is not declared on the flow — that's a "stale FlowInstance whose flow was edited under it" bug, not a silent-fail case.

Returns

FlowState

Defined in

core/src/perspectives/FlowInstance.ts:499 (opens in a new tab)

currentStateName

• get currentStateName(): string

Name of the state this instance is currently in.

Returns

string

Defined in

core/src/perspectives/FlowInstance.ts:479 (opens in a new tab)

flowName

• get flowName(): string

Human-readable flow name — the display label. Sourced from the paired SHACLFlow.name, not from the record (which stores the URI as its canonical identity — see FlowInstanceRecord's docstring for why).

Returns

string

Defined in

core/src/perspectives/FlowInstance.ts:469 (opens in a new tab)

flowUri

• get flowUri(): string

Flow URI — the on-graph discriminator, collision-free across modules.

Returns

string

Defined in

core/src/perspectives/FlowInstance.ts:474 (opens in a new tab)

startedAtMillis

• get startedAtMillis(): number

ISO-8601 (epoch millis after Ad4mModel hydration) start time. Returns undefined when hydration didn't produce a createdAt — rare, but not fatal.

Returns

number

Defined in

core/src/perspectives/FlowInstance.ts:488 (opens in a new tab)

subject

• get subject(): string

URI of the base expression this flow runs on — matches the SHACLFlow.inputTypes that availableFlows would greenlight for this expression.

Returns

string

Defined in

core/src/perspectives/FlowInstance.ts:460 (opens in a new tab)

uri

• get uri(): string

URI of the on-graph FlowInstance node — ad4m://flow/instance/{id}.

Sourced from Ad4mModel's synthesised baseExpression, which for FlowInstanceRecord is the instance's own URI (the value FlowTransitionProposal.flowInstance references).

Returns

string

Defined in

core/src/perspectives/FlowInstance.ts:451 (opens in a new tab)

Methods

acceptProposal

▸ acceptProposal(proposal): Promise<FlowFireOutcome[]>

Parameters

Returns

Promise<FlowFireOutcome[]>

Defined in

core/src/perspectives/FlowInstance.ts:567 (opens in a new tab)

proposals

▸ proposals(): Promise<FlowTransitionProposal[]>

All FlowTransitionProposal records targeting this instance's URI.

Uses the SDNA identity discriminator (ad4m://flow/instance predicate) for the where-filter — one SPARQL round-trip, no client-side filtering.

These are written by the executor's consensus pass when it mints a transition, and by clients proposing directly. Superseded proposals are not swept here — a stale one is simply never counted by the fold, and accepting it fails with a stale-state error.

Returns

Promise<FlowTransitionProposal[]>

Defined in

core/src/perspectives/FlowInstance.ts:532 (opens in a new tab)

proposeTransition

▸ proposeTransition(toState, rationale?, outputs?): Promise<FlowProposeResult>

Propose a flow transition for this instance, as the calling agent.

The executor evaluates the guard on its own replica, seals the evidence, and either writes a new proposal or — when an equivalent one is already open, i.e. another agent pressed the same button first — co-signs that one. When the resulting vote reaches the target state's consensusRule.n, the transition fires in the same call.

How to read the result — fired vs. queued vs. no-op vs. stalled — is documented on FlowProposeResult itself.

outputs names the instances the run produces, as { className, id } pairs, for a transition into a terminal state. The proposal signs a hash over their content, every co-signer recomputes it on its own replica, and a receipt for the run speaks for exactly these instances as they stood at completion.

Throws when toState is not reachable from the derived state, when the target state carries a requires guard that is not currently satisfied on this replica, when the instance is already contested, when outputs is given for a non-terminal state or names something that is not an instance of its class, or when an open proposal on the same edge names different outputs.

Parameters

Returns

Promise<FlowProposeResult>

Defined in

core/src/perspectives/FlowInstance.ts:563 (opens in a new tab)

rejectProposal

▸ rejectProposal(proposal): Promise<number>

Withdraw our own links from a proposal; resolves to how many went.

Parameters

Returns

Promise<number>

Defined in

core/src/perspectives/FlowInstance.ts:573 (opens in a new tab)

findAll

▸ Static findAll(perspective, filter?): Promise<FlowInstance[]>

Return every live FlowInstance on the perspective (design doc §4.3).

Read-only path: never registers classes. On a perspective that has never minted a flow instance, the FlowInstanceRecord SHACL shape isn't installed yet — this returns [] in that case rather than mutating the perspective. Registration is the responsibility of start, which is the write path. (Registering on a read would sync a write to every peer in the neighbourhood — exactly what a query must not do — James PR #929 R7.)

Filter surface (all optional, all combinable):

• flowName — narrows by flow-name discriminator (e.g. "Delivery")
• subject — narrows by base-expression URI, i.e. "give me every flow running on THIS expression"

Both filters translate to a single SHACL where-filter round-trip (no client-side filtering); combining them AND-joins server-side. The string-arg shape (FlowInstance.findAll(p, "Delivery")) is shorthand for { flowName: "Delivery" }.

Records whose flow value has no matching SHACLFlow on the perspective (e.g. the flow was unregistered) are silently skipped — the wrapper can't answer currentState / availableTransitions without the shape, and callers routinely iterate the returned array without null-checks.

Parameters

Returns

Promise<FlowInstance[]>

Example

const all = await FlowInstance.findAll(perspective);
const deliveries = await FlowInstance.findAll(perspective, "Delivery");
const onThisTask = await FlowInstance.findAll(perspective, {
  subject: "ad4m://task/1",
});
const deliveriesOnTask = await FlowInstance.findAll(perspective, {
  flowName: "Delivery",
  subject: "ad4m://task/1",
});

Defined in

core/src/perspectives/FlowInstance.ts:361 (opens in a new tab)

start

▸ Static start(perspective, flowName, baseExpression): Promise<FlowInstance>

Start flowName on baseExpression: mint a new FlowInstance on the given perspective (design doc §4.3), or return the one already running there. Calling it twice, or from two clients, does not leave two runs; where two mints raced, every caller gets the earliest.

A flow runs on a subject once: a run that has reached its last state is returned too, not replaced by a new one.

Idempotently registers the hardwired FlowInstanceRecord + FlowTransitionProposal

Parameters

Returns

Promise<FlowInstance>

Model

classes on first call — the on-graph shape matches the Rust-side hardwired SDNA (parity-locked in flow-instance.test.ts / flow-transition-proposal.test.ts).

The returned wrapper carries the parsed SHACLFlow alongside the on-graph record, so currentState / availableTransitions / proposals accessors work without further round-trips.

The record's currentState is a per-replica cache the consensus engine writes as a local link. It is read back only for display — the cache-first path in gather_active_flow_contexts fills the state rendered into LLM context — and never as authority: anything that decides something (the fold, the mint pass) derives state from the signed links present now and does not consult the cache. Treat it as a display hint, not as the flow's state.

Throws

When the flow is unknown or has zero declared states (zero-state flows fire via the forthcoming atomic-action path, §6.3).

Defined in

core/src/perspectives/FlowInstance.ts:268 (opens in a new tab)

wrap

▸ Static wrap(perspective, shape, record): FlowInstance

Escape hatch used by start and findAll — not meant for general use, but public so tests that already own a FlowInstanceRecord + SHACLFlow pair (e.g. from pre-populated fixtures) can build a wrapper without going through the mint path.

Parameters

Returns

FlowInstance

Defined in

core/src/perspectives/FlowInstance.ts:228 (opens in a new tab)