@quereus/quereus 0.1.0

package/dist/src/runtime/async-util.js

@@ -0,0 +1,238 @@
+/**
+ * Async stream utilities for processing async iterables
+ * Used by CacheNode emitter, NestedLoopJoin inner side, and other streaming operations
+ */
+import { createLogger } from '../common/logger.js';
+const log = createLogger('runtime:async-util');
+/**
+ * Transform rows using a mapping function
+ */
+export async function* mapRows(src, fn) {
+    for await (const row of src) {
+        yield fn(row);
+    }
+}
+/**
+ * Filter rows using a predicate function
+ */
+export async function* filterRows(src, pred) {
+    for await (const row of src) {
+        const include = await pred(row);
+        if (include) {
+            yield row;
+        }
+    }
+}
+/**
+ * Duplicate an async iterable into two independent streams
+ * This materializes chunks internally as needed
+ */
+export function tee(src) {
+    const buffer = [];
+    let srcIterator = null;
+    let srcDone = false;
+    let consumer1Index = 0;
+    let consumer2Index = 0;
+    async function fillBuffer(targetIndex) {
+        if (srcDone || buffer.length > targetIndex) {
+            return;
+        }
+        if (!srcIterator) {
+            srcIterator = src[Symbol.asyncIterator]();
+        }
+        while (buffer.length <= targetIndex && !srcDone) {
+            const result = await srcIterator.next();
+            if (result.done) {
+                srcDone = true;
+            }
+            else {
+                buffer.push(result.value);
+            }
+        }
+    }
+    const stream1 = {
+        async *[Symbol.asyncIterator]() {
+            while (true) {
+                await fillBuffer(consumer1Index);
+                if (consumer1Index >= buffer.length) {
+                    if (srcDone)
+                        break;
+                    continue;
+                }
+                yield buffer[consumer1Index];
+                consumer1Index++;
+                // Clean up buffer when both consumers have passed this point
+                const minIndex = Math.min(consumer1Index, consumer2Index);
+                if (minIndex > 100) { // Keep some buffer for efficiency
+                    buffer.splice(0, minIndex - 100);
+                    consumer1Index -= (minIndex - 100);
+                    consumer2Index -= (minIndex - 100);
+                }
+            }
+        }
+    };
+    const stream2 = {
+        async *[Symbol.asyncIterator]() {
+            while (true) {
+                await fillBuffer(consumer2Index);
+                if (consumer2Index >= buffer.length) {
+                    if (srcDone)
+                        break;
+                    continue;
+                }
+                yield buffer[consumer2Index];
+                consumer2Index++;
+                // Clean up buffer when both consumers have passed this point
+                const minIndex = Math.min(consumer1Index, consumer2Index);
+                if (minIndex > 100) { // Keep some buffer for efficiency
+                    buffer.splice(0, minIndex - 100);
+                    consumer1Index -= (minIndex - 100);
+                    consumer2Index -= (minIndex - 100);
+                }
+            }
+        }
+    };
+    return [stream1, stream2];
+}
+/**
+ * Add buffering to an async iterable with back-pressure
+ */
+export async function* buffered(src, maxBuffer) {
+    const buffer = [];
+    const srcIterator = src[Symbol.asyncIterator]();
+    let srcDone = false;
+    let fillPromise = null;
+    // Fill buffer in background
+    async function fillBuffer() {
+        while (buffer.length < maxBuffer && !srcDone) {
+            const result = await srcIterator.next();
+            if (result.done) {
+                srcDone = true;
+            }
+            else {
+                buffer.push(result.value);
+            }
+        }
+    }
+    // Start initial fill
+    fillPromise = fillBuffer();
+    while (true) {
+        // Wait for buffer to have items or source to be done
+        await fillPromise;
+        if (buffer.length === 0 && srcDone) {
+            break;
+        }
+        if (buffer.length > 0) {
+            const item = buffer.shift();
+            yield item;
+            // Start refilling buffer if below threshold
+            if (buffer.length < maxBuffer / 2 && !srcDone) {
+                fillPromise = fillBuffer();
+            }
+        }
+    }
+}
+/**
+ * Take only the first N items from an async iterable
+ */
+export async function* take(src, count) {
+    let taken = 0;
+    for await (const item of src) {
+        if (taken >= count)
+            break;
+        yield item;
+        taken++;
+    }
+}
+/**
+ * Skip the first N items from an async iterable
+ */
+export async function* skip(src, count) {
+    let skipped = 0;
+    for await (const item of src) {
+        if (skipped < count) {
+            skipped++;
+            continue;
+        }
+        yield item;
+    }
+}
+/**
+ * Count the number of items in an async iterable (consumes the iterable)
+ */
+export async function count(src) {
+    let total = 0;
+    for await (const _ of src) {
+        total++;
+    }
+    return total;
+}
+/**
+ * Collect all items from an async iterable into an array
+ * Use with caution on large iterables
+ */
+export async function collect(src) {
+    const result = [];
+    for await (const item of src) {
+        result.push(item);
+    }
+    return result;
+}
+/**
+ * Merge multiple async iterables into a single stream
+ * Items are yielded as soon as they become available from any source
+ */
+export async function* merge(...sources) {
+    const iterators = sources.map(src => src[Symbol.asyncIterator]());
+    const pending = new Map();
+    // Start initial reads
+    for (let i = 0; i < iterators.length; i++) {
+        pending.set(i, iterators[i].next());
+    }
+    while (pending.size > 0) {
+        // Wait for the first iterator to produce a result
+        const entries = Array.from(pending.entries());
+        const promises = entries.map(([index, promise]) => promise.then(result => ({ index, result })));
+        const { index, result } = await Promise.race(promises);
+        pending.delete(index);
+        if (!result.done) {
+            yield result.value;
+            // Start next read from this iterator
+            pending.set(index, iterators[index].next());
+        }
+        // If iterator is done, it's removed from pending and won't be read again
+    }
+}
+/**
+ * Convert an array to an async iterable
+ */
+export async function* fromArray(items) {
+    for (const item of items) {
+        yield item;
+    }
+}
+/**
+ * Add logging to an async iterable for debugging
+ */
+export async function* traced(src, name, itemLogger) {
+    log('Starting trace for %s', name);
+    let index = 0;
+    try {
+        for await (const item of src) {
+            if (itemLogger) {
+                log('%s[%d]: %s', name, index, itemLogger(item, index));
+            }
+            else {
+                log('%s[%d]: %O', name, index, item);
+            }
+            yield item;
+            index++;
+        }
+        log('Completed trace for %s (%d items)', name, index);
+    }
+    catch (error) {
+        log('Error in trace for %s after %d items: %s', name, index, error);
+        throw error;
+    }
+}
+//# sourceMappingURL=async-util.js.map

