@atomicmemory/core 1.0.0

package/dist/services/upload-helpers.js

@@ -0,0 +1,148 @@
+/**
+ * Stateless helpers extracted out of `document-upload.ts` to keep the
+ * orchestration file under the workspace 400-line cap. These are pure
+ * functions + small async wrappers — no orchestration state, no
+ * codec/store/registry coupling beyond the typed argument bag.
+ */
+import { createHash } from 'node:crypto';
+import { buildLastError, markRawStorageFailedByDocumentId, } from '../db/raw-document-status-repository.js';
+import { getRawDocumentById } from '../db/raw-document-repository.js';
+export class UploadDocumentNotFoundError extends Error {
+    documentId;
+    constructor(documentId) {
+        super(`document ${documentId} not found`);
+        this.documentId = documentId;
+        this.name = 'UploadDocumentNotFoundError';
+    }
+}
+export class ManagedStorageDisabledError extends Error {
+    constructor() {
+        super('managed_blob storage is not enabled for this deployment');
+        this.name = 'ManagedStorageDisabledError';
+    }
+}
+export class UploadDocumentConflictError extends Error {
+    documentId;
+    existingContentHash;
+    incomingContentHash;
+    constructor(documentId, existingContentHash, incomingContentHash) {
+        super(`document ${documentId} already has a managed blob with content_hash=` +
+            `${existingContentHash}; refusing to overwrite with content_hash=${incomingContentHash}`);
+        this.documentId = documentId;
+        this.existingContentHash = existingContentHash;
+        this.incomingContentHash = incomingContentHash;
+        this.name = 'UploadDocumentConflictError';
+    }
+}
+/**
+ * Surfaced when Phase β2 or Phase γ's compare-and-set found 0 rows.
+ * Means our claim was lost — another worker reclaimed the row or it
+ * was concurrently deleted. Not exported because route handlers
+ * currently map any such error to a generic 500; promote to `export`
+ * when Phase 8.5 observability needs to discriminate it.
+ */
+export class UploadClaimLostError extends Error {
+    documentId;
+    claimId;
+    phase;
+    constructor(documentId, claimId, phase) {
+        super(`upload claim ${claimId} for document ${documentId} was lost between ` +
+            `phase α and phase ${phase} (concurrent reclaim or row deletion)`);
+        this.documentId = documentId;
+        this.claimId = claimId;
+        this.phase = phase;
+        this.name = 'UploadClaimLostError';
+    }
+}
+export async function loadActive(client, input) {
+    const document = await getRawDocumentById(client, input.userId, input.documentId);
+    if (!document)
+        throw new UploadDocumentNotFoundError(input.documentId);
+    return document;
+}
+export function sha256Hex(buf) {
+    return createHash('sha256').update(buf).digest('hex');
+}
+export function describeError(err) {
+    if (err instanceof Error)
+        return `${err.name}: ${err.message}`;
+    return String(err);
+}
+/**
+ * Build the adapter-relative key the blob is stored under. Includes
+ * the content hash so byte-identical re-uploads collide on the same
+ * key (no orphan from re-uploading the same content).
+ *
+ * `userPrefix` MUST be the HMAC-SHA256-derived per-user prefix from
+ * `deriveStorageKeyPrefix(secret, userId)`. The plaintext `userId`
+ * MUST NEVER appear in any provider key/URI — the HMAC prefix is
+ * the PII-safe replacement. Stable across retries (same user → same
+ * prefix) so the same-bytes re-upload idempotency contract holds.
+ */
+export function blobKey(prefix, userPrefix, documentId, contentHash) {
+    const head = prefix.length > 0 ? prefix.replace(/^\/+|\/+$/g, '') + '/' : '';
+    return `${head}s/${userPrefix}/documents/${documentId}/${contentHash}.bin`;
+}
+/**
+ * Echo the row's existing state as the idempotent-skip response.
+ * Phase α returns this when `classifyIdempotent === 'returnExisting'`.
+ */
+export function idempotentResult(document, contentHash, sizeBytes) {
+    const status = document.rawStorageStatus;
+    return {
+        documentId: document.id,
+        storageProvider: document.storageProvider ?? '',
+        storageUri: document.storageUri ?? '',
+        contentHash,
+        sizeBytes,
+        rawStorageStatus: status,
+        storageMode: 'managed_blob',
+        rawStorageMetadata: document.rawStorageMetadata,
+        idempotentSkip: true,
+    };
+}
+export function buildUploadResult(args) {
+    return {
+        documentId: args.documentId,
+        storageProvider: args.storageProvider,
+        storageUri: args.storageUri,
+        contentHash: args.contentHash,
+        sizeBytes: args.sizeBytes,
+        rawStorageStatus: args.finalStatus,
+        storageMode: 'managed_blob',
+        rawStorageMetadata: args.rawStorageMetadata,
+        idempotentSkip: args.idempotentSkip,
+    };
+}
+/**
+ * Build the `raw_storage_metadata` JSONB Phase β2 writes:
+ *   - `codec`: the encoder's sidecar (name + version + AES-GCM internals).
+ *   - spread of `stored.providerMetadata`: `{ filecoin: { ... } }` for
+ *     Filecoin; `{}` for immediate providers.
+ *   - `upload_result.stored_status`: INTERNAL sidecar Phase γ reads
+ *     on the finalize-recovery path. Public formatters strip it.
+ */
+export function buildPhaseBeta2Metadata(stored) {
+    return {
+        codec: stored.codecMetadata,
+        ...stored.providerMetadata,
+        upload_result: { stored_status: stored.status },
+    };
+}
+/**
+ * Best-effort `raw_storage_failed` marker. Logs (does not swallow)
+ * the marker failure so the original upload error is the one the
+ * caller sees.
+ */
+export async function markRawStorageFailureBestEffort(q, userId, documentId, code, message) {
+    try {
+        await markRawStorageFailedByDocumentId({
+            q, userId, documentId,
+            lastError: buildLastError('raw_storage', code, message),
+        });
+    }
+    catch (markerErr) {
+        console.error(`[upload-raw] failed to record raw_storage_failed marker for document ${documentId}: ` +
+            `${describeError(markerErr)} (original code=${code} message=${message})`);
+    }
+}

