@hasna/mementos 0.15.2 → 0.17.0

package/dist/sdk/index.js

@@ -1,5 +1,274 @@
 // @bun
-// ../contracts/dist/client/transport.js
+// src/audit-contract.ts
+var AUDIT_TRAIL_CONTRACT = "mementos.audit.trail.v1";
+var AUDIT_EXPORT_CONTRACT = "mementos.audit.export.v1";
+var AUDIT_STATS_CONTRACT = "mementos.audit.stats.v1";
+var AUDIT_DEFAULT_LIMIT = 50;
+var AUDIT_OPERATIONS = [
+  "create",
+  "update",
+  "delete",
+  "archive",
+  "restore",
+  "read"
+];
+
+class AuditContractError extends Error {
+  code = "MEMENTOS_AUDIT_CONTRACT";
+  constructor(message) {
+    super(message);
+    this.name = "AuditContractError";
+  }
+}
+var ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+var MD5_HEX = /^[0-9a-f]{32}$/;
+var ENTRY_KEYS = new Set([
+  "id",
+  "memory_id",
+  "memory_key",
+  "operation",
+  "agent_id",
+  "old_value_hash",
+  "new_value_hash",
+  "changes",
+  "created_at"
+]);
+var PAGE_KEYS = new Set([
+  "contract",
+  "entries",
+  "count",
+  "total",
+  "limit",
+  "cursor",
+  "next_cursor",
+  "consumed",
+  "has_more",
+  "complete",
+  "snapshot_at",
+  "filters",
+  "sort"
+]);
+function object(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new AuditContractError(`${label} must be a JSON object`);
+  }
+  return value;
+}
+function exactKeys(value, allowed, label) {
+  const unexpected = Object.keys(value).filter((key) => !allowed.has(key));
+  if (unexpected.length)
+    throw new AuditContractError(`${label} has unexpected field '${unexpected[0]}'`);
+}
+function string(value, label, options = {}) {
+  if (options.nullable && value === null)
+    return null;
+  if (typeof value !== "string" || value.length === 0 || value.length > (options.max ?? 2048) || /[\u0000-\u001f\u007f]/.test(value)) {
+    throw new AuditContractError(`${label} must be a non-empty printable string of at most ${options.max ?? 2048} characters`);
+  }
+  return value;
+}
+function cursorString(value, label) {
+  if (value === null)
+    return null;
+  if (typeof value !== "string" || !value || value.length > 4096 || !/^[A-Za-z0-9_-]+$/.test(value)) {
+    throw new AuditContractError(`${label} must be a bounded base64url cursor or null`);
+  }
+  return value;
+}
+function integer(value, label, minimum = 0) {
+  if (!Number.isSafeInteger(value) || value < minimum) {
+    throw new AuditContractError(`${label} must be a safe integer >= ${minimum}`);
+  }
+  return value;
+}
+function boolean(value, label) {
+  if (typeof value !== "boolean")
+    throw new AuditContractError(`${label} must be a boolean`);
+  return value;
+}
+function canonicalAuditTimestamp(value, label) {
+  if (value instanceof Date)
+    value = value.toISOString();
+  if (typeof value !== "string")
+    throw new AuditContractError(`${label} must be a canonical UTC timestamp`);
+  const candidate = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}(?:\.\d{1,3})?$/.test(value) ? `${value.replace(" ", "T")}${value.includes(".") ? "" : ".000"}Z` : value;
+  if (!ISO_UTC.test(candidate))
+    throw new AuditContractError(`${label} must use YYYY-MM-DDTHH:mm:ss.sssZ`);
+  const parsed = new Date(candidate);
+  if (!Number.isFinite(parsed.getTime()) || parsed.toISOString() !== candidate) {
+    throw new AuditContractError(`${label} must be a real calendar timestamp`);
+  }
+  return candidate;
+}
+function auditOperation(value, label = "operation") {
+  if (typeof value !== "string" || !AUDIT_OPERATIONS.includes(value)) {
+    throw new AuditContractError(`${label} must be one of: ${AUDIT_OPERATIONS.join(", ")}`);
+  }
+  return value;
+}
+function nullableHash(value, label) {
+  if (value === null)
+    return null;
+  if (typeof value !== "string" || !MD5_HEX.test(value)) {
+    throw new AuditContractError(`${label} must be a lowercase md5 hex digest or null`);
+  }
+  return value;
+}
+function record(value, label) {
+  return object(value, label);
+}
+function validateAuditEntry(value, label = "audit entry") {
+  const row = object(value, label);
+  exactKeys(row, ENTRY_KEYS, label);
+  return {
+    id: string(row.id, `${label}.id`, { max: 512 }),
+    memory_id: string(row.memory_id, `${label}.memory_id`, { max: 512 }),
+    memory_key: string(row.memory_key, `${label}.memory_key`, { nullable: true, max: 4096 }),
+    operation: auditOperation(row.operation, `${label}.operation`),
+    agent_id: string(row.agent_id, `${label}.agent_id`, { nullable: true, max: 512 }),
+    old_value_hash: nullableHash(row.old_value_hash, `${label}.old_value_hash`),
+    new_value_hash: nullableHash(row.new_value_hash, `${label}.new_value_hash`),
+    changes: record(row.changes, `${label}.changes`),
+    created_at: canonicalAuditTimestamp(row.created_at, `${label}.created_at`)
+  };
+}
+function nullableTimestamp(value, label) {
+  return value === null ? null : canonicalAuditTimestamp(value, label);
+}
+function validateFilters(value) {
+  const filters = object(value, "audit page filters");
+  const expected = new Set(["memory_id", "since", "until", "operation", "agent_id"]);
+  exactKeys(filters, expected, "audit page filters");
+  const result = {
+    memory_id: string(filters.memory_id, "filters.memory_id", { nullable: true, max: 512 }),
+    since: nullableTimestamp(filters.since, "filters.since"),
+    until: nullableTimestamp(filters.until, "filters.until"),
+    operation: filters.operation === null ? null : auditOperation(filters.operation, "filters.operation"),
+    agent_id: string(filters.agent_id, "filters.agent_id", { nullable: true, max: 512 })
+  };
+  if (result.since && result.until && result.since > result.until) {
+    throw new AuditContractError("filters.since must not be after filters.until");
+  }
+  return result;
+}
+function compareEntryOrder(left, right) {
+  if (left.created_at !== right.created_at)
+    return left.created_at > right.created_at ? -1 : 1;
+  return left.id > right.id ? -1 : left.id < right.id ? 1 : 0;
+}
+function validateAuditPage(value, expected) {
+  const page = object(value, "audit page");
+  exactKeys(page, PAGE_KEYS, "audit page");
+  if (page.contract !== expected.contract)
+    throw new AuditContractError(`expected contract '${expected.contract}'`);
+  const entries = Array.isArray(page.entries) ? page.entries.map((entry, index) => validateAuditEntry(entry, `entries[${index}]`)) : (() => {
+    throw new AuditContractError("entries must be an array");
+  })();
+  const count = integer(page.count, "count");
+  const total = integer(page.total, "total");
+  const limit = integer(page.limit, "limit", 1);
+  const requestedLimit = integer(expected.limit, "requested limit", 1);
+  if (limit !== requestedLimit)
+    throw new AuditContractError("limit receipt does not match the request");
+  const consumed = integer(page.consumed, "consumed");
+  const cursor = cursorString(page.cursor, "cursor");
+  const nextCursor = cursorString(page.next_cursor, "next_cursor");
+  const hasMore = boolean(page.has_more, "has_more");
+  const complete = boolean(page.complete, "complete");
+  const snapshotAt = canonicalAuditTimestamp(page.snapshot_at, "snapshot_at");
+  const filters = validateFilters(page.filters);
+  const sort = object(page.sort, "sort");
+  exactKeys(sort, new Set(["field", "direction", "tie_breaker"]), "sort");
+  if (sort.field !== "created_at" || sort.direction !== "desc" || sort.tie_breaker !== "id") {
+    throw new AuditContractError("sort must be created_at desc with id tie-breaker");
+  }
+  if (cursor !== expected.cursor)
+    throw new AuditContractError("cursor receipt does not match the request");
+  for (const key of ["memory_id", "since", "until", "operation", "agent_id"]) {
+    if (filters[key] !== expected.filters[key]) {
+      throw new AuditContractError(`filters.${key} receipt does not match the request`);
+    }
+  }
+  if (count !== entries.length || count > limit || total < count || consumed < count || consumed > total) {
+    throw new AuditContractError("count/limit/consumed/total fields are inconsistent");
+  }
+  if (hasMore !== consumed < total)
+    throw new AuditContractError("has_more does not match consumed/total");
+  if (hasMore !== (nextCursor !== null))
+    throw new AuditContractError("next_cursor does not match has_more");
+  if (total > 0 && count === 0)
+    throw new AuditContractError("non-empty audit result must make progress on every page");
+  if (hasMore && nextCursor === cursor)
+    throw new AuditContractError("next_cursor must advance beyond the request cursor");
+  const shouldBeComplete = cursor === null && !hasMore && consumed === total;
+  if (complete !== shouldBeComplete)
+    throw new AuditContractError("complete is not truthful for this page");
+  if (cursor === null && consumed !== count)
+    throw new AuditContractError("initial page consumed must equal count");
+  for (let index = 1;index < entries.length; index++) {
+    if (compareEntryOrder(entries[index - 1], entries[index]) >= 0) {
+      throw new AuditContractError("entries are not strictly ordered by created_at desc, id desc");
+    }
+  }
+  const ids = new Set;
+  for (const entry of entries) {
+    if (ids.has(entry.id))
+      throw new AuditContractError(`duplicate audit entry id '${entry.id}'`);
+    ids.add(entry.id);
+    if (filters.memory_id && entry.memory_id !== filters.memory_id)
+      throw new AuditContractError("entry violates memory_id filter");
+    if (filters.operation && entry.operation !== filters.operation)
+      throw new AuditContractError("entry violates operation filter");
+    if (filters.agent_id && entry.agent_id !== filters.agent_id)
+      throw new AuditContractError("entry violates agent_id filter");
+    if (filters.since && entry.created_at < filters.since)
+      throw new AuditContractError("entry violates since filter");
+    if (filters.until && entry.created_at > filters.until)
+      throw new AuditContractError("entry violates until filter");
+    if (entry.created_at > snapshotAt)
+      throw new AuditContractError("entry is newer than the snapshot boundary");
+  }
+  return {
+    contract: expected.contract,
+    entries,
+    count,
+    total,
+    limit,
+    cursor,
+    next_cursor: nextCursor,
+    consumed,
+    has_more: hasMore,
+    complete,
+    snapshot_at: snapshotAt,
+    filters,
+    sort: { field: "created_at", direction: "desc", tie_breaker: "id" }
+  };
+}
+function validateAuditStats(value) {
+  const stats = object(value, "audit stats");
+  exactKeys(stats, new Set(["contract", "total_entries", "by_operation", "recent_24h", "snapshot_at"]), "audit stats");
+  if (stats.contract !== AUDIT_STATS_CONTRACT)
+    throw new AuditContractError(`expected contract '${AUDIT_STATS_CONTRACT}'`);
+  const total = integer(stats.total_entries, "total_entries");
+  const recent = integer(stats.recent_24h, "recent_24h");
+  const byOperationObject = object(stats.by_operation, "by_operation");
+  exactKeys(byOperationObject, new Set(AUDIT_OPERATIONS), "by_operation");
+  const byOperation = Object.fromEntries(AUDIT_OPERATIONS.map((operation) => [operation, integer(byOperationObject[operation], `by_operation.${operation}`)]));
+  if (Object.values(byOperation).reduce((sum, count) => sum + count, 0) !== total) {
+    throw new AuditContractError("by_operation counts do not sum to total_entries");
+  }
+  if (recent > total)
+    throw new AuditContractError("recent_24h exceeds total_entries");
+  return {
+    contract: AUDIT_STATS_CONTRACT,
+    total_entries: total,
+    by_operation: byOperation,
+    recent_24h: recent,
+    snapshot_at: canonicalAuditTimestamp(stats.snapshot_at, "snapshot_at")
+  };
+}
+
+// ../../node_modules/.bun/@hasna+contracts@1.0.2+e8014c875821e0be/node_modules/@hasna/contracts/dist/client/transport.js
 import { isIP } from "net";
 import { spawnSync } from "child_process";
 import { closeSync, fstatSync, openSync, readFileSync } from "fs";
