Interface: OsfqlPreviewStatement

@kortexya/reasoninglayer / OsfqlPreviewStatement

Interface: OsfqlPreviewStatement

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

One statement of a previewed OSFQL program.

Remarks

The shape is recursive: nested carries the branches of an IF and the continuations of a WITH. index is a single counter over the whole program, not a position among siblings — an IF at index 1 whose two branches are previewed carries nested entries at index 2 and 3.

Read mutates, not risk, to decide whether a statement writes. The two can disagree: MARK ?m1, CUT and SPACE CREATE ?S are risk: "process_control" with mutates: false, while CHAIN and RELEASE RESIDUATIONS share that same tier and report mutates: true. A MATCH with an inline write classifies by its write: MATCH customer(name: ?N) INSERT vip(name: ?N) (or LINK, UPSERT LINK) is risk: "additive_write", and an inline UPDATE, REMOVE, UNLINK, DELETE or DETACH DELETE — or an IF/WITH that holds one — is risk: "targeted_destructive".

Example

const statement: OsfqlPreviewStatement = {
  index: 0,
  id: 'retract',
  statement: 'Retract',
  risk: 'targeted_destructive',
  mutates: true,
  sorts: ['customer'],
  source: 'RETRACT customer(tier: "gold")',
  affected: { count: 2 },
};

Properties

affected?

optional affected?: OsfqlPreviewAffected

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

The rows the statement would affect.

Remarks

Absent means the statement HAS no affected-row set — a read, or an additive write, which adds rows rather than reaching existing ones — OR that its rows could not be counted, and then affectedError says why. Measured: a MATCH and an INSERT carry no affected block, while a destructive statement whose probe succeeds always carries one, count: 0 included. Read affectedError before reading an absent block as “no affected-row set”.

affectedError?

optional affectedError?: string

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

Why this statement’s affected rows could not be counted — the error its probe met, an unknown sort for example.

Remarks

Absent whenever affected is present, and for a statement with no affected-row set. When it is present the count is UNKNOWN: render “unknown”, never “nothing”. A MATCH with an inline UPDATE, REMOVE, UNLINK or DELETE is counted like a RETRACT: it carries affected, and this field only when its probe fails.

The probe runs against the tenant AS IT IS BEFORE THE PROGRAM, so this says the count is unknown, not that the run fails: a sort an earlier statement of the same program declares is unknown to the probe and known to the run. DEFINE s(label: string); RETRACT s(label: "x"); reports Unknown sort: s here and runs successfully.

id

id: string

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

Catalog id of the statement, e.g. match, retract, clear_facts.

index

index: number

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

Position in a single counter over the whole program, nested entries included.

mutates

mutates: boolean

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

Whether THIS statement writes the store. The verdict a write gate reads.

nested?

optional nested?: OsfqlPreviewStatement[]

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

The statements nested inside this one — the THEN and ELSE branches of an IF, the continuations of a WITH. Absent when there are none.

refusal?

optional refusal?: string

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

The refusal the run would raise for this statement, with the message POST /api/v1/osfql answers. Absent when the statement would run.

Remarks

The preview reports it when it can decide it: a stand-alone write that names a variable an earlier statement bound, or a RETRACT / UPDATE of an append-only fluent term, including an inline write of a MATCH onto a fluent entry. A write gate reads it before the user confirms.

risk

risk: RiskTier

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

Safety tier the engine assigned this entry — a coarse pre-filter.

Remarks

This is the real RiskTier union, because the preview route’s own schema publishes the enum. OsfqlCatalogEntry.risk beside it is a plain string on purpose: the catalog’s documented contract is that its enum values are copied verbatim out of a DEBUG/introspection endpoint whose fields mix casing, so narrowing it would make the SDK reject a value the engine is free to add there. Do not “fix” either one to match the other.

An entry with mixed sub-operations carries its most-dangerous dominant tier, and the security boundary re-derives the real tier per authored statement at execution — so this is a hint for the UI, never the gate.

sortDelete?

optional sortDelete?: SortDeletePreviewResponse

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

For a DROP SORT: what the sort delete with the options of the statement would do, and the refusal it would answer with.

Remarks

The body SortsClient.previewSortDelete answers. Absent for every other statement.

sorts

sorts: string[]

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

The sort names the statement names. Empty for a statement that names none.

Remarks

A feature-type word in a DEFINE (string, integer, text, date, …) is listed only when a sort of that name exists earlier in the program or in the tenant.

source

source: string

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

The exact source text of the statement, without its terminating ;.

statement

statement: string

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

Exact AST variant name, e.g. Match, Retract, Clear.