@neontechspace/fluxerly 1000.0.0-nightly.12

package/dist/internal/transport/user-agent.js

@@ -0,0 +1,42 @@
+/**
+ * The SDK's default User-Agent: Product token, installed version and homepage from the package manifest.
+ * Invariant: The manifest is read at most once, on the first request rather than at import, and a missing or malformed
+ * manifest only removes the version or homepage comment from the value.
+ * Implements [SDK contracts: Connection and recovery](/docs/SDK-CONTRACTS.md#connection-and-recovery)
+ */
+import { readFileSync } from "node:fs";
+import { record } from "../decode/primitives.js";
+import { sdkVersion } from "../logging.js";
+/** Longest caller-supplied User-Agent */
+export const userAgentMaxLength = 512;
+let cached;
+/** The package homepage, or undefined when the manifest cannot supply an HTTPS URL */
+function homepage() {
+    try {
+        const manifest = JSON.parse(readFileSync(new URL("../../../package.json", import.meta.url), "utf8"));
+        const value = record(manifest) ? manifest.homepage : undefined;
+        return typeof value === "string" && /^https:\/\/[\x21-\x7e]+$/.test(value) ? value : undefined;
+    }
+    catch {
+        // allow-silent: A missing manifest only removes the homepage comment from the User-Agent
+        return undefined;
+    }
+}
+/** `Fluxerly.js/<version> (+<homepage>)`, read once from the SDK manifest */
+export function defaultUserAgent() {
+    if (cached !== undefined)
+        return cached;
+    const version = sdkVersion();
+    const home = homepage();
+    cached = `Fluxerly.js/${/^[\x21-\x7e]+$/.test(version) ? version : "unknown"}${home === undefined ? "" : ` (+${home})`}`;
+    return cached;
+}
+/** Whether a caller value is a usable User-Agent: Printable ASCII, bounded, without surrounding spaces */
+export function validUserAgent(value) {
+    return (typeof value === "string" &&
+        value.length >= 1 &&
+        value.length <= userAgentMaxLength &&
+        /^[\x20-\x7e]+$/.test(value) &&
+        value.trim() === value);
+}
+//# sourceMappingURL=user-agent.js.map

package/dist/internal/transport/user-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-agent.js","sourceRoot":"","sources":["../../../src/internal/transport/user-agent.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAE1C,yCAAyC;AACzC,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAA;AAErC,IAAI,MAA0B,CAAA;AAE9B,sFAAsF;AACtF,SAAS,QAAQ;IACb,IAAI,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,uBAAuB,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAY,CAAA;QAC/G,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAA;QAC9D,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,0BAA0B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;IAClG,CAAC;IAAC,MAAM,CAAC;QACL,yFAAyF;QACzF,OAAO,SAAS,CAAA;IACpB,CAAC;AACL,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,gBAAgB;IAC5B,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAA;IACvC,MAAM,OAAO,GAAG,UAAU,EAAE,CAAA;IAC5B,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAA;IACvB,MAAM,GAAG,eAAe,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,GAAG,EAAE,CAAA;IACxH,OAAO,MAAM,CAAA;AACjB,CAAC;AAED,0GAA0G;AAC1G,MAAM,UAAU,cAAc,CAAC,KAAc;IACzC,OAAO,CACH,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,CAAC,MAAM,IAAI,CAAC;QACjB,KAAK,CAAC,MAAM,IAAI,kBAAkB;QAClC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC;QAC5B,KAAK,CAAC,IAAI,EAAE,KAAK,KAAK,CACzB,CAAA;AACL,CAAC"}

package/dist/internal/uploads.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Presigned attachment upload plans.
+ * Invariant: A plan authorizes individual destinations without sending bot credentials to them. Inline fallback is limited to a
+ * disabled presigned-upload feature or its explicit planning rejection, not a failed PUT or an uncertain message request.
+ * Failed operations may leave provider-owned temporary uploads, and cancellation cannot roll back a dispatched message.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { FilePart } from "./attachments.js";
+export type UploadPlan = {
+    id: number;
+    filename: string;
+    contentType: string;
+    key: string;
+    uploadId?: string;
+    parts: {
+        url: string;
+        offset: number;
+        size: number;
+    }[];
+};
+/** Validate the complete plan before dispatching any file bytes. Unknown response properties are discarded */
+export declare function decodeUploadPlans(value: unknown, files: readonly FilePart[], allowInsecure: boolean): UploadPlan[] | undefined;
+//# sourceMappingURL=uploads.d.ts.map

