@metreeca/keep 0.10.0 → 0.11.0

package/dist/index.d.ts

@@ -1,28 +1,26 @@
 import type { ResourceShape } from "@metreeca/blue/resource";
-import type { Lazy } from "@metreeca/core";
+import type { Draft, Match, Model, Slice } from "@metreeca/blue/value";
+import type { Lazy, Optional } from "@metreeca/core";
+import type { Some } from "@metreeca/core/arrays";
+import type { Awaitable } from "@metreeca/core/async";
 import type { Tag } from "@metreeca/core/language";
-import { type Reference, Resource } from "@metreeca/qest/resource";
-import { Instance, Template } from "@metreeca/qest/template";
+import { type Reference } from "@metreeca/qest/state";
 /**
  * Model-driven resource store.
  *
- * Extends {@link StoreClient} with management facilities — mutation events, transactional execution, and lifecycle —
- * to form the store surface produced by factories like
- * {@link createManagingStore}. The data surface is factored into a standalone
- * {@link StoreClient} so it can be implemented and passed around on its own (for example, the inner client handed to
- * {@link Store.execute execute} carries no `execute` of its own), while consumers of a store reach both
- * surfaces through the same object.
+ * Extends {@link StoreClient} with management facilities: mutation events, transactional execution, and lifecycle.
+ * This is the store surface returned by connector factories and by wrappers like {@link createManagingStore}. The data
+ * surface stays a standalone {@link StoreClient}, so it can be implemented and passed around on its own: for example,
+ * the client handed to an {@link Store.execute execute} task carries no `execute` of its own.
  *
- * Data methods on a store — {@link StoreClient.lookup lookup}, {@link StoreClient.create create},
- * {@link StoreClient.update update}, {@link StoreClient.delete delete}, {@link StoreClient.insert insert}, and
- * {@link StoreClient.remove remove} — are individually atomic even when executed outside
- * {@link Store.execute execute}, regardless of the number of server round-trips they may internally require.
+ * Every data method on a store is individually atomic, even when called outside {@link Store.execute execute} and
+ * regardless of the number of server round-trips it may require.
  *
  * > [!IMPORTANT]
- * > Implementations provide best-effort transaction isolation, targeting snapshot isolation where the backend
- * > supports it and degrading gracefully to the maximum level achievable by the underlying storage, down to no
- * > isolation at all. Each implementation **must** document its supported isolation level. Implementations not
- * > supporting atomic updates natively **must** emulate them by buffering and deferring mutations until commit time.
+ * > Implementations provide best-effort transaction atomicity and isolation, targeting all-or-nothing commit and
+ * > snapshot isolation where the backend supports them and degrading gracefully to the maximum level achievable by
+ * > the underlying storage, down to eagerly applied mutations with no rollback and no isolation at all. Each
+ * > implementation **must** document its supported isolation level and whether a failing transaction rolls back.
  *
  * > [!IMPORTANT]
  * > Implementations provide best-effort mutation event signalling, targeting notification for all mutations on the
@@ -33,77 +31,83 @@ export interface Store extends StoreClient {
     /**
      * Observe mutation events.
      *
-     * Each call mints an independent registration; multiple registrations of the same observer coexist and
-     * fire independently — the observer is invoked once per matching registration per mutation batch. The
-     * returned handle detaches **only** that registration; calling it more than once is a no-op and other
-     * registrations of the same observer are unaffected. Detachment is the only supported way to stop
-     * receiving events — repeated `observe` calls do not replace any prior registration.
+     * Each call creates an independent registration. Multiple registrations of the same observer coexist and fire
+     * independently: the observer is invoked once per matching registration for each mutation batch. The returned
+     * handle detaches **only** its own registration. Calling it more than once is a no-op, and other registrations of
+     * the same observer are unaffected. Detaching is the only way to stop receiving events: a repeated `observe` call
+     * never replaces an earlier registration.
      *
      * `resources` is the filter for the registration:
      *
      * - `undefined` (omitted) — no filter; the observer fires for every mutation
      * - a single {@link Reference} — fires for mutations to that resource and its
      *   {@link @metreeca/core!isNestedIRI | descendants}
-     * - an array of references — fires for mutations matching any element and its descendants
-     * - an empty array — ignored; no registration is created and the returned handle is a no-op
+     * - a collection of references — an array, a set, an iterator, or any other iterable; fires for mutations
+     *   matching any element and its descendants
+     * - an empty collection — ignored; no registration is created and the returned handle is a no-op
+     *
+     * The filter is read once, when the registration is created. Single-pass iterables are safe to pass, and later
+     * changes to the collection leave the registration untouched.
      *
      * > [!NOTE]
-     * > The observer receives only resource identifiers and an existence flag — not the mutated state.
-     * > This keeps event payloads small even when many resources are mutated within a single transaction,
-     * > and lets each observer fetch whatever data envelope it needs via {@link StoreClient.lookup lookup}.
+     * > The observer receives only resource identifiers and an existence flag, not the mutated state. Event payloads
+     * > stay small even when a single transaction mutates many resources, and each observer can fetch the data it
+     * > needs with {@link StoreClient.lookup lookup}.
      *
      * @param observer - Mutation observer invoked with each batch of matching mutations
-     * @param resources - Filter (single reference, array of references, or omitted for no filter)
+     * @param resources - Filter (a single reference, a collection of references, or omitted for no filter)
      *
      * @returns A function that detaches **this** registration
      *
-     * @throws `Error` if the store has been {@link Store.close closed}
+     * @throws {@link !Error Error} if the store has been {@link Store.close closed}
      */
