knowledgepixels / nanopub-query / 36121009261

package com.knowledgepixels.query;

import java.nio.charset.StandardCharsets;

import java.util.ArrayList;

import java.util.HashSet;

import java.util.List;

import java.util.Optional;

import java.util.Set;

import org.eclipse.rdf4j.common.transaction.IsolationLevels;

import org.eclipse.rdf4j.model.IRI;

import org.eclipse.rdf4j.model.Statement;

import org.eclipse.rdf4j.model.Value;

import org.eclipse.rdf4j.model.ValueFactory;

import org.eclipse.rdf4j.model.impl.SimpleValueFactory;

import org.eclipse.rdf4j.model.vocabulary.FOAF;

import org.eclipse.rdf4j.model.vocabulary.RDF;

import org.eclipse.rdf4j.query.BindingSet;

import org.eclipse.rdf4j.query.BooleanQuery;

import org.eclipse.rdf4j.query.QueryLanguage;

import org.eclipse.rdf4j.query.TupleQueryResult;

import org.eclipse.rdf4j.query.Update;

import org.eclipse.rdf4j.repository.RepositoryConnection;

import org.eclipse.rdf4j.repository.RepositoryResult;

import org.nanopub.vocabulary.NPA;

import org.nanopub.vocabulary.NPX;

import org.slf4j.Logger;

import org.slf4j.LoggerFactory;

import com.google.common.hash.Hashing;

import com.knowledgepixels.query.vocabulary.GEN;

import com.knowledgepixels.query.vocabulary.NPAA;

import com.knowledgepixels.query.vocabulary.NPAT;

import com.knowledgepixels.query.vocabulary.SpacesVocab;

/**

 * Drives the space-state materialization pipeline. Three entry points scheduled

 * by {@code MainVerticle}:

 * <ul>

 *   <li>{@link #tick()} — detects trust-state flips (full build) and otherwise

 *       advances the current space-state graph by an {@link #runIncrementalCycle

 *       incremental cycle} bounded by {@code (processedUpTo, currentLoadCounter]}.</li>

 *   <li>{@link #periodicRebuildTick()} — checks the {@code npa:needsFullRebuild}

 *       flag set by structural invalidations and re-runs the full build into a

 *       fresh graph, atomically flips the pointer, drops the old graph.</li>

 *   <li>{@link #cleanOrphans()} — startup cleanup of {@code npass:*} graphs the

 *       pointer isn't referencing.</li>

 * </ul>

 *

 * <p>Incremental cycle order: invalidation DELETEs (admin RI / RoleAssignment /

 * non-admin RI) → trust mirror-step delta is implicit (rebuilt only on full build) →

 * pending-account mirror delta (issue #195, bounded by its own meta-repo watermark) →

 * per-tier INSERTs (admin → alias → attachment → maintainer → member → observer) →

 * late-arrival sweep (re-run downstream tiers without the load-number filter

 * iff this cycle added any structural rows). Sets {@code npa:needsFullRebuild}

 * when an admin RI / RoleAssignment / RoleDeclaration was invalidated; periodic

 * worker turns the flag into a from-scratch rebuild.

 *

 * <p>See {@code doc/design-space-repositories.md} — this implements the "Full

 * build", "Incremental cycle", and "Periodic full rebuild" procedures.

 */

public final class AuthorityResolver {

    private static final String SPACES_REPO = "spaces";

    private static final String TRUST_REPO = "trust";

    /** Source of introduction-nanopub meta triples for the pending-account mirror (issue #195). */

    private static final String META_REPO = "meta";

    /**

     * Server-side limit, in seconds, on the invalidation checks, invalidation deletes and

     * tier inserts this class sends to the spaces repo. Equal to the client's socket read

     * timeout, so it never cuts off a request that could succeed today; its job is to stop

     * rdf4j from evaluating a request the client has already given up on. Without it, a

     * check that never finished on 2026-09-24 (rdf4j 6.1.0) kept running server-side while

     * every tick retried it, until dozens of copies pegged rdf4j on every host. An update

     * aborted by the limit rolls back as a whole.

     */

