@duckcodeailabs/dql-agent 1.14.1 → 1.14.3-rc.1

package/dist/ask-observability/store.d.ts

@@ -0,0 +1,130 @@
+import type { AskTraceDataV1, AskTraceEnvelopeV1, AskTraceExportReceiptV1, AskTraceListQueryV1, AskTraceListResponseV1, AskTraceSpanV1, AskTraceStoreStatusV1, CandidateDecisionV1, AskTraceLinkV1 } from './types.js';
+export declare const DEFAULT_ASK_TRACE_DETAIL_LIMIT = 500;
+export declare const DEFAULT_ASK_TRACE_SUMMARY_LIMIT = 2000;
+export declare const DEFAULT_ASK_TRACE_DETAIL_MAX_AGE_MS: number;
+export declare const DEFAULT_ASK_TRACE_SUMMARY_MAX_AGE_MS: number;
+export declare const DEFAULT_ASK_TRACE_MAX_DB_BYTES: number;
+export declare const DEFAULT_ASK_TRACE_MAX_DETAIL_BYTES: number;
+export declare const DEFAULT_ASK_TRACE_MAX_SPANS = 512;
+export declare const DEFAULT_ASK_TRACE_MAX_CANDIDATES = 1024;
+/**
+ * Bounded producer limits. The observer enforces detail/candidate/span caps
+ * synchronously so a rejected record cannot perturb Ask; adapters may use
+ * these public bounds for their own batching without widening persistence.
+ */
+export declare const DEFAULT_ASK_TRACE_QUEUE_CAP = 4096;
+export declare const DEFAULT_ASK_TRACE_FLUSH_BATCH = 128;
+export declare const DEFAULT_ASK_TRACE_FLUSH_INTERVAL_MS = 25;
+export interface AskTraceStoreOptions {
+    path: string;
+    maxDetailedTraces?: number;
+    maxSummaryTraces?: number;
+    detailMaxAgeMs?: number;
+    summaryMaxAgeMs?: number;
+    maxDbBytes?: number;
+    maxTraceDetailBytes?: number;
+    maxSpansPerTrace?: number;
+    maxCandidateDecisionsPerTrace?: number;
+    queueCap?: number;
+    flushBatchSize?: number;
+    flushIntervalMs?: number;
+    busyTimeoutMs?: number;
+    /** Tests and CLIs use a read-only WAL observer without creating files. */
+    readOnly?: boolean;
+}
+export interface AskTraceStoreWriteResult {
+    accepted: boolean;
+    dropped?: 'span_cap' | 'candidate_cap' | 'detail_cap' | 'store_cap' | 'queue_cap' | 'unsafe_payload' | 'unavailable';
+}
+/**
+ * Separate, local SQLite store.  Its failures are intentionally surfaced as a
+ * status to the observer/API, never thrown into Ask execution.
+ */
+export declare class AskTraceSqliteStoreV1 {
+    private db;
+    private readonly options;
+    private unavailableReason;
+    private readonly queue;
+    private readonly queuedByKey;
+    private readonly accounting;
+    /** Drops waiting to be folded into the next local persistence transaction. */
+    private readonly deferredDrops;
+    /** Lifetime drop counts remain available after a batch has persisted them. */
+    private readonly droppedTotals;
+    /** Final receipts join their final detail batch in one SQLite transaction. */
+    private readonly pendingFinalizations;
+    /** Refreshed only at lifecycle/flush boundaries, never on an Ask producer call. */
+    private databaseAtCap;
+    private flushTimer;
+    private prepared;
+    /** Reused multi-row statements remove one native boundary per recorded span. */
+    private readonly spanBatchStatements;
+    private readonly candidateBatchStatements;
+    private readonly linkBatchStatements;
+    /** Cached at open/migration so observer creation does not issue a pragma. */
+    private schemaVersion;
+    /** Completed persisted rows, refreshed after retention or at store open. */
+    private detailedTraceCount;
+    private summaryTraceCount;
+    private readonly liveTraceIds;
+    /** Age retention is checked at lifecycle boundaries, not for every Ask. */
+    private nextRetentionCheckAt;
+    constructor(options: AskTraceStoreOptions);
+    status(): AskTraceStoreStatusV1;
+    begin(envelope: AskTraceEnvelopeV1): AskTraceStoreWriteResult;
+    appendSpan(span: AskTraceSpanV1): AskTraceStoreWriteResult;
+    appendCandidate(candidate: CandidateDecisionV1): AskTraceStoreWriteResult;
+    appendLink(link: AskTraceLinkV1): AskTraceStoreWriteResult;
+    finalize(envelope: AskTraceEnvelopeV1): AskTraceStoreWriteResult;
+    markPartial(traceId: string, extraDropped?: number): void;
+    get(traceId: string): AskTraceDataV1 | undefined;
+    getByRun(runId: string): AskTraceDataV1 | undefined;
+    list(input?: AskTraceListQueryV1): AskTraceListResponseV1;
+    recordExportReceipt(traceId: string, receipt: AskTraceExportReceiptV1): void;
+    /** Number of writes waiting for the bounded local persistence batch. */
+    pendingWriteCount(): number;
+    /** Deferred drops are folded into the final compact trace receipt. */
+    droppedRecordCount(traceId: string): number;
+    /**
+     * Flush queued trace detail synchronously at a lifecycle/read boundary. Ask
+     * event production itself remains batched by `enqueue`; this method exists so
+     * a finalized run, CLI inspection, or shutdown never leaves a half-written
+     * local receipt behind.
+     */
+    flushNow(): void;
+    close(): void;
+    private accountFor;
+    private enqueue;
+    /** Finalization may only join a batch after every earlier trace record is in it. */
+    private hasQueuedWriteForTrace;
+    private scheduleFlush;
+    private flushBatch;
+    private writeSpanBatch;
+    private writeCandidateBatch;
+    private writeLinkBatch;
+    private batchStatement;
+    private open;
+    private migrate;
+    private prepareStatements;
+    private refreshRetentionCounts;
+    private maybeEnforceRetention;
+    private drop;
+    /**
+     * Keep producer-side loss accounting entirely in memory. The next bounded
+     * batch marks the trace partial; no synchronous UPDATE is issued from an
+     * Ask/tool/provider callback.
+     */
+    private recordDrop;
+    private summaryForRow;
+    private envelopeForRow;
+    private dataForRow;
+    private spanForRow;
+    private finalizeInterrupted;
+    private enforceRetention;
+    private trip;
+    private isDatabaseAtCap;
+    /** File-system stats are intentionally confined to lifecycle/flush work. */
+    private refreshCapacityState;
+}
+export declare function defaultAskTraceSqlitePath(projectRoot: string): string;
+//# sourceMappingURL=store.d.ts.map