package/dist/services/user-profile-builder.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Honcho-style user-profile builder (Sprint 3 v1.5 — H2).
+ *
+ * After a user's ingest stores >= MIN_NEW_MEMORIES_FOR_REBUILD new
+ * facts, this builder fires (post-write, fire-and-forget) a single LLM
+ * call that synthesizes a ~200-word profile capturing the user's
+ * stated preferences, persistent instructions, and open commitments.
+ *
+ * Failure-closed: throws on JSON parse failure or empty profile.
+ * Caller wraps in try/catch to keep ingest latency unaffected.
+ */
+import type { LLMProvider } from './llm.js';
+import type { MemoryServiceDeps } from './memory-service-types.js';
+export interface UserProfile {
+    profile: string;
+}
+export declare class UserProfileBuilderError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export declare function synthesizeUserProfile(memoryContents: string[], llmClient?: LLMProvider): Promise<UserProfile>;
+export declare function maybeRebuildProfileForUser(deps: MemoryServiceDeps, userId: string, newlyStoredMemoryIds: string[]): Promise<boolean>;

package/dist/services/user-profile-builder.js

@@ -0,0 +1,109 @@
+import { llm as defaultLlm } from './llm.js';
+import { extractFirstJsonObject } from './extraction.js';
+const PROFILE_MAX_TOKENS = 768;
+const PROFILE_TARGET_WORDS = 200;
+const MIN_NEW_MEMORIES_FOR_REBUILD = 3;
+const MAX_SOURCE_MEMORY_CHARS = 300;
+const MAX_SOURCES_PER_BUILD = 40;
+const MIN_PROFILE_WORD_COUNT = 20;
+const MIN_REBUILD_INTERVAL_MS = 60_000; // 60 s — coalesces bursty ingest into one rebuild
+const PROFILE_SYSTEM_PROMPT = [
+    'You synthesize a concise user profile from a list of stored memories.',
+    '',
+    'Rules:',
+    '- Capture the user’s explicit preferences, persistent instructions, and open commitments.',
+    '- Preserve specific facts (names, dates, decisions). Do not infer or speculate.',
+    '- Only state facts present in the numbered memories above. If a memory does not support a claim, do not include it.',
+    '- Write ~' + String(PROFILE_TARGET_WORDS) + ' words in three sections:',
+    '  1. Preferences: ...',
+    '  2. Instructions: ...',
+    '  3. Open commitments: ...',
+    '- Output JSON: {"profile": "<200-word document>"}.',
+    '- No markdown fences. No prose around the JSON.',
+].join('\n');
+export class UserProfileBuilderError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'UserProfileBuilderError';
+    }
+}
+function buildProfileMessages(memoryContents) {
+    const truncated = memoryContents
+        .slice(0, MAX_SOURCES_PER_BUILD)
+        .map((c, i) => `[${i + 1}] ${c.trim().slice(0, MAX_SOURCE_MEMORY_CHARS)}`);
+    return [
+        { role: 'system', content: PROFILE_SYSTEM_PROMPT },
+        {
+            role: 'user',
+            content: [
+                'MEMORIES:',
+                truncated.join('\n\n'),
+                '',
+                'Return JSON: {"profile": "<200-word profile>"}',
+            ].join('\n'),
+        },
+    ];
+}
+function parseProfileResponse(raw) {
+    if (!raw)
+        throw new UserProfileBuilderError('profile LLM returned empty content');
+    const cleaned = extractFirstJsonObject(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(cleaned);
+    }
+    catch (err) {
+        throw new UserProfileBuilderError(`profile LLM returned non-JSON: ${cleaned.slice(0, 200)}`, err);
+    }
+    const profile = typeof parsed.profile === 'string' ? parsed.profile.trim() : '';
+    if (!profile || profile.split(/\s+/).filter(Boolean).length < MIN_PROFILE_WORD_COUNT) {
+        throw new UserProfileBuilderError('profile too short or missing');
+    }
+    return { profile };
+}
+export async function synthesizeUserProfile(memoryContents, llmClient = defaultLlm) {
+    if (memoryContents.length === 0) {
+        throw new UserProfileBuilderError('cannot build profile from zero memories');
+    }
+    const messages = buildProfileMessages(memoryContents);
+    let raw;
+    try {
+        raw = await llmClient.chat(messages, {
+            temperature: 0,
+            jsonMode: true,
+            maxTokens: PROFILE_MAX_TOKENS,
+        });
+    }
+    catch (err) {
+        throw new UserProfileBuilderError(`profile LLM call failed: ${err.message}`, err);
+    }
+    return parseProfileResponse(raw);
+}
+export async function maybeRebuildProfileForUser(deps, userId, newlyStoredMemoryIds) {
+    if (!deps.config.userProfileChannelEnabled)
+        return false;
+    if (newlyStoredMemoryIds.length < MIN_NEW_MEMORIES_FOR_REBUILD)
+        return false;
+    const profileRepo = deps.stores.userProfile;
+    if (!profileRepo)
+        return false;
+    try {
+        const current = await profileRepo.getProfile(userId);
+        if (current && Date.now() - current.updated_at.getTime() < MIN_REBUILD_INTERVAL_MS) {
+            console.info(`[profile] rebuild debounced for user=${userId} (recent within ${MIN_REBUILD_INTERVAL_MS}ms)`);
+            return false;
+        }
+        const recent = await deps.stores.memory.listMemories(userId, MAX_SOURCES_PER_BUILD, 0);
+        if (recent.length === 0)
+            return false;
+        const { profile } = await synthesizeUserProfile(recent.map((m) => m.content));
+        await profileRepo.upsertProfile(userId, profile, recent.map((m) => m.id), current?.updated_at);
+        return true;
+    }
+    catch (err) {
+        console.warn(`[profile] rebuild failed for user=${userId}: ${err.message}`);
+        return false;
+    }
+}

