@coasys/ad4m / Exports / PerspectiveProxy

Class: PerspectiveProxy

PerspectiveProxy provides a high-level interface for working with AD4M Perspectives - agent-centric semantic graphs that store and organize links between expressions.

A Perspective is fundamentally a collection of links (subject-predicate-object triples) that represent an agent's view of their digital world. Through PerspectiveProxy, you can:

• Add, remove, and query links
• Work with Social DNA (subject classes and flows)
• Subscribe to real-time updates
• Share perspectives as Neighbourhoods
• Execute Prolog queries for complex graph patterns

Example

// Create and work with links
const perspective = await ad4m.perspective.add("My Space");
await perspective.add({
  source: "did:key:alice",
  predicate: "knows",
  target: "did:key:bob"
});
 
// Query links
const friends = await perspective.get({
  source: "did:key:alice",
  predicate: "knows"
});
 
// Use Social DNA
await perspective.addSdna(todoClass, "subject_class");
const todo = await perspective.createSubject("Todo", "expression://123");
 
// Subscribe to changes
perspective.on("link-added", ({ link }) => {
  console.log("New link added:", link);
});

Table of contents

Constructors

• constructor

Properties

• #client
• #ensuredSubjectClasses
• #handle
• #overlaysInFlight
• #releases
• name
• neighbourhood
• owners
• sharedUrl
• state
• uuid

Accessors

• ai

Methods

• acceptFlowProposal
• acceptInterpretation
• add
• addAutoProcessor
• addFlow
• addLinkExpression
• addLinks
• addNamedOption
• addSdna
• addSdnaAll
• addShacl
• availableFlows
• clearEnsuredSubjectClasses
• commitBatch
• createBatch
• createExpression
• createSubject
• dispose
• ensureSDNASubjectClass
• ensureSubjectClass
• ensureSubjectClasses
• escapeRegExp
• evaluateGetters
• executeAction
• findClassByProperties
• findInstancesByMetadata
• flowValidOutputs
• get
• getActionsFromSHACL
• getAllShacl
• getAllSubjectInstances
• getClassShape
• getExpression
• getFlow
• getInstanceClasses
• getNamedOptions
• getNeighbourhoodProxy
• getSdna
• getSdnaForClass
• getShacl
• getShaclNames
• getShaclTargetClass
• getSingleTarget
• getSubjectClassMetadata
• getSubjectData
• infer
• interpretationOverlays
• isSubjectInstance
• linkMutations
• listRegisteredClasses
• loadSnapshot
• mintFlowReceipt
• modelQuery
• modelSubscribe
• on
• proposeFlowTransition
• querySparql
• rejectFlowProposal
• rejectInterpretation
• remove
• removeAutoProcessor
• removeLinks
• removeSubject
• runInterpretation
• runInterpretationWithHarness
• sdnaFlows
• setSingleTarget
• snapshot
• stringOrTemplateObjectToSubjectClassName
• subjectClassTargetClasses
• subjectClasses
• subjectClassesByTemplate
• subjectClassesOf
• subscribeInfer
• subscribeQuery
• update
• updateHandle
• verifyFlowReceipt

Constructors

constructor

• new PerspectiveProxy(handle, ad4m)

Creates a new PerspectiveProxy instance. Note: Don't create this directly, use ad4m.perspective.add() instead.

Parameters

Defined in

core/src/perspectives/PerspectiveProxy.ts:611 (opens in a new tab)

Properties

#client

• Private #client: PerspectiveClient

Defined in

core/src/perspectives/PerspectiveProxy.ts:596 (opens in a new tab)

#ensuredSubjectClasses

• Private #ensuredSubjectClasses: Set<string>

Defined in

core/src/perspectives/PerspectiveProxy.ts:603 (opens in a new tab)

#handle

• Private #handle: PerspectiveHandle

Defined in

core/src/perspectives/PerspectiveProxy.ts:595 (opens in a new tab)

#overlaysInFlight

• Private #overlaysInFlight: Promise<InterpretationOverlayInfo[]> = null

The interpretationOverlays() RPC currently in flight, shared by concurrent callers.

Defined in

core/src/perspectives/PerspectiveProxy.ts:605 (opens in a new tab)

#releases

• Private #releases: Set<() => void>

Releases of the handlers on() registered and has not released yet.

Defined in

core/src/perspectives/PerspectiveProxy.ts:602 (opens in a new tab)

name

• name: string

Human-readable name of this perspective

Defined in

core/src/perspectives/PerspectiveProxy.ts:581 (opens in a new tab)

neighbourhood

• neighbourhood: NeighbourhoodExpression

If this perspective is shared, this contains the Neighbourhood metadata

Defined in

core/src/perspectives/PerspectiveProxy.ts:587 (opens in a new tab)

owners

• Optional owners: string[]

List of owners of this perspective

Defined in

core/src/perspectives/PerspectiveProxy.ts:593 (opens in a new tab)

sharedUrl

• sharedUrl: string

If this perspective is shared as a Neighbourhood, this is its URL

Defined in

core/src/perspectives/PerspectiveProxy.ts:584 (opens in a new tab)

state

• state: PerspectiveState

Current sync state if this perspective is shared

Defined in

core/src/perspectives/PerspectiveProxy.ts:590 (opens in a new tab)

uuid

• uuid: string

Unique identifier of this perspective

Defined in

core/src/perspectives/PerspectiveProxy.ts:578 (opens in a new tab)

Accessors

ai

• get ai(): AIClient

Returns a proxy object for working with AI capabilities.

Returns

AIClient

AIClient instance

