@aplaytest/store-azure 0.1.0

package/dist/backend.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The four operations the store needs from object storage.
+ *
+ * Narrow on purpose. `ContainerClient` has around forty methods, and a store
+ * written against it can only be tested against a real account or an emulator
+ * — which means in practice it is tested in CI, once, by the pipeline it was
+ * supposed to make reliable. Everything interesting about this driver is the
+ * naming scheme, the windowing and the merge semantics; none of that is Azure,
+ * and all of it is exercised against an in-memory backend in unit tests.
+ */
+export interface BlobBackend {
+    /** Blob names under `prefix`, in whatever order the service returns them. */
+    list(prefix: string): AsyncIterable<string>;
+    /** Blob bytes, or null when it does not exist. Absence is never an error. */
+    get(name: string): Promise<Uint8Array | null>;
+    put(name: string, body: Uint8Array, contentType: string): Promise<void>;
+    remove(name: string): Promise<void>;
+}
+/** In-memory `BlobBackend`, for unit tests and dry-run store construction. */
+export declare class MemoryBlobBackend implements BlobBackend {
+    private readonly blobs;
+    list(prefix: string): AsyncIterable<string>;
+    get(name: string): Promise<Uint8Array | null>;
+    put(name: string, body: Uint8Array): Promise<void>;
+    remove(name: string): Promise<void>;
+    /** Test affordance: how many objects exist, without going through the store. */
+    get size(): number;
+    names(): string[];
+}
+//# sourceMappingURL=backend.d.ts.map

package/dist/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5C,6EAA6E;IAC7E,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAC9C,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED,8EAA8E;AAC9E,qBAAa,iBAAkB,YAAW,WAAW;IACnD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IAEhD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC;IAQ5C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAI7C,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC,gFAAgF;IAChF,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,KAAK,IAAI,MAAM,EAAE;CAGlB"}

package/dist/backend.js

@@ -0,0 +1,29 @@
+/** In-memory `BlobBackend`, for unit tests and dry-run store construction. */
+export class MemoryBlobBackend {
+    blobs = new Map();
+    async *list(prefix) {
+        // Sorted so a test asserting on ordering is asserting on the store's
+        // ordering rather than on Map insertion order.
+        for (const name of [...this.blobs.keys()].sort()) {
+            if (name.startsWith(prefix))
+                yield name;
+        }
+    }
+    async get(name) {
+        return this.blobs.get(name) ?? null;
+    }
+    async put(name, body) {
+        this.blobs.set(name, body);
+    }
+    async remove(name) {
+        this.blobs.delete(name);
+    }
+    /** Test affordance: how many objects exist, without going through the store. */
+    get size() {
+        return this.blobs.size;
+    }
+    names() {
+        return [...this.blobs.keys()].sort();
+    }
+}
+//# sourceMappingURL=backend.js.map

package/dist/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAmBA,8EAA8E;AAC9E,MAAM,OAAO,iBAAiB;IACX,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IAEvD,KAAK,CAAC,CAAC,IAAI,CAAC,MAAc;QACxB,qEAAqE;QACrE,+CAA+C;QAC/C,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YACjD,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;gBAAE,MAAM,IAAI,CAAC;QAC1C,CAAC;IACH,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,IAAY;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,IAAY,EAAE,IAAgB;QACtC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAY;QACvB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,gFAAgF;IAChF,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,KAAK;QACH,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACvC,CAAC;CACF"}

package/dist/blob-store.d.ts