-    observe(observer: StoreObserver, resources?: Reference | readonly Reference[]): () => void;
+    observe(observer: StoreObserver, resources?: Some<Reference>): () => void;
     /**
      * Execute a task within a store transaction.
      *
-     * All operations performed during the task are executed atomically. If the task completes successfully, all
+     * All operations performed by the task form a single unit of work. If the task completes successfully, all
      * mutations are committed and {@link Store.observe registered observers} receive a single mutation event
-     * containing all affected resources. If the task throws or rejects — including logic errors (`RangeError`,
-     * {@link TraceError}) raised by inner {@link StoreClient} calls — no mutations are executed, no events are
-     * notified, and the error is propagated to the caller as a promise rejection.
+     * listing all affected resources. If the task throws or rejects, no events are notified and, where the
+     * implementation provides atomicity, no mutations are committed. This includes logic errors
+     * ({@link !RangeError RangeError}, {@link TraceError}) raised by inner {@link StoreClient} calls. The error is
+     * propagated to the caller as a promise rejection.
      *
-     * The task is handled its own {@link StoreClient} for the transaction. Operations performed through it belong to
-     * the transaction and commit together, kept separate from any other `execute` running at the same time.
+     * The task receives its own {@link StoreClient} for the transaction. Operations performed through it belong to
+     * the transaction, separately from any other `execute` running at the same time.
      *
      * > [!WARNING]
-     * > `execute` is not re-entrant: transaction boundaries are flat, so a task cannot open a nested transaction
-     * > and compositions must share a single outer call site.
+     * > `execute` is not re-entrant. Transaction boundaries are flat: a task cannot open a nested transaction, and
+     * > composed operations must share a single outer call.
      *
      * > [!WARNING]
-     * > The task MUST NOT retain or use the {@link StoreClient} it receives after `execute` settles: implementations
-     * > may back it with transaction-scoped state (buffered mutations, a bound backend scope) that is flushed or
-     * > discarded on completion, so any later call has undefined behaviour.
+     * > The task MUST NOT retain or use the {@link StoreClient} it receives after `execute` settles. Implementations
+     * > may back it with transaction-scoped state, such as buffered mutations or a bound backend scope, that is
+     * > flushed or discarded on completion, so any later call has undefined behaviour.
      *
      * > [!WARNING]
-     * > **Atomicity is mandatory; isolation is best-effort.** The task's mutations and their events always commit
-     * > all-or-nothing. `SNAPSHOT` is the suggested read-isolation level; each implementation declares the level it
-     * > actually provides. An implementation with neither native transactions nor `SNAPSHOT` isolation MUST buffer
-     * > the mutations and events, commit them as one batch on success, and drop the buffer on failure (a synchronous
-     * > throw or a rejected promise).
+     * > **Atomicity and isolation are best-effort.** Implementations target all-or-nothing commit of the task's
+     * > mutations and `SNAPSHOT` read isolation; each implementation declares what it actually provides. An
+     * > implementation with no native transactions SHOULD emulate atomicity by buffering the mutations, committing
+     * > them as one batch on success and dropping the buffer on failure (a synchronous throw or a rejected promise).
+     * > Where the backend makes that infeasible, mutations apply eagerly, and a failing task may leave earlier
+     * > mutations in place, with no event notified for them.
      *
      * @typeParam V - Return type of the task
      *
      * @param task - Async or sync function performing store operations within the transaction
      *
      * @returns A promise resolving to the value returned by `task`; rejects with any error raised or
-     * propagated by `task`, including a `RangeError`/{@link TraceError} from inner Store validation or a
+     * propagated by `task`, including a {@link !RangeError RangeError} or {@link TraceError} from inner validation or a
      * {@link Problem} from a transactional, network, storage, or other processing failure
      *
-     * @throws `Error` if the store has been {@link Store.close closed}
+     * @throws {@link !Error Error} if the store has been {@link Store.close closed}
      */