package/dist/services/voyage-embedding.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Voyage AI embedding provider for isolated benchmark lanes.
+ *
+ * Voyage 4 models share an embedding space across the family, allowing
+ * document and query embeddings to use different compatible models while
+ * remaining searchable in the same pgvector index.
+ */
+import type { EmbeddingConfig, EmbeddingProvider, EmbeddingTask } from './embedding.js';
+export declare const VOYAGE_API_BASE = "https://api.voyageai.com";
+export declare class VoyageEmbedding implements EmbeddingProvider {
+    private readonly config;
+    private readonly apiKey;
+    private readonly documentModel;
+    private readonly queryModel;
+    private readonly dimensions;
+    constructor(config: EmbeddingConfig, apiKey: string, documentModel: string, queryModel: string, dimensions: number);
+    embed(text: string, task: EmbeddingTask): Promise<number[]>;
+    embedBatch(texts: string[], task: EmbeddingTask): Promise<number[][]>;
+    private modelFor;
+    private requestAndTrack;
+    private writeUsage;
+}

package/dist/services/voyage-embedding.js

@@ -0,0 +1,77 @@
+/**
+ * Voyage AI embedding provider for isolated benchmark lanes.
+ *
+ * Voyage 4 models share an embedding space across the family, allowing
+ * document and query embeddings to use different compatible models while
+ * remaining searchable in the same pgvector index.
+ */
+import { estimateCostUsd, summarizeUsage, writeCostEvent, } from './cost-telemetry.js';
+export const VOYAGE_API_BASE = 'https://api.voyageai.com';
+export class VoyageEmbedding {
+    config;
+    apiKey;
+    documentModel;
+    queryModel;
+    dimensions;
+    constructor(config, apiKey, documentModel, queryModel, dimensions) {
+        this.config = config;
+        this.apiKey = apiKey;
+        this.documentModel = documentModel;
+        this.queryModel = queryModel;
+        this.dimensions = dimensions;
+    }
+    async embed(text, task) {
+        const response = await this.requestAndTrack(text, task);
+        return response.data[0].embedding;
+    }
+    async embedBatch(texts, task) {
+        if (texts.length === 0)
+            return [];
+        const response = await this.requestAndTrack(texts, task);
+        return response.data
+            .sort((a, b) => a.index - b.index)
+            .map((d) => d.embedding);
+    }
+    modelFor(task) {
+        return task === 'query' ? this.queryModel : this.documentModel;
+    }
+    async requestAndTrack(input, task) {
+        const model = this.modelFor(task);
+        const started = performance.now();
+        const response = await fetch(`${VOYAGE_API_BASE}/v1/embeddings`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify({
+                input,
+                model,
+                input_type: task,
+                output_dimension: this.dimensions,
+            }),
+            signal: AbortSignal.timeout(300_000),
+        });
+        if (!response.ok) {
+            throw new Error(`Voyage embed failed (${response.status}): ${await response.text()}`);
+        }
+        const body = await response.json();
+        this.writeUsage(model, body.usage?.total_tokens ?? null, started);
+        return body;
+    }
+    writeUsage(model, totalTokens, started) {
+        const usage = summarizeUsage(totalTokens, null, totalTokens);
+        writeCostEvent({
+            stage: 'embedding',
+            provider: this.config.embeddingProvider,
+            model,
+            requestKind: 'embedding',
+            durationMs: performance.now() - started,
+            cacheHit: false,
+            inputTokens: usage.inputTokens ?? null,
+            outputTokens: usage.outputTokens ?? null,
+            totalTokens: usage.totalTokens ?? null,
+            estimatedCostUsd: estimateCostUsd(this.config.embeddingProvider, model, usage),
+        }, this.config);
+    }
+}

