@metreeca/keep 0.9.0 → 0.11.0

package/dist/clients/batching.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Batching store client.
+ *
+ * Lets a connector serve many concurrent store requests with few backend round-trips. Requests of the same kind are
+ * coalesced into a single batch, and the connector supplies one batch {@link Handler} per kind. The resulting
+ * {@link StoreClient} adds conditional CRUD semantics on top, so handlers apply each request unconditionally.
+ *
+ * Four request kinds partition the work, each with its own handler:
+ *
+ *  - **`detect`** — probes whether each {@link Detect} entry exists in the store
+ *  - **`detail`** — materialises each {@link Detail} resource against its `model`; multi-valued members reached
+ *    by the model may be handed to the `select` handler through {@link Broker.select}
+ *  - **`select`** — materialises each {@link Select} collection against its `query`; element resources reached
+ *    by the query may be handed to the `detail` handler through {@link Broker.detail}
+ *  - **`modify`** — creates, updates, or deletes each {@link Modify} target, or links it to a collection
+ *
+ * Retrieval is driven by the requested `model` and `query`, not by the stored graph. A `detail` handler issues a
+ * `select` for each multi-valued member its model reaches, and a `select` handler issues a `detail` for each element
+ * resource its query reaches. Each request thus descends exactly as deep as its `model` or `query` nests, however
+ * deep the underlying graph runs.
+ *
+ * > [!IMPORTANT]
+ * > Handlers run concurrently and exchange nested requests through the {@link Broker}. A handler must not assume any
+ * > ordering between handlers, and must await every nested request it issues before settling the request that
+ * > depends on it.
+ *
+ * @module
+ */
+import type { Property, ResourceShape } from "@metreeca/blue/resource";
+import { type Match } from "@metreeca/blue/value";
+import { type Lazy } from "@metreeca/core";
+import type { Tag } from "@metreeca/core/language";
+import type { Query, Slot, Template } from "@metreeca/qest/model";
+import type { Reference, Resource, Value } from "@metreeca/qest/state";
+import type { StoreClient } from "../index.js";
+/**
+ * Requests accepted by {@link Broker}.
+ */
+export type Request = Detect | Detail | Select | Modify;
+/**
+ * Result of running a {@link Request}, narrowed by request variant:
+ *
+ *  - a {@link Detect} resolves to a `boolean` existence flag
+ *  - a {@link Detail} resolves to the materialised resource, typed by its shape and model
+ *  - a {@link Select} resolves to the {@link Value | values} its collection holds, untyped since its shape is
+ *    carried as a value rather than as a type parameter
+ *  - a {@link Modify} resolves to its mutated entry's {@link Reference}
+ *
+ * @typeParam R The request whose result type is selected
+ */
+export type Response<R extends Request> = R extends Select ? readonly Value[] : R extends Detail<infer T, infer S> ? Match<S, T> : R extends Modify ? Reference : R extends Detect ? boolean : never;
+/**
+ * Resource existence request.
+ *
+ * Carries the `entry` to probe, and resolves to whether that entry exists in the store.
+ */
+export type Detect = {
+    readonly entry: Reference;
+};
+/**
+ * Resource retrieval request.
+ *
+ * Carries a single resource (`entry` of `shape`), the `model` to materialise it against, and the `locale` priority
+ * for coalescing its localised content (QEST §6.2). Resolves to the materialised resource.
+ *
+ * @typeParam T The resource model selecting the members of the result
+ * @typeParam S The shape describing the resource
+ */
+export type Detail<T extends Template = Template, S extends Lazy<ResourceShape> = Lazy<ResourceShape>> = {
+    readonly entry: Reference;
+    readonly shape: S;
+    readonly model: T;
+    readonly locale: readonly Tag[];
+};
+/**
+ * Collection retrieval request.
+ *
+ * Carries a single multi-valued property (`field` on `entry` of `shape`), the `query` describing its values, and the
+ * `locale` priority for coalescing its localised content (QEST §6.2). Resolves to the materialised collection: items
+ * for a template query, rows for a projection.
+ *
+ * @typeParam T The collection query selecting the form of the result
+ */
+export type Select<T extends Query<Slot> = Query<Slot>> = {
+    readonly entry: Reference;
+    readonly shape: Lazy<ResourceShape>;
+    readonly field: Property;
+    readonly query: T;
+    readonly locale: readonly Tag[];
+};
+/**
+ * Resource mutation request.
+ *
+ * Carries the `entry` to mutate (of `shape`) and the target `state` to persist. A present `state` creates or updates
+ * the entry, and an omitted `state` deletes it. A request carrying a `link` instead adds `item` to the collection
+ * held by `entry` under `property`, leaving the rest of the entry unchanged. Resolves to the {@link Reference} of the
+ * mutated entry.
+ */
+export type Modify = {
+    readonly entry: Reference;
+    readonly shape: Lazy<ResourceShape>;
+    readonly state?: Resource;
+    readonly link?: {
+        readonly property: Property;
+        readonly item: Reference;
+    };
+};
+/**
+ * Batch handler for a single request type.
+ *
+ * Supplied by the connector to {@link createBatchingStore}, one per request type. A handler receives every request of
+ * its type accumulated since the previous batch, together with a {@link Broker} for issuing nested requests. It
+ * settles each {@link Deferred} in the batch with its result or error. The returned promise must resolve only once
+ * every request in the batch has settled, including any nested requests issued through the broker.
+ *
+ * Batches are never empty, so handlers need not guard against an empty one.
+ *
+ * @typeParam R The request variant handled
+ */
+export type Handler<R extends Request> = {
+    (batch: readonly Deferred<R>[], broker: Broker): Promise<void>;
+};
+/**
+ * A queued request paired with its promise-resolution hooks.
+ *
+ * Each batch a {@link Handler} receives is an array of `Deferred` entries. For each entry, the handler reads the
+ * `request` and settles it, calling `resolve` with its result (typed by {@link Response | Response<R>}) or `reject`
+ * with an error.
+ *
+ * @typeParam R The queued request variant: a {@link Detect} probe, a {@link Detail} resource fetch,
+ *     a {@link Select} collection fetch, or a {@link Modify} mutation
+ */
+export type Deferred<R extends Request> = {
+    readonly request: R;
+    resolve(value: Response<R>): void;
+    reject(error: unknown): void;
+};
+/**
+ * Request-submission surface over the batching {@link Handler | handlers}.
+ *
+ * Routes each request (detection, detail, selection, modification) to the handler for its type. Each call queues the
+ * request for the next batch and returns a promise that settles with its result. Handlers receive a broker to hand
+ * nested work to a sibling handler.
+ */
+export type Broker = {
+    /**
+     * Enqueue a {@link Detect} request.
+     *
+     * @param request The entry to probe
+     *
+     * @returns A promise resolving to `true` when the request's entry exists in the store; `false`
+     * otherwise
+     */
+    detect(request: Detect): Promise<boolean>;
+    /**
+     * Enqueue a {@link Detail} request.
+     *
+     * Carries no existence precondition: an entry with no stored state resolves to an empty instance of
+     * the request's `model` rather than rejecting.
+     *
+     * @param request The resource and model to materialise
+     *
+     * @returns A promise resolving to the resource materialised against the request's `model`, settled once the
+     *     owning batch and any nested requests needed to assemble it have resolved
+     */
+    detail<S extends Lazy<ResourceShape>, T extends Template>(request: Detail<T, S>): Promise<Match<S, T>>;
+    /**
+     * Enqueue a {@link Select} request.
+     *
+     * Carries no existence precondition: an entry with no matching members resolves to an empty
+     * collection rather than rejecting.
+     *
+     * @param request The property and query to materialise
+     *
+     * @returns A promise resolving to the values the collection holds as the request's `query` narrows them,
+     *     items for a template and rows for a projection, settled once the owning batch and any nested requests
+     *     needed to assemble them have resolved
+     */
+    select<T extends Query<Slot>>(request: Select<T>): Promise<readonly Value[]>;
+    /**
+     * Enqueue a {@link Modify} request.
+     *
+     * Mutates unconditionally, with no existence precondition. A present `state` upserts the entry, creating it if
+     * absent. An omitted `state` deletes the entry, and is a no-op if the entry is absent.
+     *
+     * @param request The entry and target state to persist, or the collection link to add
+     *
+     * @returns A promise resolving to the {@link Reference} of the mutated entry, settled once the owning
+     * batch has completed
+     */
+    modify(request: Modify): Promise<Reference>;
+};
+/**
+ * Creates a batching store client backed by a set of request handlers.
+ *
+ * Coalesces concurrent {@link StoreClient} calls into batches, each served by the matching `handlers` entry. The
+ * client adds conditional CRUD semantics on top of the handlers: `create`, `update` and `delete` probe for existence
+ * through the `detect` handler before handing the mutation to `modify`. `create` mints the identifier of the new
+ * resource, if its state names none, and links it to the collecting resource.
+ *
+ * The `modify` handler receives only requests whose `state` carries no `id` other than their `entry`. A request
+ * failing this check is rejected on its own, and the rest of the batch still applies. If the `modify` handler throws,
+ * the error rejects every request in its batch.
+ *
+ * @param handlers The batch handlers, one per request type
+ *
+ * @returns An immutable {@link StoreClient} serving its requests in batches through `handlers`
+ *
+ * @throws {@link !RangeError RangeError} If an update or insert `state` carries an `id` that differs from its `entry`,
+ *     or if a create `state` member filling an identifier slot is not a single path segment
+ */
+export declare function createBatchingStore(handlers: {
+    detect: Handler<Detect>;
+    detail: Handler<Detail>;
+    select: Handler<Select>;
+    modify: Handler<Modify>;
+}): StoreClient;
+//# sourceMappingURL=batching.d.ts.map

