@virjay/playscope-cocos 0.0.0-stage → 0.2.0

package/dist/cocos/index.js

@@ -0,0 +1,134 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CocosPlayScope = void 0;
+exports.init = init;
+const core_1 = require("../core");
+const game_v1_1 = require("../protocols/game-v1");
+const Storage_1 = require("./Storage");
+const XhrJsonTransport_1 = require("./XhrJsonTransport");
+__exportStar(require("../core"), exports);
+__exportStar(require("./Storage"), exports);
+__exportStar(require("./XhrJsonTransport"), exports);
+/** Host owns event semantics; this wrapper only schedules flush and releases its subscriptions. */
+class CocosPlayScope {
+    constructor(options, runtime) {
+        this.off = [];
+        this.elapsed = 0;
+        this.disposed = false;
+        this.revenueEncoder = options.adRevenueEncoder ?? game_v1_1.encodeGameV1AdRevenue;
+        this.client = options.collectionEnabled ? new core_1.PlayScopeClient(options, new Storage_1.CocosStorage(runtime.storage), runtime.transport ?? new XhrJsonTransport_1.XhrJsonTransport(), runtime.now) : null;
+        if (this.client && runtime.lifecycle) {
+            try {
+                this.off.push(runtime.lifecycle.onHide(() => { void this.flush(); }));
+                this.off.push(runtime.lifecycle.onShow(() => { void this.flush(); }));
+            }
+            catch (error) {
+                // Preserve the registration error while releasing any partially acquired resources.
+                try {
+                    this.dispose();
+                }
+                catch { /* All cleanup steps have already been attempted. */ }
+                throw error;
+            }
+        }
+    }
+    start() { if (!this.disposed) {
+        this.client?.start();
+        void this.flush();
+    } }
+    get installId() { return this.client?.installId ?? null; }
+    getDiagnostics() {
+        return this.client?.diagnostics ??
+            { pending: 0, rejected: 0, droppedEvents: 0, lastError: null, blocked: false, quarantined: 0,
+                pendingBytes: 0, quarantinedBytes: 0, maxQueueBytes: 0, persistence: 'snapshot', cleanupPending: false };
+    }
+    getQuarantinedEvents() { return this.client?.getQuarantinedEvents() ?? []; }
+    get status() {
+        if (this.client)
+            return this.client.status;
+        return { collection: this.disposed ? 'disposed' : 'disabled', delivery: this.disposed ? 'disposed' : 'disabled',
+            pendingDurability: 'persisted', retryAt: 0,
+            configuration: { state: this.disposed ? 'disposed' : 'disabled', nextAttemptAt: 0, lastError: null } };
+    }
+    track(name, properties = {}, context = {}) {
+        return this.trackWithResult(name, properties, context).status === 'accepted';
+    }
+    trackWithResult(name, properties = {}, context = {}) {
+        if (this.disposed)
+            return { status: 'disposed' };
+        return this.client?.trackWithResult(name, properties, context) ?? { status: 'collection_disabled' };
+    }
+    trackAdRevenue(fact, context = {}) {
+        return !this.disposed && !!this.client && (0, core_1.enqueueAdRevenue)(this.client, fact, context, this.revenueEncoder);
+    }
+    newSession() { if (!this.disposed)
+        this.client?.newSession(); }
+    /** Call from a persistent Cocos component's update(dt), in seconds. */
+    update(dt) {
+        if (this.disposed || !Number.isFinite(dt) || dt <= 0 || dt > 1)
+            return;
+        this.elapsed += dt;
+        if (this.elapsed >= 5) {
+            this.elapsed = 0;
+            void this.flush();
+        }
+    }
+    async flush() { if (!this.disposed)
+        await this.client?.flush(); }
+    flushWithResult() {
+        return this.client?.flushWithResult() ?? Promise.resolve(this.inactiveFlushResult());
+    }
+    retryUploads() {
+        return this.client?.retryUploads() ?? Promise.resolve(this.inactiveFlushResult());
+    }
+    refreshConfiguration() {
+        return this.client?.refreshConfiguration() ?? Promise.resolve({ status: this.disposed ? 'disposed' : 'disabled',
+            nextAttemptAt: 0, error: null });
+    }
+    inactiveFlushResult() {
+        return { status: this.disposed ? 'disposed' : 'collection_disabled', accepted: 0, rejected: 0, quarantined: 0,
+            pending: 0, durable: true, retryAt: 0, error: null };
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        let failed = false, firstError;
+        const cleanup = (release) => {
+            try {
+                release();
+            }
+            catch (error) {
+                if (!failed) {
+                    failed = true;
+                    firstError = error;
+                }
+            }
+        };
+        for (const off of this.off.splice(0))
+            cleanup(off);
+        cleanup(() => this.client?.dispose());
+        if (failed)
+            throw firstError;
+    }
+}
+exports.CocosPlayScope = CocosPlayScope;
+function init(options, runtime) {
+    const sdk = new CocosPlayScope(options, runtime);
+    sdk.start();
+    return sdk;
+}