package/dist/services/write-security.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared write-time security gate for memory ingest paths.
+ *
+ * Centralizes sanitization/trust enforcement so standard and hive ingest flows
+ * cannot diverge on whether unsafe content is allowed into storage.
+ */
+import type { LessonStore } from '../db/stores.js';
+import { type TrustScore } from './trust-scoring.js';
+export type WriteBlockReason = 'sanitization' | 'trust' | null;
+export interface WriteSecurityDecision {
+    allowed: boolean;
+    blockedBy: WriteBlockReason;
+    trust: TrustScore;
+}
+/**
+ * Config subset consumed by assessWriteSecurity. Narrow `Pick<>` of
+ * IngestRuntimeConfig so callers only need to thread what the function
+ * actually reads.
+ */
+export interface WriteSecurityAssessConfig {
+    trustScoringEnabled: boolean;
+    trustScoreMinThreshold: number;
+}
+/** Config subset consumed by recordRejectedWrite. */
+export interface WriteSecurityRecordConfig {
+    auditLoggingEnabled: boolean;
+    lessonsEnabled: boolean;
+    trustScoreMinThreshold: number;
+}
+export declare function assessWriteSecurity(content: string, sourceSite: string, config: WriteSecurityAssessConfig): WriteSecurityDecision;
+export declare function recordRejectedWrite(userId: string, content: string, sourceSite: string, decision: WriteSecurityDecision, config: WriteSecurityRecordConfig, lessons?: LessonStore | null): Promise<void>;