-    execute<V>(task: (store: StoreClient) => V | Promise<V>): Promise<V>;
+    execute<V>(task: (store: StoreClient) => Awaitable<V>): Promise<V>;
     /**
      * Release resources held by this store.
      *
      * Frees underlying resources such as database connections or file handles. Calling `close` on an
-     * already-closed store has no effect; implementations with no resources to release MAY return a
+     * already-closed store has no effect. Implementations with no resources to release MAY return a
      * resolved no-op.
      *
      * @returns A promise resolving when all resources have been released; rejects with a {@link Problem} if a
@@ -114,94 +118,86 @@ export interface Store extends StoreClient {
 /**
  * Model-driven resource CRUD operations.
  *
- * Persists and retrieves linked data resources as shape-validated states and query projections.
+ * Persists and retrieves linked data resources as shape-validated states and query projections. This is the data
+ * surface a connector implements against its backend, and the client a {@link Store.execute execute} task works
+ * through.
  */
 export interface StoreClient {
     /**
-     * Retrieve a resource.
+     * Look up a resource.
+     *
+     * Retrieves the resource identified by `entry`. The result holds only the members named by the `model`
+     * {@link Template}, and expands the linked resources the template reaches. Values are typed after the `shape`:
+     * the template states which members are wanted, not what they are.
      *
-     * The result is shaped by the `model` {@link Template}: plain identifier properties are resolved from the
-     * shape's {@link Instance}\<T\> type, while computed bindings are derived from the template value.
+     * Multi-valued members are retrieved as collections. Filtering, ordering and pagination constraints are stated
+     * under the member name, next to its retrieval keys. A {@link Projection} stated there in place of a template
+     * returns rows of computed values, keyed by the names of its bindings. A collection with no matching item is
+     * omitted from the result, like any other member without a value.
      *
      * > [!NOTE]
-     * > `shape` and `model` are kept distinct so that a single `shape` can serve many retrieval templates —
-     * > for example, a server wiring one `shape` at startup and accepting any admissible `model` decoded
-     * > from the client request on each call. Callers wanting the shape's own model as template MUST pass
-     * > it explicitly via {@link @metreeca/blue/value!model}.
+     * > `shape` and `model` are kept distinct so that a single `shape` can serve many retrieval templates. For
+     * > example, a server may wire one `shape` at startup and accept any admissible `model` decoded from each client
+     * > request. A template retrieving every member the shape declares MUST be written out explicitly.
      *
      * > [!CAUTION]
      * > By default, `model` templates support the full query language, including aggregate transforms and nested
-     * > expansion. When exposing retrieval to untrusted clients, restrict query complexity as required by setting
-     * > `plain` to `true`, `depth` to `0` or a positive value, and/or `limit` to a maximum result set size.
-     *
-     * @typeParam T - The retrieval template type
-     *
-     * @param request - Retrieval specifications
-     * @param request.entry - Absolute identifier of the resource to be retrieved
-     * @param request.shape - Resource shape driving the operation
-     * @param request.model - Retrieval template defining the data envelope
-     * @param opts - Optional retrieval options
-     * @param opts.locale - {@link Tag} priority list driving language negotiation for localised content; entries are
-     * matched in order of preference against the language tags available for each localised value. Implementations
-     * default this to `["und"]` when omitted
-     * @param opts.plain - When `true`, rejects `model` templates carrying aggregate transforms (`count`, `sum`, `min`,
-     * `max`, `avg`); defaults to `false`, admitting the full query language
-     * @param opts.depth - Maximum depth admitted for nested `model` expansion and query probe paths, each nesting
-     * level or path segment counting against the budget; `0` rejects any nested template while still accepting IRI
-     * references; omission leaves expansion unbounded
-     * @param opts.limit - Maximum value admitted for the `#` pagination constraint in `model` selections; a positive
-     * value caps the result set, rejecting any `#` exceeding it or set to `0` (unbounded) and injecting itself as a
-     * default where `#` is absent; omission, like `0`, leaves result sets unbounded
-     *
-     * @returns A promise resolving to an immutable copy of the resource data matching the specified model,
-     * or to `undefined` if the resource is not present in the store; rejects with a `RangeError` if `entry`
-     * is not an absolute IRI, a {@link TraceError} if `model` doesn't {@link validate} against the shape,
+     * > expansion. When exposing retrieval to untrusted clients, restrict query complexity through the
+     * > {@link StoreScope | scope}: set `plain` to `true`, `depth` to `0` or a positive value, and/or `limit` to a
+     * > maximum result set size.
+     *
+     * @typeParam S - The shape driving the retrieval
+     * @typeParam T - The retrieval template, naming only members the shape carries
+     *
+     * @param request - The resource to retrieve, the shape describing it and the template narrowing it
+     * @param scope - The {@link StoreScope | retrieval scope}, bounding `model` and setting the locale priority
+     *
+     * @returns A promise resolving to an immutable copy of the resource data narrowed to the members `model` names,
+     * or to `undefined` if the resource is not present in the store; rejects with a {@link !RangeError RangeError} if
+     * `entry` is not an absolute IRI, a {@link TraceError} if `model` doesn't {@link validate} against the shape,
      * or a {@link Problem} on network, storage, or other processing errors
      *
-     * @throws `Error` if the store has been {@link Store.close closed}
+     * @throws {@link !Error Error} if the store has been {@link Store.close closed}
      */
-    lookup<T extends Template>(request: {
-        readonly entry: Reference;
-        readonly shape: Lazy<ResourceShape>;
-        readonly model: T;
-    }, opts?: {
-        locale?: readonly Tag[];
-        plain?: boolean;
-        depth?: number;
-        limit?: number;
-    }): Promise<undefined | Instance<T>>;
+    lookup<S extends Lazy<ResourceShape>, T extends Model<S, T>>(request: StoreLookup<S, T>, scope?: StoreScope): Promise<Optional<Match<S, T>>>;
     /**
      * Create a resource.
      *
-     * Stores the resource's own data if the resource doesn't already exist. Specific reference kinds are handled
-     * as follows:
+     * Adds a new resource to a collection held by the resource identified by `entry`. The collecting property is the
+     * single multi-valued property named by `model`, and the new resource is stored as described by the shape that
+     * property ranges over. Nothing is created if a resource already exists under the identifier of the new one.
+     *
+     * The new resource is identified by the `id` of its `state`, which must be nested under `entry`. If `id` is left
+     * out, the store mints one under `entry`, following the identifier {@link ResourceShape.pattern | pattern} declared
+     * by the collected shape, if any. Each `{name}` slot is filled with the like-named member of `state`, which must
+     * be a single path segment. Any other slot is filled with an opaque segment. A remote store may leave the choice
+     * of identifier to the service holding the collection.
+     *
+     * Specific reference kinds are handled as follows:
      *
      * - {@link ResourceShape | embedded references} — cascades recursively with the same semantics
-     * - {@link @metreeca/blue/reference!ReferenceConstraints.captive | captive references} — accepted only as bare
-     * IRI references; inline captive batches are rejected, as `state` is always validated at depth `0`. Use
-     * {@link StoreClient.insert insert} to embed a captive tree in a single batch
-     * - {@link @metreeca/blue/reference!ReferenceConstraints.foreign | foreign references} — skipped, as their
+     * - {@link @metreeca/blue/resource!PropertyConstraints.captive | captive references} — accepted only as bare
+     * IRI references; inline captive batches are rejected, as `state` is always validated at depth `0`
+     * - {@link @metreeca/blue/resource!PropertyConstraints.foreign | foreign references} — skipped, as their
      * data is owned by the defining resource
      *
-     * @param request - Creation specifications
-     * @param request.entry - Absolute identifier of the target resource
-     * @param request.shape - Resource shape driving the operation
-     * @param request.state - Initial property values for the new resource
+     * @typeParam S - The shape driving the creation, describing the collecting resource
+     * @typeParam T - The collection slice, naming the collecting property
      *
-     * @returns A promise resolving to the `entry` {@link Reference} of the created resource, or to `undefined`
-     * if the resource already exists; rejects with a `RangeError` if `entry` is not an absolute IRI or if
-     * `state` carries an `id` differing from `entry`, a {@link TraceError} if `state` doesn't {@link validate}
+     * @param request - The resource collecting the new one, the shape describing it, the slice naming the collecting
+     * property and the initial state of the new resource
+     *
+     * @returns A promise resolving to the {@link Reference} identifying the created resource, or to `undefined`
+     * if a resource already exists under that identifier; rejects with a {@link !RangeError RangeError} if `entry` is
+     * not an absolute IRI, if `state` carries an `id` not nested under `entry` or if a member filling an identifier
+     * slot is not a single path segment, a {@link TraceError} if `model` or `state` doesn't {@link validate}
      * against the shape, or a {@link Problem} on network, storage, or other processing errors
      *
-     * @throws `Error` if the store has been {@link Store.close closed}
+     * @throws {@link !Error Error} if the store has been {@link Store.close closed}
      *
-     * @see {@link StoreClient.insert insert} for unconditional insertion
+     * @see {@link StoreClient.insert insert} for unconditional insertion under a known identifier
      */
-    create(request: {
-        readonly entry: Reference;
-        readonly shape: Lazy<ResourceShape>;
-        readonly state: Resource;
-    }): Promise<undefined | Reference>;
+    create<S extends Lazy<ResourceShape>, T extends Slice<S, T>>(request: StoreCreate<S, T>): Promise<Optional<Reference>>;
     /**
      * Update a resource.
      *
@@ -209,31 +205,25 @@ export interface StoreClient {
      * embedded data. Specific reference kinds are handled as follows:
      *
      * - {@link ResourceShape | embedded references} — cascades recursively with the same semantics
-     * - {@link @metreeca/blue/reference!ReferenceConstraints.captive | captive references} — accepted only as bare
-     * IRI references; inline captive batches are rejected, as `state` is always validated at depth `0`. Use
-     * {@link StoreClient.insert insert} to embed a captive tree in a single batch
-     * - {@link @metreeca/blue/reference!ReferenceConstraints.foreign | foreign references} — skipped, as their
+     * - {@link @metreeca/blue/resource!PropertyConstraints.captive | captive references} — accepted only as bare
+     * IRI references; inline captive batches are rejected, as `state` is always validated at depth `0`
+     * - {@link @metreeca/blue/resource!PropertyConstraints.foreign | foreign references} — skipped, as their
      * data is owned by the defining resource
      *
-     * @param request - Update specifications
-     * @param request.entry - Absolute identifier of the target resource
-     * @param request.shape - Resource shape driving the operation
-     * @param request.state - Complete replacement state for the resource
+     * @typeParam S - The shape driving the update, describing the state
+     *
+     * @param request - The resource to update, the shape validating it and its replacement state
      *
      * @returns A promise resolving to the `entry` {@link Reference} of the updated resource, or to `undefined`
-     * if the resource doesn't exist; rejects with a `RangeError` if `entry` is not an absolute IRI or if
-     * `state` carries an `id` differing from `entry`, a {@link TraceError} if `state` doesn't {@link validate}
+     * if the resource doesn't exist; rejects with a {@link !RangeError RangeError} if `entry` is not an absolute IRI
+     * or if `state` carries an `id` differing from `entry`, a {@link TraceError} if `state` doesn't {@link validate}
      * against the shape, or a {@link Problem} on network, storage, or other processing errors
      *
-     * @throws `Error` if the store has been {@link Store.close closed}
+     * @throws {@link !Error Error} if the store has been {@link Store.close closed}
      *
      * @see {@link StoreClient.insert insert} for unconditional insertion
      */
-    update(request: {
-        readonly entry: Reference;
-        readonly shape: Lazy<ResourceShape>;
-        readonly state: Resource;
-    }): Promise<undefined | Reference>;
+    update<S extends Lazy<ResourceShape>>(request: StoreUpdate<S>): Promise<Optional<Reference>>;
     /**
      * Delete a resource.
      *
@@ -241,25 +231,22 @@ export interface StoreClient {
      * Specific reference kinds are handled as follows:
      *
      * - {@link ResourceShape | embedded references} — cascades recursively with the same semantics
-     * - {@link @metreeca/blue/reference!ReferenceConstraints.captive | captive references} — cascade-deleted with
+     * - {@link @metreeca/blue/resource!PropertyConstraints.captive | captive references} — cascade-deleted with
      * the same semantics
      *
-     * @param request - Deletion specifications
-     * @param request.entry - Absolute identifier of the target resource
-     * @param request.shape - Resource shape driving the operation
+     * @typeParam S - The shape driving the deletion, identifying the data cascaded with the resource
+     *
+     * @param request - The resource to delete and the shape identifying the data cascade-deleted with it
      *
      * @returns A promise resolving to the `entry` {@link Reference} of the deleted resource, or to `undefined`
-     * if the resource doesn't exist; rejects with a `RangeError` if `entry` is not an absolute IRI, or a
-     * {@link Problem} on network, storage, or other processing errors
+     * if the resource doesn't exist; rejects with a {@link !RangeError RangeError} if `entry` is not an absolute IRI,
+     * or a {@link Problem} on network, storage, or other processing errors
      *
-     * @throws `Error` if the store has been {@link Store.close closed}
+     * @throws {@link !Error Error} if the store has been {@link Store.close closed}
      *
      * @see {@link StoreClient.remove remove} for unconditional removal
      */
-    delete(request: {
-        readonly entry: Reference;
-        readonly shape: Lazy<ResourceShape>;
-    }): Promise<undefined | Reference>;
+    delete<S extends Lazy<ResourceShape>>(request: StoreDelete<S>): Promise<Optional<Reference>>;
     /**
      * Insert a resource.
      *
@@ -267,42 +254,26 @@ export interface StoreClient {
      * data. Specific reference kinds are handled as follows:
      *
      * - {@link ResourceShape | embedded references} — cascades recursively with the same semantics
-     * - {@link @metreeca/blue/reference!ReferenceConstraints.captive | captive references} — accepted as bare IRI
-     * references or, up to `opts.depth` nesting levels, as inline batches creating or updating the captive tree
-     * - {@link @metreeca/blue/reference!ReferenceConstraints.foreign | foreign references} — skipped, as their
+     * - {@link @metreeca/blue/resource!PropertyConstraints.captive | captive references} — accepted only as bare
+     * IRI references; inline captive batches are rejected, as `state` is always validated at depth `0`
+     * - {@link @metreeca/blue/resource!PropertyConstraints.foreign | foreign references} — skipped, as their
      * data is owned by the defining resource
      *
-     * > [!CAUTION]
-     * > By default, resources accept captive reference expansion to unbounded depth. To enforce a strict insertion
-     * > process that admits only bare references, set `opts.depth` to `0` to reject all expansion; set it to a positive
-     * > value to cap the nesting depth admitted.
-     *
-     * @param request - Insertion specifications
-     * @param request.entry - Absolute identifier of the target resource
-     * @param request.shape - Resource shape driving the operation
-     * @param request.state - Complete resource state to be inserted
-     * @param opts - Optional insertion options
-     * @param opts.depth - Maximum nesting depth for expanding `captive` reference values as inline target resource
-     * states, each expansion level counting against the budget; `0` rejects all expansion, accepting bare IRI
-     * references only; omission leaves expansion unbounded
+     * @typeParam S - The shape driving the insertion, describing the state
+     *
+     * @param request - The resource to insert, the shape validating it and its state
      *
      * @returns A promise resolving to the `entry` {@link Reference} of the inserted resource; rejects with a
-     * `RangeError` if `entry` is not an absolute IRI or if `state` carries an `id` differing from `entry`, a
-     * {@link TraceError} if `state` doesn't {@link validate} against the shape, or a {@link Problem} on
+     * {@link !RangeError RangeError} if `entry` is not an absolute IRI or if `state` carries an `id` differing from
+     * `entry`, a {@link TraceError} if `state` doesn't {@link validate} against the shape, or a {@link Problem} on
      * network, storage, or other processing errors
      *
-     * @throws `Error` if the store has been {@link Store.close closed}
+     * @throws {@link !Error Error} if the store has been {@link Store.close closed}
      *
      * @see {@link StoreClient.create create} for conditional creation
      * @see {@link StoreClient.update update} for conditional replacement
      */
-    insert(request: {
-        readonly entry: Reference;
-        readonly shape: Lazy<ResourceShape>;
-        readonly state: Resource;
-    }, opts?: {
-        readonly depth?: number;
-    }): Promise<Reference>;
+    insert<S extends Lazy<ResourceShape>>(request: StoreUpdate<S>): Promise<Reference>;
     /**
      * Remove a resource.
      *
@@ -310,26 +281,65 @@ export interface StoreClient {
      * reference kinds are handled as follows:
      *
      * - {@link ResourceShape | embedded references} — cascades recursively with the same semantics
-     * - {@link @metreeca/blue/reference!ReferenceConstraints.captive | captive references} — cascade-removed with
+     * - {@link @metreeca/blue/resource!PropertyConstraints.captive | captive references} — cascade-removed with
      * the same semantics
      *
-     * @param request - Removal specifications
-     * @param request.entry - Absolute identifier of the target resource
-     * @param request.shape - Resource shape driving the operation
+     * @typeParam S - The shape driving the removal, identifying the data cascaded with the resource
+     *
+     * @param request - The resource to remove and the shape identifying the data cascade-removed with it
      *
      * @returns A promise resolving to the `entry` {@link Reference} of the removed resource; rejects with a
-     * `RangeError` if `entry` is not an absolute IRI, or a {@link Problem} on network, storage, or other
-     * processing errors
+     * {@link !RangeError RangeError} if `entry` is not an absolute IRI, or a {@link Problem} on network, storage, or
+     * other processing errors
      *
-     * @throws `Error` if the store has been {@link Store.close closed}
+     * @throws {@link !Error Error} if the store has been {@link Store.close closed}
      *
      * @see {@link StoreClient.delete delete} for conditional removal
      */
-    remove(request: {
-        readonly entry: Reference;
-        readonly shape: Lazy<ResourceShape>;
-    }): Promise<Reference>;
+    remove<S extends Lazy<ResourceShape>>(request: StoreDelete<S>): Promise<Reference>;
 }