@@ -0,0 +1,159 @@
+/**
+ * `HistoryStore` over an append-only log of run records in Azure Blob Storage.
+ *
+ * ── Why not the SQLite file that used to live here ──────────────────────────
+ * The previous shape downloaded one `history.sqlite`, ingested into it, and
+ * re-uploaded it under an `If-Match` precondition. It was small and it worked
+ * for one writer. What it could not do:
+ *
+ *   · TOLERATE OVERLAP. Two main-branch runs finishing together meant one lost
+ *     the conditional PUT. Failing is the good outcome; the workflow that
+ *     retried without re-downloading silently discarded the other run.
+ *   · STAY SMALL. Every run rewrote the whole database to append one record.
+ *   · WINDOW. Scoring reads 90 days; the file was all of history or nothing.
+ *
+ * Objects fix all three by construction — see `layout.ts` for how the name
+ * does the work. What is left is this: fetch a window, hand it to the shared
+ * `HistoryIndex`, and let the query semantics be identical to the SQL driver's
+ * because they are literally the same code.
+ *
+ * ── The read pattern this is shaped for ─────────────────────────────────────
+ * `analyzeAll` calls `attempts()` twice per (test, project) — a few hundred
+ * calls for a real suite. A store that went to the network per call would take
+ * minutes and cost a fortune in transactions. So the window is downloaded ONCE,
+ * lazily, on the first read, and every query after that is served from memory.
+ * Writes do not trigger a load: ingesting a shard is one PUT.
+ */
+import { type AzureBlobTarget, type HistoricalAttempt, type HistoryQuery, type HistoryStore, type RunRecord, type TestKey } from '@aplaytest/core';
+import type { BlobBackend } from './backend.js';
+/** Default read window. Matches `history.retainDays`, so reads see what prune keeps. */
+export declare const DEFAULT_WINDOW_DAYS = 90;
+/**
+ * Parallel downloads. Blob GETs are independent and mostly latency, so this is
+ * the difference between a 4-second load and a 90-second one; past ~32 the
+ * account starts throttling and the retries give the time back.
+ */
+export declare const DEFAULT_CONCURRENCY = 16;
+export interface BlobHistoryStoreOptions {
+    /** Key prefix inside the container. Normalised to end with `/`, or empty. */
+    readonly prefix?: string;
+    /** Days of history to read. `null` reads everything — slower every week. */
+    readonly windowDays?: number | null;
+    readonly concurrency?: number;
+    /** Injectable clock, so the window boundary is testable. */
+    readonly now?: () => number;
+    /**
+     * Score against the store; never write to it. See `AzureBlobTarget.readOnly`
+     * for why this is a mode rather than a permission error.
+     *
+     * `ingest()` still indexes the record locally, so the run being analysed is
+     * scored alongside the downloaded baseline — the PR sees its own results in
+     * context, it just does not leave them behind.
+     */
+    readonly readOnly?: boolean;
+}
+/** A blob a read could not use. Reported, never thrown — see `skipped`. */
+export interface SkippedBlob {
+    readonly name: string;
+    readonly reason: string;
+}
+export declare class BlobHistoryStore implements HistoryStore {
+    private readonly backend;
+    private readonly index;
+    private readonly prefix;
+    private readonly windowDays;
+    private readonly concurrency;
+    private readonly now;
+    private readonly readOnly;
+    /** Listing, once fetched. Answers `runCount` and `prune` with no downloads. */
+    private entries;
+    /** Whether the window's records are materialised in the index. */
+    private materialised;
+    private readonly skippedBlobs;
+    constructor(backend: BlobBackend, options?: BlobHistoryStoreOptions);
+    /**
+     * Blobs that exist but could not be read: truncated uploads, records written
+     * by a newer atest, anything hand-edited into the container.
+     *
+     * Surfaced rather than thrown, for the same reason `ingestDirectory` skips a
+     * bad file instead of failing the batch — one unreadable object among two
+     * thousand must not cost you the other 1,999. The CLI prints these, because
+     * a store that silently reads less than it should looks exactly like a store
+     * with nothing in it.
+     */
+    get skipped(): readonly SkippedBlob[];
+    /** `YYYY-MM-DD` before which blobs are outside the read window. */
+    private windowStart;
+    private ensureListing;
+    private ensureMaterialised;
+    /**
+     * One PUT. No read, no lock, no precondition — the name is derived from the
+     * run id and the shard, so a re-ingest overwrites exactly itself and two
+     * concurrent writers cannot collide.
+     */
+    ingest(run: RunRecord): Promise<void>;
+    attempts(query?: HistoryQuery): Promise<HistoricalAttempt[]>;
+    testKeys(): Promise<TestKey[]>;
+    /** Answered from the listing alone: the run id is in the blob name. */
+    runCount(): Promise<number>;
+    /**
+     * Delete runs that started before the cutoff.
+     *
+     * DAY GRANULARITY. Blobs are partitioned by date, so this deletes whole days
+     * strictly older than the cutoff's date and leaves the cutoff day alone. A
+     * retention window is a rolling approximation — trimming to the hour would
+     * mean downloading every record on the boundary day to read a timestamp
+     * already encoded, less precisely, in its name.
+     *
+     * Consider leaving retention to the account's lifecycle-management policy
+     * instead; terraform sets one up. This exists for the case where you want it
+     * to happen now, and for stores without a policy.
+     *
+     * One known edge: a sharded run that crosses midnight has shards in two
+     * partitions, and a cutoff landing between them prunes half of it. The run
+     * is at the far edge of the window and about to age out entirely, so the
+     * alternative — reading every record on the boundary day to recover a
+     * timestamp already in the name — buys a day of precision for a download.
+     */
+    prune(olderThanIso: string): Promise<number>;
+    close(): Promise<void>;
+}
+/** Build a store from a parsed `azblob://` URL. The path the CLI takes. */
+export interface OpenBlobHistoryStoreOptions extends Omit<BlobHistoryStoreOptions, 'prefix' | 'windowDays' | 'readOnly'> {
+    /**
+     * Shared-key credential, for an EMULATOR. Unset — the normal case — the
+     * driver uses `DefaultAzureCredential` and authenticates with Entra.
+     *
+     * This exists so the documented Azurite URL form is actually usable: the
+     * emulator has no Entra to federate against, so without a key the CLI can
+     * parse `http://127.0.0.1:10000/devstoreaccount1/…` and then fail to
+     * authenticate against it — a supported-looking target that never works.
+     *
+     * It does NOT weaken production. Keys are refused by the STORAGE ACCOUNT
+     * (`shared_access_key_enabled = false`), so what a client is willing to
+     * construct is irrelevant there; a key passed at a real account fails at the
+     * service. The control lives in Azure, not in this signature.
+     */
+    readonly accountKey?: string | undefined;
+}
+/**
+ * Build a {@link BlobHistoryStore} from a parsed `azblob://` URL.
+ *
+ * This is the path the CLI takes. Authentication is `DefaultAzureCredential`
+ * unless `accountKey` is set, which exists only so the Azurite emulator URL
+ * is actually usable (the emulator has no Entra to federate against).
+ *
+ * @param target - Parsed Azure Blob target (`parseHistoryUrl` of an `azblob://` URL).
+ * @param options - Optional emulator shared key and concurrency.
+ * @returns A store that implements `HistoryStore`.
+ *
+ * @example
+ * ```ts
+ * const target = parseHistoryUrl('azblob://myaccount/atest-history?readonly=1');
+ * if (target.kind !== 'azure-blob') throw new Error('expected azure-blob');
+ * const store = openBlobHistoryStore(target);
+ * const attempts = await store.attempts();
+ * ```
+ */
+export declare function openBlobHistoryStore(target: AzureBlobTarget, options?: OpenBlobHistoryStoreOptions): BlobHistoryStore;
+//# sourceMappingURL=blob-store.d.ts.map