package/dist/services/write-security.js

@@ -0,0 +1,64 @@
+/**
+ * Shared write-time security gate for memory ingest paths.
+ *
+ * Centralizes sanitization/trust enforcement so standard and hive ingest flows
+ * cannot diverge on whether unsafe content is allowed into storage.
+ */
+import { emitAuditEvent } from './audit-events.js';
+import { recordInjectionLesson, recordTrustViolationLesson } from './lesson-service.js';
+import { computeTrustScore, meetsMinimumTrust } from './trust-scoring.js';
+export function assessWriteSecurity(content, sourceSite, config) {
+    const trust = config.trustScoringEnabled
+        ? computeTrustScore(content, sourceSite)
+        : PASS_THROUGH_TRUST;
+    if (!config.trustScoringEnabled) {
+        return { allowed: true, blockedBy: null, trust };
+    }
+    if (!trust.sanitization.passed) {
+        return { allowed: false, blockedBy: 'sanitization', trust };
+    }
+    if (!meetsMinimumTrust(trust, config.trustScoreMinThreshold)) {
+        return { allowed: false, blockedBy: 'trust', trust };
+    }
+    return { allowed: true, blockedBy: null, trust };
+}
+export async function recordRejectedWrite(userId, content, sourceSite, decision, config, lessons) {
+    if (config.auditLoggingEnabled && !decision.trust.sanitization.passed) {
+        emitAuditEvent('sanitization:block', userId, {
+            fact: content.slice(0, 200),
+            findings: decision.trust.sanitization.findings,
+        }, { sourceSite });
+    }
+    if (config.lessonsEnabled && lessons && !decision.trust.sanitization.passed) {
+        await recordInjectionLesson(lessons, {
+            userId,
+            content,
+            sourceSite,
+            sanitizationResult: decision.trust.sanitization,
+        });
+    }
+    if (decision.blockedBy !== 'trust')
+        return;
+    if (config.auditLoggingEnabled) {
+        emitAuditEvent('trust:below-threshold', userId, {
+            fact: content.slice(0, 200),
+            trustScore: decision.trust.score,
+            threshold: config.trustScoreMinThreshold,
+        }, { sourceSite });
+    }
+    if (config.lessonsEnabled && lessons) {
+        await recordTrustViolationLesson(lessons, {
+            userId,
+            content,
+            sourceSite,
+            trustScore: decision.trust.score,
+        });
+    }
+}
+const PASS_THROUGH_TRUST = {
+    score: 1.0,
+    domainTrust: 1.0,
+    contentPenalty: 0,
+    injectionPenalty: 0,
+    sanitization: { passed: true, findings: [], highestSeverity: 'none' },
+};

package/dist/storage/artifact-public-redaction.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @file Per-provider redaction for `storage_artifacts` wire responses.
+ *
+ * Explicit projection from the
+ * (potentially noisy) `provider_metadata` / `identifiers` columns to
+ * the closed set of fields each provider is allowed to surface on
+ * the wire. Project-then-validate: the formatter constructs the
+ * allowlisted object by named keys, and the `StoredArtifactResponseSchema`
+ * `.strict()` parse in the route layer is the final lock that drops
+ * any field the formatter accidentally let through.
+ *
+ * Scope: backends that v1 actually writes (`local_fs`, `s3`,
+ * `filecoin`). Filecoin direct managed uploads are 501 in v1 so the
+ * filecoin formatter mostly matters for pointer-mode artifacts that
+ * carry caller-supplied `identifiers` (e.g. an IPFS CID the caller
+ * already knows).
+ */
+/** Wire shape — discoverable identifiers only. Values are scalars. */
+export type PublicArtifactIdentifiers = Record<string, string>;
+/** Wire shape — provider-side public state. */
+export type PublicArtifactProviderDetails = Record<string, unknown>;
+/**
+ * Project a raw `(identifiers, providerDetails)` pair into the
+ * provider-specific public shape. Unknown providers contribute an
+ * empty object on both fields — the formatter never falls back to a
+ * passthrough.
+ */
+export declare function redactArtifactPublic(provider: string, raw: {
+    identifiers: Record<string, unknown>;
+    providerDetails: Record<string, unknown> | null;
+}): {
+    identifiers: PublicArtifactIdentifiers;
+    providerDetails: PublicArtifactProviderDetails;
+};