Example

// Use AI to analyze perspective content
const summary = await perspective.ai.summarize();
 
// Generate new content
const suggestion = await perspective.ai.suggest("next action");

Defined in

core/src/perspectives/PerspectiveProxy.ts:2594 (opens in a new tab)

Methods

acceptFlowProposal

▸ acceptFlowProposal(proposalUri): Promise<FlowFireOutcome[]>

Parameters

Returns

Promise<FlowFireOutcome[]>

Defined in

core/src/perspectives/PerspectiveProxy.ts:928 (opens in a new tab)

acceptInterpretation

▸ acceptInterpretation(base, property?): Promise<boolean>

Accept an interpretation overlay's suggestion(s): the LLM's staged value becomes the real, human-owned value and the overlay is deleted. Pass property to accept a single predicate; omit it for the whole base.

Parameters

Returns

Promise<boolean>

Defined in

core/src/perspectives/PerspectiveProxy.ts:894 (opens in a new tab)

add

▸ add(link, status?, batchId?): Promise<LinkExpression>

Adds a new link to the perspective.

Parameters

Returns

Promise<LinkExpression>

The created LinkExpression

Example

// Add a simple relationship
await perspective.add({
  source: "did:key:alice",
  predicate: "follows",
  target: "did:key:bob"
});
 
// Add a local-only link
await perspective.add({
  source: "note://123",
  predicate: "tag",
  target: "private"
}, "local");

Defined in

core/src/perspectives/PerspectiveProxy.ts:1139 (opens in a new tab)

addAutoProcessor

▸ addAutoProcessor(config): Promise<string>

Register a neighbourhood auto-processor on this perspective. The executor then runs interpretation automatically over new source items (like Flux per channel), coordinating which peer processes each batch. Returns the processor id. Subscribe to progress via on('auto-processor-event').

Parameters

Returns

Promise<string>

Defined in

core/src/perspectives/PerspectiveProxy.ts:840 (opens in a new tab)

addFlow

▸ addFlow(name, flow): Promise<void>

Recommended way to add Flow definitions.

Store a SHACL Flow (state machine) in this Perspective using the type-safe SHACLFlow class. The flow is serialized as RDF triples (links) for native AD4M storage and querying.

Parameters

Returns

Promise<void>

Example

import { SHACLFlow } from '@coasys/ad4m';
 
const deliveryFlow = new SHACLFlow('Delivery', 'delivery://');
deliveryFlow.inputTypes = ['Task'];
deliveryFlow.interpretationHint =
  'Advance a Task through delivery: Identified → Scoped → InProgress → Review → Done.';
 
deliveryFlow.addState({ name: 'Identified', value: 0 });
deliveryFlow.addState({ name: 'Scoped',     value: 1 });
deliveryFlow.addState({ name: 'InProgress', value: 2 });
deliveryFlow.addState({ name: 'Review',     value: 3 });
deliveryFlow.addState({ name: 'Done',       value: 4 });
 
deliveryFlow.addTransition({ actionName: 'Scope',  fromState: 'Identified', toState: 'Scoped',     actions: [] });
deliveryFlow.addTransition({ actionName: 'Start',  fromState: 'Scoped',     toState: 'InProgress', actions: [] });
deliveryFlow.addTransition({ actionName: 'Submit', fromState: 'InProgress', toState: 'Review',     actions: [] });
deliveryFlow.addTransition({ actionName: 'Accept', fromState: 'Review',     toState: 'Done',       actions: [] });
 
// Optional: n distinct DIDs must co-sign a proposal before it fires.
deliveryFlow.consensusRule = { n: 2 };
 
await perspective.addFlow('Delivery', deliveryFlow);

