mrplex 0.0.1

package/dist/kernel/query/degrees.js

@@ -0,0 +1,135 @@
+/**
+ * `$degrees` binding for the graph read surface (docs/graph-plan.md §2.1,
+ * decision 5). `$degrees` is a scalar CEL intrinsic legal ONLY inside a
+ * `graph` call's `filter`: the minimum hops from the nearest root at which a
+ * document was reached.
+ *
+ * BFS visits every document at its minimal distance first, and the filter can
+ * only *prune* (visibility is monotone), so every candidate in round `r`
+ * shares `$degrees = r`. We exploit that: compile the filter once per round
+ * with `$degrees` inlined as an integer constant, then reuse the existing
+ * query-compilation machinery unchanged. This module does the inlining by
+ * rewriting the parsed CEL AST — the parser mangles `$degrees` to
+ * `__mrplex_i_degrees` (cel-parse.ts), and here we replace that ident with an
+ * `int64` constant node. Neither dialect compiler needs to know `$degrees`
+ * exists.
+ *
+ * A `$degrees` reference outside a `graph` filter reaches a dialect compiler
+ * as an unknown intrinsic and fails `filter_invalid` there — which is the
+ * desired only-in-graph behavior (decision 14).
+ */
+import { ConstantSchema, ExprSchema } from "@bufbuild/cel-spec/cel/expr/syntax_pb.js";
+import { clone, create } from "@bufbuild/protobuf";
+import { INTRINSIC_PREFIX } from "./cel-parse.js";
+/** The mangled ident the parser produces for `$degrees`. */
+export const DEGREES_MANGLED = `${INTRINSIC_PREFIX}degrees`;
+/**
+ * Return a copy of `ast` with every `$degrees` reference replaced by the
+ * integer literal `value`. Pure — the input AST is never mutated, so the
+ * per-round callers can re-bind the same parsed filter for each round.
+ */
+export function bindDegrees(ast, value) {
+    const copy = clone(ExprSchema, ast);
+    rewrite(copy, value);
+    return copy;
+}
+function rewrite(expr, value) {
+    const kind = expr.exprKind;
+    switch (kind.case) {
+        case "identExpr":
+            if (kind.value.name === DEGREES_MANGLED) {
+                // Replace the ident node in place with an int64 constant.
+                expr.exprKind = {
+                    case: "constExpr",
+                    value: create(ConstantSchema, {
+                        constantKind: { case: "int64Value", value: BigInt(value) },
+                    }),
+                };
+            }
+            return;
+        case "selectExpr":
+            if (kind.value.operand)
+                rewrite(kind.value.operand, value);
+            return;
+        case "callExpr": {
+            if (kind.value.target)
+                rewrite(kind.value.target, value);
+            for (const arg of kind.value.args)
+                rewrite(arg, value);
+            return;
+        }
+        case "comprehensionExpr": {
+            const c = kind.value;
+            if (c.iterRange)
+                rewrite(c.iterRange, value);
+            if (c.accuInit)
+                rewrite(c.accuInit, value);
+            if (c.loopCondition)
+                rewrite(c.loopCondition, value);
+            if (c.loopStep)
+                rewrite(c.loopStep, value);
+            if (c.result)
+                rewrite(c.result, value);
+            return;
+        }
+        case "listExpr":
+            for (const el of kind.value.elements)
+                rewrite(el, value);
+            return;
+        case "structExpr":
+            for (const entry of kind.value.entries) {
+                if (entry.value)
+                    rewrite(entry.value, value);
+            }
+            return;
+        default:
+            return;
+    }
+}
+/** True if the parsed filter references `$degrees` anywhere. */
+export function referencesDegrees(expr) {
+    let found = false;
+    const walk = (e) => {
+        if (found)
+            return;
+        const kind = e.exprKind;
+        switch (kind.case) {
+            case "identExpr":
+                if (kind.value.name === DEGREES_MANGLED)
+                    found = true;
+                return;
+            case "selectExpr":
+                if (kind.value.operand)
+                    walk(kind.value.operand);
+                return;
+            case "callExpr":
+                if (kind.value.target)
+                    walk(kind.value.target);
+                for (const arg of kind.value.args)
+                    walk(arg);
+                return;
+            case "comprehensionExpr": {
+                const c = kind.value;
+                for (const sub of [c.iterRange, c.accuInit, c.loopCondition, c.loopStep, c.result]) {
+                    if (sub)
+                        walk(sub);
+                }
+                return;
+            }
+            case "listExpr":
+                for (const el of kind.value.elements)
+                    walk(el);
+                return;
+            case "structExpr":
+                for (const entry of kind.value.entries)
+                    if (entry.value)
+                        walk(entry.value);
+                return;
+            default:
+                return;
+        }
+    };
+    walk(expr);
+    return found;
+}
+//# sourceMappingURL=degrees.js.map

