@l-v-yonsama/multi-platform-database-drivers 2.0.0 → 2.1.0

package/built/src/drivers/providers/performance/DynamoDbPerformanceTuningProvider.js

@@ -0,0 +1,751 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynamoDbPerformanceTuningProvider = void 0;
+const tslib_1 = require("tslib");
+const dynamoPartiqlAccessPattern_1 = require("./dynamoPartiqlAccessPattern");
+const dynamoDbBillingMode_1 = require("../../../helpers/dynamoDbBillingMode");
+const DEFAULT_MAX_PAYLOAD_BYTES = 200000;
+const MAX_MAX_PAYLOAD_BYTES = 2000000;
+const DEFAULT_MAX_INDEXES = 20;
+const MAX_MAX_INDEXES = 100;
+const DEFAULT_MAX_EVALUATED_ITEMS = 100;
+const HIGH_SCANNED_TO_RETURNED_MIN_SCANNED = 100;
+const HIGH_SCANNED_TO_RETURNED_MAX_PASS_RATE = 0.1;
+function monitoringUnavailableMessage(mode) {
+    return mode === 'cloudWatchNotSelected'
+        ? 'CloudWatch metrics and Contributor Insights are not collected because CloudWatch is not enabled for this connection.'
+        : 'CloudWatch metrics and Contributor Insights are outside the scope of local/custom DynamoDB endpoints.';
+}
+function toCloudWatchOperation(operation) {
+    return operation === 'PartiQLSelect' ? 'ExecuteStatement' : operation;
+}
+function mapKeySchema(keySchema, attributeDefinitions) {
+    var _a, _b;
+    const partitionKeyName = (_a = keySchema === null || keySchema === void 0 ? void 0 : keySchema.find((k) => k.KeyType === 'HASH')) === null || _a === void 0 ? void 0 : _a.AttributeName;
+    if (!partitionKeyName)
+        return undefined;
+    const typeOf = (name) => {
+        var _a, _b;
+        return (_b = (_a = attributeDefinitions === null || attributeDefinitions === void 0 ? void 0 : attributeDefinitions.find((a) => a.AttributeName === name)) === null || _a === void 0 ? void 0 : _a.AttributeType) !== null && _b !== void 0 ? _b : 'S';
+    };
+    const sortKeyName = (_b = keySchema === null || keySchema === void 0 ? void 0 : keySchema.find((k) => k.KeyType === 'RANGE')) === null || _b === void 0 ? void 0 : _b.AttributeName;
+    return {
+        partitionKey: {
+            attributeName: partitionKeyName,
+            attributeType: typeOf(partitionKeyName),
+        },
+        sortKey: sortKeyName
+            ? { attributeName: sortKeyName, attributeType: typeOf(sortKeyName) }
+            : undefined,
+    };
+}
+function mapProjection(projection) {
+    var _a;
+    const type = projection === null || projection === void 0 ? void 0 : projection.ProjectionType;
+    return {
+        projectionType: type === 'ALL' || type === 'KEYS_ONLY' || type === 'INCLUDE'
+            ? type
+            : 'unknown',
+        nonKeyAttributes: type === 'INCLUDE' ? (_a = projection === null || projection === void 0 ? void 0 : projection.NonKeyAttributes) !== null && _a !== void 0 ? _a : [] : undefined,
+    };
+}
+function mapThroughput(t) {
+    if (!t ||
+        (t.ReadCapacityUnits === undefined && t.WriteCapacityUnits === undefined))
+        return undefined;
+    return {
+        readCapacityUnits: t.ReadCapacityUnits,
+        writeCapacityUnits: t.WriteCapacityUnits,
+    };
+}
+function mapWarmThroughput(w) {
+    if (!w ||
+        (w.ReadUnitsPerSecond === undefined && w.WriteUnitsPerSecond === undefined))
+        return undefined;
+    return {
+        readCapacityUnits: w.ReadUnitsPerSecond,
+        writeCapacityUnits: w.WriteUnitsPerSecond,
+    };
+}
+function mapIndex(index, indexType, tableAttributeDefinitions) {
+    var _a, _b, _c, _d;
+    if (!index.IndexName)
+        return undefined;
+    const gsi = indexType === 'GSI'
+        ? index
+        : undefined;
+    return {
+        indexName: index.IndexName,
+        indexType,
+        status: gsi === null || gsi === void 0 ? void 0 : gsi.IndexStatus,
+        keySchema: (_a = mapKeySchema(index.KeySchema, tableAttributeDefinitions)) !== null && _a !== void 0 ? _a : {
+            partitionKey: {
+                attributeName: (_d = (_c = (_b = index.KeySchema) === null || _b === void 0 ? void 0 : _b[0]) === null || _c === void 0 ? void 0 : _c.AttributeName) !== null && _d !== void 0 ? _d : 'unknown',
+                attributeType: 'S',
+            },
+        },
+        projection: mapProjection(index.Projection),
+        itemCount: index.ItemCount !== undefined
+            ? {
+                value: index.ItemCount,
+                estimated: true,
+                source: 'DescribeTable.ItemCount',
+            }
+            : undefined,
+        indexSizeBytes: index.IndexSizeBytes !== undefined
+            ? {
+                value: index.IndexSizeBytes,
+                estimated: true,
+                source: 'DescribeTable.IndexSizeBytes',
+            }
+            : undefined,
+        provisionedThroughput: gsi
+            ? mapThroughput(gsi.ProvisionedThroughput)
+            : undefined,
+        onDemandThroughput: (gsi === null || gsi === void 0 ? void 0 : gsi.OnDemandThroughput)
+            ? {
+                maxReadRequestUnits: gsi.OnDemandThroughput.MaxReadRequestUnits,
+                maxWriteRequestUnits: gsi.OnDemandThroughput.MaxWriteRequestUnits,
+            }
+            : undefined,
+        warmThroughput: gsi ? mapWarmThroughput(gsi.WarmThroughput) : undefined,
+    };
+}
+function mapTableContext(table, ttl, contributorInsights) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+    const keySchema = (_a = mapKeySchema(table.KeySchema, table.AttributeDefinitions)) !== null && _a !== void 0 ? _a : {
+        partitionKey: {
+            attributeName: (_d = (_c = (_b = table.KeySchema) === null || _b === void 0 ? void 0 : _b[0]) === null || _c === void 0 ? void 0 : _c.AttributeName) !== null && _d !== void 0 ? _d : 'unknown',
+            attributeType: 'S',
+        },
+    };
+    return {
+        tableName: (_e = table.TableName) !== null && _e !== void 0 ? _e : '',
+        status: table.TableStatus,
+        billingMode: (0, dynamoDbBillingMode_1.resolveDynamoDbBillingMode)({
+            billingMode: (_f = table.BillingModeSummary) === null || _f === void 0 ? void 0 : _f.BillingMode,
+            readCapacityUnits: (_g = table.ProvisionedThroughput) === null || _g === void 0 ? void 0 : _g.ReadCapacityUnits,
+            writeCapacityUnits: (_h = table.ProvisionedThroughput) === null || _h === void 0 ? void 0 : _h.WriteCapacityUnits,
+        }),
+        keySchema,
+        attributeDefinitions: ((_j = table.AttributeDefinitions) !== null && _j !== void 0 ? _j : [])
+            .filter((a) => !!a.AttributeName)
+            .map((a) => ({
+            attributeName: a.AttributeName,
+            attributeType: a.AttributeType,
+        })),
+        localSecondaryIndexes: ((_k = table.LocalSecondaryIndexes) !== null && _k !== void 0 ? _k : [])
+            .map((i) => mapIndex(i, 'LSI', table.AttributeDefinitions))
+            .filter((i) => !!i),
+        globalSecondaryIndexes: ((_l = table.GlobalSecondaryIndexes) !== null && _l !== void 0 ? _l : [])
+            .map((i) => mapIndex(i, 'GSI', table.AttributeDefinitions))
+            .filter((i) => !!i),
+        provisionedThroughput: mapThroughput(table.ProvisionedThroughput),
+        onDemandThroughput: table.OnDemandThroughput
+            ? {
+                maxReadRequestUnits: table.OnDemandThroughput.MaxReadRequestUnits,
+                maxWriteRequestUnits: table.OnDemandThroughput.MaxWriteRequestUnits,
+            }
+            : undefined,
+        warmThroughput: mapWarmThroughput(table.WarmThroughput),
+        itemCount: table.ItemCount !== undefined
+            ? {
+                value: table.ItemCount,
+                estimated: true,
+                source: 'DescribeTable.ItemCount',
+            }
+            : undefined,
+        tableSizeBytes: table.TableSizeBytes !== undefined
+            ? {
+                value: table.TableSizeBytes,
+                estimated: true,
+                source: 'DescribeTable.TableSizeBytes',
+            }
+            : undefined,
+        tableClass: (_m = table.TableClassSummary) === null || _m === void 0 ? void 0 : _m.TableClass,
+        ttl: (ttl === null || ttl === void 0 ? void 0 : ttl.TimeToLiveStatus) !== undefined
+            ? { status: ttl.TimeToLiveStatus, attributeName: ttl.AttributeName }
+            : undefined,
+        contributorInsights,
+    };
+}
+function resolveTargetKeySchema(table, indexName) {
+    if (!indexName)
+        return { keySchema: table.keySchema };
+    const gsi = table.globalSecondaryIndexes.find((i) => i.indexName === indexName);
+    if (gsi)
+        return { keySchema: gsi.keySchema, indexType: 'GSI' };
+    const lsi = table.localSecondaryIndexes.find((i) => i.indexName === indexName);
+    if (lsi)
+        return { keySchema: lsi.keySchema, indexType: 'LSI' };
+    return undefined;
+}
+function diag(code, severity, affectsCompleteness, scope, message, extra) {
+    return Object.assign({ code, severity, affectsCompleteness, scope, message }, extra);
+}
+class DynamoDbPerformanceTuningProvider {
+    constructor(driver) {
+        this.driver = driver;
+    }
+    checkCapabilities(params) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            const monitoringMode = this.driver.monitoringMode;
+            const monitoringAvailable = monitoringMode === 'enabled';
+            const monitoringMessage = monitoringMode === 'enabled'
+                ? undefined
+                : monitoringUnavailableMessage(monitoringMode);
+            const capabilities = {
+                staticAccessPattern: {
+                    available: true,
+                    source: 'PartiQL/KeyCondition static parse against DescribeTable key schema',
+                },
+                tableDefinition: {
+                    available: true,
+                    source: 'dynamodb:DescribeTable',
+                    requiredPermissions: ['dynamodb:DescribeTable'],
+                },
+                cloudWatchMetrics: monitoringAvailable
+                    ? {
+                        available: true,
+                        source: 'cloudwatch:GetMetricData',
+                        requiredPermissions: ['cloudwatch:GetMetricData'],
+                    }
+                    : { available: false, message: monitoringMessage },
+                contributorInsightsStatus: Object.assign({}, (monitoringAvailable
+                    ? {
+                        available: true,
+                        source: 'dynamodb:DescribeContributorInsights',
+                        requiredPermissions: ['dynamodb:DescribeContributorInsights'],
+                    }
+                    : { available: false, message: monitoringMessage })),
+                observedRead: {
+                    available: true,
+                    message: 'IAM permission for a Run Observed Read is not pre-verified; an AccessDenied surfaces only after the user confirms it.',
+                    requiredPermissions: ['dynamodb:PartiQLSelect', 'dynamodb:Query'],
+                },
+            };
+            return { ok: true, message: '', result: capabilities };
+        });
+    }
+    collect(params, options) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t;
+            const limits = {
+                maxPayloadBytes: clamp((_a = params.limits) === null || _a === void 0 ? void 0 : _a.maxPayloadBytes, DEFAULT_MAX_PAYLOAD_BYTES, 1, MAX_MAX_PAYLOAD_BYTES),
+                maxIndexes: clamp((_b = params.limits) === null || _b === void 0 ? void 0 : _b.maxIndexes, DEFAULT_MAX_INDEXES, 1, MAX_MAX_INDEXES),
+            };
+            const mode = (_d = (_c = params.observation) === null || _c === void 0 ? void 0 : _c.mode) !== null && _d !== void 0 ? _d : 'static';
+            const request = params.statement.request;
+            let tableName;
+            let indexName;
+            let statementText;
+            if (request.kind === 'partiql') {
+                const extracted = (0, dynamoPartiqlAccessPattern_1.extractDynamoPartiqlTarget)(request.text);
+                if (!extracted) {
+                    return {
+                        ok: false,
+                        message: 'The PartiQL statement could not be parsed as a single SELECT.',
+                    };
+                }
+                if (params.target &&
+                    (params.target.tableName !== extracted.tableName ||
+                        params.target.indexName !== extracted.indexName)) {
+                    return {
+                        ok: false,
+                        message: 'The explicit target does not match the table/index the statement references.',
+                    };
+                }
+                tableName = extracted.tableName;
+                indexName = extracted.indexName;
+                statementText = request.text;
+            }
+            else {
+                if (!request.input.tableName) {
+                    return {
+                        ok: false,
+                        message: 'A native Query analysis input requires tableName.',
+                    };
+                }
+                tableName = request.input.tableName;
+                indexName = request.input.indexName;
+            }
+            let rawTable;
+            try {
+                rawTable = yield this.driver.describeTable(tableName);
+            }
+            catch (_u) {
+                rawTable = undefined;
+            }
+            if (!rawTable || !rawTable.TableName) {
+                return {
+                    ok: false,
+                    message: `Table "${tableName}" could not be described.`,
+                };
+            }
+            const diagnostics = [];
+            const unavailableSections = [];
+            const monitoringMode = this.driver.monitoringMode;
+            const monitoringEnabled = monitoringMode === 'enabled';
+            if (monitoringMode !== 'enabled') {
+                diagnostics.push(diag('DYNAMODB_MONITORING_COLLECTION_SKIPPED', 'info', false, 'collection', monitoringUnavailableMessage(monitoringMode), { tableName }));
+            }
+            let ttl;
+            try {
+                ttl = yield this.driver.describeTimeToLive(tableName);
+            }
+            catch (e) {
+                unavailableSections.push({
+                    section: 'tableDefinition',
+                    tableName,
+                    reason: describeError(e, 'DescribeTimeToLive failed.'),
+                    requiredPermissions: ['dynamodb:DescribeTimeToLive'],
+                });
+                diagnostics.push(diag('DYNAMODB_SECTION_COLLECTION_FAILED', 'warning', true, 'tableDefinition', 'Time to live status could not be collected.', {
+                    tableName,
+                }));
+            }
+            const contributorInsights = [];
+            if (monitoringEnabled) {
+                const ciTargets = [
+                    { resource: 'table' },
+                    ...((_e = rawTable.GlobalSecondaryIndexes) !== null && _e !== void 0 ? _e : [])
+                        .filter((i) => !!i.IndexName)
+                        .map((i) => ({ resource: 'gsi', indexName: i.IndexName })),
+                ];
+                const ciResults = yield Promise.all(ciTargets.map((target) => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                    try {
+                        const res = yield this.driver.describeContributorInsights(tableName, target.indexName);
+                        return { target, res, error: undefined };
+                    }
+                    catch (e) {
+                        return { target, res: undefined, error: e };
+                    }
+                })));
+                for (const { target, res, error } of ciResults) {
+                    if (error || !res) {
+                        unavailableSections.push({
+                            section: 'contributorInsights',
+                            tableName,
+                            indexName: target.indexName,
+                            reason: describeError(error, 'DescribeContributorInsights failed.'),
+                            requiredPermissions: ['dynamodb:DescribeContributorInsights'],
+                        });
+                        diagnostics.push(diag('DYNAMODB_SECTION_COLLECTION_FAILED', 'warning', true, 'contributorInsights', 'Contributor Insights status could not be collected.', {
+                            tableName,
+                            indexName: target.indexName,
+                        }));
+                        continue;
+                    }
+                    contributorInsights.push({
+                        resource: target.resource,
+                        status: (_f = res.status) !== null && _f !== void 0 ? _f : 'UNKNOWN',
+                        mode: res.mode,
+                        indexName: target.indexName,
+                    });
+                }
+            }
+            const table = mapTableContext(rawTable, ttl, contributorInsights);
+            const resolvedTarget = resolveTargetKeySchema(table, indexName);
+            if (!resolvedTarget) {
+                return {
+                    ok: false,
+                    message: `Index "${indexName}" was not found on table "${tableName}".`,
+                };
+            }
+            let observationEligibility = {
+                allowed: true,
+            };
+            let accessPattern;
+            if (request.kind === 'partiql') {
+                if (containsUnresolvedBindMarker(statementText)) {
+                    observationEligibility = {
+                        allowed: false,
+                        reason: 'The statement contains an unresolved bind marker (?); Run Observed Read is not available for parameterized PartiQL in v1.',
+                    };
+                }
+                accessPattern = (0, dynamoPartiqlAccessPattern_1.analyzeDynamoPartiqlAccessPattern)({
+                    sql: statementText,
+                    keySchema: resolvedTarget.keySchema,
+                    tableName,
+                    indexName,
+                    indexType: resolvedTarget.indexType,
+                });
+            }
+            else {
+                accessPattern = (0, dynamoPartiqlAccessPattern_1.analyzeDynamoNativeQueryAccessPattern)({
+                    input: request.input,
+                    keySchema: resolvedTarget.keySchema,
+                    indexType: resolvedTarget.indexType,
+                });
+            }
+            if (accessPattern.confidence === 'unknown') {
+                diagnostics.push(diag('DYNAMODB_ACCESS_PATTERN_UNRESOLVED', 'warning', true, 'accessPattern', 'The statement could not be classified as Query or Scan safely.', {
+                    tableName,
+                    indexName,
+                }));
+                unavailableSections.push({
+                    section: 'accessPattern',
+                    tableName,
+                    indexName,
+                    reason: 'The statement could not be parsed.',
+                });
+            }
+            else if (accessPattern.accessPath === 'tableScan') {
+                diagnostics.push(diag('DYNAMODB_FULL_TABLE_SCAN', 'warning', false, 'accessPattern', 'This statement performs a full table scan.', { tableName }));
+            }
+            else if (accessPattern.accessPath === 'indexScan') {
+                diagnostics.push(diag('DYNAMODB_FULL_INDEX_SCAN', 'warning', false, 'accessPattern', 'This statement performs a full index scan.', { tableName, indexName }));
+            }
+            if (accessPattern.postReadFilter.present) {
+                diagnostics.push(diag('DYNAMODB_POST_READ_FILTER', 'info', false, 'accessPattern', 'A non-key predicate is evaluated after each item is read.', {
+                    tableName,
+                    indexName,
+                }));
+            }
+            if (table.itemCount !== undefined || table.tableSizeBytes !== undefined) {
+                diagnostics.push(diag('DYNAMODB_APPROXIMATE_TABLE_METADATA', 'info', false, 'tableDefinition', 'ItemCount/TableSizeBytes are AWS approximations, updated roughly every six hours.', { tableName }));
+            }
+            let cloudWatch;
+            if (monitoringEnabled) {
+                const cwResult = yield this.driver.collectCloudWatchMetrics({
+                    tableName,
+                    indexName,
+                    indexType: resolvedTarget.indexType,
+                    operation: toCloudWatchOperation(accessPattern.operation),
+                    billingMode: table.billingMode,
+                    hasOnDemandMaxLimit: ((_g = table.onDemandThroughput) === null || _g === void 0 ? void 0 : _g.maxReadRequestUnits) !== undefined,
+                    lookbackMinutes: (_h = params.metrics) === null || _h === void 0 ? void 0 : _h.lookbackMinutes,
+                    periodSeconds: (_j = params.metrics) === null || _j === void 0 ? void 0 : _j.periodSeconds,
+                    signal: options === null || options === void 0 ? void 0 : options.signal,
+                });
+                if (cwResult.ok && cwResult.result) {
+                    cloudWatch = cwResult.result;
+                    for (const series of cloudWatch.series) {
+                        if (series.noData) {
+                            diagnostics.push(diag('DYNAMODB_CLOUDWATCH_NO_DATA', 'info', false, 'cloudWatchMetrics', `No CloudWatch datapoints for ${series.metricName} (${series.statistic}).`, {
+                                tableName,
+                                indexName: series.scope === 'gsi' ? series.indexName : undefined,
+                                metricName: series.metricName,
+                            }));
+                        }
+                    }
+                    applyThrottleDiagnostics(cloudWatch, diagnostics, tableName);
+                }
+                else {
+                    unavailableSections.push({
+                        section: 'cloudWatchMetrics',
+                        tableName,
+                        reason: cwResult.message || 'CloudWatch metrics could not be collected.',
+                        requiredPermissions: ['cloudwatch:GetMetricData'],
+                    });
+                    diagnostics.push(diag('DYNAMODB_SECTION_COLLECTION_FAILED', 'warning', true, 'cloudWatchMetrics', 'CloudWatch metrics could not be collected.', { tableName }));
+                }
+            }
+            let observation = params.statement.previousObservation;
+            const workload = params.statement.workload;
+            if (mode === 'executeOnce' || mode === 'executeComplete') {
+                if (((_k = params.observation) === null || _k === void 0 ? void 0 : _k.allowExecution) !== true) {
+                    return {
+                        ok: false,
+                        message: `observation.mode is ${mode} but observation.allowExecution was not explicitly true. A measured read requires explicit, host-confirmed authorization.`,
+                    };
+                }
+                if (!(options === null || options === void 0 ? void 0 : options.execution)) {
+                    return {
+                        ok: false,
+                        message: `observation.mode is ${mode} but no execution options were supplied.`,
+                    };
+                }
+                if (!observationEligibility.allowed) {
+                    return {
+                        ok: false,
+                        message: (_l = observationEligibility.reason) !== null && _l !== void 0 ? _l : 'This statement is not eligible for Run Observed Read.',
+                    };
+                }
+                const maxEvaluatedItems = mode === 'executeComplete'
+                    ? clamp((_m = params.observation) === null || _m === void 0 ? void 0 : _m.maxEvaluatedItems, 1000, 1, 1000)
+                    : clamp((_o = params.observation) === null || _o === void 0 ? void 0 : _o.maxEvaluatedItems, DEFAULT_MAX_EVALUATED_ITEMS, 1, DEFAULT_MAX_EVALUATED_ITEMS);
+                const maxPages = clamp((_p = params.observation) === null || _p === void 0 ? void 0 : _p.maxPages, 10, 1, 10);
+                if (mode === 'executeComplete' &&
+                    ((options.execution.kind === 'partiql' &&
+                        !this.driver.observePartiqlReadComplete) ||
+                        (options.execution.kind === 'query' &&
+                            !this.driver.observeNativeQueryReadComplete))) {
+                    return {
+                        ok: false,
+                        message: 'Complete-result Benchmark is not supported by this DynamoDB driver.',
+                    };
+                }
+                try {
+                    const observed = mode === 'executeComplete'
+                        ? options.execution.kind === 'partiql'
+                            ? yield this.driver.observePartiqlReadComplete({
+                                statement: statementText,
+                                parameters: options.execution.parameters,
+                                maxPages,
+                                timeoutMs: (_q = params.observation) === null || _q === void 0 ? void 0 : _q.timeoutMs,
+                                signal: options.signal,
+                            })
+                            : yield this.driver.observeNativeQueryReadComplete({
+                                input: options.execution.input,
+                                maxEvaluatedItems,
+                                maxPages,
+                                timeoutMs: (_r = params.observation) === null || _r === void 0 ? void 0 : _r.timeoutMs,
+                                signal: options.signal,
+                            })
+                        : options.execution.kind === 'partiql'
+                            ? yield this.driver.observePartiqlRead({
+                                statement: statementText,
+                                parameters: options.execution.parameters,
+                                maxEvaluatedItems,
+                                timeoutMs: (_s = params.observation) === null || _s === void 0 ? void 0 : _s.timeoutMs,
+                                signal: options.signal,
+                            })
+                            : yield this.driver.observeNativeQueryRead({
+                                input: options.execution.input,
+                                maxEvaluatedItems,
+                                timeoutMs: (_t = params.observation) === null || _t === void 0 ? void 0 : _t.timeoutMs,
+                                signal: options.signal,
+                            });
+                    observation = buildObservation(observed, mode, request.kind);
+                    if (observed.hasMorePages) {
+                        diagnostics.push(diag('DYNAMODB_OBSERVATION_BOUNDED', 'info', false, 'observation', mode === 'executeComplete'
+                            ? `Complete-result Benchmark reached its safety limit (${maxPages} pages / ${maxEvaluatedItems} evaluated items).`
+                            : `Run Observed Read stopped after one response / ${maxEvaluatedItems} evaluated items.`, {
+                            tableName,
+                            indexName,
+                        }));
+                    }
+                    if (observed.scannedItemCount !== undefined &&
+                        observed.scannedItemCount >= HIGH_SCANNED_TO_RETURNED_MIN_SCANNED &&
+                        observed.scannedItemCount > 0 &&
+                        observed.returnedItemCount / observed.scannedItemCount <
+                            HIGH_SCANNED_TO_RETURNED_MAX_PASS_RATE) {
+                        diagnostics.push(diag('DYNAMODB_HIGH_SCANNED_TO_RETURNED', 'warning', false, 'observation', 'A large fraction of evaluated items were filtered out after being read.', {
+                            tableName,
+                            indexName,
+                        }));
+                    }
+                }
+                catch (e) {
+                    return {
+                        ok: false,
+                        message: describeError(e, 'Run Observed Read failed.'),
+                    };
+                }
+            }
+            let context = {
+                formatVersion: 1,
+                engine: 'dynamodb',
+                service: {
+                    provider: 'AWS',
+                    service: 'DynamoDB',
+                    region: this.driver.region,
+                    endpointKind: this.driver.endpointKind,
+                    tableName,
+                    indexName,
+                },
+                statement: {
+                    language: request.kind === 'partiql' ? 'partiql' : 'dynamodb-query',
+                    text: statementText,
+                    source: params.statement.source,
+                    kind: request.kind === 'partiql' ? 'select' : 'query',
+                    observationEligibility,
+                },
+                accessPattern,
+                table: limitIndexes(table, indexName, limits.maxIndexes, diagnostics),
+                workload,
+                observation,
+                cloudWatch,
+                collection: {
+                    collectedAt: new Date().toISOString(),
+                    status: unavailableSections.length > 0 ||
+                        diagnostics.some((d) => d.affectsCompleteness)
+                        ? 'partial'
+                        : 'complete',
+                    diagnostics,
+                    unavailableSections,
+                },
+            };
+            const limited = applyPayloadLimit(context, limits.maxPayloadBytes);
+            if (!limited.ok) {
+                return {
+                    ok: false,
+                    message: 'The collected context exceeds the configured payload limit even after truncation.',
+                };
+            }
+            context = limited.context;
+            return { ok: true, message: '', result: context };
+        });
+    }
+}
+exports.DynamoDbPerformanceTuningProvider = DynamoDbPerformanceTuningProvider;
+function clamp(value, fallback, min, max) {
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.min(max, Math.max(min, Math.floor(n)));
+}
+function describeError(e, fallback) {
+    const name = e instanceof Error ? e.name : undefined;
+    if (name === 'AccessDeniedException')
+        return `${fallback} (access denied)`;
+    if (name === 'ResourceNotFoundException')
+        return `${fallback} (resource not found)`;
+    return fallback;
+}
+function containsUnresolvedBindMarker(sql) {
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < sql.length; i++) {
+        const ch = sql[i];
+        if (inSingle) {
+            if (ch === "'" && sql[i + 1] === "'")
+                i++;
+            else if (ch === "'")
+                inSingle = false;
+            continue;
+        }
+        if (inDouble) {
+            if (ch === '"' && sql[i + 1] === '"')
+                i++;
+            else if (ch === '"')
+                inDouble = false;
+            continue;
+        }
+        if (ch === "'") {
+            inSingle = true;
+            continue;
+        }
+        if (ch === '"') {
+            inDouble = true;
+            continue;
+        }
+        if (ch === '?')
+            return true;
+    }
+    return false;
+}
+function buildObservation(observed, mode, requestKind) {
+    const filterPassRate = observed.scannedItemCount !== undefined && observed.scannedItemCount > 0
+        ? observed.returnedItemCount / observed.scannedItemCount
+        : undefined;
+    const bounded = observed.hasMorePages;
+    return {
+        source: 'observedRead',
+        observedAt: new Date().toISOString(),
+        clientElapsedTimeMs: observed.clientElapsedTimeMs,
+        requestCount: observed.requestCount,
+        retryCount: observed.retryCount,
+        returnedItemCount: observed.returnedItemCount,
+        evaluatedItemCount: requestKind === 'partiql' ? undefined : observed.scannedItemCount,
+        filterPassRate: requestKind === 'partiql' ? undefined : filterPassRate,
+        consumedCapacity: observed.capacityBreakdown,
+        hasMorePages: observed.hasMorePages,
+        bounded,
+        completeness: bounded ? 'bounded' : 'complete',
+        boundDescription: bounded
+            ? mode === 'executeComplete'
+                ? 'Complete-result Benchmark reached its safety limit; a continuation key remains.'
+                : `Limited to ${mode === 'executeOnce'
+                    ? 'a single API response'
+                    : 'the source evidence'} by Run Observed Read; a continuation key remains.`
+            : undefined,
+    };
+}
+function applyThrottleDiagnostics(cloudWatch, diagnostics, tableName) {
+    const hasActivity = (metricName) => cloudWatch.series.find((s) => s.metricName === metricName && !s.noData && s.values.some((v) => v > 0));
+    const checks = [
+        ['ReadThrottleEvents', 'DYNAMODB_READ_THROTTLING_OBSERVED'],
+        [
+            'ReadKeyRangeThroughputThrottleEvents',
+            'DYNAMODB_KEY_RANGE_THROTTLING_OBSERVED',
+        ],
+        [
+            'ReadProvisionedThroughputThrottleEvents',
+            'DYNAMODB_PROVISIONED_THROTTLING_OBSERVED',
+        ],
+        [
+            'ReadMaxOnDemandThroughputThrottleEvents',
+            'DYNAMODB_ON_DEMAND_LIMIT_THROTTLING_OBSERVED',
+        ],
+        [
+            'ReadAccountLimitThrottleEvents',
+            'DYNAMODB_ACCOUNT_LIMIT_THROTTLING_OBSERVED',
+        ],
+    ];
+    for (const [metricName, code] of checks) {
+        const series = hasActivity(metricName);
+        if (series) {
+            diagnostics.push(diag(code, 'warning', false, 'cloudWatchMetrics', `${metricName} was observed in the collection window.`, { tableName, metricName }));
+        }
+    }
+}
+function limitIndexes(table, targetIndexName, maxIndexes, diagnostics) {
+    const total = table.localSecondaryIndexes.length + table.globalSecondaryIndexes.length;
+    if (total <= maxIndexes)
+        return table;
+    diagnostics.push(diag('DYNAMODB_COLLECTION_TRUNCATED', 'warning', true, 'tableDefinition', `Index list truncated to ${maxIndexes} entries.`, { tableName: table.tableName }));
+    const target = [];
+    const restLsi = [];
+    const restGsi = [];
+    for (const index of table.localSecondaryIndexes) {
+        (index.indexName === targetIndexName ? target : restLsi).push({
+            index,
+            kind: 'LSI',
+        });
+    }
+    for (const index of table.globalSecondaryIndexes) {
+        (index.indexName === targetIndexName ? target : restGsi).push({
+            index,
+            kind: 'GSI',
+        });
+    }
+    const kept = [...target, ...restGsi, ...restLsi].slice(0, Math.max(0, maxIndexes));
+    return Object.assign(Object.assign({}, table), { localSecondaryIndexes: kept
+            .filter((e) => e.kind === 'LSI')
+            .map((e) => e.index), globalSecondaryIndexes: kept
+            .filter((e) => e.kind === 'GSI')
+            .map((e) => e.index) });
+}
+function byteSize(value) {
+    var _a;
+    return Buffer.byteLength((_a = JSON.stringify(value)) !== null && _a !== void 0 ? _a : '', 'utf8');
+}
+function applyPayloadLimit(context, maxPayloadBytes) {
+    if (byteSize(context) <= maxPayloadBytes)
+        return { context, ok: true };
+    let next = context;
+    const truncatedDiag = diag('DYNAMODB_COLLECTION_TRUNCATED', 'warning', true, 'collection', 'The context was reduced to fit the payload limit.');
+    if (next.cloudWatch) {
+        next = Object.assign(Object.assign({}, next), { cloudWatch: Object.assign(Object.assign({}, next.cloudWatch), { series: next.cloudWatch.series.map((s) => (Object.assign(Object.assign({}, s), { timestamps: s.timestamps.slice(-60), values: s.values.slice(-60) }))) }) });
+    }
+    if (byteSize(next) <= maxPayloadBytes) {
+        return { context: withDiagnostic(next, truncatedDiag), ok: true };
+    }
+    const targetIndexName = next.service.indexName;
+    const stripSize = (i) => i.indexName === targetIndexName
+        ? i
+        : Object.assign(Object.assign({}, i), { itemCount: undefined, indexSizeBytes: undefined });
+    next = Object.assign(Object.assign({}, next), { table: Object.assign(Object.assign({}, next.table), { localSecondaryIndexes: next.table.localSecondaryIndexes.map(stripSize), globalSecondaryIndexes: next.table.globalSecondaryIndexes.map(stripSize) }) });
+    if (byteSize(next) <= maxPayloadBytes) {
+        return { context: withDiagnostic(next, truncatedDiag), ok: true };
+    }
+    if (next.cloudWatch) {
+        const priority = (s) => s.scope === 'operation' ? 0 : s.scope === 'table' ? 1 : 2;
+        const ordered = [...next.cloudWatch.series].sort((a, b) => priority(b) - priority(a));
+        while (ordered.length > 0 &&
+            byteSize(Object.assign(Object.assign({}, next), { cloudWatch: Object.assign(Object.assign({}, next.cloudWatch), { series: ordered }) })) > maxPayloadBytes) {
+            ordered.shift();
+        }
+        next = Object.assign(Object.assign({}, next), { cloudWatch: Object.assign(Object.assign({}, next.cloudWatch), { series: ordered }) });
+    }
+    if (byteSize(next) <= maxPayloadBytes) {
+        return { context: withDiagnostic(next, truncatedDiag), ok: true };
+    }
+    return { context: next, ok: false };
+}
+function withDiagnostic(context, d) {
+    return Object.assign(Object.assign({}, context), { collection: Object.assign(Object.assign({}, context.collection), { status: 'partial', diagnostics: [...context.collection.diagnostics, d] }) });
+}
+//# sourceMappingURL=DynamoDbPerformanceTuningProvider.js.map