package/dist/clients/batching.d.ts.map

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

package/dist/clients/batching.js

@@ -0,0 +1,109 @@
+/*
+ * Copyright © 2025-2026 Metreeca srl
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { blueprint, collection } from "@metreeca/blue/value";
+import { isString } from "@metreeca/core";
+import { immutable } from "@metreeca/core/values";
+import { createBroker, mint } from "./batching.core.js";
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/**
+ * Creates a batching store client backed by a set of request handlers.
+ *
+ * Coalesces concurrent {@link StoreClient} calls into batches, each served by the matching `handlers` entry. The
+ * client adds conditional CRUD semantics on top of the handlers: `create`, `update` and `delete` probe for existence
+ * through the `detect` handler before handing the mutation to `modify`. `create` mints the identifier of the new
+ * resource, if its state names none, and links it to the collecting resource.
+ *
+ * The `modify` handler receives only requests whose `state` carries no `id` other than their `entry`. A request
+ * failing this check is rejected on its own, and the rest of the batch still applies. If the `modify` handler throws,
+ * the error rejects every request in its batch.
+ *
+ * @param handlers The batch handlers, one per request type
+ *
+ * @returns An immutable {@link StoreClient} serving its requests in batches through `handlers`
+ *
+ * @throws {@link !RangeError RangeError} If an update or insert `state` carries an `id` that differs from its `entry`,
+ *     or if a create `state` member filling an identifier slot is not a single path segment
+ */
+export function createBatchingStore(handlers) {
+    const broker = createBroker({
+        ...handlers,
+        async modify(batch, broker) {
+            const items = batch.filter(({ request: { entry, state }, reject }) => {
+                // reject each request whose state id contradicts its entry on its own, so the
+                // rest of the batch still applies and the check stays out of storage-specific handlers
+                const matching = state?.id === undefined || state.id === entry;
+                if (!matching) {
+                    reject(new RangeError(`mismatched state id <${String(state?.id)}> for entry <${entry}>`));
+                }
+                return matching;
+            });
+            if (items.length > 0) {
+                // on backend failure, reject the surviving batch rather than throw: the broker
+                // treats a handler throw as a run-wide fault and propagates it to sibling queues
+                try {
+                    await handlers.modify(items, broker);
+                }
+                catch (error) {
+                    items.forEach(({ reject }) => reject(error));
+                }
+            }
+        }
+    });
+    return immutable({
+        async lookup({ entry, shape, model }, { locale = ["und"] } = {}) {
+            return await broker.detect({ entry })
+                ? broker.detail({ entry, shape, model, locale })
+                : undefined;
+        },
+        async create({ entry, shape, model, state }) {
+            // the new resource is stored under the identifier its state names, or under one minted for it off the
+            // blueprint of the collection; either way it is the resource probed for existence and written, not the
+            // collection
+            const target = collection(shape, model);
+            const plan = blueprint(shape, model);
+            const { id } = state;
+            const child = isString(id) ? id : mint(entry, plan, state);
+            // a collection a plain property holds is linked to its new member; one exposed through
+            // a foreign property is a view over the member's own link and reaches it on its own
+            return await broker.detect({ entry: child }) ? undefined
+                : broker.modify({ entry: child, shape: plan, state }).then(created => target.foreign
+                    ? created
+                    : broker.modify({ entry, shape, link: { property: target, item: created } }).then(() => created));
+        },
+        async update({ entry, shape, state }) {
+            // the entry identifies the target: a state carrying a different id contradicts it
+            const { id } = state;
+            if (id !== undefined && id !== entry) {
+                throw new RangeError(`mismatched state id <${String(id)}> for entry <${entry}>`);
+            }
+            return await broker.detect({ entry })
+                ? broker.modify({ entry, shape, state })
+                : undefined;
+        },
+        async delete({ entry, shape }) {
+            return await broker.detect({ entry })
+                ? broker.modify({ entry, shape })
+                : undefined;
+        },
+        insert(insert) {
+            return broker.modify(insert);
+        },
+        remove(remove) {
+            return broker.modify(remove);
+        }
+    });
+}
+//# sourceMappingURL=batching.js.map