package/dist/internal/uploads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploads.d.ts","sourceRoot":"","sources":["../../src/internal/uploads.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAGhD,MAAM,MAAM,UAAU,GAAG;IACrB,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CACzD,CAAA;AAsBD,8GAA8G;AAC9G,wBAAgB,iBAAiB,CAC7B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,aAAa,EAAE,OAAO,GACvB,UAAU,EAAE,GAAG,SAAS,CAkE1B"}

package/dist/internal/uploads.js

@@ -0,0 +1,89 @@
+import { record } from "./decode/primitives.js";
+const text = (value, max) => typeof value === "string" && value.length > 0 && value.length <= max;
+function destination(value, allowInsecure) {
+    if (!text(value, 8192))
+        return false;
+    try {
+        const url = new URL(value);
+        // Signed plan URLs are authenticated upload capabilities. Preserve their query, do not send bot auth, and never follow redirects
+        return ((url.protocol === "https:" || (allowInsecure && url.protocol === "http:")) &&
+            url.username === "" &&
+            url.password === "" &&
+            url.hash === "");
+    }
+    catch {
+        // allow-silent: An unparsable upload URL is rejected by the caller
+        return false;
+    }
+}
+/** Validate the complete plan before dispatching any file bytes. Unknown response properties are discarded */
+export function decodeUploadPlans(value, files, allowInsecure) {
+    if (!record(value) || !Array.isArray(value.attachments) || value.attachments.length !== files.length)
+        return undefined;
+    const plans = [];
+    const keys = new Set();
+    const urls = new Set();
+    for (const file of files) {
+        const matches = value.attachments.filter((item) => record(item) && item.id === file.id);
+        if (matches.length !== 1)
+            return undefined;
+        const item = matches[0];
+        if (!record(item) ||
+            item.file_size !== file.size ||
+            !text(item.filename, 255) ||
+            // oxlint-disable-next-line no-control-regex -- rejects control characters in provider filenames
+            /[\x00-\x1f\x7f/\\]/.test(item.filename) ||
+            !text(item.content_type, 255) ||
+            !/^[\x20-\x7e]+$/.test(item.content_type) ||
+            !text(item.upload_filename, 4096) ||
+            keys.has(item.upload_filename))
+            return undefined;
+        keys.add(item.upload_filename);
+        const plan = {
+            id: file.id,
+            filename: item.filename,
+            contentType: item.content_type,
+            key: item.upload_filename,
+            parts: [],
+        };
+        if (item.upload_mode === "singlepart") {
+            if (!destination(item.upload_url, allowInsecure) || item.file_size > 10_485_760)
+                return undefined;
+            plan.parts.push({ url: item.upload_url, offset: 0, size: file.size });
+        }
+        else if (item.upload_mode === "multipart") {
+            if (!text(item.upload_id, 1024) ||
+                typeof item.part_size !== "number" ||
+                !Number.isSafeInteger(item.part_size) ||
+                item.part_size <= 0 ||
+                item.part_size > 52_428_800 ||
+                !Array.isArray(item.parts) ||
+                item.parts.length === 0 ||
+                item.parts.length > 10_000 ||
+                item.parts.length !== Math.ceil(file.size / item.part_size))
+                return undefined;
+            plan.uploadId = item.upload_id;
+            for (let index = 0; index < item.parts.length; index++) {
+                const part = item.parts[index];
+                if (!record(part) || part.part_number !== index + 1 || !destination(part.upload_url, allowInsecure))
+                    return undefined;
+                const offset = index * item.part_size;
+                plan.parts.push({
+                    url: part.upload_url,
+                    offset,
+                    size: Math.min(item.part_size, file.size - offset),
+                });
+            }
+        }
+        else
+            return undefined;
+        for (const part of plan.parts) {
+            if (urls.has(part.url))
+                return undefined;
+            urls.add(part.url);
+        }
+        plans.push(plan);
+    }
+    return plans;
+}
+//# sourceMappingURL=uploads.js.map

package/dist/internal/uploads.js.map

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