package/dist/storage/artifact-public-redaction.js

@@ -0,0 +1,83 @@
+/**
+ * @file Per-provider redaction for `storage_artifacts` wire responses.
+ *
+ * Explicit projection from the
+ * (potentially noisy) `provider_metadata` / `identifiers` columns to
+ * the closed set of fields each provider is allowed to surface on
+ * the wire. Project-then-validate: the formatter constructs the
+ * allowlisted object by named keys, and the `StoredArtifactResponseSchema`
+ * `.strict()` parse in the route layer is the final lock that drops
+ * any field the formatter accidentally let through.
+ *
+ * Scope: backends that v1 actually writes (`local_fs`, `s3`,
+ * `filecoin`). Filecoin direct managed uploads are 501 in v1 so the
+ * filecoin formatter mostly matters for pointer-mode artifacts that
+ * carry caller-supplied `identifiers` (e.g. an IPFS CID the caller
+ * already knows).
+ */
+/** Closed allowlists, one per known provider. */
+const LOCAL_FS_IDENTIFIER_KEYS = ['etag'];
+const LOCAL_FS_PROVIDER_DETAIL_KEYS = [];
+const S3_IDENTIFIER_KEYS = ['etag', 'versionId'];
+const S3_PROVIDER_DETAIL_KEYS = ['bucket', 'region'];
+const FILECOIN_IDENTIFIER_KEYS = ['ipfsCid', 'pieceCid', 'carRootCid', 'dataSetId'];
+/**
+ * Filecoin currently has NO public `provider_details`. Keeping this
+ * empty prevents the wire from carrying provider fields the storage
+ * backend has not explicitly projected.
+ */
+const FILECOIN_PROVIDER_DETAIL_KEYS = [];
+/**
+ * Project a raw `(identifiers, providerDetails)` pair into the
+ * provider-specific public shape. Unknown providers contribute an
+ * empty object on both fields — the formatter never falls back to a
+ * passthrough.
+ */
+export function redactArtifactPublic(provider, raw) {
+    const idKeys = identifierKeysFor(provider);
+    const detailKeys = providerDetailKeysFor(provider);
+    return {
+        identifiers: pickStringKeys(raw.identifiers, idKeys),
+        providerDetails: pickScalarKeys(raw.providerDetails ?? {}, detailKeys),
+    };
+}
+function identifierKeysFor(provider) {
+    if (provider === 'local_fs')
+        return LOCAL_FS_IDENTIFIER_KEYS;
+    if (provider === 's3')
+        return S3_IDENTIFIER_KEYS;
+    if (provider === 'filecoin')
+        return FILECOIN_IDENTIFIER_KEYS;
+    return [];
+}
+function providerDetailKeysFor(provider) {
+    if (provider === 'local_fs')
+        return LOCAL_FS_PROVIDER_DETAIL_KEYS;
+    if (provider === 's3')
+        return S3_PROVIDER_DETAIL_KEYS;
+    if (provider === 'filecoin')
+        return FILECOIN_PROVIDER_DETAIL_KEYS;
+    return [];
+}
+function pickStringKeys(source, keys) {
+    const out = {};
+    for (const key of keys) {
+        const value = source[key];
+        if (typeof value === 'string' && value.length > 0) {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+function pickScalarKeys(source, keys) {
+    const out = {};
+    for (const key of keys) {
+        const value = source[key];
+        if (value === undefined || value === null)
+            continue;
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            out[key] = value;
+        }
+    }
+    return out;
+}