Interface: OsfqlRequest
@kortexya/reasoninglayer / OsfqlRequest
Interface: OsfqlRequest
Section titled “Interface: OsfqlRequest”Defined in: src/types/osfql.ts:42
Request to execute an OSFQL program.
Remarks
Section titled “Remarks”The query field accepts one or more OSFQL statements separated by semicolons. Supported statement types include MATCH, INSERT, RETRACT, DERIVE, UNIFY, DEFINE, AWAIT, COUNTERFACTUAL, and CAUSES.
Properties
Section titled “Properties”atomic?
Section titled “atomic?”
optionalatomic?:boolean
Defined in: src/types/osfql.ts:84
Run the program as ONE all-or-nothing unit.
Remarks
Section titled “Remarks”When a statement fails, every mutation the earlier statements made is
undone before the error is returned: no term, sort or axiom the program
wrote survives. Set it to false for the historical behaviour, where the
statements that already succeeded stay committed.
⚠️ A DROP SORT and an ALTER SORT … PARENTS must each be the ONLY
statement of their program, WHATEVER this flag says. The engine runs the
sort delete (or the move) after the program, durably, so a statement
beside it would run first and could not be undone by a refused delete. A
program that holds one beside anything else is refused with HTTP 422 —
atomic: false does not lift the rule. OsfqlClient.preview names
the cause (drop_sort_not_alone / alter_sort_not_alone) in
OsfqlPreviewResponse.atomicRefusal.
Default Value
Section titled “Default Value”true
inference?
Section titled “inference?”
optionalinference?:boolean
Defined in: src/types/osfql.ts:55
Recompute deductions in a private read snapshot and never publish a change.
Remarks
Section titled “Remarks”The engine accepts only a read-only program in this mode and refuses reactive actions. Use it to ask what the rules entail without writing the conclusions to the tenant’s store.
Default Value
Section titled “Default Value”false
maxRows?
Section titled “maxRows?”
optionalmaxRows?:number
Defined in: src/types/osfql.ts:103
The maximum number of rows any ONE candidate-set materialisation may produce.
Remarks
Section titled “Remarks”It bounds a single scan’s push and a single join’s output, which is where
an unbounded MATCH blows up. It is NOT a program-wide budget: every
statement, and every scratch environment an OPTIONAL or an UNWIND
builds, is charged against the cap from zero.
A breach is an ERROR, never a truncated answer — a caller must be able to
tell a capped result from a complete one. It throws OsfqlError
with errorType: 'row_cap' and the cap in maxRows (HTTP 422), and
nothing is written.
Default Value
Section titled “Default Value”unbounded. No default cap is applied, because one would change the answer to a query that works today.query:
string
Defined in: src/types/osfql.ts:44
The OSFQL program text (one or more statements separated by ;).
reactive?
Section titled “reactive?”
optionalreactive?:boolean
Defined in: src/types/osfql.ts:63
Opt into reactive (streaming) mode: after the program runs, any suspended
AWAIT demon whose trigger is now satisfied fires automatically — no explicit
RELEASE RESIDUATIONS needed.
Default Value
Section titled “Default Value”false — demons stay suspended until an explicit RELEASE.
semantics?
Section titled “semantics?”
optionalsemantics?:OsfqlSemantics
Defined in: src/types/osfql.ts:141
Which data model the program is answered under.
Remarks
Section titled “Remarks”Set this to 'rdf' when running a statement that
SparqlClient.translateQuery returned. Under the default 'osf'
such a statement answers differently from the SPARQL endpoint — term ids
instead of RDF identities, a list as one value instead of one solution per
element, the OSF null instead of an unbound variable — and the difference is
silent: the answers are wrong, not refused.
Omitted, the key is absent on the wire and the engine applies 'osf'.
Default Value
Section titled “Default Value”'osf'
timeoutMs?
Section titled “timeoutMs?”
optionaltimeoutMs?:number
Defined in: src/types/osfql.ts:125
A server-side deadline for this program, in milliseconds.
Remarks
Section titled “Remarks”The engine checks it cooperatively — between statements, at every plan
operation, at every candidate-set materialisation, and inside each
chainer’s own loop — and answers 504 when it passes. It is clamped by
the engine’s own OSFKB_OSFQL_TIMEOUT_SECS.
This is the ENGINE’s deadline, distinct from the client-side RequestOptions.timeoutMs: this one makes the engine stop working and roll an atomic program back, whereas the client-side one only stops waiting for the answer.
0 is the explicit opt-out — no deadline at all.
A breach throws DeadlineExceededError (HTTP 504), which a caller retries rather than rewrites.
Default Value
Section titled “Default Value”the engine's program backstop (default 600 s).