package/dist/blob-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob-store.d.ts","sourceRoot":"","sources":["../src/blob-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAKH,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,OAAO,EACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAShD,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,MAAM,WAAW,uBAAuB;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AA2CD,qBAAa,gBAAiB,YAAW,YAAY;IAgBjD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAf1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgB;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IAEnC,+EAA+E;IAC/E,OAAO,CAAC,OAAO,CAAwB;IACvC,kEAAkE;IAClE,OAAO,CAAC,YAAY,CAAS;IAE7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;gBAG/B,OAAO,EAAE,WAAW,EACrC,OAAO,GAAE,uBAA4B;IASvC;;;;;;;;;OASG;IACH,IAAI,OAAO,IAAI,SAAS,WAAW,EAAE,CAEpC;IAED,mEAAmE;IACnE,OAAO,CAAC,WAAW;YAKL,aAAa;YAoBb,kBAAkB;IAqChC;;;;OAIG;IACG,MAAM,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBrC,QAAQ,CAAC,KAAK,GAAE,YAAiB,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAKhE,QAAQ,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAKpC,uEAAuE;IACjE,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAKjC;;;;;;;;;;;;;;;;;;OAkBG;IACG,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAsB5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7B;AAED,2EAA2E;AAC3E,MAAM,WAAW,2BACf,SAAQ,IAAI,CAAC,uBAAuB,EAAE,QAAQ,GAAG,YAAY,GAAG,UAAU,CAAC;IAC3E;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,2BAAgC,GACxC,gBAAgB,CAelB"}

package/dist/blob-store.js