package/dist/internal/user-cache.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Optional user and private-conversation cache with collection and per-resource stale-completion fences.
+ * Invariant: It keeps public snapshots only, bounded per resource, and a stale completion never repopulates invalidated data.
+ * Every applied store, removal and whole-kind clear is recorded to the client's change hub, a replacement counting as one store.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { ResourceCacheSettings } from "#sdk/cache";
+import type { CacheDiagnostic } from "#sdk/client";
+import type { DirectMessageChannel, User } from "#sdk/users";
+import type { LogicalScheduler } from "./logical-scheduler.js";
+import type { CacheChangeHub } from "./cache-changes.js";
+export type UserResources = {
+    users: User;
+    directMessages: DirectMessageChannel;
+};
+type Kind = keyof UserResources;
+export type UserCacheGuard = {
+    readonly kind: Kind;
+    readonly id?: string;
+    readonly mutation: boolean;
+    readonly replace: boolean;
+    readonly collectionEpoch: object;
+    readonly targetEpoch: object;
+};
+/** Optional client-owned public snapshots with collection and per-resource stale-completion fences */
+export declare class UserCache {
+    #private;
+    private readonly settings;
+    private readonly now;
+    readonly changes?: CacheChangeHub | undefined;
+    private readonly report;
+    constructor(settings: Partial<Record<Kind, Required<ResourceCacheSettings>>>, now: () => number, logical?: LogicalScheduler, changes?: CacheChangeHub | undefined, report?: (error: unknown) => void);
+    begin(kind: Kind, options?: {
+        id?: string;
+        mutation?: boolean;
+        replace?: boolean;
+    }): UserCacheGuard;
+    complete(guard: UserCacheGuard, values: readonly (User | DirectMessageChannel)[]): void;
+    get<K extends Kind>(kind: K, id: string): UserResources[K] | undefined;
+    diagnostics(kind: Kind): CacheDiagnostic;
+    entries<K extends Kind>(kind: K, limit: number): readonly UserResources[K][];
+    /** Release retained account/conversation observations and make reads begun earlier ineligible to restore them */
+    clear(): void;
+    invalidate(kind: Kind, id?: string): void;
+    failed(guard: UserCacheGuard): void;
+    gap(affects?: (guildId: string | null | undefined) => boolean): void;
+    close(): void;
+}
+export {};
+//# sourceMappingURL=user-cache.d.ts.map

package/dist/internal/user-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-cache.d.ts","sourceRoot":"","sources":["../../src/internal/user-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,KAAK,EAAE,oBAAoB,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAE5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAIxD,MAAM,MAAM,aAAa,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,cAAc,EAAE,oBAAoB,CAAA;CAAE,CAAA;AACjF,KAAK,IAAI,GAAG,MAAM,aAAa,CAAA;AAI/B,MAAM,MAAM,cAAc,GAAG;IACzB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC/B,CAAA;AAED,sGAAsG;AACtG,qBAAa,SAAS;;IAkBd,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAEpB,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAL3B,YACqB,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAChE,GAAG,EAAE,MAAM,MAAM,EAClC,OAAO,CAAC,EAAE,gBAAgB,EACjB,OAAO,CAAC,EAAE,cAAc,YAAA,EAChB,MAAM,GAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAsB,EAWtE;IAED,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,cAAc,CAyBtG;IAED,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,SAAS,CAAC,IAAI,GAAG,oBAAoB,CAAC,EAAE,QAsB/E;IAED,GAAG,CAAC,CAAC,SAAS,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,SAAS,CAQrE;IAED,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,eAAe,CAYvC;IAED,OAAO,CAAC,CAAC,SAAS,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,aAAa,CAAC,CAAC,CAAC,EAAE,CAS3E;IAED,iHAAiH;IACjH,KAAK,SAGJ;IAED,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,MAAM,QAWjC;IAED,MAAM,CAAC,KAAK,EAAE,cAAc,QAO3B;IAED,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,KAAK,OAAO,QAU5D;IAED,KAAK,SAQJ;CA8FJ"}

package/dist/internal/user-cache.js