package/dist/core/ClientOwnership.d.ts

@@ -0,0 +1,6 @@
+import type { StoragePort } from './types';
+export declare class PlayScopeOwnershipError extends Error {
+    readonly code = "duplicate_client";
+    constructor();
+}
+export declare function claimStorage(storage: StoragePort, key: string): () => void;

package/dist/core/ClientOwnership.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlayScopeOwnershipError = void 0;
+exports.claimStorage = claimStorage;
+// Symbol.for shares ownership across this package's ESM and CommonJS entries.
+// The registry covers one JS runtime, not other tabs or native processes.
+const registryKey = Symbol.for('playscope.storageOwners.v1');
+const runtime = globalThis;
+const owners = runtime[registryKey] ?? (runtime[registryKey] = new WeakMap());
+class PlayScopeOwnershipError extends Error {
+    constructor() {
+        super('PlayScope already has an active writer for this storage scope');
+        this.code = 'duplicate_client';
+        this.name = 'PlayScopeOwnershipError';
+    }
+}
+exports.PlayScopeOwnershipError = PlayScopeOwnershipError;
+function claimStorage(storage, key) {
+    const scope = storage.ownershipScope ?? storage;
+    let keys = owners.get(scope);
+    if (!keys) {
+        keys = new Map();
+        owners.set(scope, keys);
+    }
+    if (keys.has(key))
+        throw new PlayScopeOwnershipError();
+    const token = {};
+    keys.set(key, token);
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        if (keys.get(key) === token)
+            keys.delete(key);
+        if (!keys.size && owners.get(scope) === keys)
+            owners.delete(scope);
+    };
+}

package/dist/core/ClientScope.d.ts

@@ -0,0 +1,5 @@
+import type { ClientScope, PlayScopeOptions } from './types';
+import type { State } from './PersistentState';
+export declare function resolveClientScope(options: PlayScopeOptions): ClientScope;
+/** Never change an installation identity, token, queue, or storage key to repair a scope conflict. */
+export declare function bindClientScope(state: State, expected: ClientScope, existed: boolean, legacy?: ClientScope): void;