package/dist/kernel/query/degrees.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"degrees.js","sourceRoot":"","sources":["../../../src/kernel/query/degrees.ts"],"names":[],"mappings":"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"}

package/dist/kernel/query/graph-ast.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Graph-predicate recognizers over the CEL AST — design §11.2 "CEL surface"
+ * (links-plan.md WS4). Shared by both dialect compilers so `$in_static` etc.
+ * are detected identically; each compiler emits its own SQL.
+ *
+ * The parser mangles `$name` → `__mrplex_i_name` (cel-parse.ts), so the four
+ * possession-language intrinsics arrive as ordinary function calls:
+ *
+ *   $in_static("g")          → call __mrplex_i_in_static("g")
+ *   $has_static("g","field") → call __mrplex_i_has_static("g","field")
+ *   $backlinks_static()      → call __mrplex_i_backlinks_static()   (a collection)
+ *   $links_static()          → call __mrplex_i_links_static()       (a collection)
+ *
+ * Collections are only meaningful as the target of `.size()` or as the
+ * iterRange of `.exists()`/`.all()`; a bare collection call as a boolean is
+ * rejected by the dialect compiler (it never reaches a boolean context).
+ *
+ * Phasing (§11.2): Phase 1 ships the **bare names** ($in/$has/$backlinks()/
+ * $links()) AND their `_static` forms — both resolve against the static
+ * index today. The bare name is defined as the future union $x_static ∪
+ * $x_dyn; with no dynamic edges yet, that union IS the static set, so
+ * `$in` == `$in_static` for now. When Phase 2 adds embedded queries, `$in`
+ * transparently widens to include them while `$in_static` stays pinned to
+ * the index. Only the `_dyn` variants are unimplemented (they need
+ * embedded queries) and are rejected with an actionable error.
+ */
+import type { CelExpr } from "./ast.js";
+/** Direction of a graph edge relative to the current (outer) document. */
+export type GraphDirection = "in" | "has" | "backlinks" | "links";
+/** A boolean membership predicate: $in_static(glob) / $has_static(glob, field?). */
+export type GraphMembership = {
+    direction: "in" | "has";
+    glob: string;
+    field?: string;
+};
+/** A collection: $backlinks_static() / $links_static(). */
+export type GraphCollection = {
+    direction: "backlinks" | "links";
+};
+/**
+ * Throw if `fn` is a reserved (`_dyn`) graph name. Called by the dialect
+ * compilers before their generic "unsupported function" fallthrough so the
+ * message is actionable ("use $in / $in_static").
+ */
+export declare function assertNotReservedGraphName(fn: string): void;
+export declare function asGraphMembership(expr: CelExpr): GraphMembership | null;
+/**
+ * If `expr` is a collection call ($backlinks / $links, or their _static
+ * forms), return its structured form; otherwise null. Throws on args.
+ */
+export declare function asGraphCollection(expr: CelExpr): GraphCollection | null;

package/dist/kernel/query/graph-ast.js

