Clarification of the meaning of a reasoning scope.

[phochste]

In https://w3c-cg.github.io/n3Builtins/#scope , the scope is defined as (my emphasis):

"A scope is either a concretely stated N3 graph, or the reasoning scope, that is, the deductive closure of the whole N3 graph included in the reasoning run, with the exception of the concrete application of the rule the built-in occurs in."

Which means that the following Notation3 should not result in a :test :is false?

@prefix : <http://example.org/> .
@prefix log: <http://www.w3.org/2000/10/swap/log#> .

:a :b :c.

{
    ?ThisDoc log:includes { :a ?X :c. }.
}
=>
{
   # All this is not in the reasoning scope of ?ThisDoc ?
    :a :WRONG :c.

    :foo :bar ?X.

    {
        :foo :bar :WRONG.
    }
    => 
    {
        :result :is false.
    }.
}.

[josd]

I propose the following:

Definition of scope

Scope = the graph of triples that a builtin treats as its local dataset while it runs.

Concretely, a scope is:

• a fixed set of triples (what the builtin queries / matches against), and
• an associated closure level tag that says which saturated snapshot this scope came from.

Scope is fixed per builtin invocation: once the builtin starts, the triples it sees do not change during that invocation.

Where the scope comes from

Explicit scope (GraphTerm)

If the controlling term is a GraphTerm (a { ... } formula term), then:

• scope triples = the triples inside that GraphTerm
• closure tag = if the GraphTerm already has one, use it; otherwise inherit from the caller context

This mode runs immediately (no closure gating).

Closure-gated scope (positive integer priority)

If the controlling term is a positive integer literal N >= 1, then:

• the builtin does not run yet
• it runs only once the engine has reached saturated closure level ≥ N
• scope triples = the frozen snapshot of the global store at that closure level
• closure tag = N (or the snapshot’s level)

This is what makes results stable and allows “wait until closure N”.

Variable / other

If the controlling term is:

• a Var: behave as priority 1, do not bind
• anything else (including 0): treat it as default priority 1

Which argument controls scope

• log:collectAllIn / log:forAllIn: the object controls the scope (GraphTerm vs priority vs var vs other).
• log:includes / log:notIncludes: the subject controls the scope.

Scope propagation rule

When a builtin runs inside a scope tagged with closure level L, and it creates/uses a scoped GraphTerm internally (e.g., for nested builtins), it propagates that same closure tag L into the new scoped GraphTerm.

That’s what prevents nested scoped builtins from “waiting forever” inside a snapshot they can’t identify.

[william-vw]

I agree that the concept of a scope should be clarified. I'm unsure whether we should go into the operational detail that @josd proposes, however. I will loop in @doerthe as well.