@@ -0,0 +1,282 @@
+/**
+ * `HistoryStore` over an append-only log of run records in Azure Blob Storage.
+ *
+ * ── Why not the SQLite file that used to live here ──────────────────────────
+ * The previous shape downloaded one `history.sqlite`, ingested into it, and
+ * re-uploaded it under an `If-Match` precondition. It was small and it worked
+ * for one writer. What it could not do:
+ *
+ *   · TOLERATE OVERLAP. Two main-branch runs finishing together meant one lost
+ *     the conditional PUT. Failing is the good outcome; the workflow that
+ *     retried without re-downloading silently discarded the other run.
+ *   · STAY SMALL. Every run rewrote the whole database to append one record.
+ *   · WINDOW. Scoring reads 90 days; the file was all of history or nothing.
+ *
+ * Objects fix all three by construction — see `layout.ts` for how the name
+ * does the work. What is left is this: fetch a window, hand it to the shared
+ * `HistoryIndex`, and let the query semantics be identical to the SQL driver's
+ * because they are literally the same code.
+ *
+ * ── The read pattern this is shaped for ─────────────────────────────────────
+ * `analyzeAll` calls `attempts()` twice per (test, project) — a few hundred
+ * calls for a real suite. A store that went to the network per call would take
+ * minutes and cost a fortune in transactions. So the window is downloaded ONCE,
+ * lazily, on the first read, and every query after that is served from memory.
+ * Writes do not trigger a load: ingesting a shard is one PUT.
+ */
+import { gunzip, gzip } from 'node:zlib';
+import { promisify } from 'node:util';
+import { HistoryIndex, RUN_SCHEMA_VERSION, shardKeyOf, } from '@aplaytest/core';
+import { StorageSharedKeyCredential } from '@azure/storage-blob';
+import { AzureBlobBackend } from './azure-backend.js';
+import { parseRunBlobName, runBlobName, runsPrefix } from './layout.js';
+const gzipAsync = promisify(gzip);
+const gunzipAsync = promisify(gunzip);
+/** Default read window. Matches `history.retainDays`, so reads see what prune keeps. */
+export const DEFAULT_WINDOW_DAYS = 90;
+/**
+ * Parallel downloads. Blob GETs are independent and mostly latency, so this is
+ * the difference between a 4-second load and a 90-second one; past ~32 the
+ * account starts throttling and the retries give the time back.
+ */
+export const DEFAULT_CONCURRENCY = 16;
+const GZIP_MAGIC = [0x1f, 0x8b];
+function isGzip(bytes) {
+    return bytes[0] === GZIP_MAGIC[0] && bytes[1] === GZIP_MAGIC[1];
+}
+/**
+ * Run a bounded number of tasks at once, preserving nothing about order.
+ *
+ * `Promise.all` over 2,000 blobs opens 2,000 sockets and gets the account to
+ * throttle; a sequential loop turns a 4-second load into a 20-minute one.
+ */
+async function pool(items, limit, work) {
+    let cursor = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        for (;;) {
+            const index = cursor;
+            cursor += 1;
+            const item = items[index];
+            if (item === undefined)
+                return;
+            await work(item);
+        }
+    });
+    await Promise.all(workers);
+}
+function isRunRecord(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    return (record['schemaVersion'] === RUN_SCHEMA_VERSION &&
+        typeof record['runId'] === 'string' &&
+        record['runId'] !== '' &&
+        Array.isArray(record['attempts']));
+}
+export class BlobHistoryStore {
+    backend;
+    index = new HistoryIndex();
+    prefix;
+    windowDays;
+    concurrency;
+    now;
+    readOnly;
+    /** Listing, once fetched. Answers `runCount` and `prune` with no downloads. */
+    entries = null;
+    /** Whether the window's records are materialised in the index. */
+    materialised = false;
+    skippedBlobs = [];
+    constructor(backend, options = {}) {
+        this.backend = backend;
+        this.prefix = options.prefix ?? '';
+        this.windowDays = options.windowDays === undefined ? DEFAULT_WINDOW_DAYS : options.windowDays;
+        this.concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
+        this.now = options.now ?? Date.now;
+        this.readOnly = options.readOnly ?? false;
+    }
+    /**
+     * Blobs that exist but could not be read: truncated uploads, records written
+     * by a newer atest, anything hand-edited into the container.
+     *
+     * Surfaced rather than thrown, for the same reason `ingestDirectory` skips a
+     * bad file instead of failing the batch — one unreadable object among two
+     * thousand must not cost you the other 1,999. The CLI prints these, because
+     * a store that silently reads less than it should looks exactly like a store
+     * with nothing in it.
+     */
+    get skipped() {
+        return this.skippedBlobs;
+    }
+    /** `YYYY-MM-DD` before which blobs are outside the read window. */
+    windowStart() {
+        if (this.windowDays === null)
+            return null;
+        return new Date(this.now() - this.windowDays * 86_400_000).toISOString().slice(0, 10);
+    }
+    async ensureListing() {
+        if (this.entries !== null)
+            return this.entries;
+        const start = this.windowStart();
+        const found = [];
+        for await (const name of this.backend.list(runsPrefix(this.prefix))) {
+            const parsed = parseRunBlobName(this.prefix, name);
+            if (parsed === null)
+                continue;
+            if (start !== null && parsed.date < start)
+                continue;
+            found.push({ ...parsed, name });
+        }
+        // Sorted by name, which sorts by date then run id then shard. Metadata
+        // merging is last-writer-wins, so a stable order is the difference between
+        // a reproducible report and one that changes with the listing's paging.
+        found.sort((a, b) => a.name.localeCompare(b.name));
+        this.entries = found;
+        return found;
+    }
+    async ensureMaterialised() {
+        if (this.materialised)
+            return;
+        const entries = await this.ensureListing();
+        const pending = entries.filter(entry => !this.index.has(entry.runId, entry.shardKey));
+        await pool(pending, this.concurrency, async (entry) => {
+            const bytes = await this.backend.get(entry.name);
+            // Pruned between the listing and the download. Not an error.
+            if (bytes === null)
+                return;
+            let record;
+            try {
+                const json = isGzip(bytes)
+                    ? (await gunzipAsync(bytes)).toString('utf8')
+                    : new TextDecoder().decode(bytes);
+                record = JSON.parse(json);
+            }
+            catch (error) {
+                this.skippedBlobs.push({
+                    name: entry.name,
+                    reason: error instanceof Error ? error.message : 'unreadable',
+                });
+                return;
+            }
+            if (!isRunRecord(record)) {
+                this.skippedBlobs.push({
+                    name: entry.name,
+                    reason: `not a schemaVersion ${RUN_SCHEMA_VERSION} run record`,
+                });
+                return;
+            }
+            this.index.add(record);
+        });
+        this.materialised = true;
+    }
+    /**
+     * One PUT. No read, no lock, no precondition — the name is derived from the
+     * run id and the shard, so a re-ingest overwrites exactly itself and two
+     * concurrent writers cannot collide.
+     */
+    async ingest(run) {
+        const shardKey = shardKeyOf(run.shard);
+        const name = runBlobName(this.prefix, run.startedAt, run.runId, shardKey);
+        // Indexed either way: a pull request scores its own run against the trunk
+        // baseline. Read-only decides whether the record outlives the job.
+        this.index.add(run);
+        if (this.readOnly)
+            return;
+        const body = await gzipAsync(Buffer.from(JSON.stringify(run), 'utf8'));
+        await this.backend.put(name, new Uint8Array(body), 'application/json');
+        // Keep an already-fetched listing honest, so `runCount()` right after an
+        // ingest does not have to re-list to see what this process just wrote.
+        if (this.entries !== null && !this.entries.some(entry => entry.name === name)) {
+            const parsed = parseRunBlobName(this.prefix, name);
+            if (parsed !== null)
+                this.entries.push({ ...parsed, name });
+        }
+    }
+    async attempts(query = {}) {
+        await this.ensureMaterialised();
+        return this.index.attempts(query);
+    }
+    async testKeys() {
+        await this.ensureMaterialised();
+        return this.index.testKeys();
+    }
+    /** Answered from the listing alone: the run id is in the blob name. */
+    async runCount() {
+        const entries = await this.ensureListing();
+        return new Set(entries.map(entry => entry.runId)).size;
+    }
+    /**
+     * Delete runs that started before the cutoff.
+     *
+     * DAY GRANULARITY. Blobs are partitioned by date, so this deletes whole days
+     * strictly older than the cutoff's date and leaves the cutoff day alone. A
+     * retention window is a rolling approximation — trimming to the hour would
+     * mean downloading every record on the boundary day to read a timestamp
+     * already encoded, less precisely, in its name.
+     *
+     * Consider leaving retention to the account's lifecycle-management policy
+     * instead; terraform sets one up. This exists for the case where you want it
+     * to happen now, and for stores without a policy.
+     *
+     * One known edge: a sharded run that crosses midnight has shards in two
+     * partitions, and a cutoff landing between them prunes half of it. The run
+     * is at the far edge of the window and about to age out entirely, so the
+     * alternative — reading every record on the boundary day to recover a
+     * timestamp already in the name — buys a day of precision for a download.
+     */
+    async prune(olderThanIso) {
+        if (this.readOnly) {
+            throw new Error('This store is open read-only, so prune would delete nothing and report success.\n' +
+                '  Retention is a main-branch operation: drop ?readonly=1 from the URL, and expect\n' +
+                '  the identity to hold "Storage Blob Data Contributor".');
+        }
+        const entries = await this.ensureListing();
+        const cutoff = olderThanIso.slice(0, 10);
+        const doomed = entries.filter(entry => entry.date < cutoff);
+        await pool(doomed, this.concurrency, entry => this.backend.remove(entry.name));
+        const removedNames = new Set(doomed.map(entry => entry.name));
+        this.entries = entries.filter(entry => !removedNames.has(entry.name));
+        this.index.prune(`${cutoff}T00:00:00.000Z`);
+        return new Set(doomed.map(entry => entry.runId)).size;
+    }
+    async close() {
+        this.index.clear();
+        this.entries = null;
+        this.materialised = false;
+    }
+}
+/**
+ * Build a {@link BlobHistoryStore} from a parsed `azblob://` URL.
+ *
+ * This is the path the CLI takes. Authentication is `DefaultAzureCredential`
+ * unless `accountKey` is set, which exists only so the Azurite emulator URL
+ * is actually usable (the emulator has no Entra to federate against).
+ *
+ * @param target - Parsed Azure Blob target (`parseHistoryUrl` of an `azblob://` URL).
+ * @param options - Optional emulator shared key and concurrency.
+ * @returns A store that implements `HistoryStore`.
+ *
+ * @example
+ * ```ts
+ * const target = parseHistoryUrl('azblob://myaccount/atest-history?readonly=1');
+ * if (target.kind !== 'azure-blob') throw new Error('expected azure-blob');
+ * const store = openBlobHistoryStore(target);
+ * const attempts = await store.attempts();
+ * ```
+ */
+export function openBlobHistoryStore(target, options = {}) {
+    const backend = new AzureBlobBackend({
+        serviceUrl: target.serviceUrl,
+        container: target.container,
+        ...(options.accountKey === undefined
+            ? {}
+            : { credential: new StorageSharedKeyCredential(target.account, options.accountKey) }),
+    });
+    return new BlobHistoryStore(backend, {
+        ...options,
+        prefix: target.prefix,
+        // `?window=` on the URL wins; unset means the default, never "everything".
+        windowDays: target.windowDays ?? DEFAULT_WINDOW_DAYS,
+        readOnly: target.readOnly,
+    });
+}
+//# sourceMappingURL=blob-store.js.map

