@smoothbricks/lmao 0.1.0

package/dist/lib/tracers/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tracer implementations
+ *
+ * @module tracers/index
+ */
+export { ArrayQueueTracer } from './ArrayQueueTracer.js';
+export { CompositeTracer } from './CompositeTracer.js';
+export { NoOpTracer } from './NoOpTracer.js';
+export { SQLiteAsyncTracer, SQLiteTracer } from './SQLiteTracer.js';
+export { StdioTracer } from './StdioTracer.js';
+export { TestTracer } from './TestTracer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/tracers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/tracers/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/lib/tracers/index.js

@@ -0,0 +1,11 @@
+/**
+ * Tracer implementations
+ *
+ * @module tracers/index
+ */
+export { ArrayQueueTracer } from './ArrayQueueTracer.js';
+export { CompositeTracer } from './CompositeTracer.js';
+export { NoOpTracer } from './NoOpTracer.js';
+export { SQLiteAsyncTracer, SQLiteTracer } from './SQLiteTracer.js';
+export { StdioTracer } from './StdioTracer.js';
+export { TestTracer } from './TestTracer.js';

package/dist/lib/types.d.ts

@@ -0,0 +1,366 @@
+/**
+ * LMAO-specific types for trace logging
+ *
+ * ## Type System
+ *
+ * - `AnySpanBuffer`: NO index signatures, accepts any schema (for generic processing)
+ * - `SpanBuffer<T>`: WITH index signatures, typed for specific schema T (T is REQUIRED)
+ *
+ * This mirrors arrow-builder's AnyColumnBuffer/ColumnBuffer<T> pattern.
+ */
+import type { AnyColumnBuffer, ColumnBuffer, ColumnValueType, EagerBinarySchema, LazyBinarySchema, Nanoseconds, TypedArray } from '@smoothbricks/arrow-builder';
+import type { OpMetadata } from './opContext/opTypes.js';
+import type { LogSchema } from './schema/LogSchema.js';
+import type { InferSchema } from './schema/types.js';
+import type { SpanBufferStats } from './spanBufferStats.js';
+import type { TraceId } from './traceId.js';
+import type { ITraceRoot } from './traceRoot.js';
+export type { LogBinding, RemappedViewConstructor } from './logBinding.js';
+export type { OpMetadata } from './opContext/opTypes.js';
+export type { extractSpanIdentity, SpanIdentity } from './traceId.js';
+export type { TracerLifecycleHooks } from './traceRoot.js';
+export type { AnyColumnBuffer, ColumnBuffer, ColumnValueType, TypedArray };
+/**
+ * AnySpanBuffer - Core buffer API for Arrow conversion and generic processing.
+ *
+ * Per specs/lmao/01b5_spanbuffer_memory_layout.md:
+ * SpanBuffer is the per-span columnar storage that holds all trace data for a single span.
+ * It uses cache-aligned TypedArrays for V8 optimization and zero-copy Arrow conversion.
+ *
+ * This interface has NO index signatures, making it compatible with any SpanBuffer<T>
+ * regardless of schema. Use this type when you need to accept any buffer:
+ * - Arrow conversion (convertToArrowTable)
+ * - Tree walking (traverseSpanTree)
+ * - Generic buffer processing utilities
+ *
+ * ## Memory Layout (per specs/lmao/01b5)
+ *
+ * ```
+ * _system ArrayBuffer (64-byte aligned):
+ * ├─ timestamp: BigInt64Array (8 bytes × capacity) - nanosecond precision
+ * └─ entry_type: Uint8Array (1 byte × capacity) - enum from ENTRY_TYPE_*
+ *
+ * _identity Uint8Array (48 bytes, immutable after creation):
+ * ├─ trace_id: bytes 0-15 (128-bit UUID)
+ * ├─ thread_id: bytes 16-23 (64-bit BigInt)
+ * ├─ span_id: bytes 24-27 (32-bit counter)
+ * ├─ parent_thread_id: bytes 28-35 (64-bit BigInt, 0 if root)
+ * └─ parent_span_id: bytes 36-39 (32-bit counter, 0 if root)
+ * ```
+ *
+ * ## Fixed Row Layout (per specs/lmao/01h)
+ *
+ * - Row 0: span-start (written by writeSpanStart)
+ * - Row 1: span-end (span-ok, span-err, or span-exception)
+ * - Rows 2+: log entries (info, debug, warn, error, tag, ff-access)
+ *
+ * @see SpanBuffer<T> for schema-typed version with index signatures
+ */
+export interface AnySpanBuffer extends AnyColumnBuffer {
+    /**
+     * System ArrayBuffer containing timestamp and entry_type columns.
+     * 64-byte aligned for CPU cache optimization and SIMD operations.
+     */
+    readonly _system: ArrayBuffer;
+    /**
+     * Identity bytes (48 bytes) containing trace_id, thread_id, span_id, parent info.
+     * Immutable after buffer creation - identity never changes.
+     */
+    readonly _identity: Uint8Array;
+    /**
+     * Nanosecond timestamps for each entry (BigInt64Array).
+     *
+     * Per specs/lmao/01b3_high_precision_timestamps.md:
+     * - Uses performance.now() anchored to epoch for nanosecond precision
+     * - Row 0: span-start timestamp
+     * - Row 1: span-end timestamp (ok/err/exception)
+     * - Rows 2+: log entry timestamps
+     */
+    readonly timestamp: BigInt64Array;
+    /**
+     * Entry type enum for each row (Uint8Array, 1 byte per entry).
+     *
+     * Per specs/lmao/01h_entry_types_and_logging_primitives.md:
+     * Values are ENTRY_TYPE_* constants (span-start=1, span-ok=2, etc.)
+     */
+    readonly entry_type: Uint8Array;
+    /**
+     * Timestamp of span start (row 0).
+     *
+     * Internal helper getter (underscore-prefixed) to avoid conflicts with schema columns.
+     */
+    readonly _spanStartTime: Nanoseconds;
+    /**
+     * Most recent non-zero timestamp in this span's written rows, including overflow buffers.
+     * Returns null if no written row has a timestamp yet.
+     *
+     * Internal helper getter (underscore-prefixed) to avoid conflicts with schema columns.
+     */
+    readonly _lastLoggedTime: Nanoseconds | null;
+    /**
+     * Current write position (next row to write).
+     * Starts at 2 after span-start (row 0) and span-end placeholder (row 1).
+     */
+    _writeIndex: number;
+    /**
+     * Maximum number of rows this buffer can hold.
+     * Per specs/lmao/01b2_buffer_self_tuning.md: Capacity adapts based on workload.
+     */
+    readonly _capacity: number;
+    /**
+     * Next buffer in overflow chain (created when _writeIndex >= _capacity).
+     * Per specs/lmao/01b2: Buffers chain rather than resize for predictable allocation.
+     */
+    _overflow?: AnySpanBuffer;
+    /**
+     * Span ID - 32-bit counter unique within this trace.
+     * Per specs/lmao/01b4_span_identity.md: Monotonic counter, not globally unique.
+     */
+    readonly span_id: number;
+    /**
+     * Thread ID - 64-bit identifier for this execution thread/context.
+     * Per specs/lmao/01b4: Combines worker ID + sequence for uniqueness.
+     */
+    readonly thread_id: bigint;
+    /**
+     * Trace ID - 128-bit UUID identifying the entire trace.
+     * Per specs/lmao/01b4: Propagated to all child spans and buffers.
+     */
+    readonly trace_id: TraceId;
+    /**
+     * Whether this span has a parent (false for root spans).
+     */
+    readonly _hasParent: boolean;
+    /**
+     * Parent's span ID (0 if root span).
+     */
+    readonly parent_span_id: number;
+    /**
+     * Parent's thread ID (0n if root span).
+     */
+    readonly parent_thread_id: bigint;
+    /**
+     * Schema for this buffer (accessed via constructor.schema).
+     * All buffers from same defineOpContext share the same schema.
+     * Underscore prefix since this is an internal property.
+     */
+    readonly _logSchema: LogSchema;
+    /**
+     * Column entries for Arrow conversion iteration.
+     * For SpanBuffer: delegates to _logSchema._columns (unprefixed names)
+     * For RemappedBufferView: built in constructor with prefixed names from mapping
+     *
+     * This enables Arrow conversion to iterate column names correctly regardless of
+     * whether the buffer is wrapped in a RemappedBufferView.
+     */
+    readonly _columns: ReadonlyArray<[string, unknown]>;
+    /**
+     * Shared stats for all buffers from same defineOpContext (accessed via constructor.stats).
+     * Enables self-tuning capacity learning across all ops in the same context.
+     * Underscore prefix since this is an internal property.
+     */
+    readonly _stats: SpanBufferStats;
+    /**
+     * Child spans created via ctx.span().
+     * Per specs/lmao/01c: Parent-child relationship for trace tree.
+     */
+    _children: AnySpanBuffer[];
+    /**
+     * Parent span buffer (undefined for root).
+     * Set during createChildSpanBuffer().
+     */
+    _parent?: AnySpanBuffer;
+    /**
+     * Root trace context - shared by all buffers in a trace.
+     * Contains anchorEpochNanos/anchorPerfNow for timestamp calculation.
+     */
+    _traceRoot: ITraceRoot;
+    /**
+     * Op metadata for this span - identifies WHICH OP IS EXECUTING.
+     * Per specs/lmao/01j and opgroup-refactor.md:
+     * - Used for rows 1+ (log entries, tags, span-ok/err) attribution
+     * - For Op calls: set to op.metadata
+     * - For plain functions: inherited from parent's _opMetadata
+     * - Different from _callsiteMetadata which identifies WHO CALLED span()
+     */
+    _opMetadata: OpMetadata;
+    /**
+     * Callsite metadata - where ctx.span() was called from.
+     * Different from _opMetadata when calling into another op.
+     * Per specs/lmao/01j: Row 0 gets callsite, rows 1+ get op metadata.
+     */
+    _callsiteMetadata?: OpMetadata;
+    /**
+     * Scoped attribute values - inherited by child spans.
+     *
+     * Per specs/lmao/01i_span_scope_attributes.md:
+     * - Frozen object (never mutated, replaced on setScope)
+     * - Child spans inherit by reference (safe because frozen)
+     * - Applied to all rows at Arrow conversion via TypedArray.fill()
+     */
+    _scopeValues: Readonly<Record<string, unknown>>;
+    /**
+     * Message column values - category strings (eager, always allocated).
+     * Contains span names, log messages, exception messages, etc.
+     */
+    readonly message_values: string[];
+    readonly message_nulls: Uint8Array;
+    /**
+     * Line number column values - Float64Array (lazy but always present).
+     * Contains source code line numbers injected by transformer.
+     */
+    readonly line_values: Float64Array;
+    readonly line_nulls: Uint8Array;
+    /**
+     * Error code column values - category strings (lazy but always present).
+     */
+    readonly error_code_values: string[];
+    readonly error_code_nulls: Uint8Array;
+    /**
+     * Retry attempt column values - number (lazy but always present).
+     */
+    readonly retry_attempt_values: Float64Array;
+    readonly retry_attempt_nulls: Uint8Array;
+    /**
+     * Retry delay column values in milliseconds - number (lazy but always present).
+     */
+    readonly retry_delay_ms_values: Float64Array;
+    readonly retry_delay_ms_nulls: Uint8Array;
+    /**
+     * Exception stack trace column values - text strings (lazy but always present).
+     */
+    readonly exception_stack_values: string[];
+    readonly exception_stack_nulls: Uint8Array;
+    /**
+     * Feature flag value column - category strings (lazy but always present).
+     */
+    readonly ff_value_values: string[];
+    readonly ff_value_nulls: Uint8Array;
+    /**
+     * Uint64 value column - BigUint64Array (lazy but always present).
+     */
+    readonly uint64_value_values: BigUint64Array;
+    readonly uint64_value_nulls: Uint8Array;
+    /**
+     * Set message for a row (span name for row 0, log message for rows 2+).
+     * @returns this buffer for chaining (returns AnySpanBuffer for variance)
+     */
+    message(pos: number, val: string): AnySpanBuffer;
+    /**
+     * Set source line number for a row.
+     * Per specs/lmao/01o: Injected by transformer at compile time.
+     */
+    line(pos: number, val: number): AnySpanBuffer;
+    /**
+     * Set error code for a row (used by span-err and error log entries).
+     */
+    error_code(pos: number, val: string): AnySpanBuffer;
+    /**
+     * Set retry attempt for a row (used by span-retry entries).
+     */
+    retry_attempt(pos: number, val: number): AnySpanBuffer;
+    /**
+     * Set retry delay in ms for a row (used by span-retry entries).
+     */
+    retry_delay_ms(pos: number, val: number): AnySpanBuffer;
+    /**
+     * Set exception stack trace for a row (used by span-exception).
+     */
+    exception_stack(pos: number, val: string): AnySpanBuffer;
+    /**
+     * Set feature flag value for a row (used by ff-access entries).
+     */
+    ff_value(pos: number, val: string): AnySpanBuffer;
+    /**
+     * Set uint64 value for a row (general-purpose bigint storage).
+     */
+    uint64_value(pos: number, val: bigint): AnySpanBuffer;
+    /**
+     * Get or create an overflow buffer for this span.
+     *
+     * This method handles the full overflow lifecycle:
+     * 1. Returns existing _overflow if already created
+     * 2. Notifies tracer.onStatsWillResetFor() before stats may reset
+     * 3. Checks capacity tuning based on utilization
+     * 4. Creates new overflow buffer via bufferStrategy
+     * 5. Links this._overflow to the new buffer
+     *
+     * SpanLogger calls this when buffer is full, then prefills scope on the new buffer.
+     *
+     * @returns The overflow buffer (existing or newly created)
+     */
+    getOrCreateOverflow(): AnySpanBuffer;
+    /**
+     * Check if this span is a parent of another span.
+     * Used for tree traversal and validation.
+     */
+    isParentOf(other: AnySpanBuffer): boolean;
+    /**
+     * Check if this span is a child of another span.
+     * Used for tree traversal and validation.
+     */
+    isChildOf(other: AnySpanBuffer): boolean;
+    /**
+     * Copy this span's thread_id bytes to a destination array.
+     * Used for Arrow column building (zero-copy when possible).
+     */
+    copyThreadIdTo(dest: Uint8Array, offset: number): void;
+    /**
+     * Copy this span's parent_thread_id bytes to a destination array.
+     * Used for Arrow column building (zero-copy when possible).
+     */
+    copyParentThreadIdTo(dest: Uint8Array, offset: number): void;
+}
+type SetterValueType<S> = S extends {
+    __schema_type: 'enum';
+} ? number : S extends {
+    __schema_type: 'category' | 'text';
+} ? string : S extends {
+    __schema_type: 'number';
+} ? number : S extends {
+    __schema_type: 'bigUint64';
+} ? bigint : S extends {
+    __schema_type: 'boolean';
+} ? boolean : S extends LazyBinarySchema<infer T> | EagerBinarySchema<infer T> ? T : unknown;
+type ValuesArrayType<S> = S extends {
+    __schema_type: 'enum';
+} ? Uint8Array : S extends {
+    __schema_type: 'category' | 'text';
+} ? string[] : S extends {
+    __schema_type: 'number';
+} ? Float64Array : S extends {
+    __schema_type: 'bigUint64';
+} ? BigUint64Array : S extends {
+    __schema_type: 'boolean';
+} ? Uint8Array : S extends LazyBinarySchema | EagerBinarySchema ? unknown[] : TypedArray | string[];
+type FilterSchemaFields<T> = {
+    [K in keyof T as T[K] extends (...args: unknown[]) => unknown ? never : K]: T[K];
+};
+/**
+ * SpanBuffer<T> - Fully typed buffer for a specific schema.
+ *
+ * Extends AnySpanBuffer with:
+ * - Schema-specific _values/_nulls properties
+ * - Schema-specific setter methods
+ * - Index signatures for dynamic access
+ *
+ * T is REQUIRED - there is no default. Use AnySpanBuffer for generic processing.
+ */
+export type SpanBuffer<T extends LogSchema> = AnySpanBuffer & {
+    _children: SpanBuffer<T>[];
+    _parent?: SpanBuffer<T>;
+    _overflow?: SpanBuffer<T>;
+    readonly _logSchema: T;
+    _scopeValues: Readonly<Partial<InferSchema<T>>>;
+    isParentOf(other: SpanBuffer<T>): boolean;
+    isChildOf(other: SpanBuffer<T>): boolean;
+    [key: `${string}_values`]: TypedArray | string[] | unknown[] | undefined;
+    [key: `${string}_nulls`]: Uint8Array | undefined;
+} & {
+    readonly [K in keyof FilterSchemaFields<T['fields']> as `${K & string}_values`]: ValuesArrayType<FilterSchemaFields<T['fields']>[K]>;
+} & {
+    readonly [K in keyof FilterSchemaFields<T['fields']> as `${K & string}_nulls`]: Uint8Array;
+} & {
+    [K in keyof FilterSchemaFields<T['fields']>]: (pos: number, val: SetterValueType<FilterSchemaFields<T['fields']>[K]>) => SpanBuffer<T>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/types.d.ts.map

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

package/dist/lib/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/utf8Cache.d.ts

@@ -0,0 +1,111 @@
+/**
+ * SIEVE-based cache for UTF-8 string encoding
+ *
+ * Per string storage design specs:
+ * - Category/text columns store raw JS strings in hot path (zero cost)
+ * - UTF-8 encoding happens in cold path (Arrow conversion)
+ * - Frequent strings benefit from caching to avoid re-encoding
+ *
+ * Uses SIEVE algorithm (NSDI'24) which is simpler AND better than LRU
+ * for web workloads. SIEVE achieves ~9% lower miss ratio than LRU-K,
+ * ARC, and 2Q while being much simpler to implement.
+ *
+ * @see https://junchengyang.com/publication/nsdi24-SIEVE.pdf
+ */
+import type { Utf8Encoder } from '@smoothbricks/arrow-builder';
+type EncodedUtf8Batch = {
+    data: Uint8Array;
+    offsets: Int32Array;
+};
+type Utf8CacheStats = {
+    hits: number;
+    misses: number;
+    hitRate: number;
+    size: number;
+};
+/**
+ * UTF-8 encoding cache using SIEVE eviction algorithm
+ *
+ * This cache is used during Arrow conversion to avoid re-encoding
+ * strings that appear multiple times across buffers or conversions.
+ *
+ * Thread-safety: JavaScript is single-threaded, so no locks needed.
+ * The cache is safe to use in async contexts since JS awaits don't
+ * allow concurrent access to the same cache instance.
+ */
+export declare class Utf8Cache implements Utf8Encoder {
+    private readonly cache;
+    private readonly encoder;
+    private hits;
+    private misses;
+    constructor(maxSize?: number);
+    /**
+     * Get UTF-8 encoded bytes for a string, using cache if available
+     *
+     * @param str - String to encode
+     * @returns UTF-8 encoded bytes
+     */
+    encode(str: string): Uint8Array;
+    /**
+     * Calculate UTF-8 byte length of a string
+     *
+     * Uses cache if available to avoid re-encoding.
+     *
+     * @param str - String to measure
+     * @returns UTF-8 byte length
+     */
+    byteLength(str: string): number;
+    /**
+     * Encode string directly into buffer at offset
+     *
+     * @param str - String to encode
+     * @param buffer - Target buffer
+     * @param offset - Offset in buffer to write at
+     * @returns Number of bytes written
+     */
+    encodeInto(str: string, buffer: Uint8Array, offset: number): number;
+    /**
+     * Encode multiple strings, returning concatenated bytes and offsets
+     *
+     * This is optimized for Arrow dictionary construction where we need
+     * both the concatenated bytes and the offset array.
+     *
+     * @param strings - Array of strings to encode
+     * @returns Concatenated UTF-8 bytes and Arrow-format offsets
+     */
+    encodeMany(strings: readonly string[]): EncodedUtf8Batch;
+    /**
+     * Get cache statistics
+     */
+    get stats(): Utf8CacheStats;
+    /**
+     * Reset statistics (useful for per-conversion tracking)
+     */
+    resetStats(): void;
+    /**
+     * Clear the cache entirely
+     */
+    clear(): void;
+}
+/**
+ * Global UTF-8 cache instance
+ *
+ * Using a global cache provides cross-conversion caching benefits:
+ * - Strings that appear in multiple spans/buffers are cached
+ * - Warm cache improves performance over time
+ *
+ * The SIEVE eviction ensures bounded memory even with unbounded inputs.
+ */
+export declare const globalUtf8Cache: Utf8Cache;
+/**
+ * Create a new UTF-8 cache with custom size
+ *
+ * Use this when you want a dedicated cache instance (e.g., for testing
+ * or for isolation between different conversion contexts).
+ *
+ * @param maxSize - Maximum number of entries to cache
+ * @returns New Utf8Cache instance
+ */
+export declare function createUtf8Cache(maxSize?: number): Utf8Cache;
+export {};
+//# sourceMappingURL=utf8Cache.d.ts.map

package/dist/lib/utf8Cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utf8Cache.d.ts","sourceRoot":"","sources":["../../src/lib/utf8Cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAY/D,KAAK,gBAAgB,GAAG;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAE,CAAC;AAClE,KAAK,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtF;;;;;;;;;GASG;AACH,qBAAa,SAAU,YAAW,WAAW;IAC3C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAG7C,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;gBAEP,OAAO,SAA0B;IAI7C;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU;IAa/B;;;;;;;OAOG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAe/B;;;;;;;OAOG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAOnE;;;;;;;;OAQG;IACH,UAAU,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB;IA4BxD;;OAEG;IACH,IAAI,KAAK,IAAI,cAAc,CAQ1B;IAED;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;OAEG;IACH,KAAK,IAAI,IAAI;CAKd;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,WAAkB,CAAC;AAE/C;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAE3D"}