@@ -0,0 +1,139 @@
+/**
+ * Graph-predicate recognizers over the CEL AST — design §11.2 "CEL surface"
+ * (links-plan.md WS4). Shared by both dialect compilers so `$in_static` etc.
+ * are detected identically; each compiler emits its own SQL.
+ *
+ * The parser mangles `$name` → `__mrplex_i_name` (cel-parse.ts), so the four
+ * possession-language intrinsics arrive as ordinary function calls:
+ *
+ *   $in_static("g")          → call __mrplex_i_in_static("g")
+ *   $has_static("g","field") → call __mrplex_i_has_static("g","field")
+ *   $backlinks_static()      → call __mrplex_i_backlinks_static()   (a collection)
+ *   $links_static()          → call __mrplex_i_links_static()       (a collection)
+ *
+ * Collections are only meaningful as the target of `.size()` or as the
+ * iterRange of `.exists()`/`.all()`; a bare collection call as a boolean is
+ * rejected by the dialect compiler (it never reaches a boolean context).
+ *
+ * Phasing (§11.2): Phase 1 ships the **bare names** ($in/$has/$backlinks()/
+ * $links()) AND their `_static` forms — both resolve against the static
+ * index today. The bare name is defined as the future union $x_static ∪
+ * $x_dyn; with no dynamic edges yet, that union IS the static set, so
+ * `$in` == `$in_static` for now. When Phase 2 adds embedded queries, `$in`
+ * transparently widens to include them while `$in_static` stays pinned to
+ * the index. Only the `_dyn` variants are unimplemented (they need
+ * embedded queries) and are rejected with an actionable error.
+ */
+import { KernelError } from "../errors.js";
+import { INTRINSIC_PREFIX } from "./cel-parse.js";
+const P = INTRINSIC_PREFIX;
+// Bare names AND their `_static` forms both map to the static index today.
+// The bare name is the DESIGNED-FOR-THE-FUTURE union $x_static ∪ $x_dyn
+// (§11.2); Phase 1 has no dynamic edges, so the union is exactly the static
+// set — so `$in` == `$in_static` for now, and callers who want to *stay*
+// static-only forever write `$in_static`. When Phase 2 lands embedded
+// queries, `$in` transparently widens to include them; `$in_static` does
+// not. Only `_dyn` is unimplemented (it needs embedded queries).
+const MEMBERSHIP_FNS = {
+    [`${P}in`]: "in",
+    [`${P}in_static`]: "in",
+    [`${P}has`]: "has",
+    [`${P}has_static`]: "has",
+};
+const COLLECTION_FNS = {
+    [`${P}backlinks`]: "backlinks",
+    [`${P}backlinks_static`]: "backlinks",
+    [`${P}links`]: "links",
+    [`${P}links_static`]: "links",
+};
+// `_dyn` variants — reserved until Phase 2 ships embedded queries. Recognized
+// only to produce a clear error, never compiled.
+const RESERVED_FNS = new Set([
+    `${P}in_dyn`,
+    `${P}has_dyn`,
+    `${P}backlinks_dyn`,
+    `${P}links_dyn`,
+]);
+function reservedName(fn) {
+    // __mrplex_i_in_dyn → $in_dyn
+    return `$${fn.slice(P.length)}`;
+}
+/**
+ * Throw if `fn` is a reserved (`_dyn`) graph name. Called by the dialect
+ * compilers before their generic "unsupported function" fallthrough so the
+ * message is actionable ("use $in / $in_static").
+ */
+export function assertNotReservedGraphName(fn) {
+    if (RESERVED_FNS.has(fn)) {
+        const name = reservedName(fn);
+        const base = name.replace(/_dyn$/, "");
+        throw new KernelError("filter_invalid", {
+            reason: `${name}() needs Phase 2 (embedded queries); use ${base}() (static today, static∪dynamic later) or ${base}_static() to stay static-only`,
+        });
+    }
+}
+/** A string-constant argument's value, or undefined if not a string const. */
+function stringArg(expr) {
+    if (!expr || expr.exprKind.case !== "constExpr")
+        return undefined;
+    const k = expr.exprKind.value.constantKind;
+    return k?.case === "stringValue" ? k.value : undefined;
+}
+/**
+ * If `expr` is a membership call ($in_static / $has_static), return its
+ * structured form; otherwise null. Throws filter_invalid on a malformed
+ * call (wrong arity, non-string args) so mistakes surface clearly.
+ */
+/** Human name for a mangled graph fn (`__mrplex_i_in` → `$in`). */
+function displayName(fn) {
+    return `$${fn.slice(P.length)}`;
+}
+export function asGraphMembership(expr) {
+    if (expr.exprKind.case !== "callExpr")
+        return null;
+    const call = expr.exprKind.value;
+    const direction = MEMBERSHIP_FNS[call.function];
+    if (!direction)
+        return null;
+    const name = displayName(call.function);
+    if (call.target !== undefined) {
+        throw new KernelError("filter_invalid", {
+            reason: `${name} is a free function, not a method`,
+        });
+    }
+    const glob = stringArg(call.args[0]);
+    if (glob === undefined || call.args.length < 1 || call.args.length > 2) {
+        throw new KernelError("filter_invalid", {
+            reason: `${name}(path-or-glob [, field]) takes a string glob and an optional string field`,
+        });
+    }
+    let field;
+    if (call.args.length === 2) {
+        field = stringArg(call.args[1]);
+        if (field === undefined) {
+            throw new KernelError("filter_invalid", {
+                reason: `${name} field argument must be a string`,
+            });
+        }
+    }
+    return field === undefined ? { direction, glob } : { direction, glob, field };
+}
+/**
+ * If `expr` is a collection call ($backlinks / $links, or their _static
+ * forms), return its structured form; otherwise null. Throws on args.
+ */
+export function asGraphCollection(expr) {
+    if (expr.exprKind.case !== "callExpr")
+        return null;
+    const call = expr.exprKind.value;
+    const direction = COLLECTION_FNS[call.function];
+    if (!direction)
+        return null;
+    if (call.target !== undefined || call.args.length !== 0) {
+        throw new KernelError("filter_invalid", {
+            reason: `${displayName(call.function)}() takes no arguments`,
+        });
+    }
+    return { direction };
+}
+//# sourceMappingURL=graph-ast.js.map