package/dist/blob-store.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @aplaytest/store-azure — run history in Azure Blob Storage.
+ *
+ * Split out of `@aplaytest/core` deliberately. Core's contract is "no Playwright,
+ * no network, no model", and it is the package every consumer installs,
+ * including the reporter that loads inside the test process. Putting an 8 MB
+ * SDK and a credential chain behind that import would make every Playwright
+ * run pay for a feature only the analyze job uses.
+ *
+ * Install it alongside the CLI where history has to outlive the run:
+ *
+ *   npm i -D @aplaytest/cli @aplaytest/store-azure
+ *   aplaytest history ingest --db azblob://<account>/atest-history --runs .atest/runs
+ */
+export { BlobHistoryStore, openBlobHistoryStore, DEFAULT_WINDOW_DAYS, DEFAULT_CONCURRENCY } from './blob-store.js';
+export type { BlobHistoryStoreOptions, OpenBlobHistoryStoreOptions, SkippedBlob, } from './blob-store.js';
+export { AzureBlobBackend } from './azure-backend.js';
+export type { AzureBlobBackendOptions } from './azure-backend.js';
+export { MemoryBlobBackend } from './backend.js';
+export type { BlobBackend } from './backend.js';
+export { LAYOUT_VERSION, LayoutError, encodeSegment, decodeSegment, partitionOf, runBlobName, parseRunBlobName, runsPrefix, } from './layout.js';
+export type { RunBlobName } from './layout.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACnH,YAAY,EACV,uBAAuB,EACvB,2BAA2B,EAC3B,WAAW,GACZ,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAElE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EACL,cAAc,EACd,WAAW,EACX,aAAa,EACb,aAAa,EACb,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @aplaytest/store-azure — run history in Azure Blob Storage.
+ *
+ * Split out of `@aplaytest/core` deliberately. Core's contract is "no Playwright,
+ * no network, no model", and it is the package every consumer installs,
+ * including the reporter that loads inside the test process. Putting an 8 MB
+ * SDK and a credential chain behind that import would make every Playwright
+ * run pay for a feature only the analyze job uses.
+ *
+ * Install it alongside the CLI where history has to outlive the run:
+ *
+ *   npm i -D @aplaytest/cli @aplaytest/store-azure
+ *   aplaytest history ingest --db azblob://<account>/atest-history --runs .atest/runs
+ */
+export { BlobHistoryStore, openBlobHistoryStore, DEFAULT_WINDOW_DAYS, DEFAULT_CONCURRENCY } from './blob-store.js';
+export { AzureBlobBackend } from './azure-backend.js';
+export { MemoryBlobBackend } from './backend.js';
+export { LAYOUT_VERSION, LayoutError, encodeSegment, decodeSegment, partitionOf, runBlobName, parseRunBlobName, runsPrefix, } from './layout.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAOnH,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGjD,OAAO,EACL,cAAc,EACd,WAAW,EACX,aAAa,EACb,aAAa,EACb,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,UAAU,GACX,MAAM,aAAa,CAAC"}