package/dist/src/runtime/async-util.js.map

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

package/dist/src/runtime/cache/shared-cache.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared cache utilities based on the existing working cache emitter
+ * Provides reusable caching patterns for CacheNode, NLJ inner caching, and CTE materialization
+ */
+import type { Row } from '../../common/types.js';
+/**
+ * Cache strategy for handling overflow
+ */
+export type CacheStrategy = 'memory' | 'spill';
+/**
+ * Configuration for shared cache behavior
+ */
+export interface SharedCacheConfig {
+    /** Maximum rows before abandoning cache */
+    threshold: number;
+    /** Strategy when threshold exceeded */
+    strategy: CacheStrategy;
+    /** Optional identifier for logging */
+    name?: string;
+}
+/**
+ * Cache state for a shared cache instance
+ * Based on the proven closure pattern from the existing cache emitter
+ */
+export interface CacheState {
+    /** Cached result rows (undefined if not cached or abandoned) */
+    cachedResult?: Row[];
+    /** Whether caching was abandoned due to threshold */
+    cacheAbandoned: boolean;
+    /** Number of times cache has been consumed */
+    consumeCount: number;
+}
+/**
+ * Create a cache state object
+ */
+export declare function createCacheState(): CacheState;
+/**
+ * Shared cache implementation using the proven streaming-first pattern
+ * This is extracted from the existing working cache emitter
+ */
+export declare function streamWithCache(sourceIterable: AsyncIterable<Row>, config: SharedCacheConfig, state: CacheState): AsyncIterable<Row>;
+/**
+ * Factory function to create a reusable cache function
+ * Returns a function that can be called multiple times with different sources
+ */
+export declare function createCacheFunction(config: SharedCacheConfig): (source: AsyncIterable<Row>) => AsyncIterable<Row>;
+/**
+ * Helper to wrap an async iterable with caching using the proven pattern
+ * This is the main utility that other components should use
+ */
+export declare function withSharedCache(source: AsyncIterable<Row>, config: SharedCacheConfig): {
+    iterable: AsyncIterable<Row>;
+    state: CacheState;
+};
+/**
+ * Get cache effectiveness metrics
+ */
+export declare function getCacheMetrics(state: CacheState): {
+    isCached: boolean;
+    isAbandoned: boolean;
+    consumeCount: number;
+    cachedRows?: number;
+};
+/**
+ * Clear cache state (useful for testing or manual cache invalidation)
+ */
+export declare function clearCache(state: CacheState): void;
+//# sourceMappingURL=shared-cache.d.ts.map