package/dist/kernel/query/graph-ast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-ast.js","sourceRoot":"","sources":["../../../src/kernel/query/graph-ast.ts"],"names":[],"mappings":"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"}

package/dist/kernel/query/query.d.ts

@@ -0,0 +1,56 @@
+/**
+ * kernel.query orchestration — design §5.
+ *
+ * The kernel resolves repo access, parses CEL eagerly (so
+ * `filter_invalid` surfaces before storage), and builds a structured
+ * `SearchPlan` the adapter compiles into its dialect's SQL (m5-plan
+ * WS2). Semantic mode composes vector_search → SearchPlan with a
+ * candidate-id whitelist.
+ */
+import type { RepoRow, Storage, VersionRow } from "../../storage/types.js";
+import { type ClaimMatcher } from "../auth/scope.js";
+import type { PathConfig } from "../path-config.js";
+import type { QueryHit, Version } from "../wire.js";
+export type QuerySpec = {
+    /** Slug, glob, or list. Omitted = every repo the caller can address. */
+    repo?: string | string[];
+    filter?: string;
+    text?: string;
+    semantic?: string;
+    limit?: number;
+    include_hidden?: boolean;
+    include_system?: boolean;
+    /**
+     * Fields to project onto each hit (docs/query-select-plan.md). Names bare
+     * frontmatter keys (`title`) or `$`-intrinsics (`$path`, `$body`, …).
+     * Defaults to `["$path"]` — the identity you almost always want and the
+     * cheapest thing to return.
+     */
+    select?: string[];
+};
+export type QueryDeps = {
+    storage: Storage;
+    serverPathConfig: PathConfig;
+    toVersionWire: (row: VersionRow, repoSlug: string) => Version;
+    /**
+     * Optional semantic-query embed hook. When absent and `spec.semantic` is set,
+     * runQuery throws `semantic_unavailable` (m4-plan §5 decision 4).
+     */
+    queryEmbed?: (semantic: string) => Promise<{
+        vector: number[];
+        model: string;
+        dim: number;
+    }>;
+};
+/** M2 default when the spec omits limit. */
+export declare const DEFAULT_QUERY_LIMIT = 50;
+/**
+ * `claims` is null when the call supplies no scope (full visibility) or a
+ * normalized `ClaimMatcher[]` narrowing what's visible (noauth plan §1).
+ */
+export declare function runQuery(claims: ClaimMatcher[] | null, spec: QuerySpec, deps: QueryDeps): Promise<QueryHit[]>;
+/**
+ * Compute a repo's effective config — exported for callers that want to
+ * apply per-repo sigils outside the main query loop (e.g., surfaces).
+ */
+export declare function repoEffectiveConfig(repo: RepoRow, serverConfig: PathConfig): PathConfig;