package/dist/clients/batching.js.map

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

package/dist/clients/validating.d.ts

@@ -0,0 +1,41 @@
+import type { StoreClient } from "../index.js";
+/**
+ * Creates a validating store backed by a delegate.
+ *
+ * Each method validates its inputs against the supplied shape before forwarding the request to `store`:
+ *
+ * - `entry` must be an absolute IRI with no query string and no fragment; otherwise the request is rejected with a
+ *   {@link !RangeError RangeError}
+ * - `model` is validated as a {@link @metreeca/blue!validate | template} for {@link StoreClient.lookup lookup},
+ *   within the query-complexity bounds (`plain`, `depth`, `limit`) of the caller's
+ *   {@link StoreScope | retrieval scope}, and as a collection slice for {@link StoreClient.create create}
+ * - `state.id`, if present, must be nested under `entry` for {@link StoreClient.create create}, and equal to `entry`
+ *   for {@link StoreClient.update update} and {@link StoreClient.insert insert}; otherwise the request is rejected
+ *   with a {@link !RangeError RangeError}
+ * - `state` is validated as a resource with captive expansion capped at depth `0`, so inline captive batches are
+ *   rejected; {@link StoreClient.create create} validates it against the shape of the collected resources, and
+ *   {@link StoreClient.update update} and {@link StoreClient.insert insert} against the supplied shape
+ *
+ * The `trusted` option controls whether {@link StoreClient.lookup lookup} responses are re-validated against the
+ * shape, as narrowed by the caller's `model`. It defaults to `false`, the safe choice for connectors whose source may
+ * deliver non-conforming data, such as a remote REST endpoint. Local stores that compute results themselves can pass
+ * `trusted: true` to skip the redundant check.
+ *
+ * Validation failures surface as {@link @metreeca/core!TraceError | TraceError} or {@link !RangeError RangeError}
+ * rejections, in line with the unified {@link Store} error channel.
+ *
+ * @param store - Inner StoreClient receiving the validated requests
+ * @param options - Optional validation options
+ *
+ * @returns An immutable {@link StoreClient} wrapping `store` with input validation
+ */
+export declare function createValidatingStore(store: StoreClient, { trusted }?: {
+    /**
+     * Whether to skip re-validation of {@link StoreClient.lookup lookup} responses against the shape, as narrowed by
+     * the caller's `model`.
+     *
+     * @defaultValue `false`, treating the wrapped store as untrusted
+     */
+    readonly trusted?: boolean;
+}): StoreClient;
+//# sourceMappingURL=validating.d.ts.map

