Interface: OsfqlPreviewResponse

@kortexya/reasoninglayer

---

@kortexya/reasoninglayer / OsfqlPreviewResponse

Interface: OsfqlPreviewResponse

Defined in: src/types/osfql.ts:941

Response from previewing an OSFQL program: what each statement would do, decided without running anything.

Remarks

HTTP 200 for a program that parses, including the empty program, which answers { mutates: false, statements: [] }. Three failures throw instead: a program that does not parse or compile (HTTP 400, OsfqlError with errorType parse / compile); an affected-row probe that outgrows the request’s maxRows (HTTP 422, OsfqlError with errorType: 'row_cap'); and a probe abandoned at the request’s timeoutMs (HTTP 504, DeadlineExceededError).

Example

const preview = await client.osfql.preview('RETRACT customer(tier: "gold");');
if (preview.mutates) {
  const destructive = preview.statements.filter((s) => s.mutates);
  console.log(destructive[0].affected?.count); // 2
}

Properties

atomicRefusal?

optional atomicRefusal?: OsfqlAtomicRefusal | null

Defined in: src/types/osfql.ts:962

Why the program would be refused before it runs, when it would be.

Remarks

Reported in EITHER atomic mode: a DROP SORT or an ALTER SORT beside another statement is refused in both. Absent — or null — otherwise.

---

mutates

mutates: boolean

Defined in: src/types/osfql.ts:952

Whether ANY statement of the program mutates the store.

Remarks

It folds every nested statement. Verified against the dev engine on 2026-09-18: MATCH customer(name: ?N, spend: ?S); IF ?S > 60 THEN RETRACT customer(name: ?N); answers true, and so does an IF whose only writing branch is the ELSE. It also folds an inline-write MATCH, which a first-statement classification would read as safe.

---

statements

statements: OsfqlPreviewStatement[]

Defined in: src/types/osfql.ts:954

One entry per top-level statement, in document order.