@@ -0,0 +1,273 @@
+import { ExpiryQueue, ExpiryTimer } from "./expiry-queue.js";
+import { retentionAge } from "./retention-age.js";
+import { cacheStats, readStats } from "./cache.js";
+const targetGuardCapacity = 256;
+/** Optional client-owned public snapshots with collection and per-resource stale-completion fences */
+export class UserCache {
+    settings;
+    now;
+    changes;
+    report;
+    #entries = { users: new Map(), directMessages: new Map() };
+    #bytes = { users: 0, directMessages: 0 };
+    #stats = { users: cacheStats(), directMessages: cacheStats() };
+    #collectionEpoch = { users: {}, directMessages: {} };
+    #targetEpoch = { users: {}, directMessages: {} };
+    // Keep only the latest active guard per ID, with a conservative collection fence if callers exceed the bound
+    #targets = {
+        users: new Map(),
+        directMessages: new Map(),
+    };
+    #closed = false;
+    #expiry = new ExpiryQueue((entry) => this.#entries[entry.kind].get(entry.value.id) === entry);
+    #timer;
+    constructor(settings, now, logical, changes, report = () => undefined) {
+        this.settings = settings;
+        this.now = now;
+        this.changes = changes;
+        this.report = report;
+        this.#timer = new ExpiryTimer("user cache", now, () => {
+            this.#purge();
+            this.#schedule();
+        }, logical);
+    }
+    begin(kind, options = {}) {
+        const mutation = options.mutation === true;
+        const replace = options.replace === true;
+        const collection = options.id === undefined || replace;
+        if (collection)
+            this.#advanceCollection(kind);
+        else {
+            this.#targetEpoch[kind] = {};
+            const targets = this.#targets[kind];
+            if (!targets.has(options.id) && targets.size >= targetGuardCapacity)
+                this.#advanceCollection(kind);
+        }
+        const guard = {
+            kind,
+            ...(options.id === undefined ? {} : { id: options.id }),
+            mutation,
+            replace,
+            collectionEpoch: this.#collectionEpoch[kind],
+            targetEpoch: this.#targetEpoch[kind],
+        };
+        if (!collection && !this.#closed)
+            this.#targets[kind].set(options.id, guard);
+        if (mutation) {
+            if (options.id === undefined)
+                this.#clearKind(kind);
+            else
+                this.#remove(kind, options.id);
+            this.#schedule();
+        }
+        return guard;
+    }
+    complete(guard, values) {
+        if (this.#closed) {
+            this.#finish(guard);
+            return;
+        }
+        if (!this.#current(guard)) {
+            // A stale write can still have changed Fluxer state, so evict only the resource it could affect
+            if (guard.mutation)
+                this.invalidate(guard.kind, guard.id);
+            this.#finish(guard);
+            return;
+        }
+        const settings = this.settings[guard.kind];
+        if (guard.mutation) {
+            if (guard.id === undefined)
+                this.#clearKind(guard.kind);
+            else
+                this.#remove(guard.kind, guard.id);
+        }
+        else if (guard.replace)
+            this.#clearKind(guard.kind);
+        if (settings && settings.maxAgeMs !== 0 && settings.maxEntries !== 0) {
+            this.#purge();
+            for (const value of values)
+                this.#observe(guard.kind, value, settings);
+        }
+        this.#finish(guard);
+        this.#schedule();
+    }
+    get(kind, id) {
+        const entry = this.#peek(kind, id);
+        // A disabled kind holds nothing, so its lookups are not counted
+        if (this.settings[kind])
+            this.#stats[kind][entry ? "hits" : "misses"]++;
+        if (!entry)
+            return undefined;
+        this.#entries[kind].delete(id);
+        this.#entries[kind].set(id, entry);
+        return entry.value;
+    }
+    diagnostics(kind) {
+        this.#purge();
+        this.#schedule();
+        const settings = this.settings[kind];
+        return {
+            configured: settings !== undefined,
+            retainedEntries: this.#entries[kind].size,
+            accountedBytes: this.#bytes[kind],
+            maxEntries: settings?.maxEntries ?? null,
+            maxBytes: settings?.maxBytes ?? null,
+            ...readStats(this.#stats[kind]),
+        };
+    }
+    entries(kind, limit) {
+        this.#purge();
+        this.#schedule();
+        const entries = [];
+        for (const entry of this.#entries[kind].values()) {
+            entries.push(entry.value);
+            if (entries.length === limit)
+                break;
+        }
+        return Object.freeze(entries);
+    }
+    /** Release retained account/conversation observations and make reads begun earlier ineligible to restore them */
+    clear() {
+        if (this.#closed)
+            return;
+        this.gap();
+    }
+    invalidate(kind, id) {
+        if (this.#closed)
+            return;
+        if (id === undefined) {
+            this.#advanceCollection(kind);
+            this.#clearKind(kind);
+        }
+        else {
+            this.#targetEpoch[kind] = {};
+            this.#targets[kind].delete(id);
+            this.#remove(kind, id);
+        }
+        this.#schedule();
+    }
+    failed(guard) {
+        if (this.#closed) {
+            this.#finish(guard);
+            return;
+        }
+        if (guard.mutation || this.#current(guard))
+            this.invalidate(guard.kind, guard.id);
+        this.#finish(guard);
+    }
+    gap(affects) {
+        if (!affects || affects(undefined)) {
+            this.#advanceCollection("users");
+            this.#clearKind("users");
+        }
+        if (!affects || affects(null)) {
+            this.#advanceCollection("directMessages");
+            this.#clearKind("directMessages");
+        }
+        this.#schedule();
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#advanceCollection("users");
+        this.#advanceCollection("directMessages");
+        this.#clearKind("users");
+        this.#clearKind("directMessages");
+        this.#schedule();
+    }
+    #advanceCollection(kind) {
+        this.#collectionEpoch[kind] = {};
+        this.#targets[kind].clear();
+    }
+    #current(guard) {
+        if (guard.collectionEpoch !== this.#collectionEpoch[guard.kind])
+            return false;
+        return guard.id === undefined || guard.replace
+            ? guard.targetEpoch === this.#targetEpoch[guard.kind]
+            : this.#targets[guard.kind].get(guard.id) === guard;
+    }
+    #finish(guard) {
+        if (guard.id !== undefined && !guard.replace && this.#targets[guard.kind].get(guard.id) === guard)
+            this.#targets[guard.kind].delete(guard.id);
+    }
+    #peek(kind, id) {
+        const entry = this.#entries[kind].get(id);
+        if (entry && entry.expires !== null && entry.expires <= this.now()) {
+            this.#remove(kind, id);
+            this.#stats[kind].evictions.expiry++;
+            return undefined;
+        }
+        return entry;
+    }
+    /** Remove one retained snapshot, reporting the deletion unless the caller replaces it. Returns whether one was removed */
+    #remove(kind, id, notify = true) {
+        const entry = this.#entries[kind].get(id);
+        if (!entry)
+            return false;
+        this.#entries[kind].delete(id);
+        this.#bytes[kind] -= entry.bytes;
+        if (notify && this.changes?.active)
+            this.changes.record(kind, "delete", id);
+        return true;
+    }
+    #clearKind(kind) {
+        const held = this.#entries[kind].size > 0;
+        this.#entries[kind].clear();
+        this.#bytes[kind] = 0;
+        if (held && this.changes?.active)
+            this.changes.record(kind, "clear", null);
+    }
+    #observe(kind, value, settings) {
+        const resolved = retentionAge(settings.maxAgeMs, value, `${kind} cache`, "snapshot");
+        if (this.#closed)
+            return;
+        if ("error" in resolved) {
+            this.#remove(kind, value.id);
+            this.report(resolved.error);
+            return;
+        }
+        const age = resolved.age;
+        // A replacement reports one set, while an older copy that the new one cannot replace reports a delete
+        const replaced = this.#remove(kind, value.id, false);
+        const bytes = age === 0 ? 0 : Buffer.byteLength(JSON.stringify(value));
+        if (age === 0 || bytes > settings.maxBytes) {
+            if (replaced && this.changes?.active)
+                this.changes.record(kind, "delete", value.id);
+            return;
+        }
+        const entries = this.#entries[kind];
+        while (entries.size >= settings.maxEntries || this.#bytes[kind] > settings.maxBytes - bytes) {
+            this.#remove(kind, entries.keys().next().value);
+            this.#stats[kind].evictions.capacity++;
+        }
+        const entry = {
+            kind,
+            value,
+            bytes,
+            expires: age === null ? null : this.now() + age,
+        };
+        entries.set(value.id, entry);
+        this.#bytes[kind] += bytes;
+        if (entry.expires !== null)
+            this.#expiry.push(entry);
+        if (this.changes?.active)
+            this.changes.record(kind, "set", value.id);
+    }
+    #purge() {
+        this.#expiry.purge(this.now(), (entry) => {
+            if (this.#remove(entry.kind, entry.value.id))
+                this.#stats[entry.kind].evictions.expiry++;
+        });
+    }
+    #schedule() {
+        if (this.#closed) {
+            this.#timer.cancel();
+            this.#expiry.clear();
+            return;
+        }
+        this.#expiry.compact(this.#entries.users.size + this.#entries.directMessages.size);
+        this.#timer.set(this.#expiry.next());
+    }
+}
+//# sourceMappingURL=user-cache.js.map