+/**
+ * Store retrieval scope.
+ *
+ * Bounds the aggregates, nesting depth and page size a {@link StoreClient.lookup lookup} admits in its `model`, and
+ * sets the locale priority for its localised content. Every member is optional. An empty scope admits any `model`
+ * the shape validates, and resolves localised content against the undetermined `und` tag alone.
+ */
+export type StoreScope = {
+    /**
+     * {@link Tag} priority list driving language negotiation for localised content.
+     *
+     * Entries are matched in order of preference against the language tags available for each localised value.
+     *
+     * @defaultValue `["und"]`
+     */
+    locale?: readonly Tag[];
+    /**
+     * Whether to reject `model` templates carrying aggregate transforms (`count`, `sum`, `min`, `max`, `avg`),
+     * admitting retrieval but not computation.
+     *
+     * @defaultValue `false`, admitting the full query language
+     */
+    plain?: boolean;
+    /**
+     * Maximum nesting admitted for `model` expansion and query probe paths.
+     *
+     * Each nested resource or path segment counts against the budget. `0` rejects any nested template, but still
+     * admits IRI references.
+     *
+     * @defaultValue Unbounded
+     */
+    depth?: number;
+    /**
+     * Maximum page size admitted for the `#` pagination constraint on `model` collections.
+     *
+     * A positive value caps the result set. A `#` exceeding it, or set to `0` (unbounded), is rejected, and a
+     * collection with no `#` is held to it. `0` leaves result sets unbounded.
+     *
+     * @defaultValue `0`
+     */
+    limit?: number;
+};
 /**
  * Store mutation observer.
  *
@@ -353,6 +363,102 @@ export interface StoreObserver {
      */
     (mutations: {
         readonly [entry: Reference]: boolean;
-    }): void | Promise<void>;
+    }): Awaitable<void>;
 }