package/dist/src/runtime/cache/shared-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-cache.d.ts","sourceRoot":"","sources":["../../../../src/runtime/cache/shared-cache.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAC;AAKjD;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,QAAQ,EAAE,aAAa,CAAC;IACxB,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B,gEAAgE;IAChE,YAAY,CAAC,EAAE,GAAG,EAAE,CAAC;IACrB,qDAAqD;IACrD,cAAc,EAAE,OAAO,CAAC;IACxB,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CAM7C;AAED;;;GAGG;AACH,wBAAuB,eAAe,CACrC,cAAc,EAAE,aAAa,CAAC,GAAG,CAAC,EAClC,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,UAAU,GACf,aAAa,CAAC,GAAG,CAAC,CAiDpB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,IAGtB,QAAQ,aAAa,CAAC,GAAG,CAAC,KAAG,aAAa,CAAC,GAAG,CAAC,CAGrF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC9B,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,EAC1B,MAAM,EAAE,iBAAiB,GACvB;IACF,QAAQ,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC;IAC7B,KAAK,EAAE,UAAU,CAAC;CAClB,CAUA;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG;IACnD,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB,CAOA;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAIlD"}

package/dist/src/runtime/cache/shared-cache.js

@@ -0,0 +1,107 @@
+/**
+ * Shared cache utilities based on the existing working cache emitter
+ * Provides reusable caching patterns for CacheNode, NLJ inner caching, and CTE materialization
+ */
+import { createLogger } from '../../common/logger.js';
+const log = createLogger('runtime:cache:shared');
+/**
+ * Create a cache state object
+ */
+export function createCacheState() {
+    return {
+        cachedResult: undefined,
+        cacheAbandoned: false,
+        consumeCount: 0
+    };
+}
+/**
+ * Shared cache implementation using the proven streaming-first pattern
+ * This is extracted from the existing working cache emitter
+ */
+export async function* streamWithCache(sourceIterable, config, state) {
+    const { threshold, name = 'cache' } = config;
+    // If we already have cached data, return it
+    if (state.cachedResult) {
+        state.consumeCount++;
+        log('Serving %s from cache (access #%d, %d rows)', name, state.consumeCount, state.cachedResult.length);
+        yield* state.cachedResult;
+        return;
+    }
+    // If we previously abandoned caching, just stream through
+    if (state.cacheAbandoned) {
+        log('%s cache abandoned due to previous threshold exceed, streaming directly', name);
+        yield* sourceIterable;
+        return;
+    }
+    // First time - pipeline results while building cache
+    log('Building %s cache with threshold %d while pipelining', name, threshold);
+    let cache = [];
+    // Pipeline while caching (proven pattern from existing emitter)
+    for await (const row of sourceIterable) {
+        // Always yield immediately (streaming-first)
+        yield row;
+        // Try to cache if we haven't exceeded threshold
+        if (cache) {
+            if (cache.length < threshold) {
+                // Cache the row (deep copy to avoid reference issues)
+                cache.push([...row]);
+            }
+            else {
+                // Hit threshold - dump cache and abandon caching
+                log('%s cache threshold %d exceeded at row %d, dumping cache and continuing to pipeline', name, threshold, cache.length);
+                cache = undefined;
+            }
+        }
+    }
+    // If we finished without exceeding threshold, cache is ready
+    if (cache) {
+        log('%s cache built successfully with %d rows', name, cache.length);
+        state.cachedResult = cache;
+    }
+    else {
+        state.cacheAbandoned = true;
+    }
+}
+/**
+ * Factory function to create a reusable cache function
+ * Returns a function that can be called multiple times with different sources
+ */
+export function createCacheFunction(config) {
+    const state = createCacheState();
+    return async function* cachedIterable(source) {
+        yield* streamWithCache(source, config, state);
+    };
+}
+/**
+ * Helper to wrap an async iterable with caching using the proven pattern
+ * This is the main utility that other components should use
+ */
+export function withSharedCache(source, config) {
+    const state = createCacheState();
+    const iterable = {
+        async *[Symbol.asyncIterator]() {
+            yield* streamWithCache(source, config, state);
+        }
+    };
+    return { iterable, state };
+}
+/**
+ * Get cache effectiveness metrics
+ */
+export function getCacheMetrics(state) {
+    return {
+        isCached: !!state.cachedResult,
+        isAbandoned: state.cacheAbandoned,
+        consumeCount: state.consumeCount,
+        cachedRows: state.cachedResult?.length
+    };
+}
+/**
+ * Clear cache state (useful for testing or manual cache invalidation)
+ */
+export function clearCache(state) {
+    state.cachedResult = undefined;
+    state.cacheAbandoned = false;
+    state.consumeCount = 0;
+}
+//# sourceMappingURL=shared-cache.js.map