    private static final int SERVER_TIME_LIMIT_SECONDS = TripleStore.SOCKET_TIMEOUT_SECONDS;

    /** NPA constants pulled in locally (trust-side). */

    /**

     * Class of the introduced-but-unapproved account rows written by

     * {@link #mirrorPendingAccounts} (issue #195).

     *

     * <p>Deliberately <em>not</em> {@code npa:AccountState}. An {@code AccountState}

     * row is the pubkey→agent identity binding every authority join in this class

     * resolves through ({@code PUBLISHER_IS_ADMIN}, {@link #publisherIsTieredRole},

     * {@link #adminTierUpdate}, the {@code revoker*} blocks), and those joins pair it

     * with a {@code RoleInstantiation} keyed on the <em>agent</em>. Since an

     * introduction is self-asserted, emitting these rows as bare {@code AccountState}

     * would let anyone bind their own key to any agent that already holds authority

     * without having an approved account — 43 such agents existed on the production

     * fleet when this was written, three of them admins. The distinct class fails

     * closed for every existing join site, and for published queries that cannot be

     * retrofitted.

     */

    /** Trust status stamped on pending rows and on the roles materialized through them. */

    /**

     * Trust-approved set: rows with one of these {@code npa:trustStatus} values

     * are mirrored into the space-state graph. Per

     * {@code doc/design-trust-state-repos.md}, these are the two "authority-

     * approving" statuses; {@code npa:contested}, {@code npa:skipped}, and the

     * transient statuses are distinct values of the same predicate and are

     * excluded automatically by this positive-list filter.

     */

    private static AuthorityResolver instance;

    /** Returns the singleton. */