+/**
+ * Store lookup request.
+ *
+ * Names the resource to retrieve with {@link StoreClient.lookup lookup}, the shape describing it and the template
+ * narrowing the result.
+ *
+ * @typeParam S - The shape driving the retrieval
+ * @typeParam T - The retrieval template, naming only members the shape carries
+ */
+export type StoreLookup<S extends Lazy<ResourceShape>, T extends Model<S, T>> = {
+    /**
+     * Absolute identifier of the resource to be retrieved.
+     */
+    readonly entry: Reference;
+    /**
+     * Resource shape the retrieval is validated against, possibly deferred to break definition cycles.
+     */
+    readonly shape: S;
+    /**
+     * Retrieval template defining the data envelope of the result.
+     *
+     * The template names only members carried by `shape`, each in a form its range admits. Multi-valued members may
+     * also state filtering, ordering and pagination constraints, or a projection in place of a template.
+     */
+    readonly model: T;
+};
+/**
+ * Store creation request.
+ *
+ * Names the resource collecting a new one with {@link StoreClient.create create}, the property holding the
+ * collection and the initial state of the new resource.
+ *
+ * @typeParam S - The shape driving the creation, describing the collecting resource
+ * @typeParam T - The collection slice, naming the collecting property
+ */
+export type StoreCreate<S extends Lazy<ResourceShape>, T extends Slice<S, T>> = {
+    /**
+     * Absolute identifier of the resource collecting the new one.
+     */
+    readonly entry: Reference;
+    /**
+     * Resource shape the creation is validated against, describing the collecting resource, possibly deferred to
+     * break definition cycles.
+     */
+    readonly shape: S;
+    /**
+     * Collection slice naming the multi-valued property of `shape` that collects the new resource.
+     */
+    readonly model: T;
+    /**
+     * Initial state of the new resource; an explicit `id` must be nested under `entry`.
+     */
+    readonly state: Draft<S, T>;
+};
+/**
+ * Store update request.
+ *
+ * Names the resource to store with {@link StoreClient.update update} or {@link StoreClient.insert insert}, the shape
+ * describing it and the complete state replacing its current data.
+ *
+ * @typeParam S - The shape driving the persistence, describing the state
+ */
+export type StoreUpdate<S extends Lazy<ResourceShape>> = {
+    /**
+     * Absolute identifier of the resource to be persisted.
+     */
+    readonly entry: Reference;
+    /**
+     * Resource shape `state` is validated against, possibly deferred to break definition cycles.
+     */
+    readonly shape: S;
+    /**
+     * Complete state for the resource, as `shape` describes it, replacing any existing data; its `id`, if stated,
+     * must match `entry`.
+     */
+    readonly state: Draft<S>;
+};
+/**
+ * Store deletion request.
+ *
+ * Names the resource to discard with {@link StoreClient.delete delete} or {@link StoreClient.remove remove} and the
+ * shape identifying the data discarded with it.
+ *
+ * @typeParam S - The shape driving the deletion, identifying the data cascaded with the resource
+ */
+export type StoreDelete<S extends Lazy<ResourceShape>> = {
+    /**
+     * Absolute identifier of the resource to be discarded.
+     */
+    readonly entry: Reference;
+    /**
+     * Resource shape identifying the embedded and captive data discarded with the resource, possibly deferred to
+     * break definition cycles.
+     */
+    readonly shape: S;
+};
 //# sourceMappingURL=index.d.ts.map