package/dist/core/ClientScope.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveClientScope = resolveClientScope;
+exports.bindClientScope = bindClientScope;
+const PersistentState_1 = require("./PersistentState");
+function resolveClientScope(options) {
+    const scope = { baseUrl: options.baseUrl, projectId: options.projectId,
+        environment: options.client.environment ?? 'production' };
+    return normalize(scope);
+}
+function normalize(scope) {
+    if (!scope || typeof scope.baseUrl !== 'string' || !scope.baseUrl.replace(/\/+$/, '') ||
+        typeof scope.projectId !== 'string' || !scope.projectId || !['production', 'test'].includes(scope.environment))
+        throw new TypeError('Invalid client scope');
+    return { baseUrl: scope.baseUrl.replace(/\/+$/, ''), projectId: scope.projectId, environment: scope.environment };
+}
+function equal(a, b) {
+    return a.baseUrl === b.baseUrl && a.projectId === b.projectId && a.environment === b.environment;
+}
+/** Never change an installation identity, token, queue, or storage key to repair a scope conflict. */
+function bindClientScope(state, expected, existed, legacy) {
+    if (state.scope) {
+        if (!equal(normalize(state.scope), expected))
+            throw new PersistentState_1.PlayScopeInitializationError('scope_mismatch');
+        return;
+    }
+    if (existed) {
+        if (!legacy)
+            throw new PersistentState_1.PlayScopeInitializationError('scope_migration_required');
+        if (!equal(normalize(legacy), expected))
+            throw new PersistentState_1.PlayScopeInitializationError('scope_mismatch');
+    }
+    state.scope = { ...expected };
+}

package/dist/core/ConfigurationSync.d.ts

@@ -0,0 +1,18 @@
+import type { ConfigurationContext, ConfigurationResult, ConfigurationStatus } from './types';
+/** Optional scheduler with its own in-flight task, failures and Retry-After budget. */
+export declare class ConfigurationSync {
+    private readonly resolve;
+    private readonly context;
+    private readonly now;
+    private task;
+    private nextAttemptAt;
+    private failures;
+    private lastError;
+    private disposed;
+    constructor(resolve: ((context: ConfigurationContext) => Promise<number>) | undefined, context: () => Promise<ConfigurationContext>, now: () => number);
+    get status(): ConfigurationStatus;
+    refresh(): Promise<ConfigurationResult>;
+    private result;
+    private run;
+    dispose(): void;
+}

package/dist/core/ConfigurationSync.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigurationSync = void 0;
+const HttpError_1 = require("./HttpError");
+/** Optional scheduler with its own in-flight task, failures and Retry-After budget. */
+class ConfigurationSync {
+    constructor(resolve, context, now) {
+        this.resolve = resolve;
+        this.context = context;
+        this.now = now;
+        this.task = null;
+        this.nextAttemptAt = 0;
+        this.failures = 0;
+        this.lastError = null;
+        this.disposed = false;
+    }
+    get status() {
+        return { state: this.disposed ? 'disposed' : !this.resolve ? 'disabled' : this.task ? 'syncing' :
+                this.lastError && this.now() < this.nextAttemptAt ? 'backoff' : 'idle',
+            nextAttemptAt: this.nextAttemptAt, lastError: this.lastError };
+    }
+    refresh() {
+        if (this.disposed)
+            return Promise.resolve(this.result('disposed'));
+        if (!this.resolve)
+            return Promise.resolve(this.result('disabled'));
+        if (this.task)
+            return this.task;
+        if (this.now() < this.nextAttemptAt)
+            return Promise.resolve(this.result('not_due'));
+        // Defer execution until task ownership is established, including synchronous host callbacks.
+        const task = Promise.resolve().then(() => this.run());
+        this.task = task;
+        void task.then(() => { if (this.task === task)
+            this.task = null; });
+        return task;
+    }
+    result(status) {
+        return { status, nextAttemptAt: this.nextAttemptAt, error: this.lastError };
+    }
+    async run() {
+        try {
+            const context = await this.context();
+            if (this.disposed)
+                return this.result('disposed');
+            const refresh = await this.resolve(context);
+            if (this.disposed)
+                return this.result('disposed');
+            this.nextAttemptAt = this.now() + Math.max(60, Math.min(86400, Number.isFinite(refresh) && refresh > 0 ? refresh : 3600)) * 1000;
+            this.failures = 0;
+            this.lastError = null;
+            return this.result('refreshed');
+        }
+        catch (error) {
+            if (this.disposed)
+                return this.result('disposed');
+            const http = error instanceof HttpError_1.PlayScopeHttpError ? error : null;
+            const storageUnavailable = error instanceof HttpError_1.StorageUnavailableError;
+            this.lastError = http ? `http_${http.status}` : storageUnavailable ? 'storage_unavailable' : 'configuration_error';
+            this.nextAttemptAt = this.now() + Math.max(http?.retryAfterMs ?? 0, Math.min(3600000, 60000 * 2 ** Math.min(this.failures++, 6)));
+            return this.result(storageUnavailable ? 'storage_unavailable' : 'failed');
+        }
+    }
+    dispose() { this.disposed = true; }
+}
+exports.ConfigurationSync = ConfigurationSync;