package/dist/internal/user-cache.js.map

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

package/dist/internal/users.d.ts

@@ -0,0 +1,41 @@
+/**
+ * User and private-conversation operations and projections.
+ * Invariant: Projections keep the public-field allowlist shared by explicit reads and complete user observations.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { DirectMessageChannel, DirectMessageGroupEdit, DirectMessageLatestMessages, User, UserProfile, UserProfileQuery } from "#sdk/users";
+import type { MessageCore } from "#sdk/messages";
+import type { MessageDecoder } from "./message-fields.js";
+import { InputValidationFailure } from "#sdk/input-validation";
+/** Validated requests executed by the client's shared REST scheduler */
+export interface UserRequest<A> {
+    readonly majorId: string;
+    readonly path: string;
+    readonly method: "GET" | "POST" | "PATCH" | "DELETE";
+    readonly status: 200 | 204;
+    readonly json?: string;
+    readonly decode: (value: unknown) => A | undefined;
+    readonly resource: "users" | "directMessages";
+    readonly id?: string;
+    readonly replace?: boolean;
+    readonly verifyType?: "private" | "group";
+    /** Skips all user-cache conflict guards and writes while retaining the shared REST scheduler and retries */
+    readonly noCache?: boolean;
+}
+type UserValidationResult<A> = UserRequest<A> | InputValidationFailure;
+/** Public-field allowlist, shared by explicit reads and complete user observations */
+export declare function decodeUser(value: unknown): User | undefined;
+export declare function decodeDirectMessage(value: unknown): DirectMessageChannel | undefined;
+export declare function userFetch(id: string): UserValidationResult<User>;
+/** Build one explicit profile read with only a caller-selected guild context and no relationship-expansion flags */
+export declare function userProfile(id: string, query?: UserProfileQuery): UserValidationResult<UserProfile>;
+export declare function directMessageOpen(id: string): UserValidationResult<DirectMessageChannel>;
+export declare function directMessageFetch(id: string): UserValidationResult<DirectMessageChannel>;
+export declare function directMessageList(): UserRequest<readonly DirectMessageChannel[]>;
+/** Request latest messages only for explicit private-channel IDs, without cache admission or conversation enumeration */
+export declare function directMessageLatestMessages(ids: readonly string[]): UserValidationResult<DirectMessageLatestMessages>;
+export declare function directMessageLatestMessages<M extends MessageCore>(ids: readonly string[], decode: MessageDecoder<M>): UserValidationResult<DirectMessageLatestMessages<M>>;
+export declare function directMessageEdit(id: string, input: DirectMessageGroupEdit): UserValidationResult<DirectMessageChannel>;
+export declare function directMessageClose(id: string, recipient?: string): UserValidationResult<void>;
+export {};
+//# sourceMappingURL=users.d.ts.map