package/dist/kernel/query/query.js

@@ -0,0 +1,276 @@
+/**
+ * kernel.query orchestration — design §5.
+ *
+ * The kernel resolves repo access, parses CEL eagerly (so
+ * `filter_invalid` surfaces before storage), and builds a structured
+ * `SearchPlan` the adapter compiles into its dialect's SQL (m5-plan
+ * WS2). Semantic mode composes vector_search → SearchPlan with a
+ * candidate-id whitelist.
+ */
+import { slugMatchesPattern } from "../auth/glob.js";
+import { claimsGrantRepo, claimsToScopeGroups } from "../auth/scope.js";
+import { KernelError } from "../errors.js";
+import { effectivePathConfig, parseRepoOverride } from "../path-config.js";
+import { parseCel } from "./cel-parse.js";
+const KNOWN_SPEC_FIELDS = new Set([
+    "repo",
+    "filter",
+    "text",
+    "semantic",
+    "limit",
+    "include_hidden",
+    "include_system",
+    "select",
+]);
+/**
+ * Projectable `$`-intrinsics (docs/query-select-plan.md §3): the filter
+ * compilers' filterable columns (`$path`, `$updated_at`, `$body`) plus the
+ * version-identity fields that are projectable but not filterable. Each maps
+ * a `$name` to the value read off the already-built `Version` wire object.
+ * `select` validates against this registry and rejects unknown `$names`.
+ */
+const VERSION_INTRINSIC_PROJECTORS = {
+    $path: (v) => v.path,
+    $repo: (v) => v.repo,
+    $version_id: (v) => v.version_id,
+    $prev_version_id: (v) => v.prev_version_id,
+    $next_version_id: (v) => v.next_version_id,
+    $updated_at: (v) => v.created_at,
+    $author: (v) => v.author,
+    $body: (v) => v.body,
+    $content_hash: (v) => v.content_hash,
+};
+/** All `$`-intrinsics valid in `select` (includes semantic-mode-only fields). */
+const SELECTABLE_INTRINSICS = new Set([
+    ...Object.keys(VERSION_INTRINSIC_PROJECTORS),
+    "$semantic_score",
+]);
+/** Identity default — the cheapest useful projection (§2). */
+const DEFAULT_SELECT = ["$path"];
+/** M2 default when the spec omits limit. */
+export const DEFAULT_QUERY_LIMIT = 50;
+/**
+ * `claims` is null when the call supplies no scope (full visibility) or a
+ * normalized `ClaimMatcher[]` narrowing what's visible (noauth plan §1).
+ */
+export async function runQuery(claims, spec, deps) {
+    validateSpec(spec);
+    const select = spec.select ?? [...DEFAULT_SELECT];
+    // 1. Resolve repos the caller can address.
+    const reposById = new Map();
+    for (const row of await deps.storage.repos_list())
+        reposById.set(row.id, row);
+    const targetRepos = filterReposByAccessAndSpec(claims, spec, reposById, deps.serverPathConfig);
+    if (targetRepos.length === 0)
+        return [];
+    // 2. Parse CEL filter eagerly — `filter_invalid` before storage.
+    let filterAst;
+    if (spec.filter !== undefined) {
+        const ast = parseCel(spec.filter);
+        if (!ast.expr) {
+            throw new KernelError("filter_invalid", { reason: "empty filter" });
+        }
+        filterAst = ast.expr;
+    }
+    // 3. Per-repo sigil exclusion (§3.5.5).
+    const sigils = buildPerRepoSigilExclusion(targetRepos, deps.serverPathConfig, spec.include_hidden ?? false, spec.include_system ?? false);
+    // 4. Scope filter — absent claims see everything; claims contribute groups.
+    const scope = buildScope(claims, targetRepos);
+    const userLimit = spec.limit ?? DEFAULT_QUERY_LIMIT;
+    if (userLimit <= 0)
+        return [];
+    // 5. Semantic branch (M4): vector_search → candidate whitelist → SearchPlan.
+    if (spec.semantic !== undefined) {
+        if (!deps.queryEmbed) {
+            throw new KernelError("semantic_unavailable", {
+                reason: "no embedding hook configured on this server",
+            });
+        }
+        let embed;
+        try {
+            embed = await deps.queryEmbed(spec.semantic);
+        }
+        catch (err) {
+            throw new KernelError("semantic_unavailable", {
+                reason: `embedding hook failed at query time: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        if (embed.vector.length !== embed.dim) {
+            throw new KernelError("semantic_unavailable", {
+                reason: `embedding hook returned vector.length ${embed.vector.length} != dim ${embed.dim}`,
+            });
+        }
+        const semanticK = Math.min(userLimit * 4, 200);
+        const hits = await deps.storage.vector_search(targetRepos.map((r) => r.id), embed.model, embed.vector, semanticK);
+        if (hits.length === 0)
+            return [];
+        const candidateIds = hits.map((h) => h.version_id);
+        const distanceById = new Map(hits.map((h) => [h.version_id, h.score]));
+        const plan = {
+            repo_ids: targetRepos.map((r) => r.id),
+            limit: candidateIds.length,
+            text: spec.text,
+            filter_ast: filterAst,
+            sigils,
+            scope,
+            candidate_ids: candidateIds,
+        };
+        const rows = await deps.storage.versions_search(plan);
+        rows.sort((a, b) => (distanceById.get(a.id) ?? 1) - (distanceById.get(b.id) ?? 1));
+        return rows.slice(0, userLimit).map((row) => {
+            const repoSlug = reposById.get(row.repo_id).slug;
+            const distance = distanceById.get(row.id);
+            return projectHit(deps.toVersionWire(row, repoSlug), select, {
+                semanticScore: distance === undefined ? undefined : cosineDistanceToSimilarity(distance),
+            });
+        });
+    }
+    // 6. Non-semantic path.
+    const plan = {
+        repo_ids: targetRepos.map((r) => r.id),
+        limit: userLimit,
+        text: spec.text,
+        filter_ast: filterAst,
+        sigils,
+        scope,
+    };
+    const rows = await deps.storage.versions_search(plan);
+    return rows.map((row) => {
+        const repoSlug = reposById.get(row.repo_id).slug;
+        return projectHit(deps.toVersionWire(row, repoSlug), select);
+    });
+}
+/** Cosine similarity from storage cosine distance (0 = identical, 2 = opposite). */
+function cosineDistanceToSimilarity(distance) {
+    return 1 - distance;
+}
+function projectHit(v, select, ctx = {}) {
+    const hit = {};
+    for (const name of select) {
+        if (name === "$semantic_score") {
+            if (ctx.semanticScore !== undefined) {
+                hit.$semantic_score = ctx.semanticScore;
+            }
+            continue;
+        }
+        if (name.startsWith("$")) {
+            hit[name] = VERSION_INTRINSIC_PROJECTORS[name](v);
+        }
+        else if (v.frontmatter[name] !== undefined) {
+            hit[name] = v.frontmatter[name];
+        }
+    }
+    return hit;
+}
+// -----------------------------------------------------------------------------
+// Validation
+// -----------------------------------------------------------------------------
+function validateSpec(spec) {
+    for (const key of Object.keys(spec)) {
+        if (!KNOWN_SPEC_FIELDS.has(key)) {
+            throw new KernelError("filter_invalid", {
+                reason: `unknown QuerySpec field: ${JSON.stringify(key)}`,
+            });
+        }
+    }
+    if (spec.semantic !== undefined) {
+        if (typeof spec.semantic !== "string" || spec.semantic.trim().length === 0) {
+            throw new KernelError("filter_invalid", {
+                reason: "the `semantic` mode requires a non-empty query string",
+            });
+        }
+    }
+    if (spec.limit !== undefined) {
+        if (typeof spec.limit !== "number" || !Number.isSafeInteger(spec.limit) || spec.limit < 0) {
+            throw new KernelError("filter_invalid", {
+                reason: `invalid limit: ${JSON.stringify(spec.limit)}`,
+            });
+        }
+    }
+    if (spec.select !== undefined) {
+        if (!Array.isArray(spec.select) || spec.select.some((s) => typeof s !== "string")) {
+            throw new KernelError("filter_invalid", { reason: "select must be an array of strings" });
+        }
+        for (const name of spec.select) {
+            if (name.startsWith("$") && !SELECTABLE_INTRINSICS.has(name)) {
+                // Derive the "expected" list from the registry so the message can't
+                // drift from the code (mirrors the filter compiler's intrinsic error).
+                const expected = [...SELECTABLE_INTRINSICS].sort().join(", ");
+                throw new KernelError("filter_invalid", {
+                    reason: `unknown intrinsic ${name} in select (expected ${expected})`,
+                });
+            }
+        }
+    }
+}
+// -----------------------------------------------------------------------------
+// Repo resolution
+// -----------------------------------------------------------------------------
+function filterReposByAccessAndSpec(claims, spec, reposById, serverConfig) {
+    const patterns = spec.repo === undefined ? undefined : Array.isArray(spec.repo) ? spec.repo : [spec.repo];
+    const systemSigils = serverConfig.system_sigils;
+    return [...reposById.values()]
+        .filter((repo) => {
+        if (claims !== null && !claimsGrantRepo(claims, repo.slug))
+            return false;
+        if (systemSigils.some((sigil) => repo.slug.startsWith(sigil)))
+            return false;
+        if (patterns === undefined)
+            return true;
+        return patterns.some((pattern) => slugMatchesPattern(pattern, repo.slug));
+    })
+        .sort((a, b) => a.slug.localeCompare(b.slug));
+}
+// -----------------------------------------------------------------------------
+// Per-repo sigil exclusion (§5.1, §3.5.5)
+// -----------------------------------------------------------------------------
+function buildPerRepoSigilExclusion(repos, serverConfig, includeHidden, includeSystem) {
+    if (repos.length === 0)
+        return [];
+    const groups = new Map();
+    for (const repo of repos) {
+        const cfg = effectivePathConfig(serverConfig, parseRepoOverride(repo.path_config));
+        const sigils = [];
+        if (!includeHidden)
+            sigils.push(...cfg.hidden_sigils);
+        if (!includeSystem)
+            sigils.push(...cfg.system_sigils);
+        const key = JSON.stringify(sigils);
+        const existing = groups.get(key);
+        if (existing) {
+            existing.repoIds.push(repo.id);
+        }
+        else {
+            groups.set(key, { sigils, repoIds: [repo.id] });
+        }
+    }
+    const out = [];
+    for (const { sigils, repoIds } of groups.values()) {
+        if (sigils.length === 0)
+            continue;
+        out.push({ repo_ids: repoIds, sigils });
+    }
+    return out;
+}
+// -----------------------------------------------------------------------------
+// Scope → SearchPlan.scope (§8.2)
+// -----------------------------------------------------------------------------
+function buildScope(claims, targetRepos) {
+    // Absent scope = full visibility. The repo-access filter already limited
+    // targetRepos, so an empty groups list here means the claims grant no path
+    // in any addressable repo — deny.
+    if (claims === null)
+        return { kind: "allow_all" };
+    const groups = claimsToScopeGroups(claims, targetRepos);
+    if (groups.length === 0)
+        return { kind: "deny_all" };
+    return { kind: "groups", groups };
+}
+/**
+ * Compute a repo's effective config — exported for callers that want to
+ * apply per-repo sigils outside the main query loop (e.g., surfaces).
+ */
+export function repoEffectiveConfig(repo, serverConfig) {
+    return effectivePathConfig(serverConfig, parseRepoOverride(repo.path_config));
+}
+//# sourceMappingURL=query.js.map