package/dist/core/FactEncoding.d.ts

@@ -0,0 +1,10 @@
+/** JSB-compatible UTF-8 accounting without TextEncoder. */
+export declare function utf8Bytes(value: string): number;
+/** Only immutable, SDK-owned snapshots may be cached here. */
+export declare class FactEncoding {
+    private readonly cache;
+    get(value: object): {
+        json: string;
+        bytes: number;
+    };
+}

package/dist/core/FactEncoding.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FactEncoding = void 0;
+exports.utf8Bytes = utf8Bytes;
+/** JSB-compatible UTF-8 accounting without TextEncoder. */
+function utf8Bytes(value) {
+    let bytes = 0;
+    for (const ch of value) {
+        const n = ch.codePointAt(0);
+        bytes += n <= 0x7f ? 1 : n <= 0x7ff ? 2 : n <= 0xffff ? 3 : 4;
+    }
+    return bytes;
+}
+/** Only immutable, SDK-owned snapshots may be cached here. */
+class FactEncoding {
+    constructor() {
+        this.cache = new WeakMap();
+    }
+    get(value) {
+        let encoded = this.cache.get(value);
+        if (!encoded) {
+            const json = JSON.stringify(value);
+            encoded = { json, bytes: utf8Bytes(json) };
+            this.cache.set(value, encoded);
+        }
+        return encoded;
+    }
+}
+exports.FactEncoding = FactEncoding;

package/dist/core/HttpError.d.ts

@@ -0,0 +1,10 @@
+export declare class PlayScopeHttpError extends Error {
+    readonly status: number;
+    readonly retryAfterMs: number;
+    readonly path?: string | undefined;
+    constructor(status: number, retryAfterMs?: number, path?: string | undefined);
+}
+/** Internal storage barrier, distinct from transport/protocol failures. */
+export declare class StorageUnavailableError extends Error {
+    constructor();
+}

package/dist/core/HttpError.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageUnavailableError = exports.PlayScopeHttpError = void 0;
+class PlayScopeHttpError extends Error {
+    constructor(status, retryAfterMs = 0, path) {
+        super(`PlayScope HTTP ${status}`);
+        this.status = status;
+        this.retryAfterMs = retryAfterMs;
+        this.path = path;
+    }
+}
+exports.PlayScopeHttpError = PlayScopeHttpError;
+/** Internal storage barrier, distinct from transport/protocol failures. */
+class StorageUnavailableError extends Error {
+    constructor() { super('storage_unavailable'); }
+}
+exports.StorageUnavailableError = StorageUnavailableError;

package/dist/core/OutboxStore.d.ts

@@ -0,0 +1,31 @@
+import type { StoragePort } from './types';
+import type { State } from './PersistentState';
+import { FactEncoding } from './FactEncoding';
+/** Copy-on-write segments and a single atomic manifest commit. The journal bounds failed-write garbage. */
+export declare class OutboxStore {
+    private readonly storage;
+    private readonly key;
+    private readonly encoding;
+    private segmented;
+    private segments;
+    private cleanupPending_;
+    private existed_;
+    private readonly prefix;
+    private readonly journalKey;
+    constructor(storage: StoragePort, key: string, mode: 'snapshot' | 'segmented' | undefined, encoding: FactEncoding);
+    private requireDeletion;
+    get mode(): 'snapshot' | 'segmented';
+    get cleanupPending(): boolean;
+    get hasStoredState(): boolean;
+    private read;
+    private decode;
+    private manifest;
+    private isSegmentKey;
+    load(now: () => number, restoreCache?: (value: unknown) => unknown): State;
+    private refs;
+    private write;
+    private remove;
+    private cleanup;
+    private partition;
+    save(state: State): void;
+}

