Python
import type {
ImportIssue,
ImportJob,
LiveSyncHealth,
MemoryProcessingSummary,
ModelProfile,
SourceResponse,
} from "@one-memory/contracts";
/** SDK memory states `memhub memories list --status` may ask for. */
export const MEMORY_STATUSES = [
"active",
"superseded",
"shadow",
"negated",
"conflicted",
"archived",
] as const;
/**
* HTTP 200 is not a contract. Everything here re-checks the shape and the
* bounds of a Core response before any of it is projected into output, so a
* malformed or misbound answer is reported as invalid instead of being printed
* as a smaller truth. Returning null always means "do not show this".
*/
const ID_MAX = 128;
const LABEL_MAX = 256;
const LIST_MAX = 500;
const LIVE_SYNC_STATES = [
"idle",
"running",
"degraded",
"unavailable",
] as const;
const PROVIDER_KINDS = [
"hy_default",
"openai_compatible",
"anthropic",
"ollama",
"local_onnx",
] as const;
const CREDENTIAL_STATES = ["available", "missing", "unavailable"] as const;
const IMPORT_STATUSES = [
"pending",
"running",
"paused",
"interrupted",
"completed",
"failed",
"cancelled",
] as const;
const SCAN_PHASES = ["discover", "read", "emit", "done"] as const;
const CAPABILITY_STATES = ["not_implemented", "implemented"] as const;
const VERIFICATION_STATES = ["fixture_only", "real_replayed"] as const;
const SYNC_COMPLETENESS = [
"full_dynamic",
"additions_only",
"one_time_snapshot",
] as const;
const CANDIDATE_KINDS = [
"default",
"environment_override",
"user_selected",
] as const;
const LOCATION_STATES = [
"found",
"not_found",
"inaccessible",
"invalid",
] as const;
const LIVE_SYNC_MODES = ["polling", "watch_and_polling"] as const;
export interface SourceConnectionCandidate {
source_id: string;
display_name: string;
candidate_kind: (typeof CANDIDATE_KINDS)[number];
candidate_root_id: string;
candidate_revision?: number;
requires_override_confirmation: boolean;
}
export function validateSources(value: unknown): SourceResponse[] | null {
return list(value, (item) => {
const source = record(item);
const sourceId = source && text(source.source_id, ID_MAX);
const displayName = source && text(source.display_name, LABEL_MAX);
const storageKinds = source && identifiers(source.storage_kinds);
const capabilities = source && record(source.capabilities);
const grantRevision = source && count(source.grant_revision);
// `stringOrNull` is a type guard, not a getter: it reports the shape but
// does not hand back the value. Read the string explicitly, and treat a
// present-but-malformed value as its own failure rather than as absent.
let rootId: string | null | undefined;
if (source !== null && source !== undefined && "root_id" in source) {
rootId = stringOrNull(source.root_id, LABEL_MAX)
? (source.root_id as string | null)
: undefined;
}
if (
!source ||
sourceId === null ||
displayName === null ||
storageKinds === null ||
typeof source.available !== "boolean" ||
typeof source.authorized !== "boolean" ||
!booleanOrNull(source.detected) ||
!stringOrNull(source.root_label, LABEL_MAX) ||
!oneOf(source.candidate_kind, CANDIDATE_KINDS) ||
count(source.imported_conversations) === null ||
count(source.imported_messages) === null ||
!capabilities ||
!oneOf(capabilities.historical_import, CAPABILITY_STATES) ||
!oneOf(capabilities.incremental_import, CAPABILITY_STATES) ||
!oneOf(capabilities.live_sync, CAPABILITY_STATES) ||
!oneOf(capabilities.recall, CAPABILITY_STATES) ||
!oneOf(capabilities.installer, CAPABILITY_STATES) ||
!oneOf(capabilities.verification, VERIFICATION_STATES) ||
!oneOf(source.sync_completeness, SYNC_COMPLETENESS) ||
typeof source.sync_enabled !== "boolean" ||
grantRevision === null ||
("root_id" in source && rootId === undefined) ||
(source.location_state !== undefined &&
!oneOf(source.location_state, LOCATION_STATES))
) {
return null;
}
return {
source_id: sourceId,
display_name: displayName,
storage_kinds: storageKinds,
available: source.available,
authorized: source.authorized,
detected: source.detected,
root_label: source.root_label,
candidate_path: "",
candidate_kind: source.candidate_kind,
imported_messages: source.imported_messages,
imported_conversations: source.imported_conversations,
capabilities: {
historical_import: capabilities.historical_import,
incremental_import: capabilities.incremental_import,
live_sync: capabilities.live_sync,
recall: capabilities.recall,
installer: capabilities.installer,
verification: capabilities.verification,
},
sync_completeness: source.sync_completeness,
sync_enabled: source.sync_enabled,
...(typeof source.location_state === "string"
? { location_state: source.location_state }
: {}),
grant_revision: grantRevision,
root_id: rootId,
} as unknown as SourceResponse;
});
}
export function validateSourceConnectionCandidates(
value: unknown,
): SourceConnectionCandidate[] | null {
if (!Array.isArray(value) || value.length > LIST_MAX) return null;
const candidates: SourceConnectionCandidate[] = [];
const seen = new Set<string>();
for (const item of value) {
const source = record(item);
if (!source) return null;
const sourceId = text(source.source_id, ID_MAX);
const displayName = text(source.display_name, LABEL_MAX);
const rootId =
source.candidate_root_id === null
? null
: text(source.candidate_root_id, LABEL_MAX);
const revision = count(source.candidate_revision);
if (
sourceId === null ||
displayName === null ||
seen.has(sourceId) ||
!oneOf(source.candidate_kind, CANDIDATE_KINDS) ||
typeof source.available !== "boolean" ||
!oneOf(source.location_state, LOCATION_STATES) ||
revision === null ||
(source.candidate_root_id !== null && rootId === null)
) {
return null;
}
seen.add(sourceId);
// The catalog includes supported-but-not-installed sources. They are valid
// status rows, not connection candidates. Preserve strict identity checks
// for every selected, found source instead of rejecting the whole catalog.
if (source.available === true && source.location_state === "found") {
if (rootId === null) return null;
candidates.push({
source_id: sourceId,
display_name: displayName,
candidate_kind: source.candidate_kind,
candidate_root_id: rootId,
candidate_revision: revision,
requires_override_confirmation: source.candidate_kind !== "default",
});
}
}
return candidates;
}
export function validateLiveSync(value: unknown): LiveSyncHealth[] | null {
return list(value, (item) => {
const health = record(item);
const sourceId = health && text(health.source_id, ID_MAX);
if (
!health ||
sourceId === null ||
!oneOf(health.mode, LIVE_SYNC_MODES) ||
!oneOf(health.state, LIVE_SYNC_STATES) ||
!stringOrNull(health.last_job_id, ID_MAX) ||
!stringOrNull(health.last_attempt_at, LABEL_MAX) ||
!stringOrNull(health.last_success_at, LABEL_MAX) ||
(health.last_error_code !== undefined &&
health.last_error_code !== null &&
text(health.last_error_code, LABEL_MAX) === null)
) {
return null;
}
return {
source_id: sourceId,
mode: health.mode,
state: health.state,
last_job_id: health.last_job_id ?? null,
last_attempt_at: health.last_attempt_at ?? null,
last_success_at: health.last_success_at ?? null,
last_error_code: health.last_error_code ?? null,
} as LiveSyncHealth;
});
}
export function validateImportJobs(value: unknown): ImportJob[] | null {
return list(value, validateImportJob);
}
export function validateImportJob(value: unknown): ImportJob | null {
const job = record(value);
if (!job) return null;
const jobId = text(job.job_id, ID_MAX);
const sourceId = text(job.source_id, ID_MAX);
if (
jobId === null ||
sourceId === null ||
(job.operation !== undefined &&
!oneOf(job.operation, ["history", "sync"] as const)) ||
!oneOf(job.status, IMPORT_STATUSES) ||
(job.phase !== null && !oneOf(job.phase, SCAN_PHASES)) ||
!stringOrNull(job.checkpoint, LABEL_MAX) ||
text(job.created_at, LABEL_MAX) === null ||
text(job.updated_at, LABEL_MAX) === null
) {
return null;
}
for (const key of [
"discovered",
"discovered_targets",
"emitted",
"stored",
"revised",
"merged",
"skipped",
"errors",
]) {
if (count(job[key]) === null) return null;
}
return {
job_id: jobId,
user_id: "local",
source_id: sourceId,
operation: job.operation ?? "history",
status: job.status,
phase: job.phase,
checkpoint: job.checkpoint,
discovered: job.discovered,
discovered_targets: job.discovered_targets,
emitted: job.emitted,
stored: job.stored,
revised: job.revised,
merged: job.merged,
skipped: job.skipped,
errors: job.errors,
created_at: job.created_at,
updated_at: job.updated_at,
} as ImportJob;
}
export function validateImportIssues(
value: unknown,
jobId: string,
): ImportIssue[] | null {
return list(value, (item) => {
const issue = record(item);
if (!issue) return null;
const returnedJobId = text(issue.job_id, ID_MAX);
if (
issue.conversation_id !== null &&
text(issue.conversation_id, ID_MAX) === null
) {
return null;
}
const conversationId = issue.conversation_id as string | null;
const reason = text(issue.reason, LABEL_MAX);
const createdAt = text(issue.created_at, LABEL_MAX);
const issueId = count(issue.issue_id);
if (
returnedJobId !== jobId ||
reason === null ||
createdAt === null ||
issueId === null ||
!oneOf(issue.kind, ["error", "skip"] as const)
) {
return null;
}
return {
issue_id: issueId,
job_id: returnedJobId,
kind: issue.kind,
conversation_id: conversationId,
reason,
created_at: createdAt,
};
});
}
export function validateProcessing(
value: unknown,
): MemoryProcessingSummary | null {
const summary = record(value);
if (!summary) return null;
for (const key of [
"pending",
"fresh_pending",
"backlog_pending",
"outside_window_pending",
"running",
"waiting_for_model",
"completed",
"failed",
]) {
if (count(summary[key]) === null) return null;
}
const blocked = summary.blocked_stages;
if (blocked !== undefined && blocked !== null) {
const stages = list(blocked, (item) => {
const stage = record(item);
return stage &&
text(stage.kind, LABEL_MAX) !== null &&
text(stage.reason, LABEL_MAX) !== null &&
count(stage.count) !== null
? stage
: null;
});
if (stages === null) return null;
}
return summary as unknown as MemoryProcessingSummary;
}
export function validateModelProfiles(value: unknown): ModelProfile[] | null {
return list(value, (item) => {
const profile = record(item);
if (
!profile ||
text(profile.name, LABEL_MAX) === null ||
!oneOf(profile.provider_kind, PROVIDER_KINDS) ||
text(profile.model, LABEL_MAX) === null ||
typeof profile.has_api_key !== "boolean" ||
typeof profile.is_active !== "boolean" ||
(profile.credential_state !== undefined &&
profile.credential_state !== null &&
!oneOf(profile.credential_state, CREDENTIAL_STATES))
) {
return null;
}
return profile as unknown as ModelProfile;
});
}
/** `GET /api/v2/home-summary`: the SDK-authority home card. */
export interface SdkHomeSummary {
schema_version: 2;
memory_count: number;
latest: { memory_id: string } | null;
observed_at: string;
}
export function validateHomeSummary(value: unknown): SdkHomeSummary | null {
const summary = record(value);
if (
!summary ||
summary.schema_version !== 2 ||
count(summary.memory_count) === null ||
text(summary.observed_at, LABEL_MAX) === null
) {
return null;
}
const latest = summary.latest;
if (latest !== null) {
const memory = record(latest);
if (!memory || typeof memory.memory_id !== "string" || !memory.memory_id) {
return null;
}
}
return summary as unknown as SdkHomeSummary;
}
function identifiers(value: unknown): string[] | null {
return list(value ?? [], (item) => text(item, ID_MAX));
}
function list<T>(
value: unknown,
validate: (item: unknown) => T | null,
): T[] | null {
if (!Array.isArray(value) || value.length > LIST_MAX) return null;
const items: T[] = [];
for (const item of value) {
const valid = validate(item);
if (valid === null) return null;
items.push(valid);
}
return items;
}
function record(value: unknown): Record<string, unknown> | null {
return typeof value === "object" && value !== null && !Array.isArray(value)
? (value as Record<string, unknown>)
: null;
}
function text(value: unknown, max: number): string | null {
return typeof value === "string" && value.length <= max ? value : null;
}
function count(value: unknown): number | null {
return typeof value === "number" && Number.isSafeInteger(value) && value >= 0
? value
: null;
}
function booleanOrNull(value: unknown): value is boolean | null {
return value === null || typeof value === "boolean";
}
function stringOrNull(value: unknown, max: number): value is string | null {
return value === null || text(value, max) !== null;
}
function oneOf<T extends string>(
value: unknown,
allowed: readonly T[],
): value is T {
return typeof value === "string" && allowed.includes(value as T);
}