Interface: OsfqlRefusal

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

Machine-actionable detail of a write the engine refused.

Remarks

Present on an OsfqlError (errorType: 'execution', HTTP 422) when the failure is a REFUSAL with a typed cause, so a gate or a self-repair loop can rewrite the statement instead of parsing prose. code is one of:

link_endpoint_not_found, link_endpoint_ambiguous, link_endpoint_binding_mismatch, upsert_ambiguous — the write-designation ladder;
key_value_clash, key_meet_bottom, key_meet_non_principal — the write contradicts the term that already holds the sort’s @key;
bound_constraint_violated — a CHECK ON axiom of the sort refused the values;
write_targets_derived_fact — every term the write designated is a rule’s conclusion; the repairs name the premises to write and the rule to withdraw;
retract_has_referrers — other terms designate a matched term; CASCADE or DETACH repairs it;
retract_named_by_rules — rule terms name a matched term; withdraw the rules first;
retract_cascade_too_large — the CASCADE closure exceeds cascadeLimit; retract in batches;
write_creates_rule — the write carried a non-empty list under when, which would make the term a rule; the use_derive repair states it with DERIVE. A scalar when is ordinary data.
governed_sort_write_refused — the write, delete or rule conclusion targets a @governed sort (or a descendant of one), whose terms only an engine-internal door writes. No principal is exempt and no rewrite repairs it.

Each count has ONE meaning across every code: candidates is what the refused statement’s pattern designated, referrers what blocks a RETRACT, cascadeLimit the bound a RETRACT … CASCADE exceeded.

Example

const refusal: OsfqlRefusal = {
  code: 'upsert_ambiguous',
  sort: 'customer',
  candidates: 2,
  repairs: [
    {
      kind: 'add_discriminator_or_key',
      rewrite: 'UPSERT customer(<add @key feature or discriminator>);',
    },
  ],
};

Properties

candidates

candidates: number

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

How many terms the refused statement’s own pattern designated.

Remarks

link_endpoint_not_found: 0;
link_endpoint_ambiguous, upsert_ambiguous: 2, read as “two or more” (the designation scan stops at the second match);
link_endpoint_binding_mismatch: 1, the bound term;
write_targets_derived_fact: the exact number designated, all of them derived facts;
key_value_clash, key_meet_bottom, key_meet_non_principal: 1, the existing keyed term;
bound_constraint_violated: 1, the term being written;
write_creates_rule: 1 for the term an INSERT writes, or the number of terms an UPDATE designated;
governed_sort_write_refused: 1;
retract_has_referrers, retract_named_by_rules, retract_cascade_too_large: the exact number of asserted terms the RETRACT pattern matched. It is NOT the number of blocking terms — read referrers for that.

cascadeLimit?

optional cascadeLimit?: number

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

For retract_cascade_too_large only: the bound the CASCADE closure exceeded. The closure walk stops at the bound, so its full size is not reported — only that it is larger. Absent for every other code.

code

code: string

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

Typed refusal cause, snake_case, copied verbatim.

referrers?

optional referrers?: number

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

The terms outside the matched set that block a RETRACT: for retract_has_referrers the data terms that designate a matched term, for retract_named_by_rules the rule terms that name one. Absent for every other code.

repairs

repairs: OsfqlRepair[]

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

Concrete rewrites, most-preferred first. Empty when no statement rewrite repairs the refusal: key_value_clash, key_meet_bottom, bound_constraint_violated, retract_named_by_rules and retract_cascade_too_large.

role?

optional role?: string

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

The link endpoint role (source / target) when the statement is a link.

sort

sort: string

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

The sort the refusal concerns: the sort the refused statement’s pattern names or, for key_*, bound_constraint_violated and write_targets_derived_fact through a bound variable, the sort of the term being written.