package/dist/layout.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The blob naming scheme — the whole concurrency story, encoded in a path.
+ *
+ * The store this replaces was one SQLite file on a blob: download it, ingest,
+ * upload it back under an ETag precondition. That works exactly until two runs
+ * overlap, at which point the loser either fails the step or discards the
+ * winner's attempts, and it re-uploads the entire history to record thirty
+ * seconds of it.
+ *
+ * Here a run record is an object and the container is an append-only log:
+ *
+ *   <prefix>v1/runs/2026/08/30/<runId>/<shard>.json.gz
+ *
+ * Three properties follow directly from the name, with no locking:
+ *
+ *   · IDEMPOTENT. A re-ingested shard computes the same name and overwrites
+ *     itself. The scoped-delete and UPSERT gymnastics the SQL driver needs to
+ *     avoid double-counting are a naming rule here.
+ *   · CONCURRENT. Two shards of one run, and two overlapping main-branch runs,
+ *     write different names. Nothing races, so nothing needs a precondition.
+ *   · CHEAP TO WINDOW. The date is in the path, so a 90-day read filters the
+ *     LISTING and downloads only what it will score, and the run id is in the
+ *     path, so counting runs needs no downloads at all.
+ *
+ * All pure string work: no client, no credential, no network.
+ */
+/** Bumped only for a change no existing reader can parse. Old prefixes stay readable. */
+export declare const LAYOUT_VERSION = "v1";
+export declare function encodeSegment(value: string): string;
+export declare function decodeSegment(value: string): string;
+export declare class LayoutError extends Error {
+    constructor(message: string);
+}
+/**
+ * The date partition a run belongs to, taken from `startedAt`.
+ *
+ * Thrown rather than defaulted. A record whose timestamp cannot be read has no
+ * place in a time-windowed store: filed under today it would look current
+ * forever and never prune, and filed under the epoch it would vanish from
+ * every window. `ingestDirectory` catches this and reports the file as
+ * skipped, which is the visible failure the silent ones are worth trading for.
+ */
+export declare function partitionOf(startedAt: string): string;
+export interface RunBlobName {
+    readonly runId: string;
+    readonly shardKey: string;
+    /** `YYYY-MM-DD`, so it compares against an ISO timestamp with `<`. */
+    readonly date: string;
+}
+export declare function runBlobName(prefix: string, startedAt: string, runId: string, shardKey: string): string;
+/** Everything a listing needs to answer, so the common queries need no downloads. */
+export declare function parseRunBlobName(prefix: string, name: string): RunBlobName | null;
+/** Prefix every run blob shares, so a listing can skip anything else in the container. */
+export declare function runsPrefix(prefix: string): string;
+//# sourceMappingURL=layout.d.ts.map

package/dist/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,yFAAyF;AACzF,eAAO,MAAM,cAAc,OAAO,CAAC;AAcnC,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAYnD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWnD;AAED,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAI5B;AAID;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQrD;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GACf,MAAM,CAER;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAkBjF;AAED,0FAA0F;AAC1F,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjD"}