package/dist/src/runtime/cache/shared-cache.js.map

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

package/dist/src/runtime/emission-context.d.ts

@@ -0,0 +1,121 @@
+import type { Database } from '../core/database.js';
+import type { SchemaManager } from '../schema/manager.js';
+import type { TableSchema } from '../schema/table.js';
+import type { FunctionSchema } from '../schema/function.js';
+import type { VirtualTableModule } from '../vtab/module.js';
+import type { CollationFunction } from '../util/comparison.js';
+/**
+ * Represents a dependency on a schema object that was resolved during emission.
+ * Used for plan invalidation when schema changes.
+ */
+export interface SchemaDependency {
+    readonly type: 'table' | 'function' | 'vtab_module' | 'collation';
+    readonly schemaName?: string;
+    readonly objectName: string;
+    readonly objectVersion?: number;
+}
+/**
+ * Tracks schema dependencies and provides a unique identifier for a set of dependencies.
+ */
+export declare class DependencyTracker {
+    private dependencies;
+    private _fingerprint;
+    /**
+     * Records a dependency on a schema object.
+     */
+    addDependency(dep: SchemaDependency): void;
+    /**
+     * Gets all tracked dependencies.
+     */
+    getDependencies(): SchemaDependency[];
+    /**
+     * Gets a fingerprint representing the current set of dependencies.
+     * This can be used to quickly check if dependencies have changed.
+     */
+    getFingerprint(): string;
+    /**
+     * Checks if this tracker has any dependencies that overlap with the given dependency.
+     */
+    dependsOn(dep: SchemaDependency): boolean;
+    /**
+     * Clears all tracked dependencies.
+     */
+    clear(): void;
+    private dependencyKey;
+    private parseDependencyKey;
+}
+/**
+ * Context provided to emitters during plan emission.
+ * Allows schema lookups and tracks dependencies for plan invalidation.
+ * Also captures schema object references for runtime use.
+ */
+export declare class EmissionContext {
+    readonly db: Database;
+    private readonly schemaManager;
+    private readonly dependencyTracker;
+    private readonly schemaSnapshot;
+    constructor(db: Database);
+    /**
+     * Looks up a table schema and records the dependency.
+     * Also captures the table reference for runtime use.
+     */
+    findTable(tableName: string, schemaName?: string): TableSchema | undefined;
+    /**
+     * Looks up a function schema and records the dependency.
+     * Also captures the function reference for runtime use.
+     */
+    findFunction(funcName: string, numArgs: number): FunctionSchema | undefined;
+    /**
+     * Looks up a virtual table module and records the dependency.
+     * Also captures the module reference for runtime use.
+     */
+    getVtabModule(moduleName: string): {
+        module: VirtualTableModule<any, any>;
+        auxData?: unknown;
+    } | undefined;
+    /**
+     * Looks up a collation and records the dependency.
+     * Also captures the collation reference for runtime use.
+     */
+    getCollation(collationName: string): CollationFunction | undefined;
+    /**
+     * Gets the dependency tracker for this emission context.
+     */
+    getDependencyTracker(): DependencyTracker;
+    /**
+     * Gets a snapshot of all dependencies recorded during emission.
+     */
+    getDependencies(): SchemaDependency[];
+    /**
+     * Gets a fingerprint representing all dependencies.
+     */
+    getDependencyFingerprint(): string;
+    /**
+     * Provides access to the database instance for cases where direct access is needed.
+     * Use sparingly - prefer the specific lookup methods above.
+     */
+    getDatabase(): Database;
+    /**
+     * Provides access to the schema manager for cases where direct access is needed.
+     * Use sparingly - prefer the specific lookup methods above.
+     */
+    getSchemaManager(): SchemaManager;
+    /**
+     * Retrieves a captured schema object by its key.
+     * This allows runtime instructions to use the schema objects that were
+     * captured at emission time, providing consistency even if the schema changes.
+     */
+    getCapturedSchemaObject<T = any>(key: string): T | undefined;
+    /**
+     * Validates that all captured schema objects still exist in the current schema.
+     * This can be called at the start of query execution to provide early error detection.
+     * Only validates objects that were actually captured during emission.
+     */
+    validateCapturedSchemaObjects(): void;
+    /**
+     * Gets the number of schema objects captured during emission.
+     * Useful for debugging and testing.
+     */
+    getCapturedObjectCount(): number;
+}
+//# sourceMappingURL=emission-context.d.ts.map