@@ -798,6 +1067,11 @@ function mementosResolverInputs(env, credentials = {}) {
 }
 
 // src/sdk/index.ts
+var MEMENTOS_MACHINE_REGISTRATION_CONTRACT = "mementos.machine-registration.v1";
+var MEMENTOS_MACHINE_LIST_CONTRACT = "mementos.machines.v1";
+var MEMENTOS_MACHINE_MUTATION_CONTRACT = "mementos.machine-mutation.v1";
+var MEMENTOS_MACHINE_TOUCH_CONTRACT = "mementos.machine-touch.v1";
+
 class MementosError extends Error {
   status;
   details;
@@ -816,9 +1090,297 @@ class MementosConfigError extends Error {
     this.name = "MementosConfigError";
   }
 }
+var SESSION_JOBS_PAGE_CONTRACT = "mementos.sessions.jobs.v2";
+function sdkProtocolError(operation, detail) {
+  return new MementosError(`mementos ${operation} returned a malformed 2xx response: ${detail}`, 502);
+}
+function sessionProtocolError(detail) {
+  return sdkProtocolError("session jobs", detail);
+}
+function auditSdkError(operation, error) {
+  if (error instanceof MementosError)
+    throw error;
+  const detail = error instanceof Error ? error.message : String(error);
+  throw sdkProtocolError(operation, detail);
+}
+function sdkAuditIdentifier(value, label) {
+  if (value === undefined)
+    return null;
+  if (!value || value.length > 512 || /[\u0000-\u001f\u007f]/.test(value)) {
+    throw new AuditContractError(`${label} must be a non-empty printable string of at most 512 characters`);
+  }
+  return value;
+}
+function sdkAuditFilters(input) {
+  const filters = {
+    memory_id: sdkAuditIdentifier(input.memory_id, "memory_id"),
+    since: input.since === undefined ? null : canonicalAuditTimestamp(input.since, "since"),
+    until: input.until === undefined ? null : canonicalAuditTimestamp(input.until, "until"),
+    operation: input.operation === undefined ? null : auditOperation(input.operation),
+    agent_id: sdkAuditIdentifier(input.agent_id, "agent_id")
+  };
+  if (filters.since && filters.until && filters.since > filters.until) {
+    throw new AuditContractError("since must not be after until");
+  }
+  return filters;
+}
+function sdkAuditCursor(cursor) {
+  if (cursor === undefined)
+    return;
+  if (!cursor || cursor.length > 4096 || !/^[A-Za-z0-9_-]+$/.test(cursor)) {
+    throw new AuditContractError("cursor must be a bounded base64url audit cursor");
+  }
+  return cursor;
+}
+function sdkAuditLimit(limit) {
+  if (limit === undefined)
+    return;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000) {
+    throw new AuditContractError("limit must be an integer between 1 and 1000");
+  }
+  return limit;
+}
+function sdkObject(value, operation, field = "response") {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw sdkProtocolError(operation, `expected ${field} to be a JSON object`);
+  }
+  return value;
+}
+var SDK_MACHINE_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+function sdkMachineHostname(value, operation) {
+  const normalized = value.trim().replace(/\.+$/, "").toLowerCase();
+  if (!normalized || normalized.length > 253 || /[\u0000-\u001f\u007f/\\\s]/.test(normalized) || normalized !== value) {
+    throw sdkProtocolError(operation, "machine.hostname is not canonical");
+  }
+  return normalized;
+}
+function sdkMachinePlatform(value, operation) {
+  const normalized = value.trim().toLowerCase();
+  if (!normalized || normalized.length > 64 || !/^[a-z0-9._-]+$/.test(normalized) || normalized !== value) {
+    throw sdkProtocolError(operation, "machine.platform is not canonical");
+  }
+  return normalized;
+}
+function sdkMachineName(value, operation) {
+  if (typeof value !== "string" || !value || value.length > 128 || /[\u0000-\u001f\u007f]/.test(value)) {
+    throw sdkProtocolError(operation, "machine.name is outside the public contract");
+  }
+  return value;
+}
+function sdkMachineTimestamp(value, operation, field) {
+  if (typeof value !== "string" || !SDK_MACHINE_TIMESTAMP.test(value)) {
+    throw sdkProtocolError(operation, `machine.${field} is not a canonical UTC timestamp`);
+  }
+  const parsed = new Date(value);
+  if (!Number.isFinite(parsed.getTime()) || parsed.toISOString() !== value) {
+    throw sdkProtocolError(operation, `machine.${field} is not a real calendar timestamp`);
+  }
+  return value;
+}
+function sdkMachine(value, operation) {
+  const machine = sdkObject(value, operation, "machine");
+  if (typeof machine["id"] !== "string" || !machine["id"]) {
+    throw sdkProtocolError(operation, "expected machine.id to be a non-empty string");
+  }
+  if (typeof machine["hostname"] !== "string" || typeof machine["platform"] !== "string") {
+    throw sdkProtocolError(operation, "expected machine hostname/platform strings");
+  }
+  if (typeof machine["is_primary"] !== "boolean") {
+    throw sdkProtocolError(operation, "expected machine.is_primary to be a boolean");
+  }
+  const createdAt = sdkMachineTimestamp(machine["created_at"], operation, "created_at");
+  const lastSeenAt = sdkMachineTimestamp(machine["last_seen_at"], operation, "last_seen_at");
+  if (lastSeenAt < createdAt)
+    throw sdkProtocolError(operation, "machine.last_seen_at precedes created_at");
+  return {
+    id: machine["id"],
+    name: sdkMachineName(machine["name"], operation),
+    hostname: sdkMachineHostname(machine["hostname"], operation),
+    platform: sdkMachinePlatform(machine["platform"], operation),
+    is_primary: machine["is_primary"],
+    created_at: createdAt,
+    last_seen_at: lastSeenAt
+  };
+}
+function sdkMachineMutation(value, operation, expectedId) {
+  const response = sdkObject(value, operation);
+  if (response["contract"] !== MEMENTOS_MACHINE_MUTATION_CONTRACT) {
+    throw sdkProtocolError(operation, `expected contract '${MEMENTOS_MACHINE_MUTATION_CONTRACT}'`);
+  }
+  const machine = sdkMachine(response["machine"], operation);
+  if (machine.id !== expectedId) {
+    throw sdkProtocolError(operation, "returned machine id does not match the requested stable id");
+  }
+  return machine;
+}
+function sessionObject(value, field = "response") {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw sessionProtocolError(`expected ${field} to be a JSON object`);
+  }
+  return value;
+}
+function sessionString(object2, field, nullable = false) {
+  const value = object2[field];
+  if (nullable && value === null)
+    return null;
+  if (typeof value !== "string" || !nullable && value.length === 0) {
+    throw sessionProtocolError(`expected '${field}' to be ${nullable ? "a string or null" : "a non-empty string"}`);
+  }
+  return value;
+}
+function sessionCount(object2, field) {
+  const value = object2[field];
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw sessionProtocolError(`expected '${field}' to be a non-negative safe integer`);
+  }
+  return value;
+}
+function decodeSessionJob(value, index) {
+  const job = sessionObject(value, `jobs[${index}]`);
+  const source = sessionString(job, "source");
+  if (!["claude-code", "codex", "manual", "open-sessions"].includes(source)) {
+    throw sessionProtocolError(`jobs[${index}] has unsupported 'source'`);
+  }
+  const status = sessionString(job, "status");
+  if (!["pending", "processing", "completed", "failed"].includes(status)) {
+    throw sessionProtocolError(`jobs[${index}] has unsupported 'status'`);
+  }
+  const metadata = sessionObject(job["metadata"], `jobs[${index}].metadata`);
+  return {
+    id: sessionString(job, "id"),
+    session_id: sessionString(job, "session_id"),
+    agent_id: sessionString(job, "agent_id", true),
+    project_id: sessionString(job, "project_id", true),
+    source,
+    status,
+    transcript: typeof job["transcript"] === "string" ? job["transcript"] : (() => {
+      throw sessionProtocolError(`jobs[${index}] expected 'transcript' to be a string`);
+    })(),
+    chunk_count: sessionCount(job, "chunk_count"),
+    memories_extracted: sessionCount(job, "memories_extracted"),
+    error: sessionString(job, "error", true),
+    metadata,
+    created_at: sessionString(job, "created_at"),
+    started_at: sessionString(job, "started_at", true),
+    completed_at: sessionString(job, "completed_at", true)
+  };
+}
+function decodeSessionJobsPage(value) {
+  const page = sessionObject(value);
+  if (page["contract"] !== SESSION_JOBS_PAGE_CONTRACT) {
+    throw sessionProtocolError(`expected contract '${SESSION_JOBS_PAGE_CONTRACT}'`);
+  }
+  if (!Array.isArray(page["jobs"]))
+    throw sessionProtocolError("expected 'jobs' to be an array");
+  const jobs = page["jobs"].map(decodeSessionJob);
+  const count = sessionCount(page, "count");
+  const limit = sessionCount(page, "limit");
+  const offset = sessionCount(page, "offset");
+  if (limit < 1)
+    throw sessionProtocolError("expected 'limit' to be positive");
+  if (count !== jobs.length || count > limit) {
+    throw sessionProtocolError("page count is inconsistent with jobs/limit");
+  }
+  if (typeof page["has_more"] !== "boolean")
+    throw sessionProtocolError("expected 'has_more' to be a boolean");
+  const nextOffset = page["next_offset"];
+  if (nextOffset !== null && (!Number.isSafeInteger(nextOffset) || nextOffset < 0)) {
+    throw sessionProtocolError("expected 'next_offset' to be a non-negative safe integer or null");
+  }
+  if (page["has_more"] === true && nextOffset !== offset + jobs.length) {
+    throw sessionProtocolError("'has_more' requires the exact next offset");
+  }
+  if (page["has_more"] === false && nextOffset !== null) {
+    throw sessionProtocolError("terminal page must set 'next_offset' to null");
+  }
+  return {
+    contract: SESSION_JOBS_PAGE_CONTRACT,
+    jobs,
+    count,
+    limit,
+    offset,
+    has_more: page["has_more"],
+    next_offset: nextOffset
+  };
+}
+function decodeSessionIngestReceipt(value, transcript, expectedSessionId) {
+  const receipt = sessionObject(value);
+  if (receipt["contract"] !== "mementos.sessions.ingest.v2") {
+    throw sdkProtocolError("session ingest", "expected contract 'mementos.sessions.ingest.v2'");
+  }
+  const jobId = sessionString(receipt, "job_id");
+  if (receipt["status"] !== "queued")
+    throw sdkProtocolError("session ingest", "expected status 'queued'");
+  const message = sessionString(receipt, "message");
+  const rawJob = sessionObject(receipt["job"], "job");
+  const job = decodeSessionJob({ ...rawJob, transcript }, 0);
+  if (job.id !== jobId || job.session_id !== expectedSessionId) {
+    throw sdkProtocolError("session ingest", "job receipt identity does not match the request");
+  }
+  return {
+    contract: "mementos.sessions.ingest.v2",
+    job_id: jobId,
+    status: "queued",
+    message,
+    job
+  };
+}
+function decodeQueueStats(value) {
+  const stats = sessionObject(value);
+  return {
+    pending: sessionCount(stats, "pending"),
+    processing: sessionCount(stats, "processing"),
+    completed: sessionCount(stats, "completed"),
+    failed: sessionCount(stats, "failed")
+  };
+}
+var SDK_RESOURCE_TYPES = new Set(["project", "memory", "entity", "agent", "connector", "file"]);
+var SDK_LOCK_TYPES = new Set(["advisory", "exclusive"]);
+function decodeResourceLock(value, operation) {
+  const lock = sessionObject(value, "lock");
+  const resourceType = sessionString(lock, "resource_type");
+  const lockType = sessionString(lock, "lock_type");
+  if (!SDK_RESOURCE_TYPES.has(resourceType)) {
+    throw sdkProtocolError(operation, "unsupported 'resource_type'");
+  }
+  if (!SDK_LOCK_TYPES.has(lockType)) {
+    throw sdkProtocolError(operation, "unsupported 'lock_type'");
+  }
+  return {
+    id: sessionString(lock, "id"),
+    resource_type: resourceType,
+    resource_id: sessionString(lock, "resource_id"),
+    agent_id: sessionString(lock, "agent_id"),
+    lock_type: lockType,
+    locked_at: sessionString(lock, "locked_at"),
+    expires_at: sessionString(lock, "expires_at")
+  };
+}
+function decodeResourceLocks(value, operation) {
+  if (!Array.isArray(value))
+    throw sdkProtocolError(operation, "expected a JSON array");
+  return value.map((lock) => decodeResourceLock(lock, operation));
+}
+function decodeBooleanReceipt(value, field, operation) {
+  const receipt = sessionObject(value);
+  if (typeof receipt[field] !== "boolean")
+    throw sdkProtocolError(operation, `expected '${field}' to be a boolean`);
+  return { [field]: receipt[field] };
+}
+function decodeCountReceipt(value, field, operation) {
+  const receipt = sessionObject(value);
+  const count = receipt[field];
+  if (!Number.isSafeInteger(count) || count < 0) {
+    throw sdkProtocolError(operation, `expected '${field}' to be a non-negative safe integer`);
+  }
+  return { [field]: count };
+}
 var MEMENTOS_DEFAULT_BASE_URL = "http://localhost:19428";
 function resolveMementosApiBase(rawBaseUrl, explicitPrefix) {
-  const trimmed = (rawBaseUrl ?? MEMENTOS_DEFAULT_BASE_URL).trim().replace(/\/+$/, "") || MEMENTOS_DEFAULT_BASE_URL;
+  if (rawBaseUrl === undefined || rawBaseUrl.trim() === "") {
+    throw new Error("mementos base URL is required for this explicit-base helper; ordinary SDK clients must resolve the hosted authority through the credential chain or opt into local mode");
+  }
+  const trimmed = rawBaseUrl.trim().replace(/\/+$/, "");
   let url;
   try {
     url = new URL(trimmed);
@@ -927,10 +1489,10 @@ class MementosClient {
   _resolveOptions;
   _pinnedAuthority = null;
   constructor(config = {}) {
-    const resolved = resolveMementosApiBase(config.baseUrl, config.prefix);
+    const prefix = config.baseUrl !== undefined ? resolveMementosApiBase(config.baseUrl, config.prefix).prefix : config.prefix?.replace(/\/+$/, "") || "/v1";
     this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
     this.apiKey = config.apiKey;
-    this.prefix = resolved.prefix;
+    this.prefix = prefix;
     this._resolveOptions = {
       ...config.baseUrl !== undefined ? { baseUrl: config.baseUrl } : {},
       ...config.apiKey !== undefined ? { apiKey: config.apiKey } : {},
@@ -1044,6 +1606,8 @@ class MementosClient {
         q["agent_id"] = filter.agent_id;
       if (filter.project_id)
         q["project_id"] = filter.project_id;
+      if (filter.project_id && filter.include_unassigned_project)
+        q["include_unassigned_project"] = true;
       if (filter.session_id)
         q["session_id"] = filter.session_id;
       if (filter.namespace)
@@ -1202,6 +1766,126 @@ class MementosClient {
   listAgentsByProject(projectId) {
     return this.get(`/api/agents`, { project_id: projectId });
   }
+  async getMemoryAuditTrail(memoryId, options = {}) {
+    const operation = "GET /v1/memories/:id/audit-trail";
+    try {
+      const filters = sdkAuditFilters({ memory_id: memoryId });
+      const requestedLimit = sdkAuditLimit(options.limit);
+      const limit = requestedLimit ?? AUDIT_DEFAULT_LIMIT;
+      const requestedCursor = sdkAuditCursor(options.cursor);
+      const cursor = requestedCursor ?? null;
+      const response = await this.get(`/api/memories/${encodeURIComponent(filters.memory_id)}/audit-trail`, { limit: requestedLimit, cursor: requestedCursor });
+      return validateAuditPage(response, { contract: AUDIT_TRAIL_CONTRACT, cursor, filters, limit });
+    } catch (error) {
+      return auditSdkError(operation, error);
+    }
+  }
+  async exportAuditLog(options = {}) {
+    const operation = "GET /v1/audit/export";
+    try {
+      const filters = sdkAuditFilters(options);
+      const requestedLimit = sdkAuditLimit(options.limit);
+      const limit = requestedLimit ?? AUDIT_DEFAULT_LIMIT;
+      const requestedCursor = sdkAuditCursor(options.cursor);
+      const cursor = requestedCursor ?? null;
+      const response = await this.get("/api/audit/export", {
+        since: filters.since ?? undefined,
+        until: filters.until ?? undefined,
+        operation: filters.operation ?? undefined,
+        agent_id: filters.agent_id ?? undefined,
+        limit: requestedLimit,
+        cursor: requestedCursor
+      });
+      return validateAuditPage(response, { contract: AUDIT_EXPORT_CONTRACT, cursor, filters, limit });
+    } catch (error) {
+      return auditSdkError(operation, error);
+    }
+  }
+  async getAuditStats() {
+    const operation = "GET /v1/audit/stats";
+    try {
+      return validateAuditStats(await this.get("/api/audit/stats"));
+    } catch (error) {
+      return auditSdkError(operation, error);
+    }
+  }
+  async listMachines() {
+    const operation = "GET /v1/machines";
+    const response = sdkObject(await this.get("/api/machines"), operation);
+    if (response["contract"] !== MEMENTOS_MACHINE_LIST_CONTRACT || response["complete"] !== true || !Array.isArray(response["machines"])) {
+      throw sdkProtocolError(operation, `expected contract '${MEMENTOS_MACHINE_LIST_CONTRACT}', complete=true, and a machines array`);
+    }
+    const machines = response["machines"].map((entry, index) => sdkMachine(entry, `${operation} machines[${index}]`));
+    if (!Number.isSafeInteger(response["count"]) || response["count"] !== machines.length) {
+      throw sdkProtocolError(operation, "count does not match machines.length");
+    }
+    if (new Set(machines.map((machine) => machine.id)).size !== machines.length || new Set(machines.map((machine) => machine.hostname)).size !== machines.length || new Set(machines.map((machine) => machine.name)).size !== machines.length) {
+      throw sdkProtocolError(operation, "machine ids, hostnames, or names are duplicated");
+    }
+    if (machines.filter((machine) => machine.is_primary).length > 1) {
+      throw sdkProtocolError(operation, "more than one machine is primary");
+    }
+    return { machines, count: machines.length, complete: true };
+  }
+  async registerMachine(input) {
+    const operation = "POST /v1/machines";
+    const response = sdkObject(await this.post("/api/machines", input), operation);
+    if (response["contract"] !== MEMENTOS_MACHINE_REGISTRATION_CONTRACT || typeof response["created"] !== "boolean") {
+      throw sdkProtocolError(operation, `expected contract '${MEMENTOS_MACHINE_REGISTRATION_CONTRACT}' and a boolean created receipt`);
+    }
+    const machine = sdkMachine(response["machine"], operation);
+    const identity = sdkObject(response["identity"], operation, "identity");
+    if (identity["idempotency_key"] !== "normalized_hostname" || identity["stable_id"] !== machine.id) {
+      throw sdkProtocolError(operation, "identity receipt does not match the stable machine id");
+    }
+    const expectedHostname = sdkMachineHostname(input.hostname.trim().replace(/\.+$/, "").toLowerCase(), operation);
+    const expectedPlatform = sdkMachinePlatform(input.platform.trim().toLowerCase(), operation);
+    if (machine.hostname !== expectedHostname || machine.platform !== expectedPlatform) {
+      throw sdkProtocolError(operation, "registration receipt does not match the requested hostname/platform");
+    }
+    if (response["created"] === true) {
+      const expectedName = input.name?.trim() || expectedHostname;
+      if (machine.name !== expectedName)
+        throw sdkProtocolError(operation, "created registration receipt does not match the requested name");
+    }
+    return machine;
+  }
+  async getMachine(id) {
+    return sdkMachineMutation(await this.get(`/api/machines/${encodeURIComponent(id)}`), "GET /v1/machines/:id", id);
+  }
+  async renameMachine(id, name) {
+    const normalizedName = name.trim();
+    const machine = sdkMachineMutation(await this.patch(`/api/machines/${encodeURIComponent(id)}`, { name: normalizedName }), "PATCH /v1/machines/:id", id);
+    if (machine.name !== normalizedName)
+      throw sdkProtocolError("PATCH /v1/machines/:id", "returned name does not match the requested rename");
+    return machine;
+  }
+  async setPrimaryMachine(id) {
+    const machine = sdkMachineMutation(await this.post(`/api/machines/${encodeURIComponent(id)}/primary`), "POST /v1/machines/:id/primary", id);
+    if (!machine.is_primary)
+      throw sdkProtocolError("POST /v1/machines/:id/primary", "returned machine is not primary");
+    return machine;
+  }
+  async touchMachine(id) {
+    const operation = "POST /v1/machines/:id/touch";
+    const response = sdkObject(await this.post(`/api/machines/${encodeURIComponent(id)}/touch`), operation);
+    if (response["contract"] !== MEMENTOS_MACHINE_TOUCH_CONTRACT || response["touched"] !== true || response["id"] !== id) {
+      throw sdkProtocolError(operation, "expected touched=true for the requested stable id");
+    }
+    const machine = sdkMachine(response["machine"], operation);
+    if (machine.id !== id || response["touched_at"] !== machine.last_seen_at) {
+      throw sdkProtocolError(operation, "touch receipt does not match the returned machine");
+    }
+    return machine;
+  }
+  async deleteMachine(id) {
+    const operation = "DELETE /v1/machines/:id";
+    const response = sdkObject(await this.delete(`/api/machines/${encodeURIComponent(id)}`), operation);
+    if (response["contract"] !== MEMENTOS_MACHINE_MUTATION_CONTRACT || response["deleted"] !== true || response["id"] !== id) {
+      throw sdkProtocolError(operation, "expected deleted=true for the requested stable id");
+    }
+    return { deleted: true, id };
+  }
   listProjects() {
     return this.get("/api/projects");
   }
@@ -1422,30 +2106,30 @@ class MementosClient {
   }
   async acquireLock(input) {
     try {
-      return await this.post("/api/locks", input);
-    } catch (e) {
-      if (e instanceof Error && e.message.includes("409"))
+      return decodeResourceLock(await this.post("/api/locks", input), "lock acquire");
+    } catch (error) {
+      if (error instanceof MementosError && error.status === 409)
         return null;
-      throw e;
+      throw error;
     }
   }
-  checkLock(resourceType, resourceId, lockType) {
+  async checkLock(resourceType, resourceId, lockType) {
     const params = { resource_type: resourceType, resource_id: resourceId };
     if (lockType)
       params["lock_type"] = lockType;
-    return this.get("/api/locks", params);
+    return decodeResourceLocks(await this.get("/api/locks", params), "lock list");
   }
-  releaseLock(lockId, agentId) {
-    return this.request("DELETE", `/api/locks/${lockId}`, { agent_id: agentId });
+  async releaseLock(lockId, agentId) {
+    return decodeBooleanReceipt(await this.request("DELETE", `/api/locks/${encodeURIComponent(lockId)}`, { agent_id: agentId }), "released", "lock release");
   }
-  listAgentLocks(agentId) {
-    return this.get(`/api/agents/${agentId}/locks`);
+  async listAgentLocks(agentId) {
+    return decodeResourceLocks(await this.get(`/api/agents/${encodeURIComponent(agentId)}/locks`), "agent lock list");
   }
-  releaseAllAgentLocks(agentId) {
-    return this.request("DELETE", `/api/agents/${agentId}/locks`);
+  async releaseAllAgentLocks(agentId) {
+    return decodeCountReceipt(await this.request("DELETE", `/api/agents/${encodeURIComponent(agentId)}/locks`), "released", "agent lock release");
   }
-  cleanExpiredLocks() {
-    return this.post("/api/locks/clean", {});
+  async cleanExpiredLocks() {
+    return decodeCountReceipt(await this.post("/api/locks/clean", {}), "cleaned", "lock cleanup");
   }
   createTask(input) {
     return this.post("/api/tasks", input);
@@ -1567,27 +2251,53 @@ class MementosClient {
   rollbackSynthesis(runId) {
     return this.post(`/api/synthesis/rollback/${runId}`, {});
   }
-  ingestSession(input) {
-    return this.post("/api/sessions/ingest", input);
+  async ingestSession(input) {
+    return decodeSessionIngestReceipt(await this.post("/api/sessions/ingest", input), input.transcript, input.session_id);
   }
-  getSessionJob(jobId) {
-    return this.get(`/api/sessions/jobs/${jobId}`);
+  async getSessionJob(jobId) {
+    return decodeSessionJob(await this.get(`/api/sessions/jobs/${encodeURIComponent(jobId)}`), 0);
   }
-  listSessionJobs(filter) {
+  async listSessionJobs(filter) {
     const params = new URLSearchParams;
     if (filter?.agent_id)
       params.set("agent_id", filter.agent_id);
     if (filter?.project_id)
       params.set("project_id", filter.project_id);
+    if (filter?.session_id)
+      params.set("session_id", filter.session_id);
     if (filter?.status)
       params.set("status", filter.status);
-    if (filter?.limit)
+    if (filter?.limit !== undefined)
       params.set("limit", String(filter.limit));
+    if (filter?.offset !== undefined)
+      params.set("offset", String(filter.offset));
     const qs = params.toString() ? `?${params.toString()}` : "";
-    return this.get(`/api/sessions/jobs${qs}`);
+    const response = await this.get(`/api/sessions/jobs${qs}`);
+    const page = decodeSessionJobsPage(response);
+    if (filter?.limit !== undefined && page.limit !== filter.limit) {
+      throw sessionProtocolError("server did not preserve requested 'limit'");
+    }
+    if (filter?.offset !== undefined && page.offset !== filter.offset) {
+      throw sessionProtocolError("server did not preserve requested 'offset'");
+    }
+    for (const job of page.jobs) {
+      if (filter?.agent_id !== undefined && job.agent_id !== filter.agent_id) {
+        throw sessionProtocolError("server did not preserve requested 'agent_id'");
+      }
+      if (filter?.project_id !== undefined && job.project_id !== filter.project_id) {
+        throw sessionProtocolError("server did not preserve requested 'project_id'");
+      }
+      if (filter?.session_id !== undefined && job.session_id !== filter.session_id) {
+        throw sessionProtocolError("server did not preserve requested 'session_id'");
+      }
+      if (filter?.status !== undefined && job.status !== filter.status) {
+        throw sessionProtocolError("server did not preserve requested 'status'");
+      }
+    }
+    return page;
   }
-  getSessionQueueStats() {
-    return this.get("/api/sessions/queue/stats");
+  async getSessionQueueStats() {
+    return decodeQueueStats(await this.get("/api/sessions/queue/stats"));
   }
 }
 var sdk_default = MementosClient;
@@ -1596,8 +2306,16 @@ export {
   resolveMementosApiBase,
   sdk_default as default,
   __resetMementosSdkLocalNotice,
+  SESSION_JOBS_PAGE_CONTRACT,
   MementosError,
   MementosConfigError,
   MementosClient,
-  MEMENTOS_DEFAULT_BASE_URL
+  MEMENTOS_MACHINE_TOUCH_CONTRACT,
+  MEMENTOS_MACHINE_REGISTRATION_CONTRACT,
+  MEMENTOS_MACHINE_MUTATION_CONTRACT,
+  MEMENTOS_MACHINE_LIST_CONTRACT,
+  MEMENTOS_DEFAULT_BASE_URL,
+  AUDIT_TRAIL_CONTRACT as MEMENTOS_AUDIT_TRAIL_CONTRACT,
+  AUDIT_STATS_CONTRACT as MEMENTOS_AUDIT_STATS_CONTRACT,
+  AUDIT_EXPORT_CONTRACT as MEMENTOS_AUDIT_EXPORT_CONTRACT
 };