    public static synchronized AuthorityResolver get() {

        }

    }

    // ---------------- Operational metrics snapshot ----------------

    //

    // Updated at the end of each runFullBuild / runIncrementalCycle, read by

    // MetricsCollector via the get*() accessors below. volatile is enough —

    // writers serialise via the synchronized methods, and readers (Prometheus

    // scrapes) only need most-recent visibility, not transactional consistency

    // across the snapshot. Defaults to zero values so a scrape that races a

    // boot before the first cycle returns 0, not NaN.

    private volatile long lastInsertedTriplesTotal;

    private volatile long lastFullBuildDurationMs;

    private volatile long lastIncrementalCycleDurationMs;

    private volatile long lastProcessedUpToLag;

    /**

     * Raised when the space-state bookkeeping in the {@code spaces} repo cannot be

     * <em>read</em>, as opposed to being legitimately absent.

     *

     * <p>The distinction is the whole point. Before 2026-08-05 every reader here

     * collapsed both cases onto the same value — {@code null} pointer, load counter

     * {@code 0}, {@code processedUpTo} {@code -1} — so a degraded RDF4J looked

     * identical to a fresh install. On that day RDF4J was answering reads with

     * {@code Read timed out}; {@link #tick()} saw a {@code null} pointer, logged a

     * "trust-state flip" that had not happened, and ran a full build whose every

     * source read also failed. The build inserted nothing, published the resulting

     * empty graph, and dropped the previous good one — 2730 triples of live space

     * state, on a query server that then served zero rows to every state query for

     * hours. A sibling instance that stayed healthy still had all of it.

     *

     * <p>Throwing instead lets the caller abort. Doing nothing this tick is always

     * safe; acting on a failed read is not.

     */

    static class SpaceStateUnavailableException extends RuntimeException {

        SpaceStateUnavailableException(String message, Throwable cause) {

    }

    // ---------------- Public entry points ----------------

    /**

     * Poll entry point. Behaviour:

     * <ul>

     *   <li>If no current space-state graph or the trust state has flipped → full build.</li>

     *   <li>Otherwise → {@link #runIncrementalCycle incremental cycle} on the load-number

     *       delta {@code (processedUpTo, currentLoadCounter]}. No-op if {@code

     *       processedUpTo == currentLoadCounter}.</li>

     * </ul>

     * Safe to call repeatedly on a schedule. Gated by {@link FeatureFlags#spacesEnabled()}.

     */

    public void tick() {

        }

        // Any of the reads below may throw SpaceStateUnavailableException. Let it

        // propagate: the caller logs "AuthorityResolver tick failed" and we retry on

        // the next tick with the state untouched.

        }

        }

        // A pointer at a graph that never got its processedUpTo stamp means the build

        // that published it did not finish. runIncrementalCycle used to log "missing

        // processedUpTo; skipping" and return — every 2 s, forever, with every

        // state-backed query answering empty in the meantime. Rebuild instead.

                    + "stamp (incomplete or damaged build); running full build", currentGraph);

        }

        // Integrity check: the stateTripleCount stamp is rewritten by every mutation,

        // so a disagreement means part of a write was lost after the fact — e.g. rdf4j

        // dropping acked-but-unmerged changesets across a restart (2026-08-22: a state

        // graph survived with 7,439 of 19,283 triples, processedUpTo intact, and served

        // truncated authority data until repaired by hand). A stamp of -1 is a graph

        // published by a pre-stamp version: skip, it becomes verifiable at its next

        // mutation.

                        + "but its stateTripleCount stamp says {} — truncated or partially lost "

            }

        }

    /**

     * Periodic worker. If {@code npa:needsFullRebuild} was raised by an

     * incremental cycle's structural DELETE, runs a from-scratch rebuild into

     * a fresh space-state graph (using the current trust-state hash and load

     * counter) and clears the flag. No-op when the flag is not set. Safe to

     * call concurrently with {@link #tick()} when both are scheduled on the

     * same single-threaded executor.

     */

    public void periodicRebuildTick() {

        }

    /**

     * Startup cleanup: drop any {@code npass:*} graph that the

     * {@code npa:hasCurrentSpaceState} pointer isn't pointing at. Orphans come

     * from crashes mid-build. Safe to call at any time; idempotent.

     */

    public synchronized void cleanOrphans() {

        IRI current;

        try {

            // Every npass:* graph is "not the current one" when the pointer cannot be

            // read, so continuing here would drop the live state along with the

            // orphans. Skipping costs nothing: orphans are inert, and the next start

            // will clean them up.

            }

            }

    // ---------------- Full build ----------------

    /**

     * Mutex-protected full build of the space-state graph for the given trust

     * state. Captures {@code M = currentLoadCounter}, mirrors trust-approved

     * rows, (PR 2b: runs per-tier UPDATE loops from scratch), stamps

     * {@code processedUpTo = M}, flips the pointer, drops the previous graph.

     */

    synchronized void runFullBuild(String trustStateHash) {

            // "Already current" is only true if that graph was actually finished AND

            // still holds everything it claims to. Without the processedUpTo check

            // this early return was the second half of the 2026-08-05 trap: once a

            // damaged graph was published, the pointer name still matched, so every

            // subsequent full build returned here and the instance could never repair

            // itself. The integrity-count check closes the same loophole for the

            // 2026-08-22 shape (graph truncated after publication, stamps intact) —

            // without it, tick() would detect the mismatch, call this method, and be

            // bounced right back here forever.

            }

                    + "unfinished or inconsistent (processedUpTo={}, countConsistent={}); "

        }

        // 1. Mirror trust-approved rows into the new graph.

        // 1b. Mirror introduced-but-unapproved accounts (issue #195). Runs before the

        //     tier loops so this build's observer(self,pending) pass sees the rows.

        //     Additive and authority-free, so it is deliberately not part of the

        //     empty-build guard below.

        // 2. Per-tier UPDATE loops (from scratch: lastProcessed = -1 so the

        //    delta filter FILTER(?ln > ?lastProcessed) includes everything).

        // 2b. Refuse to publish an empty build over a state we already have — but only

        // when the emptiness cannot be true.

        //

        // Steps 4 and 5 below are destructive, so a build that read nothing must not

        // reach them. The trap is that "produced nothing" has two causes: every source

        // read failed, or the sources really are empty. Refusing in the second case

        // would pin a stale space state forever, and stale trust data is

        // over-permissive — revocations would stop propagating. That is the wrong way

        // to fail for a trust-derived state.

        //

        // So the condition is: nothing was produced *while the trust state still has

        // content to mirror*. That is the shape of a read failure. A genuinely empty

        // trust state yields an empty build and is published normally.

        //

        // Only guarded when a previous state exists: a genuinely empty first build on

        // a fresh instance has nothing to lose and must still be allowed to publish.

        //

        // Note this would NOT have fired on 2026-08-05: that build reported

        // subspace-prefix=2478, so it was not empty. The wipe there came from the

        // registry's trust state collapsing (correctly reflected) plus 2478 triples

        // that were reported inserted and then measured as zero. This guard is for the

        // total-read-failure case, which the same outage came close to several times.

                    + "(mirrored=0, inserted=0) while trust state {} still has content and {} "

                    + "holds the current state — refusing to flip the pointer or drop it. "

                    + "This is the shape of a total read failure; the next tick will retry.",

            }

        }

        // 3. Stamp processedUpTo inside the new graph.

        // 3b. Stamp the integrity triple-count, so tick() can detect a graph

        //     that later loses part of its content (truncated writes, dropped

        //     changesets across a store restart) and rebuild it automatically.

        // 4. Flip the current-space-state pointer.

        // 5. Drop the old graph if a *different* one existed. Dropping it when

        //    rebuilding in place would delete what we just built.

        }

                        + "subjects: adminRIs={} attachmentRAs={} nonAdminRIs={} "

                        + "(inserted-triples: admin={} alias={} preset-attachment={} preset-assignment-ref={} attachment={} maintainer={} member={} observer={} "

                        + "subspace={} subspace-prefix={} maintained-resource={} governing-space-ref={}) durationMs={}",

    // ---------------- Incremental cycle ----------------

    /**

     * Single delta cycle on the current space-state graph. Bounded by

     * {@code (processedUpTo, currentLoadCounter]}; no-op if the range is empty.

     *

     * <p>Order:

     * <ol>

     *   <li>Apply invalidation DELETEs (admin RI, RoleAssignment, non-admin RI)

     *       and the RoleDeclaration ASK. Any DELETE on a structural kind sets

     *       {@code npa:needsFullRebuild} to bound the staleness from sticky

     *       downstream entries; the periodic worker turns that into a from-scratch

     *       rebuild on its next pass.</li>

     *   <li>Run per-tier INSERTs in the same order as the full build.</li>

     *   <li>Late-arrival sweep: if any structural row was added, re-run downstream

     *       tier INSERTs with {@code lastProcessed = -1} to catch candidates whose

     *       enabling event landed in this same cycle. Dedup filters protect

     *       against double-insert.</li>

     *   <li>Bump {@code processedUpTo} to {@code currentLoadCounter}.</li>

     * </ol>

     */

    synchronized void runIncrementalCycle(IRI graph) {

            // tick() now catches this first and rebuilds, so reaching here means a

            // direct caller. Still refuse to run a delta against a graph that was

            // never finished — the deltas would be layered onto missing base rows.

                    + "skipping (a full build is needed to repair this graph)", graph);

        }

        }

        // Pending-account delta (issue #195), before the tier loops so a newcomer's

        // introduction and their self-signed role can land in the same cycle. Keyed on

        // the meta repo's own load numbers, hence its own watermark.

                || (counts.admin > 0)

                || (counts.alias > 0)

                || (counts.presetAttachment > 0)

                || (counts.attachment > 0)

                || (counts.subSpace > 0)

            // Late-arrival sweep: leaf tiers (attachment/maintainer/member/observer)

            // can promote candidates whose enabling event arrived in this same cycle.

            // Sub-space admit is also re-run here for Mode-B late-arrival (a new

            // partner declaration can validate an older primary that the regular

            // pass's load-number filter excluded). The URL-prefix fallback also

            // re-runs so newly-orphaned children pick up derived edges. Skip the

            // admin tier — its only enabling event is the admin grant itself,

            // already handled by the regular pass.

        }

        // Re-stamp the integrity count after this cycle's mutations (also

        // upgrades pre-stamp graphs to verifiable on their first mutation).

                + counts.presetAssignmentRef

                + counts.attachment + counts.maintainer + counts.member + counts.observer

                + counts.subSpace + counts.subSpacePrefix + counts.maintainedResource

                + counts.governingSpaceRef;

                        + "subjects: adminRIs={} attachmentRAs={} nonAdminRIs={} "

                        + "(inserted-triples: admin={} alias={} preset-attachment={} preset-assignment-ref={} attachment={} maintainer={} member={} observer={} "

                        + "subspace={} subspace-prefix={} maintained-resource={} governing-space-ref={}) "

                        + "structuralInvalidation={} structuralAdds={} durationMs={}",

    /**

     * Runs the four invalidation-DELETE / ASK steps. Sets {@code npa:needsFullRebuild}

     * when admin-RI, RoleAssignment, or RoleDeclaration invalidations matched (the

     * three structural kinds). Leaf-tier RI deletes don't set the flag. A step runs

     * only when the delta holds the kind of record it looks for ({@link DeltaKinds}).

     *

     * @return true iff at least one structural kind was invalidated

     */

    boolean applyInvalidations(IRI graph, long lastProcessed) {

        // Each check runs only when its kind of record is in the delta; see DeltaKinds for

        // why this is exact.

        }

        }

        // Role-declaration invalidation is deliberately NOT acted on (see

        // nonAdminTierUpdate): a role assignment is governed by the admin-validated

        // attachment, not by the declaration author's later supersession/retraction, so

        // an invalidated RD neither deletes rows nor triggers a rebuild.

        // Sub-space declarations are structural — invalidating one (Mode A) or one

        // of two co-declarations (Mode B) changes the validated parent/child

        // topology. The DELETE removes the per-declaration row; the convenience-edge

        // cleanup then drops the now-unbacked direct triples (issue #125 finding #5)

        // instead of leaving them sticky until the periodic rebuild. The structural

        // flag still fires so downstream rows derived through a removed edge stay

        // rebuild-bounded.

        }

        // Space-alias declarations are structural — invalidating one removes an

        // owl:sameAs edge that feeds the admin-authority closure (issue #113). The

        // DELETE removes the per-declaration row; the convenience-edge cleanup then

        // drops the now-unbacked npa:sameAsSpace edge (issue #125 finding #5 — the

        // load-bearing case), so admin authority can no longer outlive a retraction

        // until the next periodic rebuild.

        }

        // Preset-derived RoleAssignment removal (issue #302). NOT npx:invalidates: a newer

        // admin-authored same-(preset,resource) assignment supersedes by dct:created (a

        // gen:DeactivatedPresetAssignment, or any newer assignment that is no longer active).

        // Structural — sticky downstream non-admin RIs derived through a removed attachment

        // are bounded by the periodic full rebuild. The DELETE is scoped by

        // npa:derivedFromPreset so directly-published gen:hasRole attachments are never

        // touched; the §4.3 re-INSERT re-materializes only currently-active pairs in the same

        // cycle. See doc/design-preset-role-materialization.md §4.4.

        }

        // Admin role-instantiation revocation (issue #129). STRUCTURAL — admin RIs feed every

        // downstream tier, so a removed admin must bound the staleness via a full rebuild

        // (mirrors adminInvalidationDelete). Root admins are exempt inside the check-where.

        }

        // Role detachment (issue #129). STRUCTURAL — removing a (ref, role) attachment

        // (direct or preset-derived) cascades to the instantiations anchored on it, bounded

        // by the periodic full rebuild. The attachment-tier inline filters then keep the

        // detached role suppressed until a newer attachment / preset assignment out-ranks it.

        }

        // Non-admin role-instantiation revocation (issue #129), run once per tier so the

        // authorization arms are the compile-time set for that tier (mirrors the inline

        // suppression filter). STRUCTURAL: a revoked maintainer or member is a sub-granting

        // authority — members/observers they granted are validated via the maint-pub /

        // member-pub arms of nonAdminTierUpdate, so removing the revoked agent's own RI must

        // schedule a full rebuild to re-evaluate (and drop) those now-unauthorized downstream

        // grants. The inline suppression filter prevents re-materialization on that rebuild.

            }

        // Both deletes are npx:invalidates-based, so they can only match when an

        // invalidator is in the delta.

            // Leaf-tier RI deletes — no flag.

            // Ref-scoped preset-assignment listing stamps whose assignment nanopub was

            // hard-retracted (issue #122) — no flag (display leaf, nothing downstream).

        }

        // Maintained-resource declaration deletes — no flag (leaf relation, no

        // downstream caches to bound). The per-declaration delete removes the row; the

        // convenience-edge cleanup drops the now-unbacked isMaintainedBy edges (issue

        // #125 finding #5). Guarded so the orphan-sweep only scans when something was

        // actually invalidated (the delete itself was already a no-op otherwise).

        }

    }

    /**

     * Runs the four leaf tiers (attachment/maintainer/member/observer) with

     * {@code lastProcessed = -1} so the load-number filter on the candidate

     * side admits everything. Dedup filters in the tier templates prevent

     * double-insert. Used by the late-arrival sweep.

     */

    TierInsertedTriples runDownstreamWithoutLoadFilter(IRI graph) {

        // Alias late-arrival: catches alias declarations whose canonical admin grant

        // became valid only in this same cycle (the load-number filter on the

        // declaration's nanopub would otherwise exclude it). Runs first so the

        // attachment / role tiers below see this cycle's fresh npa:sameAsSpace edges.

        // Sub-space late-arrival: catches Mode-B candidates whose primary

        // declaration is older than lastProcessed but whose partner just landed.

        // Maintained-resource late-arrival: catches declarations that landed

        // before the publisher's admin grant became valid in this state.

        // URL-prefix fallback: re-run after the late-arrival sub-space admit so

        // any newly-validated children get their fallback edges suppressed (for

        // future inserts) and any newly-orphaned children pick up fallback edges.

        // Reflexive governing-space-ref late sweep (issue #130): catches refs whose

        // SpaceRef aggregate became visible only this cycle. Self-healing dedup.

        // Preset-attachment late-arrival: catches assignments whose preset declaration or

        // admin grant only became valid in this same cycle. Runs before attachment(late)

        // so the non-admin late tiers below see this cycle's fresh preset-derived RAs.

        // Ref-scoped preset-assignment late stamp: catches assignments whose authorizing

        // admin grant only became valid this cycle (the load filter would skip the older

        // assignment nanopub). Mirrors the preset-attachment late sweep above.

                        PUBLISHER_IS_SELF_PENDING, PENDING_ROLE_STAMP));

    }

    /**

     * Cheap ASK: did any new {@code npa:RoleDeclaration} extraction land in the

     * load-number delta {@code (lastProcessed, ∞)}? Used by the late-arrival

     * trigger so an RD that arrives in the same cycle as a matching candidate

     * still gets validated.

     */

    boolean newRoleDeclarationsArrived(long lastProcessed) {

                PREFIX npa: <%1$s>

                ASK {

                  GRAPH <%2$s> {

                    ?rd a npa:RoleDeclaration ;

                        npa:viaNanopub ?np .

                  }

                  GRAPH <%3$s> {

                    ?np npa:hasLoadNumber ?ln .

                    FILTER (?ln > %4$d)

                  }

                }

    }

    /**

     * Cheap ASK: did any new {@code npa:PresetAssignment} or {@code npa:PresetDeclaration}

     * extraction land in the load-number delta {@code (lastProcessed, ∞)}? Drives the

     * late-arrival re-run so a preset assignment that arrives in the same cycle as its

     * declaration (or admin grant) still materializes, and so an arriving newer assignment

     * triggers the deactivation/latest-wins re-evaluation.

     */

    boolean newPresetAssignmentsArrived(long lastProcessed) {

                PREFIX npa: <%1$s>

                ASK {

                  GRAPH <%2$s> {

                    ?x a ?t ;

                       npa:viaNanopub ?np .

                    FILTER (?t = npa:PresetAssignment || ?t = npa:PresetDeclaration)

                  }

                  GRAPH <%3$s> {

                    ?np npa:hasLoadNumber ?ln .

                    FILTER (?ln > %4$d)

                  }

                }

    }

    /**

     * Which kinds of record the load-number delta {@code (lastProcessed, ∞)} holds, as far

     * as {@link #applyInvalidations} is concerned. Every invalidation check joins its delta

     * nanopub to exactly one of these kinds inside its own WHERE clause, and each gate below

     * is that sub-pattern on its own. A check can therefore only match when its gate does,

     * so skipping the check on a false gate is exact, not a heuristic.

     *

     * <p>Most cycles bring none of these (an admin grant, a role assignment, a new space),

     * yet every check used to be evaluated anyway. The checks are large joins whose plans

     * hinge on rdf4j's cardinality estimates: on 2026-09-24 the preset-deactivation check

     * never finished on rdf4j 6.1.0 after a routine admin grant and took the fleet down.

     * The gates are two-pattern lookups that plan the same on any version.

     *

     * @param invalidators      a nanopub with an {@code npx:invalidates} triple

     * @param presetAssignments an {@code npa:PresetAssignment} extraction

     * @param roleRevocations   an {@code npa:RoleRevocation} extraction

     * @param roleDetachments   an {@code npa:RoleDetachment} extraction

     */

                      boolean roleRevocations, boolean roleDetachments) {

    }

    /** Reads the {@link DeltaKinds} of the delta {@code (lastProcessed, ∞)}. */

    DeltaKinds readDeltaKinds(long lastProcessed) {

    }

    /**

     * Cheap ASK: did a nanopub with an {@code npx:invalidates} triple land in the delta

     * {@code (lastProcessed, ∞)}? The gate of every {@code npx:invalidates}-based check and

     * delete in {@link #applyInvalidations}.

     */

    boolean invalidatorsArrived(long lastProcessed) {

                PREFIX npa: <%1$s>

                ASK {

                  GRAPH <%2$s> {

                    ?invNp <%3$s> ?target ;

                           npa:hasLoadNumber ?ln .

                    FILTER (?ln > %4$d)

                  }

                }

    }

    /**

     * Cheap ASK: did an extraction of the given type land in the delta

     * {@code (lastProcessed, ∞)}?

     */

    boolean extractionsArrived(IRI type, long lastProcessed) {

                PREFIX npa: <%1$s>

                ASK {

                  GRAPH <%2$s> {

                    ?x a <%3$s> ;

                       npa:viaNanopub ?np .

                  }

                  GRAPH <%4$s> {

                    ?np npa:hasLoadNumber ?ln .

                    FILTER (?ln > %5$d)

                  }

                }

    }

    // ---------------- Tier UPDATE loops ----------------

    /**

     * Per-tier inserted-triple tallies for one build or cycle. Counts the sum

     * of {@code (graphSize_after - graphSize_before)} across all iterations of

     * each tier's fixed-point INSERT loop — i.e. inserted *triples*, not

     * distinct subjects (a single RoleInstantiation insert writes 4–5 triples).

     *

     * <p>Used internally by the {@link #runIncrementalCycle structuralAdds}

     * boolean check (we only care whether any tier inserted at all).

     * Not what the log lines report: see {@link TierSubjectTotals} +

     * {@link #computeTierSubjectTotals} for the distinct-subject totals

     * surfaced to operators.

     */

    /**

     * Total triples inserted across every tier. Used both for the metrics gauge and

     * for the empty-build guard in {@link #runFullBuild}, so the two can never

     * disagree about what "this build produced nothing" means.

     */

    static long totalInserted(TierInsertedTriples c) {

                + c.attachment + c.maintainer + c.member + c.observer

                + c.subSpace + c.subSpacePrefix + c.maintainedResource

                + c.governingSpaceRef;

    }

        int admin;

        int alias;

        int presetAttachment;

        int presetAssignmentRef;

        int attachment;

        int maintainer;

        int member;

        int observer;

        int subSpace;

        int subSpacePrefix;

        int maintainedResource;

        int governingSpaceRef;

    }

    /**

     * Snapshot of distinct-subject totals in a space-state graph at a moment

     * in time. Independent of which tier-loop added each subject.

     */

    /**

     * Runs the five tier loops in order: admin → {@code gen:hasRole} attachment

     * validation → maintainer → member → observer. Each loop iterates a SPARQL

     * INSERT to fixed point (no new triples added). Returns per-tier counts.

     *

     * @param graph         target space-state graph

     * @param lastProcessed load-number horizon; use {@code -1} for full build

     */

    TierInsertedTriples runAllTierLoops(IRI graph, long lastProcessed) {

        // Alias admit runs after the admin closure has settled (both the authority

        // gate and the anti-hijack check read the admin set) and before attachment /

        // role tiers (their alias-aware admin lookups consume the npa:sameAsSpace edge

        // this pass emits). See issue #113.

        // Sub-space admit runs after admin closure has settled (Mode A + Mode B both

        // need the admin set). Independent of role tiers — order between subspace

        // and attachment / maintainer / member / observer doesn't matter.

        // Maintained-resource admit also depends only on the admin closure. Single

        // Mode A: publisher must be admin of the maintaining space. No co-declaration

        // partner, no URL-prefix fallback.

        // URL-prefix sub-space fallback runs after the explicit-declaration admit

        // pass commits so the per-child suppression check sees this cycle's fresh

        // validations. No load filter — depends on which Spaces exist, not on

        // delta-arrivals; the dedup FILTER NOT EXISTS prevents re-insertion.

        // Reflexive governing-space-ref edges (issue #130). Self-healing, no load filter;

        // runs after the maintained-resource admit so a maintained resource that is itself

        // a space already has its maintained governing edge by now (the two are independent

        // anyway — different subjects/objects). Order vs. other tiers doesn't matter.

        // Preset-attachment runs immediately before the regular attachment tier so the

        // gen:RoleAssignment rows it materializes (from active, admin-authored preset

        // assignments) are picked up by the downstream non-admin tiers in the same pass,

        // exactly like directly-published attachments. See

        // doc/design-preset-role-materialization.md.

        // Ref-scoped preset-assignment listing stamp (issue #122). Display-only leaf —

        // independent of the role tiers and of structuralAdds; order doesn't matter.

                GEN.MAINTAINER_ROLE, PUBLISHER_IS_ADMIN));

        // Member tier: admin OR maintainer publisher — split into two simpler updates

        // so the query planner doesn't struggle with the UNION.