@_linked/core 2.18.0-next.20260904105013 → 2.18.0-next.20260904105507

package/CHANGELOG.md

@@ -4,6 +4,90 @@
 
 ### Minor Changes
 
+- [#208](https://github.com/linked-cm/core/pull/208) [`085cfad`](https://github.com/linked-cm/core/commit/085cfadd4ebf0e584da9476a234b6ec47b261b5f) Thanks [@flyon](https://github.com/flyon)! - Ask queries — a first-class query kind whose answer is a boolean — plus two `rdf:type` / `sh:path`
+  resolution fixes it surfaced.
+
+  ## Ask queries
+
+  `.exists()` is a shortcut for an ask, not a special case of select. An ask carries a **pattern and
+  nothing else** — no projection, sorting or pagination — at every layer: `AskBuilder`, `IRAskQuery`,
+  an `op: 'ask'` wire envelope, and `ASK WHERE { … }` in SPARQL.
+
+  ```ts
+  await Person.exists({ id }); // ASK { ?a0 a <PersonClass> . FILTER(?a0 = <id>) }
+  await Person.select()
+    .where((p) => p.name.equals("Semmy"))
+    .exists(); // ASK with the filter
+  await Shape.exists(uri); // ASK { <uri> ?p ?o }
+  ```
+
+  **`Shape.exists(uri)` on the base class asks whether a node exists at all** — no `rdf:type`
+  constraint, under any shape or none. (`Shape` is free to mean "anything": the shapes themselves are
+  described by `NodeShape` and `PropertyShape`.) A shapeless ask has no shape to route on, so
+  `LinkedStorage` asks **every** dataset it knows and ORs the answers, short-circuiting on the first
+  `true` — cheap precisely because the answers are booleans. Any router implementing `IDataset`
+  inherits that obligation: a shapeless ask means "anywhere I can reach", not "in my default store".
+
+  ### Breaking: `IDataset.askQuery(query: AskQuery): Promise<boolean>` is required
+
+  Every store must implement it; `query.shape` is optional. **No code path in this package rewrites an
+  ask as a select** — a store with no boolean primitive decides for itself how to answer, and
+  defaulting that here would hide the choice. `askQuery` must resolve to a real boolean (a non-boolean
+  is rejected, not coerced, since a truthy value would read as "exists") and must reject on failure.
+
+  ### Wire format `1.1`
+
+  An ask travels as its own envelope, discriminated by `op: 'ask'`:
+
+  ```json
+  {"v": "1.1", "op": "ask", "shape": "…/Person", "subject": "…/p1"}
+  {"v": "1.1", "op": "ask", "subject": "https://example.org/thing"}
+  ```
+
+  Omitting `shape` **is** the shapeless form. There is no `fields`, `limit`, `offset`, `sortBy` or
+  `one`, so a receiver has nothing to validate or ignore. `fromJSON` routes `op: 'ask'` to an
+  `AskBuilder` and still throws `Unknown query op` on anything unrecognised, so an older peer fails
+  loud rather than reinterpreting the envelope as a select. Deploy receivers first.
+
+  New exports: `AskBuilder`, `isAskQuery`, and the `AskQuery` / `AskQueryJSON` / `RawAskInput` /
+  `AskSpec` types. `lower()` gains an ask overload returning `IRAskQuery`; `askToAlgebra` /
+  `askToSparql` / `askPlanToSparql` / `SparqlAskPlan` / `mapSparqlAskResult` are the SPARQL arm.
+
+  ## Breaking: a shape must declare a `targetClass`
+
+  A query or mutation on a shape with none — on it or on any shape it extends — now throws instead of
+  silently typing instances with the shape's own IRI.
+
+  ```ts
+  @linkedShape
+  class Person extends Shape {
+    static targetClass = { id: "https://example.org/Person" }; // required
+  }
+  ```
+
+  `rdf:type` names the class a node **is**; the shape IRI identifies the SHACL description _of_ that
+  class — a different node. Substituting one for the other conflated them, and did so invisibly: read
+  and write used the same substitution, so data round-tripped and nothing surfaced the mistake.
+  `targetClass` is read off the shape class, so JavaScript static inheritance already walks the
+  superclass chain.
+
+  ## A declared `sh:path` is always the predicate
+
+  The resolver skipped any shape or property IRI beginning `linked://tmp/`, substituting the property
+  shape's own "shadow" IRI. That skip existed only so this repo's fixtures could assert shape-derived
+  predicates; it is gone, along with the `linked://tmp/` special case. Two mutation paths that built
+  traversal predicates by hand — bypassing the resolver — now go through it, fixing an expression
+  update (`p.bestFriend.name`) that emitted the shadow IRI as a predicate and therefore matched
+  nothing.
+
+  ## Migration
+
+  - Declare a `targetClass` on any shape lacking one. Data written under the old behaviour is typed
+    with the shape IRI: either set that IRI as the `targetClass`, or retype the nodes.
+  - Implement `askQuery` on any `IDataset`.
+  - A shape declaring a `linked://tmp/` path gets its declared path as the predicate instead of the
+    shadow IRI. No released code minted such IRIs, so this is expected to affect nobody.
+
 - [#205](https://github.com/linked-cm/core/pull/205) [`48ecb4d`](https://github.com/linked-cm/core/commit/48ecb4dbdc20471bf19a4c4cc9d58ef90f5cd1b1) Thanks [@flyon](https://github.com/flyon)! - Expose the meta-model's SHACL constraint table via `getPropertyShapeTerms()` /
   `getPropertyShapeTerm(label)`, so an alternative serializer can look up each constraint's
   predicate, datatype and node kind rather than hard-coding its own copy.
@@ -42,12 +126,13 @@
   preloads, sorting and pagination — none of them can change whether a _match_ exists, and
   honouring `offset` while dropping the projection could actively flip the answer, since
   `OFFSET` skips rows of a solution sequence whose cardinality depends on the projection.
-  Kept: filters, `minus` entries and the subject. `LIMIT 1` is then applied. So
-  `Person.select(p => p.name).orderBy(…).offset(10).exists()` emits the same minimal
-  `SELECT DISTINCT ?a0 … LIMIT 1` as a bare `Person.exists({id})`.
+  Kept: filters, `minus` entries and the subject. So
+  `Person.select(p => p.name).orderBy(…).offset(10).exists()` costs and answers exactly the same
+  as a bare `Person.exists({id})`.
 
-  Purely additive. No IR, algebra, wire-format or `IDataset` change — it lowers to an
-  ordinary SELECT, so every store implementation supports it as-is.
+  See the ask-query entry in this release for what that normalised query becomes on the wire and in
+  SPARQL: `.exists()` is a shortcut for an ask query, which is its own query kind with its own
+  `IDataset.askQuery` method.
 
 ### Patch Changes
 

package/lib/esm/index.d.ts

@@ -17,6 +17,9 @@ export { PropertyPath, walkPropertyPath } from './queries/PropertyPath.js';
 export { FieldSet } from './queries/FieldSet.js';
 export type { FieldSetEntry, FieldSetInput, FieldSetJSON, FieldSetFieldJSON } from './queries/FieldSet.js';
 export type { QueryBuilderJSON } from './queries/QueryBuilder.js';
+export { AskBuilder, isAskQuery } from './queries/AskBuilder.js';
+export type { AskSpec } from './queries/AskBuilder.js';
+export type { AskQuery, AskQueryJSON, RawAskInput } from './queries/AskQuery.js';
 export { CreateBuilder } from './queries/CreateBuilder.js';
 export { UpdateBuilder } from './queries/UpdateBuilder.js';
 export { DeleteBuilder } from './queries/DeleteBuilder.js';

package/lib/esm/index.js

@@ -21,6 +21,7 @@ export { PropertyPath, walkPropertyPath } from './queries/PropertyPath.js';
 // Phase 3a — FieldSet
 export { FieldSet } from './queries/FieldSet.js';
 // Phase 3b — Mutation builders
+export { AskBuilder, isAskQuery } from './queries/AskBuilder.js';
 export { CreateBuilder } from './queries/CreateBuilder.js';
 export { UpdateBuilder } from './queries/UpdateBuilder.js';
 export { DeleteBuilder } from './queries/DeleteBuilder.js';

package/lib/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAC,UAAU,EAAE,SAAS,EAAC,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAC,OAAO,EAAC,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAC,uBAAuB,EAAC,MAAM,qCAAqC,CAAC;AAC5E,sEAAsE;AACtE,OAAO,EAAC,KAAK,EAAC,MAAM,mBAAmB,CAAC;AACxC,kEAAkE;AAClE,OAAO,EAAC,QAAQ,EAAE,WAAW,EAAE,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAQnF,OAAO,EAAC,aAAa,EAAC,MAAM,0BAA0B,CAAC;AACvD,2CAA2C;AAC3C,OAAO,EAAC,aAAa,EAAE,YAAY,EAAC,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAC,KAAK,EAAC,MAAM,oBAAoB,CAAC;AAEzC,OAAO,EAAC,QAAQ,EAAC,MAAM,uBAAuB,CAAC;AAE/C,OAAO,EACL,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAC,YAAY,EAAE,gBAAgB,EAAC,MAAM,2BAA2B,CAAC;AAEzE,sBAAsB;AACtB,OAAO,EAAC,QAAQ,EAAC,MAAM,uBAAuB,CAAC;AAM/C,+BAA+B;AAC/B,OAAO,EAAC,aAAa,EAAC,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAC,aAAa,EAAC,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAC,aAAa,EAAC,MAAM,4BAA4B,CAAC;AAGzD,8CAA8C;AAC9C,OAAO,EAAC,cAAc,EAAC,MAAM,iCAAiC,CAAC;AAE/D,OAAO,EAAC,IAAI,EAAC,MAAM,uBAAuB,CAAC;AAe3C,sEAAsE;AACtE,OAAO,EACL,cAAc,EACd,WAAW,GACZ,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,cAAc,EACd,iBAAiB,GAClB,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAC,UAAU,EAAE,SAAS,EAAC,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAC,OAAO,EAAC,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAC,uBAAuB,EAAC,MAAM,qCAAqC,CAAC;AAC5E,sEAAsE;AACtE,OAAO,EAAC,KAAK,EAAC,MAAM,mBAAmB,CAAC;AACxC,kEAAkE;AAClE,OAAO,EAAC,QAAQ,EAAE,WAAW,EAAE,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAQnF,OAAO,EAAC,aAAa,EAAC,MAAM,0BAA0B,CAAC;AACvD,2CAA2C;AAC3C,OAAO,EAAC,aAAa,EAAE,YAAY,EAAC,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAC,KAAK,EAAC,MAAM,oBAAoB,CAAC;AAEzC,OAAO,EAAC,QAAQ,EAAC,MAAM,uBAAuB,CAAC;AAE/C,OAAO,EACL,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAC,YAAY,EAAE,gBAAgB,EAAC,MAAM,2BAA2B,CAAC;AAEzE,sBAAsB;AACtB,OAAO,EAAC,QAAQ,EAAC,MAAM,uBAAuB,CAAC;AAM/C,+BAA+B;AAC/B,OAAO,EAAC,UAAU,EAAE,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAG/D,OAAO,EAAC,aAAa,EAAC,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAC,aAAa,EAAC,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAC,aAAa,EAAC,MAAM,4BAA4B,CAAC;AAGzD,8CAA8C;AAC9C,OAAO,EAAC,cAAc,EAAC,MAAM,iCAAiC,CAAC;AAE/D,OAAO,EAAC,IAAI,EAAC,MAAM,uBAAuB,CAAC;AAe3C,sEAAsE;AACtE,OAAO,EACL,cAAc,EACd,WAAW,GACZ,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,cAAc,EACd,iBAAiB,GAClB,MAAM,gCAAgC,CAAC"}

package/lib/esm/interfaces/IDataset.d.ts

@@ -1,4 +1,5 @@
 import type { SelectQuery } from '../queries/SelectQuery.js';
+import type { AskQuery } from '../queries/AskQuery.js';
 import type { CreateQuery } from '../queries/CreateQuery.js';
 import type { UpdateQuery } from '../queries/UpdateQuery.js';
 import type { DeleteQuery, DeleteResponse } from '../queries/DeleteQuery.js';
@@ -20,6 +21,27 @@ export interface IDataset {
      */
     init?(): Promise<any>;
     selectQuery(query: SelectQuery): Promise<SelectResult>;
+    /**
+     * Answer an ask query — a boolean, not a result set.
+     *
+     * **Required.** An {@link AskQuery} carries a pattern and nothing else: no
+     * projection, no sorting, no pagination. A SPARQL-backed store emits
+     * `ASK WHERE { … }`; another backend answers it however it can.
+     *
+     * It is required rather than optional, and this package contains **no path that
+     * rewrites an ask as a select**. A store that has no boolean primitive decides
+     * for itself how to answer — that decision belongs to the store, and defaulting
+     * it here would hide it.
+     *
+     * `query.shape` is optional: absent means no `rdf:type` constraint at all
+     * ("does a node with this IRI exist"), which lowers to `ASK { <iri> ?p ?o }`.
+     *
+     * Must resolve to a real boolean — a non-boolean is rejected, not coerced,
+     * since a truthy value would silently read as "exists". Must reject on
+     * failure: reporting an unreachable store as `false` is the failure mode this
+     * API was built to remove.
+     */
+    askQuery(query: AskQuery): Promise<boolean>;
     updateQuery?(query: UpdateQuery): Promise<UpdateResult>;
     createQuery?(query: CreateQuery): Promise<CreateResult>;
     deleteQuery?(query: DeleteQuery): Promise<DeleteResponse>;

package/lib/esm/queries/AskBuilder.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `AskBuilder` — a query whose answer is a boolean.
+ *
+ * A small sibling of `SelectBuilder` rather than a mode of it. It can only hold a
+ * pattern (shape, subject(s), where, minus), so the normalisation an existence
+ * check needs is a property of the *type*: there is no projection, sorting or
+ * pagination to drop, because none can be set.
+ */
+import { type ShapeConstructor } from '../shapes/Shape.js';
+import type { WherePath } from './SelectQuery.js';
+import type { RawMinusEntry } from './IRDesugar.js';
+import type { NodeShapeData } from '../shapes/SHACL.js';
+import type { NodeReferenceValue } from './QueryFactory.js';
+import type { IDataset } from '../interfaces/IDataset.js';
+import { PendingQueryContext } from './QueryContext.js';
+import type { AskQuery, AskQueryJSON, RawAskInput } from './AskQuery.js';
+/** Everything an ask can carry. Assembled by `.exists()` or by `Shape.exists()`. */
+export type AskSpec = {
+    /** The shape class whose instances are asked about; omitted = shapeless. */
+    shapeClass?: ShapeConstructor<any>;
+    subject?: NodeReferenceValue | PendingQueryContext;
+    subjects?: NodeReferenceValue[];
+    where?: WherePath;
+    minusEntries?: RawMinusEntry[];
+    /** `.for(null)` was called — there is no subject to ask about. */
+    nullSubject?: boolean;
+};
+export declare class AskBuilder implements PromiseLike<boolean>, Promise<boolean> {
+    private readonly _spec;
+    private constructor();
+    /** Build from an assembled spec — used by `.exists()` and `Shape.exists()`. */
+    static of(spec: AskSpec): AskBuilder;
+    /**
+     * A shapeless ask: does a node with this IRI exist at all, under any type or
+     * none? Lowers to `ASK { <iri> ?p ?o }`.
+     */
+    static forNode(id: string | NodeReferenceValue | PendingQueryContext | null | undefined): AskBuilder;
+    /** Discriminator for the free `lower()` function and dataset routing. */
+    readonly __queryKind: "ask";
+    /** The shape asked about — `undefined` for a shapeless ask. */
+    get shape(): NodeShapeData | undefined;
+    toRawInput(): RawAskInput;
+    toJSON(): AskQueryJSON;
+    static fromJSON(json: AskQueryJSON): AskBuilder;
+    /**
+     * Execute and resolve to a real boolean.
+     *
+     * Never `null`, never a row. A store, transport or lowering failure **rejects**;
+     * it is never reported as `false`. The one case that resolves `false` without
+     * querying is a query with no subject to ask about — `.for(null)`, or a
+     * `PendingQueryContext` as the subject that has not landed: "does the node with
+     * no id exist?" has a correct total answer, and it is `false`.
+     */
+    exec(target?: IDataset): Promise<boolean>;
+    /** `await` triggers execution. */
+    then<TResult1 = boolean, TResult2 = never>(onfulfilled?: ((value: boolean) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<boolean | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<boolean>;
+    get [Symbol.toStringTag](): string;
+}
+/** Narrow an unknown query object to an ask. */
+export declare function isAskQuery(query: unknown): query is AskQuery;

package/lib/esm/queries/AskBuilder.js

@@ -0,0 +1,178 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { resolveShape } from './resolveShape.js';
+import { PendingQueryContext } from './QueryContext.js';
+import { encodeContextRef, isContextRefJSON } from './ContextRef.js';
+import { WIRE_VERSION, assertWireVersion } from './wireVersion.js';
+import { getQueryDispatch, resolveExistence } from './queryDispatch.js';
+import { resolveUriOrThrow } from '../utils/NodeReference.js';
+import { serializeWherePath, serializeRawMinusEntry, deserializeWherePath, deserializeRawMinusEntry, } from './QueryBuilderSerialization.js';
+export class AskBuilder {
+    constructor(spec) {
+        /** Discriminator for the free `lower()` function and dataset routing. */
+        this.__queryKind = 'ask';
+        this._spec = spec;
+    }
+    /** Build from an assembled spec — used by `.exists()` and `Shape.exists()`. */
+    static of(spec) {
+        return new AskBuilder(spec);
+    }
+    /**
+     * A shapeless ask: does a node with this IRI exist at all, under any type or
+     * none? Lowers to `ASK { <iri> ?p ?o }`.
+     */
+    static forNode(id) {
+        if (id === null || id === undefined) {
+            return new AskBuilder({ nullSubject: true });
+        }
+        if (id instanceof PendingQueryContext) {
+            return new AskBuilder({ subject: id });
+        }
+        const ref = typeof id === 'string' ? { id: resolveUriOrThrow(id) } : id;
+        return new AskBuilder({ subject: ref });
+    }
+    /** The shape asked about — `undefined` for a shapeless ask. */
+    get shape() {
+        var _a;
+        return (_a = this._spec.shapeClass) === null || _a === void 0 ? void 0 : _a.shape;
+    }
+    toRawInput() {
+        const { shapeClass, subject, subjects, where, minusEntries, nullSubject } = this._spec;
+        const input = {};
+        // Carried so lowering can reject it. `exec()` answers `false` before
+        // dispatching, but a store handed the builder directly (e.g. after
+        // `fromJSON`) would otherwise lower a subject-less query that matches every
+        // instance of the shape and answer `true`.
+        if (nullSubject)
+            input.nullSubject = true;
+        if (shapeClass)
+            input.shape = shapeClass;
+        if (subject)
+            input.subject = subject;
+        if (subjects && subjects.length > 0)
+            input.subjects = subjects;
+        if (where)
+            input.where = where;
+        if (minusEntries && minusEntries.length > 0)
+            input.minusEntries = minusEntries;
+        return input;
+    }
+    toJSON() {
+        var _a;
+        const { shapeClass, subject, subjects, where, minusEntries, nullSubject } = this._spec;
+        const json = { v: WIRE_VERSION, op: 'ask' };
+        if (shapeClass) {
+            json.shape = ((_a = shapeClass.shape) === null || _a === void 0 ? void 0 : _a.id) || '';
+        }
+        if (subject instanceof PendingQueryContext) {
+            // Carry the reference, not its (possibly unresolved) id, so the receiver
+            // resolves it against its own context map at lowering time.
+            json.subject = encodeContextRef(subject.contextName);
+        }
+        else if (subject && typeof subject === 'object' && 'id' in subject) {
+            json.subject = subject.id;
+        }
+        if (subjects && subjects.length > 0) {
+            json.subjects = subjects.map((s) => s.id);
+        }
+        // A shapeless ask carries neither — both name properties, which only a shape
+        // can resolve — so `shapeClass` is present whenever these are.
+        if (where && shapeClass) {
+            json.where = serializeWherePath(where, shapeClass.shape);
+        }
+        if (minusEntries && minusEntries.length > 0 && shapeClass) {
+            json.minusEntries = minusEntries.map((e) => serializeRawMinusEntry(e, shapeClass.shape));
+        }
+        if (nullSubject) {
+            json.nullSubject = true;
+        }
+        return json;
+    }
+    static fromJSON(json) {
+        var _a, _b;
+        assertWireVersion(json.v);
+        const shapeClass = json.shape
+            ? resolveShape(json.shape)
+            : undefined;
+        const spec = {};
+        if (shapeClass)
+            spec.shapeClass = shapeClass;
+        if (json.subject !== undefined) {
+            spec.subject = isContextRefJSON(json.subject)
+                ? new PendingQueryContext(json.subject['@ctx'])
+                : { id: json.subject };
+        }
+        if (json.subjects && json.subjects.length > 0) {
+            spec.subjects = json.subjects.map((id) => ({ id }));
+        }
+        if (json.where || ((_a = json.minusEntries) === null || _a === void 0 ? void 0 : _a.length)) {
+            // A where clause or minus entry names properties, and a property is only
+            // resolvable through a shape. A shapeless ask cannot carry either.
+            if (!shapeClass) {
+                throw new Error('An ask envelope with a `where` or `minusEntries` must name a `shape`: ' +
+                    'the clause references properties, which are resolved through the shape.');
+            }
+            if (json.where) {
+                spec.where = deserializeWherePath(shapeClass.shape, json.where);
+            }
+            if ((_b = json.minusEntries) === null || _b === void 0 ? void 0 : _b.length) {
+                spec.minusEntries = json.minusEntries.map((e) => deserializeRawMinusEntry(shapeClass.shape, e));
+            }
+        }
+        if (json.nullSubject)
+            spec.nullSubject = true;
+        return new AskBuilder(spec);
+    }
+    /**
+     * Execute and resolve to a real boolean.
+     *
+     * Never `null`, never a row. A store, transport or lowering failure **rejects**;
+     * it is never reported as `false`. The one case that resolves `false` without
+     * querying is a query with no subject to ask about — `.for(null)`, or a
+     * `PendingQueryContext` as the subject that has not landed: "does the node with
+     * no id exist?" has a correct total answer, and it is `false`.
+     */
+    exec(target) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { nullSubject, subject } = this._spec;
+            if (nullSubject)
+                return false;
+            if (subject instanceof PendingQueryContext && !subject.id)
+                return false;
+            // `async` ensures a missing global dispatch rejects rather than throwing
+            // synchronously past the caller's `.catch()`.
+            const dispatch = target !== null && target !== void 0 ? target : getQueryDispatch();
+            return resolveExistence(dispatch, this);
+        });
+    }
+    /** `await` triggers execution. */
+    then(onfulfilled, onrejected) {
+        return this.exec().then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.then().catch(onrejected);
+    }
+    finally(onfinally) {
+        return this.then().finally(onfinally);
+    }
+    get [Symbol.toStringTag]() {
+        return 'AskBuilder';
+    }
+}
+/** Narrow an unknown query object to an ask. */
+export function isAskQuery(query) {
+    return (!!query && query.__queryKind === 'ask');
+}
+//# sourceMappingURL=AskBuilder.js.map

package/lib/esm/queries/AskBuilder.js.map

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

package/lib/esm/queries/AskQuery.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The ask query — "does any solution exist?", answered with a boolean.
+ *
+ * An ask carries a **pattern and nothing else**: no projection, no sorting, no
+ * pagination. Those shape or window a *solution sequence*, and an ask has no
+ * solution sequence to shape — so rather than being ignored or guarded against,
+ * they are simply not expressible here.
+ *
+ * `.exists()` is the first question asked this way; it is a shortcut for the
+ * general form, not a special case of select.
+ */
+import type { NodeShapeData } from '../shapes/SHACL.js';
+import type { WherePath } from './SelectQuery.js';
+import type { RawMinusEntry } from './IRDesugar.js';
+import type { NodeReferenceValue } from './QueryFactory.js';
+import type { PendingQueryContext } from './QueryContext.js';
+import type { ContextRefJSON } from './ContextRef.js';
+import type { WherePathJSON, RawMinusEntryJSON } from './QueryBuilderSerialization.js';
+/**
+ * The live, closed (read-only) ask query — the object an `IDataset` receives.
+ *
+ * `shape` is **optional**. Absent means no `rdf:type` constraint at all: "does a
+ * node with this IRI exist", independent of any shape. A dataset reads
+ * `toJSON()` to forward the query, or `lower()` to get canonical IR.
+ */
+export interface AskQuery {
+    readonly __queryKind: 'ask';
+    /** The shape whose instances are asked about; absent for a shapeless ask. */
+    readonly shape?: NodeShapeData;
+    toJSON(): AskQueryJSON;
+    toRawInput(): RawAskInput;
+}
+/** Pre-lowering input, as the builder hands it to `lower()`. */
+export type RawAskInput = {
+    /** `.for(null)` — no subject to ask about. Lowering rejects it; see `lowerAsk`. */
+    nullSubject?: boolean;
+    shape?: {
+        shape?: {
+            id?: string;
+        };
+        id?: string;
+    };
+    subject?: NodeReferenceValue | PendingQueryContext;
+    subjects?: NodeReferenceValue[];
+    where?: WherePath;
+    minusEntries?: RawMinusEntry[];
+};
+/**
+ * The DSL-JSON wire form of an ask query.
+ *
+ * Carries `op: 'ask'` — the same discriminator mutation envelopes use, so
+ * `fromJSON` routes on it and an older peer rejects an unknown op loudly rather
+ * than reinterpreting the envelope as a select.
+ *
+ * Every field is pattern-bearing. There is deliberately no `fields`, `limit`,
+ * `offset`, `sortBy` or `one`: a receiver has nothing to validate or ignore.
+ *
+ * ```json
+ * {"v": "1.1", "op": "ask",
+ *  "shape": "https://linked.cm/shape/core/Person",
+ *  "subject": "linked://tmp/entities/p1"}
+ *
+ * {"v": "1.1", "op": "ask", "subject": "https://example.org/thing"}
+ * ```
+ *
+ * The second has no `shape` — that absence *is* the shapeless discriminator.
+ */
+export type AskQueryJSON = {
+    v?: string;
+    op: 'ask';
+    /** Omitted for a shapeless ask (no `rdf:type` constraint). */
+    shape?: string;
+    /** A node id, or a `{@ctx: name}` reference resolved at lowering. */
+    subject?: string | ContextRefJSON;
+    subjects?: string[];
+    where?: WherePathJSON;
+    minusEntries?: RawMinusEntryJSON[];
+    /** `.for(null)` — no subject to ask about; the answer is `false` without querying. */
+    nullSubject?: boolean;
+};

package/lib/esm/queries/AskQuery.js

@@ -0,0 +1,7 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+export {};
+//# sourceMappingURL=AskQuery.js.map

package/lib/esm/queries/AskQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AskQuery.js","sourceRoot":"","sources":["../../../src/queries/AskQuery.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/lib/esm/queries/IntermediateRepresentation.d.ts

@@ -3,7 +3,7 @@ import type { PathExpr } from '../paths/PropertyPathExpr.js';
 export type IRDirection = 'ASC' | 'DESC';
 export type IRAlias = string;
 export type IRValue = string | number | boolean | null;
-export type IRQuery = IRSelectQuery | IRCreateMutation | IRUpdateMutation | IRDeleteMutation | IRDeleteAllMutation | IRDeleteWhereMutation | IRUpdateWhereMutation;
+export type IRQuery = IRSelectQuery | IRAskQuery | IRCreateMutation | IRUpdateMutation | IRDeleteMutation | IRDeleteAllMutation | IRDeleteWhereMutation | IRUpdateWhereMutation;
 export type IRSelectQuery = {
     kind: 'select';
     root: IRShapeScanPattern;
@@ -18,6 +18,27 @@ export type IRSelectQuery = {
     singleResult?: boolean;
     resultMap?: IRResultMapEntry[];
 };
+/**
+ * A query whose answer is a boolean.
+ *
+ * Carries a pattern and nothing else. There is no `projection`, `orderBy`,
+ * `limit` or `offset`: each of those shapes or windows a *solution sequence*, and
+ * an ask has none — so rather than being ignored during conversion, or guarded
+ * against, they are unrepresentable.
+ *
+ * `root` is **optional**. Absent means no `rdf:type` constraint at all — "does a
+ * node with this IRI exist", under any shape or none — which lowers to
+ * `ASK { <iri> ?p ?o }`. A rootless ask carries no `patterns` or `where`, since
+ * both reference properties and a property is only resolvable through a shape.
+ */
+export type IRAskQuery = {
+    kind: 'ask';
+    root?: IRShapeScanPattern;
+    patterns: IRGraphPattern[];
+    where?: IRExpression;
+    subjectId?: string;
+    subjectIds?: string[];
+};
 export type IRProjectionItem = {
     alias: IRAlias;
     expression: IRExpression;

package/lib/esm/queries/QueryBuilder.d.ts

@@ -127,26 +127,26 @@ export declare class SelectBuilder<S extends Shape = Shape, R = any, Result = an
      * **Kept** — filters, `minus` entries and the subject: those decide whether a match
      * exists. `LIMIT 1` is then applied.
      *
-     * So `.select(…).orderBy(…).offset(10).exists()` costs, and answers, exactly the same
-     * as a bare `.exists()`:
+     * So `.select(…).orderBy(…).offset(10).exists()` costs, and answers, exactly the
+     * same as a bare `.exists()`. Against a SPARQL store that goes out as:
      *
      * ```sparql
-     * SELECT DISTINCT ?a0 WHERE { ?a0 rdf:type <…> . FILTER(?a0 = <…>) } LIMIT 1
+     * ASK WHERE { ?a0 rdf:type <…> . FILTER(?a0 = <…>) }
      * ```
      *
-     * Pagination is dropped rather than honoured on purpose. `OFFSET` skips rows of the
-     * *solution sequence*, whose cardinality depends on the projection — a multi-valued
-     * projected property yields several rows per subject. Keeping `offset` while dropping
-     * the projection would let the same chain answer `true` before normalisation and
-     * `false` after. `exists()` therefore answers a question about the **match set**,
-     * not about a page of it.
+     * Pagination does not survive, and cannot: `OFFSET` skips rows of a *solution
+     * sequence*, and an ask has none. (Nor is it merely dropped — an
+     * {@link AskBuilder} has nowhere to hold it.) `exists()` answers a question about
+     * the **match set**, not about a page of it.
      *
      * ### Errors are not swallowed
      *
      * A store, transport or lowering failure rejects the returned promise; it is never
      * reported as `false`. That includes an unresolved query-context reference in a
      * where clause, which `exec()` deliberately reports as `null` ("not ready") but
-     * which `exists()` must not flatten into a boolean.
+     * which `exists()` must not flatten into a boolean — and a store whose `askQuery`
+     * resolves to something that is not a boolean, which rejects rather than being
+     * coerced into one.
      *
      * The one case that does resolve `false` without querying is a query with **no
      * subject to ask about** — `.for(null)`, `.for(undefined)`, or an unresolved
@@ -156,6 +156,16 @@ export declare class SelectBuilder<S extends Shape = Shape, R = any, Result = an
      * @param target Optional explicit dataset, as for {@link exec}.
      */
     exists(target?: IDataset): Promise<boolean>;
+    /**
+     * Reduce this select to the ask query that answers the same existence question.
+     *
+     * Only the pattern survives — shape, subject(s), filters, `minus`. The
+     * projection, preloads, sorting and pagination are not "dropped" so much as
+     * unrepresentable: {@link AskBuilder} has nowhere to put them. That is the point
+     * of it being a separate builder rather than a mode of this one — the
+     * normalisation cannot be forgotten or half-applied.
+     */
+    private _toAsk;
     /**
      * Preload a component's query fields at the given property path.
      *