package/dist/ask-observability/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/ask-observability/store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAEV,cAAc,EACd,kBAAkB,EAClB,uBAAuB,EAEvB,mBAAmB,EACnB,sBAAsB,EAEtB,cAAc,EACd,qBAAqB,EAErB,mBAAmB,EACnB,cAAc,EACf,MAAM,YAAY,CAAC;AAIpB,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAClD,eAAO,MAAM,+BAA+B,OAAQ,CAAC;AACrD,eAAO,MAAM,mCAAmC,QAA4B,CAAC;AAC7E,eAAO,MAAM,oCAAoC,QAA6B,CAAC;AAC/E,eAAO,MAAM,8BAA8B,QAAoB,CAAC;AAChE,eAAO,MAAM,kCAAkC,QAAkB,CAAC;AAClE,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAC/C,eAAO,MAAM,gCAAgC,OAAQ,CAAC;AACtD;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AACjD,eAAO,MAAM,6BAA6B,MAAM,CAAC;AACjD,eAAO,MAAM,mCAAmC,KAAK,CAAC;AAEtD,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6BAA6B,CAAC,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,UAAU,GAAG,eAAe,GAAG,YAAY,GAAG,WAAW,GAAG,WAAW,GAAG,gBAAgB,GAAG,aAAa,CAAC;CACtH;AAkED;;;GAGG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,EAAE,CAAgC;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8G;IACtI,OAAO,CAAC,iBAAiB,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuC;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2C;IACtE,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAA+C;IACpF,mFAAmF;IACnF,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,UAAU,CAA4C;IAC9D,OAAO,CAAC,QAAQ,CAAyC;IACzD,gFAAgF;IAChF,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAyC;IAC7E,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAyC;IAClF,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAyC;IAC7E,6EAA6E;IAC7E,OAAO,CAAC,aAAa,CAAK;IAC1B,4EAA4E;IAC5E,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,2EAA2E;IAC3E,OAAO,CAAC,oBAAoB,CAAK;gBAErB,OAAO,EAAE,oBAAoB;IAoBzC,MAAM,IAAI,qBAAqB;IAU/B,KAAK,CAAC,QAAQ,EAAE,kBAAkB,GAAG,wBAAwB;IA8D7D,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,wBAAwB;IA0C1D,eAAe,CAAC,SAAS,EAAE,mBAAmB,GAAG,wBAAwB;IAkCzE,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,wBAAwB;IAoB1D,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,GAAG,wBAAwB;IA8BhE,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,SAAI,GAAG,IAAI;IAKpD,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAOhD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAOnD,IAAI,CAAC,KAAK,GAAE,mBAAwB,GAAG,sBAAsB;IAsD7D,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB,GAAG,IAAI;IAW5E,wEAAwE;IACxE,iBAAiB,IAAI,MAAM;IAI3B,sEAAsE;IACtE,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAI3C;;;;;OAKG;IACH,QAAQ,IAAI,IAAI;IAOhB,KAAK,IAAI,IAAI;IAcb,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,OAAO;IA6Bf,oFAAoF;IACpF,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,aAAa;IAiBrB,OAAO,CAAC,UAAU;IAoGlB,OAAO,CAAC,cAAc;IAmBtB,OAAO,CAAC,mBAAmB;IAqB3B,OAAO,CAAC,cAAc;IAoBtB,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,IAAI;IA0DZ,OAAO,CAAC,OAAO;IA0Gf,OAAO,CAAC,iBAAiB;IA4CzB,OAAO,CAAC,sBAAsB;IAY9B,OAAO,CAAC,qBAAqB;IAa7B,OAAO,CAAC,IAAI;IAKZ;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,cAAc;IAiCtB,OAAO,CAAC,UAAU;IAqBlB,OAAO,CAAC,UAAU;IAkBlB,OAAO,CAAC,mBAAmB;IAmB3B,OAAO,CAAC,gBAAgB;IAuDxB,OAAO,CAAC,IAAI;IAcZ,OAAO,CAAC,eAAe;IAWvB,4EAA4E;IAC5E,OAAO,CAAC,oBAAoB;CAG7B;AAED,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAErE"}