package/dist/core/OutboxStore.js

@@ -0,0 +1,228 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutboxStore = void 0;
+const PersistentState_1 = require("./PersistentState");
+const FactEncoding_1 = require("./FactEncoding");
+const uuid_1 = require("./uuid");
+const KINDS = ['queue', 'quarantined'];
+const SEGMENT_BYTES = 32 * 1024;
+const SEGMENT_EVENTS = 32;
+function object(v) { return !!v && typeof v === 'object' && !Array.isArray(v); }
+function corrupt() { throw new PersistentState_1.PlayScopeInitializationError('state_corrupt'); }
+function checksum(value) {
+    let hash = 2166136261;
+    for (let i = 0; i < value.length; i++)
+        hash = Math.imul(hash ^ value.charCodeAt(i), 16777619);
+    return (hash >>> 0).toString(16);
+}
+/** Copy-on-write segments and a single atomic manifest commit. The journal bounds failed-write garbage. */
+class OutboxStore {
+    constructor(storage, key, mode, encoding) {
+        this.storage = storage;
+        this.key = key;
+        this.encoding = encoding;
+        this.segments = [];
+        this.cleanupPending_ = false;
+        this.existed_ = false;
+        if (mode !== undefined && mode !== 'snapshot' && mode !== 'segmented')
+            throw new TypeError('Invalid persistence mode');
+        this.segmented = mode === 'segmented';
+        if (this.segmented)
+            this.requireDeletion();
+        this.prefix = `${key}:outbox:v2:`;
+        this.journalKey = `${key}:outbox:journal:v2`;
+    }
+    requireDeletion() {
+        if (typeof this.storage.removeString !== 'function')
+            throw new PersistentState_1.PlayScopeInitializationError('storage_capability_missing');
+    }
+    get mode() { return this.segmented ? 'segmented' : 'snapshot'; }
+    get cleanupPending() { return this.cleanupPending_; }
+    get hasStoredState() { return this.existed_; }
+    read(key) {
+        try {
+            return this.storage.getString(key);
+        }
+        catch {
+            throw new PersistentState_1.PlayScopeInitializationError('storage_unavailable');
+        }
+    }
+    decode(raw) { try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return corrupt();
+    } }
+    manifest(raw) {
+        if (raw === null)
+            return null;
+        const value = this.decode(raw);
+        if (!object(value) || value.schemaVersion !== 2)
+            return null;
+        if (!object(value.outbox))
+            return corrupt();
+        const keys = new Set();
+        for (const kind of KINDS) {
+            const refs = value.outbox[kind];
+            if (!Array.isArray(refs))
+                return corrupt();
+            for (const ref of refs) {
+                if (!object(ref) || typeof ref.key !== 'string' || !this.isSegmentKey(ref.key, kind) || keys.has(ref.key) ||
+                    !Number.isSafeInteger(ref.count) || ref.count < 1 || ref.count > SEGMENT_EVENTS ||
+                    !Number.isSafeInteger(ref.bytes) || ref.bytes < 1 || typeof ref.checksum !== 'string')
+                    return corrupt();
+                keys.add(ref.key);
+            }
+        }
+        return value;
+    }
+    isSegmentKey(key, kind) {
+        if (!key.startsWith(this.prefix))
+            return false;
+        const suffix = key.slice(this.prefix.length);
+        return new RegExp(`^${kind ?? '(queue|quarantined)'}:[0-9a-f-]{36}$`, 'i').test(suffix);
+    }
+    load(now, restoreCache) {
+        const raw = this.read(this.key), manifest = this.manifest(raw);
+        this.existed_ = raw !== null;
+        if (!manifest)
+            return (0, PersistentState_1.parseState)(raw, now, restoreCache);
+        this.requireDeletion();
+        this.segmented = true;
+        const lists = { queue: [], quarantined: [] };
+        for (const kind of KINDS)
+            for (const ref of manifest.outbox[kind]) {
+                const payload = this.read(ref.key);
+                if (payload === null || (0, FactEncoding_1.utf8Bytes)(payload) !== ref.bytes || checksum(payload) !== ref.checksum)
+                    return corrupt();
+                const segment = this.decode(payload);
+                if (!object(segment) || segment.schemaVersion !== 2 || segment.kind !== kind ||
+                    !Array.isArray(segment.items) || segment.items.length !== ref.count || !segment.items.every(object))
+                    return corrupt();
+                lists[kind].push(...segment.items);
+                this.segments.push({ kind, ref, items: segment.items });
+            }
+        // Reuse the explicit v1 metadata/fact validator; no persisted fact is transformed by migration.
+        const state = (0, PersistentState_1.parseState)(JSON.stringify({ ...manifest, schemaVersion: 1, ...lists }), now, restoreCache);
+        // Bind descriptors to the validated objects returned by the legacy parser.
+        for (const kind of KINDS) {
+            let offset = 0;
+            for (const segment of this.segments.filter(segment => segment.kind === kind)) {
+                segment.items = state[kind].slice(offset, offset + segment.ref.count);
+                offset += segment.ref.count;
+            }
+        }
+        return state;
+    }
+    refs(manifest) {
+        return manifest ? KINDS.flatMap(kind => manifest.outbox[kind].map(ref => ref.key)) : [];
+    }
+    write(key, value) {
+        this.storage.setString(key, value);
+        this.storage.flush();
+        if (this.storage.getString(key) !== value)
+            throw new Error('storage_unavailable');
+    }
+    remove(key) {
+        this.storage.removeString(key);
+        this.storage.flush();
+        if (this.storage.getString(key) !== null)
+            throw new Error('storage_unavailable');
+    }
+    cleanup(keep) {
+        const raw = this.read(this.journalKey);
+        if (raw === null) {
+            this.cleanupPending_ = false;
+            return;
+        }
+        this.cleanupPending_ = true;
+        const journal = this.decode(raw);
+        if (!object(journal) || journal.schemaVersion !== 2 || !Array.isArray(journal.keys) ||
+            !journal.keys.every(key => typeof key === 'string' && this.isSegmentKey(key)))
+            return corrupt();
+        for (const key of journal.keys)
+            if (!keep.has(key))
+                this.remove(key);
+        this.remove(this.journalKey);
+        this.cleanupPending_ = false;
+    }
+    partition(kind, items) {
+        const old = this.segments.filter(segment => segment.kind === kind);
+        const byFirst = new Map(old.map(segment => [segment.items[0], segment]));
+        const segments = [], writes = new Map();
+        let index = 0;
+        const match = (at) => {
+            const segment = byFirst.get(items[at]);
+            return segment && segment.items.every((item, offset) => items[at + offset] === item) ? segment : undefined;
+        };
+        while (index < items.length) {
+            const previous = match(index);
+            // Rebuild a small tail when appending, so one extra fact does not create a new tiny segment.
+            if (previous && (previous !== old[old.length - 1] || index + previous.items.length === items.length || previous.items.length === SEGMENT_EVENTS ||
+                previous.ref.bytes >= SEGMENT_BYTES)) {
+                segments.push(previous);
+                index += previous.items.length;
+                continue;
+            }
+            const chunk = [], encoded = [];
+            let bytes = 0;
+            while (index < items.length && chunk.length < SEGMENT_EVENTS) {
+                if (chunk.length && match(index))
+                    break;
+                const fact = this.encoding.get(items[index]);
+                if (chunk.length && bytes + fact.bytes + 1 > SEGMENT_BYTES)
+                    break;
+                chunk.push(items[index++]);
+                encoded.push(fact.json);
+                bytes += fact.bytes + 1;
+            }
+            const payload = `{"schemaVersion":2,"kind":"${kind}","items":[${encoded.join(',')}]}`;
+            const ref = { key: `${this.prefix}${kind}:${(0, uuid_1.telemetryUuid)()}`, count: chunk.length,
+                bytes: (0, FactEncoding_1.utf8Bytes)(payload), checksum: checksum(payload) };
+            writes.set(ref.key, payload);
+            segments.push({ kind, ref, items: chunk });
+        }
+        return { segments, writes };
+    }
+    save(state) {
+        if (!this.segmented) {
+            this.write(this.key, JSON.stringify(state));
+            return;
+        }
+        try {
+            // An earlier failure may have committed the root before its read-back failed.
+            // Always consult the actual root before collecting any staged or retired key.
+            const committed = this.manifest(this.read(this.key));
+            this.cleanup(new Set(this.refs(committed)));
+            const next = KINDS.map(kind => this.partition(kind, state[kind]));
+            const segments = next.flatMap(part => part.segments);
+            const writes = new Map(next.flatMap(part => [...part.writes]));
+            const retained = new Set(segments.map(segment => segment.ref.key));
+            const garbage = this.refs(committed).filter(key => !retained.has(key));
+            if (writes.size || garbage.length) {
+                // Persist intent before the first new key, retaining every old referenced key until commit.
+                this.write(this.journalKey, JSON.stringify({ schemaVersion: 2, keys: [...writes.keys(), ...garbage] }));
+                this.cleanupPending_ = true;
+                for (const [key, value] of writes)
+                    this.write(key, value);
+            }
+            const { queue: _queue, quarantined: _quarantined, ...metadata } = state;
+            const root = JSON.stringify({ ...metadata, schemaVersion: 2, outbox: {
+                    queue: next[0].segments.map(segment => segment.ref), quarantined: next[1].segments.map(segment => segment.ref)
+                } });
+            this.write(this.key, root);
+            this.segments = segments;
+            // GC is not part of fact durability. A failed cleanup remains journaled and must finish before another write.
+            try {
+                this.cleanup(retained);
+            }
+            catch { /* Retry cleanup before the next persistence operation. */ }
+        }
+        catch (error) {
+            // Reconciliation after an uncertain commit must not reuse references that GC might have retired.
+            this.segments = [];
+            throw error;
+        }
+    }
+}
+exports.OutboxStore = OutboxStore;

