knowledgepixels / nanopub-query / 27544702113

package com.knowledgepixels.query;

import java.util.ArrayList;

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.QueryLanguage;

import org.eclipse.rdf4j.query.TupleQueryResult;

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.knowledgepixels.query.vocabulary.GEN;

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) → mirror-step delta is implicit (rebuilt only on full build) →

 * 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";

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

    /**

     * 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;

    // ---------------- 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() {

        }

        }

    /**

     * 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 void cleanOrphans() {

            }

            }

    // ---------------- 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) {

        }

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

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

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

        // 3. Stamp processedUpTo inside the new graph.

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

        // 5. Drop the old graph if one existed.

        }

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

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

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

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

                        + "subspace={} subspace-prefix={} maintained-resource={}) 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) {

                    graph);

        }

        }

                || (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.

        }

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

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

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

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

                        + "subspace={} subspace-prefix={} maintained-resource={}) "

                        + "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.

     *

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

     */

    boolean applyInvalidations(IRI graph, long lastProcessed) {

        }

        }

        // RoleDeclaration ASK only — RDs aren't materialized into the space-state

        // graph, so there's nothing to DELETE here. The flag still flips because

        // sticky downstream RIs derived from the now-invalidated RD need a

        // from-scratch recompute.

        }

        // 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

        // direct triples are left sticky and cleaned on the next periodic rebuild.

        }

        // 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 npa:sameAsSpace edge

        // is left sticky and cleaned on the next periodic rebuild (same policy as

        // sub-space declarations).

        }

        // 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.

        }

        // Leaf-tier RI deletes — no flag.

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

        // downstream caches to bound).

    }

    /**

     * 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.

        // 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.

    }

    /**

     * 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)

                  }

                }

    }

    // ---------------- 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.

     */

        int admin;

        int alias;

        int presetAttachment;

        int attachment;

        int maintainer;

        int member;

        int observer;

        int subSpace;

        int subSpacePrefix;

        int maintainedResource;

    }

    /**

     * 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.

        // 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.

                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.

                GEN.MEMBER_ROLE, PUBLISHER_IS_ADMIN));

        // Observer tier: self-evidence OR a downward grant from any higher tier.

        // ObserverRole is the default tier when a role definition omits an

        // explicit subclass (see "Role types" in design-space-repositories.md), so

        // most "X assigned Y this role" nanopubs land here. Restricting the tier

        // to PUBLISHER_IS_SELF would silently drop those grants. The four

        // sub-loops mirror the trust-state's downward-only chain: admin grants

        // anything; maintainers and members grant observer; everyone may

        // self-attest.

                GEN.OBSERVER_ROLE, PUBLISHER_IS_ADMIN));

                GEN.OBSERVER_ROLE, PUBLISHER_IS_SELF));

    }

    /**

     * Builds a publisher constraint requiring the publisher to be a validated holder

     * of the given tier's role (maintainer or member) in the target space.

     * Owns its own AccountState resolution so ?publisher is bound through the

     * targeted (pkh → agent) lookup rather than enumerated.

     */

    private static String publisherIsTieredRole(IRI tierClass) {

        // Re-keyed on the assignment's ref (alias → canonical already resolved by the

        // attachment tier). Relies on materialized non-admin RIs carrying their role

        // property (npa:regularProperty / npa:inverseProperty) — supplied by the

        // enrichment in nonAdminTierUpdate; without it this constraint matched nothing.

                ?acct a npa:AccountState ;

                      npa:pubkey ?pkh ;

                      npa:agent  ?publisher .

                ?tierRI a gen:RoleInstantiation ;

                        npa:forSpaceRef ?spaceRef ;

                        npa:forAgent ?publisher .

                ?rdT a npa:RoleDeclaration ;

                     npa:hasRoleType <%1$s> .

                { ?tierRI npa:regularProperty ?predT . ?rdT gen:hasRegularProperty ?predT . }

                UNION

                { ?tierRI npa:inverseProperty ?predT . ?rdT gen:hasInverseProperty ?predT . }

    }

    /** Wraps {@link #runTierLoop} with tier-name context for logs/exceptions. */

    private int runTierLabeled(String tier, IRI graph, String sparqlUpdate) {

        try {

        }

    }

    /**

     * Runs a single tier's INSERT to fixed point. Counts rows by probing

     * graph size before/after each INSERT; stops when the size doesn't change.

     *

     * @return total number of triples inserted by this tier across all iterations

     */

    int runTierLoop(IRI graph, String sparqlUpdate) {

        while (true) {

            // Note: no explicit transaction wrapping here. In tests we observed that

            // HTTPRepository's RDF4J-transaction protocol silently no-op'd cross-graph

            // SPARQL UPDATEs with UNION sub-patterns inside conn.begin()/commit(),

            // while the same UPDATE POSTed directly to /statements applied correctly.

            // A bare prepareUpdate().execute() takes the direct /statements path and

            // runs the UPDATE atomically per SPARQL 1.1 semantics — which is all we

            // need; there's nothing else to commit atomically alongside the UPDATE.

            }

    }

    private long graphSize(IRI graph) {

        }

    }

    /**

     * Distinct-subject totals in the given space-state graph, broken down by

     * RoleInstantiation kind (admin-pinned vs not) and RoleAssignment.

     * Three SELECT-COUNT queries — cheap, called once per build/cycle for

     * the user-facing log line. Returns zeros on failure (logged) so a flaky

     * count read can't wedge the cycle.

     */

    TierSubjectTotals computeTierSubjectTotals(IRI graph) {

                ?ri a gen:RoleInstantiation ; npa:inverseProperty gen:hasAdmin .

                """, "ri");

                ?ra a gen:RoleAssignment .

                """, "ra");

                ?ri a gen:RoleInstantiation .

                FILTER NOT EXISTS { ?ri npa:inverseProperty gen:hasAdmin }

                """, "ri");

    }

    private long countDistinctSubjects(IRI graph, String wherePattern, String varName) {

                PREFIX npa: <%1$s>

                PREFIX gen: <%2$s>

                SELECT (COUNT(DISTINCT ?%3$s) AS ?n) WHERE {

                  GRAPH <%4$s> {

                    %5$s

                  }

                }

                """, NPA.NAMESPACE, GEN.NAMESPACE, varName, graph, wherePattern);

        }

    }

    // ---------------- SPARQL templates ----------------

    /**

     * Reusable invalidation filter on a bound nanopub-IRI variable. Pass the bare

     * variable name (no leading {@code ?}); e.g. {@code invalidationFilter("np")}

     * produces an outer-scoped {@code FILTER NOT EXISTS { GRAPH npa:graph

     * { ?_inv_np npx:invalidates ?np . } }}.

     *

     * <p>Joins on the raw {@code npx:invalidates} triple in {@code npa:graph},

     * which {@link com.knowledgepixels.query.NanopubLoader} writes into the

     * spaces repo from two complementary directions, making the filter symmetric

     * in load order:

     * <ul>

     *   <li>At the invalidator's own load: the loader's space-repo trigger fires

     *       whenever the nanopub has either its own space-relevant extractions

     *       OR an {@code npx:invalidates}/{@code npx:retracts}/{@code npx:supersedes}

     *       triple, so a pure-retraction nanopub still lands its raw triple plus

     *       {@code npa:hasLoadNumber} stamp in {@code npa:graph}.</li>

     *   <li>At the invalidated target's load (when the invalidator landed

     *       earlier): {@code NanopubLoader.getInvalidatingStatements} reads the

     *       triple back from the meta repo and mirrors it into the target's own

     *       write to the spaces repo.</li>

     * </ul>

     *

     * <p>The earlier shape joined on a structured {@code npa:Invalidation} entry

     * in {@code npa:spacesGraph} that was only emitted on the invalidator's side

     * AND only when the invalidated target's meta had already loaded, leaving a

     * window where a superseding nanopub loaded before its target produced no

     * entry and the stale row was never filtered out (see also the matching

     * change in the tier-specific {@code *InvalidationCheckWhere}/{@code

     * *InvalidationDelete} templates below).

     *

     * <p>Important: this filter must be placed OUTSIDE the surrounding

     * {@code GRAPH npa:spacesGraph { ... }} block, not nested inside it. When

     * nested, RDF4J's planner couples the FILTER NOT EXISTS evaluation into the

     * join order (per-row scan multiplied by the candidate set), which we

     * measured turning a 39ms query into a 60s+ timeout on the live observer-tier

     * data. Outside the GRAPH block, the planner defers the filter until

     * {@code ?np}/{@code ?rdNp} are bound and does a targeted index lookup.

     *

     * <p>Variable names must match {@code [A-Za-z0-9_]+} per SPARQL grammar —

     * embedding a {@code ?} inside {@code ?_inv_?np} would yield a parse error.

     */

    private static String invalidationFilter(String bareVarName) {

                + " ?_inv_" + bareVarName

                + " <" + NPX.INVALIDATES + "> ?" + bareVarName + " . } }";

    }

    /**

     * Admin tier: seed from {@code npadef:...hasRootAdmin} (trusted by construction)

     * plus closed-over admin grants; insert any {@code gen:RoleInstantiation} with

     * {@code npa:inverseProperty gen:hasAdmin} whose publisher (resolved via mirrored

     * trust-approved AccountState) is already in the admin set.

     *

     * <p>The seed is gated by {@link #spaceRefAliveFilter} (not the per-nanopub

     * {@code invalidationFilter("defNp")}): the {@code hasRootAdmin} seed is anchored

     * to the root NPID, which is the immutable space-ref identity, so superseding the

     * root <em>nanopub</em> with a continuation revision must not strip the seed —

     * only retracting every definition of the ref removes it. See issue #110.

     */

    static String adminTierUpdate(IRI graph, long lastProcessed) {

        // Order tuned for RDF4J's evaluator:

        //   1. Anchor on the small (seed UNION closed-over) set to bind ?publisher

        //      and ?space cheaply.

        //   2. Resolve ?pkh from the mirrored AccountState row (?publisher bound).

        //   3. Probe instantiations using the now-bound (?space, ?pkh) — targeted

        //      lookup, not a full RoleInstantiation scan.

        //   4. Load-number filter on bound ?np.

        //   5. Dedup at the end.

        // Authority is keyed on the space *ref* (npa:forSpaceRef), not the bare Space

        // IRI: two refs that share an IRI but have different roots are independent

        // domains (see doc/design-spaceref-isolation.md). The instantiation evidence in

        // the extraction graph is IRI-keyed (a gen:hasAdmin nanopub names the bare IRI),

        // so we project it per-ref by joining each instantiation naming ?space to the

        // admin rows of every ref of ?space whose admin set contains the publisher. The

        // inserted subject is minted per (?ri, ?spaceRef) so one instantiation validating

        // into N refs yields N distinct rows. TRANSITIONAL-DUAL-EMIT (Phase 4: remove):

        // forSpace is still emitted alongside forSpaceRef so the not-yet-migrated

        // downstream tiers / pre-ref read queries keep functioning on a mixed-version

        // fleet; it is dropped once everything keys on forSpaceRef.

                PREFIX npa:  <%1$s>

                PREFIX gen:  <%2$s>

                INSERT { GRAPH <%3$s> {

                  ?sri a gen:RoleInstantiation ;

                       npa:forSpaceRef ?spaceRef ;

                       npa:forSpace ?space ;

                       npa:inverseProperty gen:hasAdmin ;

                       npa:forAgent ?agent ;

                       npa:viaNanopub ?np .

                } }

                WHERE {

                  # 1. Anchor: who is already an admin of which space ref?

                  {

                    # Seed branch: root-admin of a space ref that is still alive

                    # (has at least one non-invalidated definition). NOT filtered on

                    # ?def's own invalidation — superseding the root nanopub with a

                    # continuation revision must keep the seed; only a fully-retracted

                    # ref drops it (issue #110).

                    GRAPH <%4$s> {

                      ?def a npa:SpaceDefinition ;

                           npa:forSpaceRef  ?spaceRef ;

                           npa:hasRootAdmin ?publisher .

                      ?spaceRef npa:spaceIri ?space .

                    }

                    %7$s

                  }

                  UNION

                  {

                    # Closed-over branch: an existing admin of this ref. Recurse on the

                    # ref, then resolve its bare IRI to probe the IRI-keyed instantiation.

                    GRAPH <%3$s> {

                      ?prev a gen:RoleInstantiation ;

                            npa:forSpaceRef     ?spaceRef ;

                            npa:inverseProperty gen:hasAdmin ;

                            npa:forAgent        ?publisher .

                    }

                    GRAPH <%4$s> {

                      ?spaceRef npa:spaceIri ?space .

                    }

                  }

                  # 2. Mirror: resolve ?publisher → ?pkh via the trust-approved row.

                  GRAPH <%3$s> {

                    ?acct a npa:AccountState ;

                          npa:agent  ?publisher ;

                          npa:pubkey ?pkh .

                  }

                  # 3. Targeted instantiation lookup by space + pubkey (IRI-keyed).

                  GRAPH <%4$s> {

                    ?ri a gen:RoleInstantiation ;

                        npa:forSpace        ?space ;

                        npa:inverseProperty gen:hasAdmin ;

                        npa:forAgent        ?agent ;

                        npa:pubkeyHash      ?pkh ;

                        npa:viaNanopub      ?np .

                  }

                  # 3a. Mint the per-ref state subject: (?ri, ?spaceRef) → ?sri.

                  BIND(IRI(CONCAT(STR(?ri), "__", ENCODE_FOR_URI(STR(?spaceRef)))) AS ?sri)

                  %6$s

                  # 4. Load-number filter on bound ?np.

                  GRAPH <%8$s> {

                    ?np npa:hasLoadNumber ?ln .

                    FILTER (?ln > %5$d)

                  }

                  # 5. Dedup last — keyed on (ref, agent).

                  FILTER NOT EXISTS { GRAPH <%3$s> {

                    ?existing a gen:RoleInstantiation ;

                              npa:forSpaceRef ?spaceRef ;

                              npa:forAgent ?agent ;

                              npa:inverseProperty gen:hasAdmin .

                  } }

                }

                NPA.NAMESPACE,

                GEN.NAMESPACE,

                graph,

                SpacesVocab.SPACES_GRAPH,

                NPA.GRAPH);

    }

    /**

     * Seed-survival filter for the admin tier (issue #110). The {@code hasRootAdmin}

     * seed is anchored to the root NPID, which is the immutable space-ref identity, so

     * it must survive supersession of the root <em>nanopub</em> by a continuation

     * revision (a later definition re-roots to the same ref via

     * {@code gen:hasRootDefinition} and so carries no {@code hasRootAdmin} of its own).

     * The previous {@code invalidationFilter("defNp")} dropped the seed the moment the

     * root revision was superseded, leaving the whole admin closure — and everything

     * cascading from it — unmaterialized for any space whose definition had ever been

     * updated.

     *

     * <p>Expressed positively: the seed survives iff the space ref still has at least

     * one non-invalidated {@link SpacesVocab#SPACE_DEFINITION}. A fully-retracted ref

     * (every definition invalidated) has no live definition, so the {@code FILTER

     * EXISTS} fails and the seed correctly disappears. Anchored on the already-bound

     * {@code ?spaceRef}, so it's a targeted lookup over that ref's (few) definitions.

     */

    private static String spaceRefAliveFilter() {

                FILTER EXISTS {

                  GRAPH <%1$s> {

                    ?liveDef a npa:SpaceDefinition ;

                             npa:forSpaceRef ?spaceRef ;

                             npa:viaNanopub  ?liveNp .

                  }

                  %2$s

                }

    }

    /**

     * {@code gen:hasRole} attachment validation: an attachment is validated iff its

     * publisher is already a validated admin of the target space. Adds

     * {@code gen:RoleAssignment} rows to the space-state graph.

     */

    static String attachmentValidationUpdate(IRI graph, long lastProcessed) {

        // Ref-keyed (see doc/design-spaceref-isolation.md). The attachment names a bare

        // Space IRI; it is validated per-ref for every ref of that IRI whose admin set

        // contains the publisher (direct), or — when the named IRI is an owl:sameAs alias

        // — for the canonical ref it maps to (issue #113). ?targetRef is the ref the

        // RoleAssignment attaches to; the inserted subject is minted per (?ra, ?targetRef)

        // so one attachment validating into N refs yields N distinct rows.

        // TRANSITIONAL-DUAL-EMIT (Phase 4: remove): forSpace (the attached IRI, possibly an

        // alias) is kept so the non-admin tier can probe the IRI-keyed instantiations

        // naming it, and so pre-ref read queries keep functioning on a mixed-version fleet.

                PREFIX npa:  <%1$s>

                PREFIX gen:  <%2$s>

                INSERT { GRAPH <%3$s> {

                  ?ra2 a gen:RoleAssignment ;

                       npa:forSpaceRef ?targetRef ;

                       npa:forSpace ?space ;

                       gen:hasRole  ?role ;

                       npa:viaNanopub ?np .

                } }

                WHERE {

                  GRAPH <%4$s> {

                    ?ra a gen:RoleAssignment ;

                        npa:forSpace ?space ;

                        gen:hasRole  ?role ;

                        npa:pubkeyHash ?pkh ;

                        npa:viaNanopub ?np .

                  }

                  GRAPH <%7$s> {

                    ?np npa:hasLoadNumber ?ln .

                    FILTER (?ln > %5$d)

                  }