Rejects, storing nothing, when a consensusRule carries a key the executor does not know or a key written twice (#1144): the error names the state and the key.

Defined in

core/src/perspectives/PerspectiveProxy.ts:1710 (opens in a new tab)

addLinkExpression

▸ addLinkExpression(link, status?, batchId?): Promise<LinkExpression>

Adds a pre-signed LinkExpression to the perspective.

Parameters

Returns

Promise<LinkExpression>

The added LinkExpression

Defined in

core/src/perspectives/PerspectiveProxy.ts:1195 (opens in a new tab)

addLinks

▸ addLinks(links, status?, batchId?): Promise<LinkExpression[]>

Adds multiple links to the perspective in a single operation. More efficient than adding links one by one.

Parameters

Returns

Promise<LinkExpression[]>

Array of created LinkExpressions

Defined in

core/src/perspectives/PerspectiveProxy.ts:1154 (opens in a new tab)

addNamedOption

▸ addNamedOption(className, propertyName, value, label?): Promise<void>

Adds a named option (sh:in value) to a property of a registered class. This appends to the existing sh:in list stored on the property shape.

Parameters

Returns

Promise<void>

Defined in

core/src/perspectives/PerspectiveProxy.ts:2544 (opens in a new tab)

addSdna

▸ addSdna(name, sdnaCode, sdnaType, shaclJson?): Promise<boolean>

Adds Social DNA code to the perspective.

Recommended: Use addShacl instead, which accepts the SHACLShape type directly. This method is primarily for the RPC API layer and legacy Prolog code.

Parameters

Returns

Promise<boolean>

Example

// Recommended: Use addShacl() with SHACLShape type
const shape = new SHACLShape('recipe://Recipe');
shape.addProperty({ name: 'title', path: 'recipe://title', datatype: 'xsd:string' });
await perspective.addShacl('Recipe', shape);
 
// Legacy: Prolog code is auto-converted to SHACL
await perspective.addSdna('Recipe', prologCode, 'subject_class');

Defined in

core/src/perspectives/PerspectiveProxy.ts:1549 (opens in a new tab)

addSdnaAll

▸ addSdnaAll(entries): Promise<boolean[]>

Batch variant of addSdna — registers multiple SDNA entries in a single RPC call. Acquires the Rust-side mutex once for the entire batch.

Parameters

Returns

Promise<boolean[]>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1557 (opens in a new tab)

addShacl

▸ addShacl(name, shape): Promise<void>

Recommended way to add SDNA schemas.

Store a SHACL shape in this Perspective. The executor writes it as links, as it does for @Model classes. The shape needs a targetClass and keeps its nodeShapeUri, which must end with {name}Shape.

Parameters

Returns

Promise<void>

Example

import { SHACLShape } from '@coasys/ad4m';
 
const shape = new SHACLShape('recipe://Recipe');
shape.addProperty({ 
  name: 'title', 
  path: 'recipe://title', 
  datatype: 'xsd:string',
  minCount: 1 
});
shape.addProperty({
  name: 'ingredients',
  path: 'recipe://has_ingredient',
  // No maxCount = relation
});
 
await perspective.addShacl('Recipe', shape);

Defined in

core/src/perspectives/PerspectiveProxy.ts:1618 (opens in a new tab)

availableFlows

▸ availableFlows(exprAddr): Promise<string[]>

Returns all Social DNA flows that can be started from the given expression.

Post-flowable retirement: a flow is a candidate iff its inputTypes declaration is compatible with the expression. Matching rules:

• Empty inputTypes or one containing the "any" wildcard → always matches (same behaviour as the legacy flowable === "any" case).
• Otherwise, at least one of the expression's registered subject-class URIs (resolved via subjectClassesOf) must appear in inputTypes. This is the concrete-type match the design doc's §5 spawn engine calls for; without it, a flow declaring inputTypes: ["Task"] was previously never returned by availableFlows("some-task-uri") — the entire point of typed flows was silently unreachable (James PR #929 J#3).

The expression is classified against the perspective's registered classes only. An expression whose class is not registered on this perspective matches no typed flow (absence, not falsehood — same discipline as subjectClassesOf); typed flows requiring unknown classes are still returned to their untyped-caller peers.

Parameters

Returns

Promise<string[]>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1434 (opens in a new tab)

clearEnsuredSubjectClasses

▸ clearEnsuredSubjectClasses(): void

Clear the per-instance ensured subject class cache. Call this after wiping a perspective's links so that subsequent register() calls re-add SHACL definitions.

Returns

void

Defined in

core/src/perspectives/PerspectiveProxy.ts:2374 (opens in a new tab)

commitBatch

▸ commitBatch(batchId): Promise<LinkExpressionMutations>

Commits a batch of operations

Parameters

Returns

Promise<LinkExpressionMutations>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1268 (opens in a new tab)

createBatch

▸ createBatch(): Promise<string>

Creates a new batch for grouping operations

Returns

Promise<string>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1263 (opens in a new tab)

createExpression

▸ createExpression(content, languageAddress): Promise<string>

Creates a new Expression in the specified Language.

Parameters

Returns

Promise<string>

URI of the created Expression

Defined in

core/src/perspectives/PerspectiveProxy.ts:1290 (opens in a new tab)

createSubject

▸ createSubject<T, B>(subjectClass, exprAddr, initialValues?, batchId?): Promise<B extends undefined ? T : string>

Creates a new subject instance of the given subject class

Type parameters

Parameters

Returns

Promise<B extends undefined ? T : string>

A proxy object for the created subject, or just the expression address if in batch mode

Defined in

core/src/perspectives/PerspectiveProxy.ts:1887 (opens in a new tab)

dispose

▸ dispose(): void

Removes every handler this proxy registered. Other proxies for the same perspective keep theirs.

Returns

void

Defined in

core/src/perspectives/PerspectiveProxy.ts:1318 (opens in a new tab)

ensureSDNASubjectClass

▸ ensureSDNASubjectClass(jsClass): Promise<void>

Takes a JS class (its constructor) and assumes that it was decorated by the

Parameters

Returns

Promise<void>

Subject Class

etc. decorators. It then tests if there is a subject class already present in the perspective's SDNA that matches the given class. If there is no such class, it gets the JS class's SDNA by calling its static generateSDNA() function and adds it to the perspective's SDNA.

Defined in

core/src/perspectives/PerspectiveProxy.ts:2338 (opens in a new tab)

ensureSubjectClass

▸ ensureSubjectClass(jsClass): Promise<void>

Takes a JS class (its constructor) and ensures the SHACL subject class exists.

Parameters

Returns

Promise<void>

Defined in

core/src/perspectives/PerspectiveProxy.ts:2343 (opens in a new tab)

ensureSubjectClasses

▸ ensureSubjectClasses(jsClasses): Promise<void>

Batch-registers multiple model classes as SHACL subject classes in a single RPC call. Skips classes already registered on this perspective instance.

Parameters

Returns

Promise<void>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1565 (opens in a new tab)

escapeRegExp

▸ Private escapeRegExp(str): string

Escapes special regex characters in a string to prevent ReDoS attacks and regex injection when building dynamic regular expressions.

Parameters

Returns

string

The escaped string safe for use in RegExp constructor

Defined in

core/src/perspectives/PerspectiveProxy.ts:649 (opens in a new tab)

evaluateGetters

▸ evaluateGetters(className, instanceIds, propertyNames?): Promise<Record<string, Record<string, any>>>

Evaluate property getters for a batch of instances in a single RPC call. Returns a map of { instanceId: { prop: value, ... } }.

Use this instead of Ad4mModel.evaluateGetters() for lazy-loading getter-backed properties on visible items (e.g. replyingTo on messages).

Parameters

Returns

Promise<Record<string, Record<string, any>>>

Map of instance ID → evaluated property values

Defined in

core/src/perspectives/PerspectiveProxy.ts:1088 (opens in a new tab)

executeAction

▸ executeAction(actions, expression, parameters, batchId?): Promise<boolean>

Executes a set of actions on an expression with optional parameters. Used internally by Social DNA flows and subject class operations.

Actions are specified as an array of commands that modify links in the perspective. Each action is an object with the following format:

{
  action: "addLink" | "removeLink" | "setSingleTarget" | "collectionSetter",
  source: string,    // Usually "this" to reference the current expression
  predicate: string, // The predicate URI
  target: string     // The target value or "value" for parameters
}

Available commands:

• addLink: Creates a new link
• removeLink: Removes an existing link
• setSingleTarget: Removes all existing links with the same source/predicate and adds a new one
• collectionSetter: Special command for setting relation properties

When used with parameters, the special value "value" in the target field will be replaced with the actual parameter value.

Parameters

Returns

Promise<boolean>

Example

// Add a state link and remove an old one
await perspective.executeAction([
  {
    action: "addLink",
    source: "this",
    predicate: "todo://state", 
    target: "todo://doing"
  },
  {
    action: "removeLink",
    source: "this",
    predicate: "todo://state",
    target: "todo://ready"
  }
], "expression://123");
 
// Set a property using a parameter
await perspective.executeAction([
  {
    action: "setSingleTarget",
    source: "this",
    predicate: "todo://title",
    target: "value"
  }
], "expression://123", [
  { name: "title", value: "New Title" }
]);

Defined in

core/src/perspectives/PerspectiveProxy.ts:713 (opens in a new tab)

findClassByProperties

▸ Private findClassByProperties(obj): Promise<string>

Find a subject class by matching an object's properties/relations against SHACL shapes. Queries SHACL links client-side to find a class whose properties contain all required ones.

Parameters

Returns

Promise<string>

The matching class name, or null if no match found.

Defined in

core/src/perspectives/PerspectiveProxy.ts:2200 (opens in a new tab)

findInstancesByMetadata

▸ Private findInstancesByMetadata(metadata): Promise<{ base: string }[]>

Finds all instances matching subject class metadata by querying links. Returns base URIs of matching instances.

Parameters

Returns

Promise<{ base: string }[]>

Defined in

core/src/perspectives/PerspectiveProxy.ts:2110 (opens in a new tab)

flowValidOutputs

▸ flowValidOutputs(flow, state?): Promise<FlowValidOutput[]>

Which instances are, as they stand, valid outputs of flow?

Backed by receipt verification executor-side (see FlowValidOutput); an instance without a verifying receipt, or edited since its run completed, is not listed. The same predicate is available as a model-query filter: where: { producedByFlow: { flow, state? } }.

Rejects — never resolves to [] — when the flow is not on this perspective, or when it carries more receipt candidates than the executor's per-flow budget (256): "could not read every receipt" is not "no valid outputs". The filter rejects the same way.

Parameters

Returns

Promise<FlowValidOutput[]>

Defined in

core/src/perspectives/PerspectiveProxy.ts:960 (opens in a new tab)

get

▸ get(query, options?): Promise<LinkExpression[]>

Retrieves links from the perspective that match the given query.

Parameters

Returns

Promise<LinkExpression[]>

Array of matching LinkExpressions

Example

// Get all links where Alice knows someone
const links = await perspective.get({
  source: "did:key:alice",
  predicate: "knows"
});
 
// Get all comments on a post
const comments = await perspective.get({
  source: "post://123",
  predicate: "comment"
});

Defined in

core/src/perspectives/PerspectiveProxy.ts:740 (opens in a new tab)

getActionsFromSHACL

▸ Private getActionsFromSHACL(className, predicate): Promise<any[]>

Gets actions from SHACL links for a given predicate (e.g., ad4m://constructor, ad4m://destructor). Returns the parsed action array if found, or null if not found.

Parameters

Returns

Promise<any[]>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1953 (opens in a new tab)

getAllShacl

▸ getAllShacl(): Promise<{ name: string ; shape: SHACLShape }[]>

Get all SHACL shapes stored in this Perspective (one RPC call). The executor resolves all shapes in-process and returns them in bulk. A shape that fails to decode is skipped with a console.warn, so it does not hide the others.

Returns

Promise<{ name: string ; shape: SHACLShape }[]>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1658 (opens in a new tab)

getAllSubjectInstances

▸ getAllSubjectInstances<T>(subjectClass): Promise<T[]>

Returns all subject instances of the given subject class as proxy objects.

Type parameters

Parameters

Returns

Promise<T[]>

Defined in

core/src/perspectives/PerspectiveProxy.ts:2141 (opens in a new tab)

getClassShape

▸ getClassShape(className): Promise<{ className: string ; properties: { collection: boolean ; datatype?: string ; name: string ; options?: { label?: string ; value: string }[] ; predicate: string ; required: boolean ; writable: boolean }[] ; shapeUri: string }>

Returns the SHACL shape metadata for a registered class, including property names, predicates, datatypes, and cardinality constraints.

Parameters

Returns

Promise<{ className: string ; properties: { collection: boolean ; datatype?: string ; name: string ; options?: { label?: string ; value: string }[] ; predicate: string ; required: boolean ; writable: boolean }[] ; shapeUri: string }>

Shape metadata or null if the class is not registered

Defined in

core/src/perspectives/PerspectiveProxy.ts:2407 (opens in a new tab)

getExpression

▸ getExpression(expressionURI): Promise<ExpressionRendered>

Retrieves and renders an Expression referenced in this perspective.

Parameters

Returns

Promise<ExpressionRendered>

The rendered Expression

Defined in

core/src/perspectives/PerspectiveProxy.ts:1279 (opens in a new tab)

getFlow

▸ getFlow(name): Promise<SHACLFlow>

Retrieve a Flow definition by name from this Perspective

Parameters

Returns

Promise<SHACLFlow>

The SHACLFlow or null if not found

Defined in

core/src/perspectives/PerspectiveProxy.ts:1766 (opens in a new tab)

getInstanceClasses

▸ getInstanceClasses(baseExpression): Promise<string[]>

Detects which registered subject classes a given instance conforms to, based on its stored triples matching the class shapes' required properties.

Parameters

Returns

Promise<string[]>

Array of class names the instance matches

Defined in

core/src/perspectives/PerspectiveProxy.ts:2492 (opens in a new tab)

getNamedOptions

▸ getNamedOptions(className): Promise<Record<string, { label?: string ; value: string }[]>>

Returns all named options (sh:in values) for a registered class, grouped by property.

Parameters

Returns

Promise<Record<string, { label?: string ; value: string }[]>>

Record mapping property name → array of { value, label } options

Defined in

core/src/perspectives/PerspectiveProxy.ts:2523 (opens in a new tab)

getNeighbourhoodProxy

▸ getNeighbourhoodProxy(): NeighbourhoodProxy

Returns

NeighbourhoodProxy

Defined in

core/src/perspectives/PerspectiveProxy.ts:2576 (opens in a new tab)

getSdna

▸ getSdna(): Promise<string[]>

Returns the perspective's Social DNA code This will return all SDNA code elements in an array.

Returns

Promise<string[]>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1457 (opens in a new tab)

getSdnaForClass

▸ getSdnaForClass(className): Promise<string>

Returns the Social DNA code for a specific class This will return the SDNA code for the specified class, or null if not found.

Parameters

Returns

Promise<string>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1500 (opens in a new tab)

getShacl

▸ getShacl(name): Promise<SHACLShape>

Retrieve a SHACL shape by name from this Perspective (one RPC call). The executor resolves the full shape (including property sub-shapes) in-process and returns link triples for client-side reconstruction.

Parameters

Returns

Promise<SHACLShape>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1627 (opens in a new tab)

getShaclNames

▸ getShaclNames(): Promise<string[]>

List the names of every SHACL shape stored in this Perspective (one RPC call).

Returns

Promise<string[]>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1636 (opens in a new tab)

getShaclTargetClass

▸ getShaclTargetClass(name): Promise<string>

Resolve a shape's sh:targetClass by name (one RPC call).

PerspectiveClient.getShaclTargetClass now returns undefined on "not found" already (see review r3897752023 — the null→undefined coercion used to happen here and be duplicated one layer down), so this method is a pure passthrough.

Parameters

Returns

Promise<string>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1648 (opens in a new tab)

getSingleTarget

▸ getSingleTarget(query): Promise<string | void>

Gets a single target value matching a query. Useful when you expect only one result.

Parameters

Returns

Promise<string | void>

Target value or void if not found

Example

// Get a user's name
const name = await perspective.getSingleTarget({
  source: "did:key:alice",
  predicate: "name"
});

Defined in

core/src/perspectives/PerspectiveProxy.ts:1366 (opens in a new tab)

getSubjectClassMetadata

▸ getSubjectClassMetadata(className): Promise<{ properties: Map<string, { predicate: string ; resolveLanguage?: string }> ; relations: Map<string, { condition?: string ; instanceFilter?: string ; predicate: string }> ; requiredPredicates: string[] ; requiredTriples: { predicate: string ; target?: string }[] }>

Gets subject class metadata from SHACL links using SHACLShape.fromLinks(). Retrieves the SHACL shape and extracts metadata for instance queries.

Parameters

Returns

Promise<{ properties: Map<string, { predicate: string ; resolveLanguage?: string }> ; relations: Map<string, { condition?: string ; instanceFilter?: string ; predicate: string }> ; requiredPredicates: string[] ; requiredTriples: { predicate: string ; target?: string }[] }>

Defined in

core/src/perspectives/PerspectiveProxy.ts:2042 (opens in a new tab)

getSubjectData

▸ getSubjectData<T>(subjectClass, exprAddr): Promise<T>

Type parameters

Parameters

Returns

Promise<T>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1936 (opens in a new tab)

infer

▸ infer(query, options?): Promise<any>

Executes a Prolog query against the perspective's knowledge base. This is a powerful way to find complex patterns in the graph.

Parameters

Returns

Promise<any>

Query results or false if no results

Example

// Find friends of friends
const results = await perspective.infer(`
  triple(A, "knows", B),
  triple(B, "knows", C),
  A \= C
`);
 
// Find all active todos
const todos = await perspective.infer(`
  instance(Todo, "Todo"),
  property_getter("Todo", Todo, "state", "active")
`);

Defined in

core/src/perspectives/PerspectiveProxy.ts:992 (opens in a new tab)

interpretationOverlays

▸ interpretationOverlays(): Promise<InterpretationOverlayInfo[]>

Pending interpretation overlays on this perspective — LLM suggestions the §4 divergence gate staged rather than applied, awaiting human accept/reject.

Concurrent callers share one in-flight RPC. Nothing is kept after it settles, so every call made after that fetches from the executor again. acceptInterpretation and rejectInterpretation detach the in-flight RPC, so a read issued after they resolve never joins a read that started before the write. Each caller gets its own copy of the array.

Returns

Promise<InterpretationOverlayInfo[]>

Defined in

core/src/perspectives/PerspectiveProxy.ts:874 (opens in a new tab)

isSubjectInstance

▸ isSubjectInstance<T>(expression, subjectClass): Promise<boolean>

Checks if the given expression is a subject instance of the given subject class

Type parameters

Parameters

Returns

Promise<boolean>

Defined in

core/src/perspectives/PerspectiveProxy.ts:2011 (opens in a new tab)

linkMutations

▸ linkMutations(mutations, status?): Promise<LinkExpressionMutations>

Applies a set of link mutations (adds and removes) in a single operation. Useful for atomic updates to the perspective.

Parameters

Returns

Promise<LinkExpressionMutations>

Object containing results of the mutations

Defined in

core/src/perspectives/PerspectiveProxy.ts:1181 (opens in a new tab)

listRegisteredClasses

▸ listRegisteredClasses(): Promise<string[]>

Returns a list of all class names that have been registered as SHACL subject classes in this perspective (via ensureSDNASubjectClass or addSdna).

Returns

Promise<string[]>

Array of class name strings (e.g. ["Channel", "Message", "Task"])

Defined in

core/src/perspectives/PerspectiveProxy.ts:2384 (opens in a new tab)

loadSnapshot

▸ loadSnapshot(snapshot): Promise<void>

Loads a perspective snapshot, replacing current content.

Parameters

Returns

Promise<void>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1337 (opens in a new tab)

mintFlowReceipt

▸ mintFlowReceipt(instanceUri): Promise<FlowMintedReceipt>

Mint and store the receipt for a completed flow run.

Parameters

Returns

Promise<FlowMintedReceipt>

Defined in

core/src/perspectives/PerspectiveProxy.ts:965 (opens in a new tab)

modelQuery

▸ modelQuery(className, queryJson, options?): Promise<{ instances: any[] ; totalCount: number }>

Execute a model query — the executor-side replacement for SPARQL query building + JS hydration.

The executor resolves the model's shape from the perspective's SHACL triples (written by addSdna). Callers no longer ship shape metadata with the query; the perspective is the source of truth.

Parameters

Returns

Promise<{ instances: any[] ; totalCount: number }>

Object with instances array and totalCount

Defined in

core/src/perspectives/PerspectiveProxy.ts:1037 (opens in a new tab)

modelSubscribe

▸ modelSubscribe(className, queryJson): Promise<{ result: any ; subscriptionId: string }>

Subscribe to model query changes. Builds trigger SPARQL from the model shape internally in Rust, registers a subscription, runs the initial query, and pushes updated results when relevant links change.

The subscription reuses the same WS-RPC subscription channel as subscribeQuery(). Use keepAliveQuery() / disposeQuerySubscription() with the returned subscriptionId.

Parameters

Returns

Promise<{ result: any ; subscriptionId: string }>

Object with subscriptionId and initial result

Defined in

core/src/perspectives/PerspectiveProxy.ts:1110 (opens in a new tab)

on

▸ on<K>(type, handler): () => void

Call handler with every type event about this perspective, until the returned function or dispose releases it.

Type parameters

Parameters

Returns

fn

▸ (): void

Call handler with every type event about this perspective, until the returned function or dispose releases it.

Returns

void

Example

perspective.on("link-added", ({ link }) => console.log("New link:", link));
perspective.on("link-updated", ({ oldLink, newLink }) => console.log(oldLink, "->", newLink));
perspective.on("sync-state-change", ({ state }) => console.log("Sync state:", state));

Example

perspective.on("link-added", ({ link }) => console.log("New link:", link));
perspective.on("link-updated", ({ oldLink, newLink }) => console.log(oldLink, "->", newLink));
perspective.on("sync-state-change", ({ state }) => console.log("Sync state:", state));

Defined in

core/src/perspectives/PerspectiveProxy.ts:1305 (opens in a new tab)

proposeFlowTransition

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

outputs names the instances a run produces, as { className, id } pairs, for a transition into a terminal state. The proposal signs a hash over their content, and a receipt for the run can only speak for exactly these instances, as they stood at completion. Naming outputs for a non-terminal state is refused.

Parameters

Returns

Promise<FlowProposeResult>

Defined in

core/src/perspectives/PerspectiveProxy.ts:924 (opens in a new tab)

querySparql

▸ querySparql<T>(query, options?): Promise<T>

Executes a SPARQL query against the perspective's link cache. This allows powerful SQL-like queries on the link data stored in SPARQL.

Security Note: Only read-only queries (SELECT, RETURN, etc.) are permitted. Mutating operations (DELETE, UPDATE, INSERT, CREATE, DROP, DEFINE, etc.) are blocked for security reasons. Use the perspective's add/remove methods to modify links.

Cancellation: Pass { signal } from an AbortController to abort an in-flight query. The executor receives request.cancel over the WebSocket and short-circuits the JSON reply. Caveat: Oxigraph itself cannot be interrupted mid-evaluation, so an already-running scan will keep its blocking thread busy until it completes; what's saved is the serialise + network + client-deserialise tax on the result. Aborted calls reject with DOMException('Aborted', 'AbortError') — match fetch() for handling. Cached results bypass the round-trip entirely and are returned synchronously, ignoring the signal.

Type parameters

Parameters

Returns

Promise<T>

Query results as parsed JSON

Defined in

core/src/perspectives/PerspectiveProxy.ts:1018 (opens in a new tab)

rejectFlowProposal

▸ rejectFlowProposal(proposalUri): Promise<number>

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

Parameters

Returns

Promise<number>

Defined in

core/src/perspectives/PerspectiveProxy.ts:933 (opens in a new tab)

rejectInterpretation

▸ rejectInterpretation(base, property?): Promise<boolean>

Reject an interpretation overlay's suggestion(s). Omit property to reject the whole base — a rejected create deletes the suggested instance, a rejected update drops the overlay and keeps the real value.

Parameters

Returns

Promise<boolean>

Defined in

core/src/perspectives/PerspectiveProxy.ts:908 (opens in a new tab)

remove

▸ remove(link, batchId?): Promise<boolean>

Removes a link from the perspective.

Accepts either a full LinkExpressionInput (as returned by add) or a bare Link (source/predicate/target only). When a bare Link is passed the method resolves it to the first stored LinkExpression whose source, predicate, and target match, then removes that expression. A bare Link without a predicate (or with the constructor's "" stand-in) matches only stored links that themselves have no predicate. If no match is found an error is thrown naming the link so the caller knows what was expected.

Parameters

Returns

Promise<boolean>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1226 (opens in a new tab)

removeAutoProcessor

▸ removeAutoProcessor(processorId): Promise<boolean>

Stop an auto-processor by deleting its config.

The registration is data — the watch loop reads the processor set back out of the perspective's graph on every tick — so deleting the config is what stops it, and there is nothing else to unregister. The config is Shared, so this stops the processor for the neighbourhood rather than only for this peer.

Resolves true when there was a processor to remove and false when there was not; a processor another peer has already removed is not an error.

The processor's InterpretationRun nodes stay: they are the record of what it did and the processed-turn cursor, so a processor later registered under the same id resumes where this one left off rather than re-reading every turn.

Parameters

Returns

Promise<boolean>

Defined in

core/src/perspectives/PerspectiveProxy.ts:859 (opens in a new tab)

removeLinks

▸ removeLinks(links, batchId?): Promise<LinkExpression[]>

Removes multiple links from the perspective.

Parameters

Returns

Promise<LinkExpression[]>

Array of removed LinkExpressions

Defined in

core/src/perspectives/PerspectiveProxy.ts:1167 (opens in a new tab)

removeSubject

▸ removeSubject<T>(subjectClass, exprAddr, batchId?): Promise<void>

Removes a subject instance by running its (SDNA defined) destructor, which means removing links around the given expression address

Type parameters

Parameters

Returns

Promise<void>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1992 (opens in a new tab)

runInterpretation

▸ runInterpretation(transcript, basePrefix, classes?, options?): Promise<string[]>

Runs generic LLM interpretation over a conversation transcript, turning it into typed instances of this perspective's own SHACL subject classes (steered by each class's @InterpretationHint). The target shapes are resolved automatically from the perspective's registered classes, so you pass only the transcript. New instances are written as links into this perspective; the returned placements list each instance's base URI and the links written for it.

Parameters

Returns

Promise<string[]>

Defined in

core/src/perspectives/PerspectiveProxy.ts:759 (opens in a new tab)

runInterpretationWithHarness

▸ runInterpretationWithHarness(transcript, basePrefix, maxToolCalls, classes?, modelOverride?, observationId?, emitDebugEvents?, options?): Promise<string[]>

Harness-dispatched interpretation pass over this perspective (design v3 §6 — the tool-calling counterpart to runInterpretation). The LLM sees a live per-class tool surface ({Class}_query, {Class}_get, {Class}_propose_create, {Class}_propose_link_child, …) and drives the extraction via tool calls; buffered proposals drain through the same overlay gate the single-shot path uses.

Parameters

Returns

Promise<string[]>

Defined in

core/src/perspectives/PerspectiveProxy.ts:804 (opens in a new tab)

sdnaFlows

▸ sdnaFlows(): Promise<string[]>

Returns all the Social DNA flows defined in this perspective

Returns

Promise<string[]>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1398 (opens in a new tab)

setSingleTarget

▸ setSingleTarget(link, status?): Promise<void>

Sets a single target value, removing any existing targets.

Parameters

Returns

Promise<void>

Example

// Set a user's status
await perspective.setSingleTarget({
  source: "did:key:alice",
  predicate: "status",
  target: "online"
});

Defined in

core/src/perspectives/PerspectiveProxy.ts:1391 (opens in a new tab)

snapshot

▸ snapshot(): Promise<Perspective>

Creates a snapshot of the current perspective state. Useful for backup or sharing.

Returns

Promise<Perspective>

Perspective object containing all links

Defined in

core/src/perspectives/PerspectiveProxy.ts:1328 (opens in a new tab)

stringOrTemplateObjectToSubjectClassName

▸ stringOrTemplateObjectToSubjectClassName<T>(subjectClass): Promise<string>

Type parameters

Parameters

Returns

Promise<string>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1859 (opens in a new tab)

subjectClassTargetClasses

▸ subjectClassTargetClasses(): Promise<string[]>

Return the full target-class URIs of every registered SubjectClass.

Unlike subjectClasses, which strips the namespace and returns bare names ("Space", "Channel"), this method returns the complete URIs ("we://Space", "flux://Channel"). The full URI is the key that load_shape resolves against, so it is the only collision-safe identifier — two apps can both declare a class called "Template" under different namespaces, and the bare name cannot distinguish them.

Callers that need to check whether a set of models are already registered should call this once and test membership against the returned set, rather than issuing one queryLinks per model.

One queryLinks round trip, no executor-side changes. A failed lookup rejects rather than answering [], which would read as "nothing is registered" and lead such a caller to register everything again.

Returns

Promise<string[]>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1848 (opens in a new tab)

subjectClasses

▸ subjectClasses(): Promise<string[]>

Returns all the Subject classes defined in this perspectives SDNA

Uses SHACL-based lookup (Prolog-free implementation).

Returns

Promise<string[]>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1808 (opens in a new tab)

subjectClassesByTemplate

▸ subjectClassesByTemplate(obj): Promise<string[]>

Returns all subject classes that match the given template object. This function looks at the properties of the template object and its setters and relations to create a Prolog query that finds all subject classes that would be converted to a proxy object with exactly the same properties and relations.

Since there could be multiple subject classes that match the given criteria, this function returns a list of class names.

Parameters

Returns

Promise<string[]>

Defined in

core/src/perspectives/PerspectiveProxy.ts:2298 (opens in a new tab)

subjectClassesOf

▸ subjectClassesOf(uris): Promise<Record<string, string[]>>

Resolve each URI to the names of every subject class it is an instance of.

The counterpart of isSubjectInstance, which asks the same question one class at a time. Without this, finding the class of an arbitrary URI meant looping over every registered class — a round trip each — and doing it again for every URI.

Class membership in AD4M is structural — a URI belongs to a class when it carries that class's flags and required properties — so membership is not exclusive: an instance conforms to its parent classes, and to any unrelated class whose required set happens to be a subset of what it carries. Every match is returned.

The list is ordered most specific first, meaning by the number of triples the class requires — a subclass requires everything its parent does and more — with ties broken alphabetically so that every peer answers identically. A caller that can only act on one class should take classes[0], but that head is only a heuristic: it is arbitrary between two unrelated classes requiring the same number of triples, which is exactly the case the full list exists to expose.

A URI is absent from the result when no registered class matched it. That covers two situations, and nothing here separates them: the URI may not be a subject instance at all, or it may be an instance of a class this perspective has not registered. Absence is used rather than an empty list because an empty list would claim the stronger thing — that the URI belongs to no class — which this cannot know.

Parameters

Returns

Promise<Record<string, string[]>>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1071 (opens in a new tab)

subscribeInfer

▸ subscribeInfer(query): Promise<QuerySubscriptionProxy>

Creates a subscription for a Prolog query that updates in real-time.

This method:

1. Creates the subscription on the Rust side
2. Sets up the subscription callback
3. Waits for the initial result to come through the subscription channel
4. Returns a fully initialized QuerySubscriptionProxy

The returned subscription is guaranteed to be ready to receive updates, as this method waits for the initialization process to complete.

The subscription will be automatically cleaned up on both frontend and backend when dispose() is called. Make sure to call dispose() when you're done to prevent memory leaks and ensure proper cleanup of resources.

Parameters

Returns

Promise<QuerySubscriptionProxy>

Initialized QuerySubscriptionProxy instance

Example

// Subscribe to active todos
const subscription = await perspective.subscribeInfer(`
  instance(Todo, "Todo"),
  property_getter("Todo", Todo, "state", "active")
`);
 
// Subscription is already initialized here
console.log("Initial result:", subscription.result);
 
// Set up callback for future updates
subscription.onResult((todos) => {
  console.log("Active todos:", todos);
});
 
// Clean up subscription when done
subscription.dispose();

Defined in

core/src/perspectives/PerspectiveProxy.ts:2637 (opens in a new tab)

subscribeQuery

▸ subscribeQuery(query): Promise<QuerySubscriptionProxy>

Creates a subscription for a SPARQL query that updates in real-time.

This method:

1. Creates the subscription on the Rust side
2. Sets up the subscription callback
3. Waits for the initial result to come through the subscription channel
4. Returns a fully initialized QuerySubscriptionProxy

The returned subscription is guaranteed to be ready to receive updates, as this method waits for the initialization process to complete.

The subscription will be automatically cleaned up on both frontend and backend when dispose() is called. Make sure to call dispose() when you're done to prevent memory leaks and ensure proper cleanup of resources.

/** Subscribe to a query with live updates via the SPARQL subscription endpoint.

Parameters

Returns

Promise<QuerySubscriptionProxy>

Initialized QuerySubscriptionProxy instance

Defined in

core/src/perspectives/PerspectiveProxy.ts:2673 (opens in a new tab)

update

▸ update(oldLink, newLink, batchId?): Promise<LinkExpression>

Updates an existing link with new data.

Parameters

Returns

Promise<LinkExpression>

Defined in

core/src/perspectives/PerspectiveProxy.ts:1206 (opens in a new tab)

updateHandle

▸ updateHandle(handle): void

Update the proxy's internal handle and public fields in-place. Keeps the same object reference so all holders see the update.

Parameters

Returns

void

Defined in

core/src/perspectives/PerspectiveProxy.ts:624 (opens in a new tab)

verifyFlowReceipt

▸ verifyFlowReceipt(receipt): Promise<FlowReceiptVerdict>

Re-decide a flow receipt under this perspective's own flow catalogue. The verdict is three-way — see FlowReceiptVerdict: branch on outcome, never on a boolean you derive from it.

Parameters

Returns

Promise<FlowReceiptVerdict>

Defined in

core/src/perspectives/PerspectiveProxy.ts:942 (opens in a new tab)