package/dist/core/PersistentState.d.ts

@@ -0,0 +1,33 @@
+import type { EventFact, QuarantinedEvent, StoragePort, ClientScope } from './types';
+export interface State {
+    schemaVersion: 1;
+    installId: string;
+    firstOpenedAt: string;
+    firstOpenTracked: boolean;
+    sequence: number;
+    token: {
+        accessToken: string;
+        expiresAt: string;
+    } | null;
+    cache: unknown;
+    queue: EventFact[];
+    quarantined: QuarantinedEvent[];
+    rejected: {
+        eventId: string;
+        name: string;
+        code: string;
+    }[];
+    droppedEvents: number;
+    deduplicationKeys?: string[];
+    scope?: ClientScope;
+}
+export type InitializationErrorCode = 'storage_unavailable' | 'state_corrupt' | 'state_version_unsupported' | 'cache_restore_failed' | 'storage_capability_missing' | 'scope_mismatch' | 'scope_migration_required';
+/** Construction fails without overwriting stored data. Retry by constructing a new client. */
+export declare class PlayScopeInitializationError extends Error {
+    readonly code: InitializationErrorCode;
+    readonly retryable: boolean;
+    constructor(code: InitializationErrorCode);
+}
+export declare function isEventFact(value: unknown): value is EventFact;
+export declare function loadState(storage: StoragePort, key: string, now: () => number, restoreCache?: (value: unknown) => unknown): State;
+export declare function parseState(raw: string | null, now: () => number, restoreCache?: (value: unknown) => unknown): State;