package/dist/internal/users.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../src/internal/users.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EACR,oBAAoB,EACpB,sBAAsB,EACtB,2BAA2B,EAC3B,IAAI,EACJ,WAAW,EAEX,gBAAgB,EACnB,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAGzD,OAAO,EAAE,sBAAsB,EAAiD,MAAM,uBAAuB,CAAA;AAG7G,wEAAwE;AACxE,MAAM,WAAW,WAAW,CAAC,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;IACpD,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,CAAA;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,GAAG,SAAS,CAAA;IAClD,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,gBAAgB,CAAA;IAC7C,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,GAAG,OAAO,CAAA;IACzC,4GAA4G;IAC5G,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAC7B;AAED,KAAK,oBAAoB,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,sBAAsB,CAAA;AAOtE,sFAAsF;AACtF,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,CAyB3D;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,GAAG,SAAS,CAuCpF;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAehE;AAED,oHAAoH;AACpH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,gBAAgB,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAiDnG;AA0BD,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,oBAAoB,CAAC,oBAAoB,CAAC,CAqBxF;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,oBAAoB,CAAC,oBAAoB,CAAC,CAczF;AAED,wBAAgB,iBAAiB,IAAI,WAAW,CAAC,SAAS,oBAAoB,EAAE,CAAC,CAuBhF;AAED,yHAAyH;AACzH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,oBAAoB,CAAC,2BAA2B,CAAC,CAAA;AACtH,wBAAgB,2BAA2B,CAAC,CAAC,SAAS,WAAW,EAC7D,GAAG,EAAE,SAAS,MAAM,EAAE,EACtB,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,GAC1B,oBAAoB,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC,CAAA;AA8CvD,wBAAgB,iBAAiB,CAC7B,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,sBAAsB,GAC9B,oBAAoB,CAAC,oBAAoB,CAAC,CA6D5C;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAc7F"}