package/dist/src/runtime/emission-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emission-context.d.ts","sourceRoot":"","sources":["../../../src/runtime/emission-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAI5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAI/D;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,aAAa,GAAG,WAAW,CAAC;IAClE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;GAEG;AACH,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,YAAY,CAAuB;IAE3C;;OAEG;IACH,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI;IAM1C;;OAEG;IACH,eAAe,IAAI,gBAAgB,EAAE;IAIrC;;;OAGG;IACH,cAAc,IAAI,MAAM;IAQxB;;OAEG;IACH,SAAS,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO;IAKzC;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,kBAAkB;CAS1B;AAED;;;;GAIG;AACH,qBAAa,eAAe;aAKC,EAAE,EAAE,QAAQ;IAJxC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA2B;IAC7D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0B;gBAE7B,EAAE,EAAE,QAAQ;IAKxC;;;OAGG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAe1E;;;OAGG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAc3E;;;OAGG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG;QAAE,MAAM,EAAE,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS;IAc1G;;;OAGG;IACH,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAclE;;OAEG;IACH,oBAAoB,IAAI,iBAAiB;IAIzC;;OAEG;IACH,eAAe,IAAI,gBAAgB,EAAE;IAIrC;;OAEG;IACH,wBAAwB,IAAI,MAAM;IAIlC;;;OAGG;IACH,WAAW,IAAI,QAAQ;IAIvB;;;OAGG;IACH,gBAAgB,IAAI,aAAa;IAIjC;;;;OAIG;IACH,uBAAuB,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAI5D;;;;OAIG;IACH,6BAA6B,IAAI,IAAI;IAsErC;;;OAGG;IACH,sBAAsB,IAAI,MAAM;CAGhC"}