package/dist/clients/validating.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validating.d.ts","sourceRoot":"","sources":["../../src/clients/validating.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAAS,WAAW,EAAc,MAAM,aAAa,CAAC;AAGlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,WAAW,EAAE,EAEzD,OAAe,EAEf,GAAE;IAEF;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAErB,GAAG,WAAW,CAkJnB"}

package/dist/clients/validating.js

@@ -0,0 +1,150 @@
+/*
+ * Copyright © 2025-2026 Metreeca srl
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Validating store wrapper.
+ *
+ * Guards a {@link StoreClient} against malformed requests, checking entries, models and states against the request
+ * shape before they reach the backend. Retrieval responses from untrusted sources can be re-validated as well.
+ *
+ * @module
+ */
+import { validate } from "@metreeca/blue";
+import { blueprint } from "@metreeca/blue/value";
+import { error } from "@metreeca/core";
+import { isNestedIRI } from "@metreeca/core/resource";
+import { TraceError } from "@metreeca/core/trace";
+import { immutable } from "@metreeca/core/values";
+import { isReference } from "@metreeca/qest/state";
+/**
+ * Creates a validating store backed by a delegate.
+ *
+ * Each method validates its inputs against the supplied shape before forwarding the request to `store`:
+ *
+ * - `entry` must be an absolute IRI with no query string and no fragment; otherwise the request is rejected with a
+ *   {@link !RangeError RangeError}
+ * - `model` is validated as a {@link @metreeca/blue!validate | template} for {@link StoreClient.lookup lookup},
+ *   within the query-complexity bounds (`plain`, `depth`, `limit`) of the caller's
+ *   {@link StoreScope | retrieval scope}, and as a collection slice for {@link StoreClient.create create}
+ * - `state.id`, if present, must be nested under `entry` for {@link StoreClient.create create}, and equal to `entry`
+ *   for {@link StoreClient.update update} and {@link StoreClient.insert insert}; otherwise the request is rejected
+ *   with a {@link !RangeError RangeError}
+ * - `state` is validated as a resource with captive expansion capped at depth `0`, so inline captive batches are
+ *   rejected; {@link StoreClient.create create} validates it against the shape of the collected resources, and
+ *   {@link StoreClient.update update} and {@link StoreClient.insert insert} against the supplied shape
+ *
+ * The `trusted` option controls whether {@link StoreClient.lookup lookup} responses are re-validated against the
+ * shape, as narrowed by the caller's `model`. It defaults to `false`, the safe choice for connectors whose source may
+ * deliver non-conforming data, such as a remote REST endpoint. Local stores that compute results themselves can pass
+ * `trusted: true` to skip the redundant check.
+ *
+ * Validation failures surface as {@link @metreeca/core!TraceError | TraceError} or {@link !RangeError RangeError}
+ * rejections, in line with the unified {@link Store} error channel.
+ *
+ * @param store - Inner StoreClient receiving the validated requests
+ * @param options - Optional validation options
+ *
+ * @returns An immutable {@link StoreClient} wrapping `store` with input validation
+ */
+export function createValidatingStore(store, { trusted = false } = {}) {
+    return immutable({
+        async lookup({ entry, shape, model }, opts) {
+            return store.lookup({
+                entry: assertEntry(entry),
+                shape,
+                model: assertModel(model, shape, opts)
+            }, opts).then(result => {
+                // ;(cast) blue types the validated copy by its own `Delivery` inference rather than by the `Match`
+                // the store states; the copy is returned, rather than the raw response, as it carries the verdict
+                return (trusted || result === undefined ? immutable(result) : validate(result, { shape, model })({
+                    value: value => value,
+                    trace: trace => { throw new TraceError("invalid response", trace ?? []); }
+                }));
+            });
+        },
+        async create({ entry, shape, model, state }) {
+            const $entry = assertEntry(entry);
+            const $model = validate(model, { shape, model: true })({
+                value: value => value,
+                trace: trace => { throw new TraceError("invalid model", trace ?? []); }
+            });
+            // the new resource is validated against the shape the collecting property ranges over, and a stated
+            // identifier is held to the collection it is created through
+            const plan = blueprint(shape, $model);
+            const { id } = state;
+            const $state = id === undefined || isReference(id) && isNestedIRI($entry, id) ? state
+                : error(new RangeError(`state id <${String(id)}> not nested under entry <${entry}>`));
+            // the validator hands back the state itself where it passes, so the typed input is relayed as it
+            // stands once the check has run, the blueprint being resolved at runtime rather than typed
+            validate($state, { shape: plan, depth: 0 })({
+                value: () => undefined,
+                trace: trace => { throw new TraceError("invalid state", trace ?? []); }
+            });
+            return store.create({ entry: $entry, shape, model: $model, state: $state });
+        },
+        async update({ entry, shape, state }) {
+            const $entry = assertEntry(entry);
+            return store.update({
+                entry: $entry,
+                shape,
+                state: validate(assertIdentity($entry, state), { shape, depth: 0 })({
+                    value: () => state,
+                    trace: trace => { throw new TraceError("invalid state", trace ?? []); }
+                })
+            });
+        },
+        async delete({ entry, shape }) {
+            return store.delete({ entry: assertEntry(entry), shape });
+        },
+        async insert({ entry, shape, state }) {
+            const $entry = assertEntry(entry);
+            return store.insert({
+                entry: $entry,
+                shape,
+                state: validate(assertIdentity($entry, state), { shape, depth: 0 })({
+                    value: () => state,
+                    trace: trace => { throw new TraceError("invalid state", trace ?? []); }
+                })
+            });
+        },
+        async remove({ entry, shape }) {
+            return store.remove({
+                entry: assertEntry(entry),
+                shape
+            });
+        }
+    });
+    function assertEntry(entry) {
+        if (!isReference(entry)) {
+            throw new RangeError(`expected absolute IRI <${entry}>`);
+        }
+        if (entry.includes("?") || entry.includes("#")) {
+            throw new RangeError(`unexpected query or fragment in <${entry}>`);
+        }
+        return entry;
+    }
+    function assertIdentity(entry, state) {
+        const { id } = state;
+        return id === undefined || id === entry ? state
+            : error(new RangeError(`mismatched state id <${String(id)}> for entry <${entry}>`));
+    }
+    function assertModel(model, shape, opts = {}) {
+        return validate(model, { ...opts, shape, model: true })({
+            value: value => value,
+            trace: trace => { throw new TraceError("invalid model", trace ?? []); }
+        });
+    }
+}
+//# sourceMappingURL=validating.js.map

package/dist/clients/validating.js.map

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