clay-server 5.2.0-beta.2 → 5.2.0-beta.4

package/lib/knowledge-db-storage.js

@@ -0,0 +1,72 @@
+// Version 1 persists opaque JSON aggregate snapshots with a stable _id and revision.
+// _id is the existing Knowledge identity, not a query expression. Engines may map it
+// to their own primary key; aggregate format/limits remain application responsibilities.
+// Each adapter is bound to one server-authorized Mate-project store; get/list cannot
+// broaden that scope. Facades for the same store must share locks and committed cache.
+//
+// initialize() -> Promise<void>; hasStore()/isReady() -> boolean.
+// get(id) -> Promise<snapshot|null>; list() -> Promise<snapshot[]>;
+// getCached() -> snapshot[] (committed, detached, no initialization side effect).
+// insert(snapshot) -> Promise<void> (reject ALREADY_EXISTS; never overwrite).
+// replaceIfRevision(id, revision, snapshot) -> Promise<boolean>: atomic compare and
+// full replacement, false on missing/mismatch without writing. Same-revision writes
+// are allowed for receipts/projection status. Identity must remain unchanged.
+// serialize(scope, work) -> Promise<result>: same-scope callbacks exclude each other
+// across all facades of one physical store. Callback receives no engine objects and
+// may await adapter operations; this is not a multi-aggregate transaction or I/O lock.
+// Engines separately serialize reads/writes/maintenance/recovery as needed. A failed
+// write may have committed durably; restore readable committed state before releasing
+// the I/O gate, or invalidate it. Never turn committed success into maintenance failure.
+// Domain operation receipts resolve ambiguous retries; the adapter does not own them.
+// diagnostics() -> Promise<JSON> is optional, engine-specific and never a native handle.
+
+var METHODS = ["initialize", "hasStore", "isReady", "get", "list", "getCached", "insert", "replaceIfRevision", "serialize"];
+function invalid(message) { return Object.assign(new Error("Invalid Knowledge storage adapter: " + message), { code: "INVALID_STORAGE_ADAPTER" }); }
+function validateAdapter(adapter) {
+  if (!adapter || typeof adapter !== "object" || adapter.contractVersion !== 1) throw invalid("contractVersion must be 1.");
+  METHODS.forEach(function (name) { if (typeof adapter[name] !== "function") throw invalid(name + " must be a function."); });
+  if (adapter.diagnostics !== undefined && typeof adapter.diagnostics !== "function") throw invalid("diagnostics must be a function when supplied.");
+  return adapter;
+}
+function bindAdapter(adapter) {
+  function snapshot(value) {
+    if (!value || Object.getPrototypeOf(value) !== Object.prototype || typeof value._id !== "string" || !Number.isInteger(value.revision)) throw invalid("snapshot must be a plain aggregate with _id and integer revision.");
+    return value;
+  }
+  function snapshots(values) { if (!Array.isArray(values)) throw invalid("list/getCached must return an array."); values.forEach(snapshot); return values; }
+  function call(name, args, check) {
+    var result;
+    try { result = adapter[name].apply(adapter, args); } catch (cause) { return Promise.reject(cause); }
+    if (!result || typeof result.then !== "function") return Promise.reject(invalid(name + " must return a Promise."));
+    return result.then(check);
+  }
+  function flag(name) { var value = adapter[name](); if (typeof value !== "boolean") throw invalid(name + " must return a boolean."); return value; }
+  var bound = {
+    contractVersion: 1,
+    initialize: function () { return call("initialize", [], function () {}); },
+    hasStore: function () { return flag("hasStore"); }, isReady: function () { return flag("isReady"); },
+    get: function (id) { return call("get", [id], function (value) { if (value === null) return null; snapshot(value); if (value._id !== id) throw invalid("get returned a different identity."); return value; }); },
+    list: function () { return call("list", [], snapshots); }, getCached: function () { return snapshots(adapter.getCached()); },
+    insert: function (value) { return call("insert", [value], function (result) { if (result !== undefined) throw invalid("insert must resolve without a native result."); }); },
+    replaceIfRevision: function (id, revision, value) { return call("replaceIfRevision", [id, revision, value], function (result) { if (typeof result !== "boolean") throw invalid("replaceIfRevision must resolve to a boolean."); return result; }); },
+    serialize: function (scope, work) { return call("serialize", [scope, function () { return work(); }], function (result) { return result; }); }
+  };
+  if (typeof adapter.diagnostics === "function") bound.diagnostics = function () {
+    return call("diagnostics", [], function (result) { try { return JSON.parse(JSON.stringify(result)); } catch (cause) { throw invalid("diagnostics must resolve to JSON data."); } });
+  };
+  return bound;
+}
+function createDefaultKnowledgeDbStorage(options) {
+  // Lazy engine loading: injected adapters can run domain code without NeDB installed.
+  return require("./knowledge-db-storage-nedb").createKnowledgeDbNedbStorage(options);
+}
+function createKnowledgeDbStorage(options) {
+  var settings = options || {}; var adapter;
+  if (settings.storageAdapter !== undefined) adapter = settings.storageAdapter;
+  else if (settings.storageFactory !== undefined) {
+    if (typeof settings.storageFactory !== "function") throw invalid("storageFactory must be a synchronous function.");
+    adapter = settings.storageFactory({ projectDir: settings.projectDir });
+  } else adapter = module.exports.createDefaultKnowledgeDbStorage({ projectDir: settings.projectDir });
+  return bindAdapter(validateAdapter(adapter));
+}
+module.exports = { createKnowledgeDbStorage: createKnowledgeDbStorage, createDefaultKnowledgeDbStorage: createDefaultKnowledgeDbStorage, validateAdapter: validateAdapter, invalid: invalid };

package/lib/knowledge-file-store.js

@@ -136,7 +136,13 @@ function createKnowledgeFileStore(cwd, options) {
     var listed = list(); var identity = listed.filter(function (entry) { return entry.name === item.name; })[0]; if (!identity) return; ensureMetadata(true);
     var folder = path.join(historyRoot, identity.id); safeDirectory(folder, true);
     var target = path.join(folder, Date.now() + "-" + item.revision + ".md");
-    fs.writeFileSync(target, item.content, { flag: "wx", mode: 0o600 });
+    try { fs.writeFileSync(target, item.content, { flag: "wx", mode: 0o600 }); }
+    catch (error) {
+      // A move and its link rewrite can snapshot the same revision in one millisecond.
+      if (error.code !== "EEXIST") throw error;
+      var stat = fs.lstatSync(target);
+      if (!stat.isFile() || stat.isSymbolicLink() || fs.readFileSync(target, "utf8") !== item.content) throw error;
+    }
   }
   function save(name, content, expectedRevision) {
     var clean = cleanName(name); if (!clean || itemType(clean) !== "text") throw new Error("Only valid Markdown documents can be edited.");

package/lib/mate-avatar-catalog.js

@@ -0,0 +1,12 @@
+// Stable catalog identities are the only accepted library references.
+var catalog = require('./public/mate-avatars/catalog.json');
+var ids = new Set(catalog.map(function (entry) { return entry.id; }));
+function valid(id) { return typeof id === 'string' && ids.has(id); }
+function validate(profile, mate) {
+  if (profile !== undefined && (!profile || typeof profile !== 'object' || Array.isArray(profile))) return 'Choose a valid Mate profile.';
+  if (profile && Object.prototype.hasOwnProperty.call(profile, 'avatarCatalogId') && profile.avatarCatalogId !== '' && !valid(profile.avatarCatalogId) && !(profile.avatarCatalogId === 'lead-clay' && mate && mate.builtinKey === 'clay')) {
+    return 'Choose an avatar from the Clay catalog.';
+  }
+  return null;
+}
+module.exports = { valid: valid, validate: validate };

package/lib/mate-avatar-migration.js

@@ -0,0 +1,41 @@
+// Stable v1 migration, run only against the caller's normal Mate registry.
+var catalog = require('./mate-avatar-catalog');
+var managedArtwork = { clay: ['/clay-studio-symbol.png', '/mates/ally.png', '/mate-avatars/lead-clay.png'], ally: ['/mates/ally.png'] };
+function mappedId(mate) {
+  var p = mate.profile || mate;
+  var key = JSON.stringify([mate.id || '', p.avatarStyle || 'imprint', p.avatarSeed || mate.id || p.displayName || mate.name || 'Mate']);
+  var hash = 2166136261;
+  for (var i = 0; i < key.length; i++) hash = Math.imul(hash ^ key.charCodeAt(i), 16777619) >>> 0;
+  var index = hash % 96;
+  return (index < 48 ? 'B' : 'C') + String(index % 48 + 1).padStart(2, '0');
+}
+function hasCustom(mate) {
+  var p = mate.profile || {};
+  var custom = p.avatarCustom || mate.avatarCustom;
+  if (!custom) return false;
+  var managed = managedArtwork[mate.builtinKey] || [];
+  return managed.indexOf(custom) === -1;
+}
+function normalizeMate(mate) {
+  if (!mate || hasCustom(mate)) return false;
+  var before = JSON.stringify(mate.profile || {});
+  var p = Object.assign({}, mate.profile || {});
+  p.avatarCatalogId = mate.builtinKey === 'clay' ? 'lead-clay' : catalog.valid(p.avatarCatalogId) ? p.avatarCatalogId : mappedId(mate);
+  p.avatarStyle = 'catalog';
+  delete p.avatarSeed;
+  if (p.avatarCustom) p.avatarCustom = '';
+  if (mate.builtinKey === 'clay') p.avatarLocked = true;
+  if (before === JSON.stringify(p) && !Object.prototype.hasOwnProperty.call(mate, 'avatarStyle') && !Object.prototype.hasOwnProperty.call(mate, 'avatarSeed') && !Object.prototype.hasOwnProperty.call(mate, 'avatarCustom')) return false;
+  mate.profile = p;
+  delete mate.avatarStyle;
+  delete mate.avatarSeed;
+  delete mate.avatarCustom;
+  return true;
+}
+function migrate(data) {
+  var changed = false;
+  data.mates.forEach(function (mate) { if (normalizeMate(mate)) changed = true; });
+  if (data.avatarCatalogMigrationVersion !== 1) { data.avatarCatalogMigrationVersion = 1; changed = true; }
+  return changed;
+}
+module.exports = { mappedId: mappedId, hasCustom: hasCustom, normalizeMate: normalizeMate, migrate: migrate };

package/lib/mate-knowledge-mate-bound.js

@@ -0,0 +1,53 @@
+// Ordinary Mate Knowledge bindings. The service supplies live validation and
+// the already-authorized scope; this module only exposes the Mate operations.
+
+function createMateBound(options) {
+  var settings = options || {};
+  var revalidate = settings.revalidate;
+  var initial = settings.initial;
+
+  function ownScope() {
+    return [revalidate().own];
+  }
+  function db(method, args) {
+    var current = revalidate();
+    if (!current.databaseService || typeof current.databaseService[method] !== "function") throw new Error("Knowledge databases are unavailable for this Mate.");
+    return current.databaseService[method](Object.assign({}, args || {}, { actor: current.actor }));
+  }
+  function text(method, args) {
+    var current = revalidate();
+    return settings.textTools[method](current.own, args || {}, current.actor);
+  }
+  return {
+    isClay: false,
+    mateId: initial.own.mateId,
+    scopeId: initial.own.scopeId,
+    listKnowledge: function (args) { return settings.listFor(ownScope(), args || {}, false); },
+    searchKnowledge: function (args) { return settings.searchFor(ownScope(), args || {}, false); },
+    readKnowledge: function (args) { return settings.readFor(ownScope(), args || {}, false); },
+    readKnowledgeDocument: function (args) { return text("read", args); },
+    createKnowledgeDocument: function (args) { return text("create", args); },
+    updateKnowledgeDocument: function (args) { return text("update", args); },
+    listKnowledgeDocumentHistory: function (args) { return text("history", args); },
+    restoreKnowledgeDocument: function (args) { return text("restore", args); },
+    listDatabases: function (args) { return db("list", args); },
+    createDatabase: function (args) { return db("create", args); },
+    readDatabase: function (args) { return db("read", args); },
+    renameDatabase: function (args) { return db("rename", args); },
+    archiveDatabase: function (args) { return db("archive", args); },
+    recoverDatabase: function (args) { return db("recover", args); },
+    updateDatabaseSchema: function (args) { return db("updateSchema", args); },
+    saveTableView: function (args) { return db("saveView", args); },
+    queryDatabase: function (args) { return db("query", args); },
+    createDatabaseRecord: function (args) { return db("createRecord", args); },
+    readDatabaseRecord: function (args) { return db("readRecord", args); },
+    updateDatabaseRecord: function (args) { return db("updateRecord", args); },
+    archiveDatabaseRecord: function (args) { return db("archiveRecord", args); },
+    recoverDatabaseRecord: function (args) { return db("recoverRecord", args); },
+    retryDatabaseSync: function (args) { return db("retryProjection", args); },
+    importDatabaseRecords: function (args) { return db("importRecords", args); },
+    readDatabaseImportProgress: function (args) { return db("readImportProgress", args); },
+  };
+}
+
+module.exports = { createMateBound: createMateBound };

package/lib/mate-knowledge-mcp-server.js

@@ -9,11 +9,17 @@
 
 var buildShape = require("./session-spawn-mcp-server").buildShape;
 var service = require("./mate-knowledge-service");
+var zod;
+try { zod = require("zod"); } catch (error) { zod = null; }
 
 var MATE_CONTRACT =
   "Your Knowledge is the durable personal and expertise context you own: what you have learned, the material you keep, and your accumulated observations. " +
   "It is yours alone. There are no other Knowledge collections available to you here, and project Logs are a separate, unrelated surface. " +
+  "Use text documents for narrative or multiline Markdown content, and databases for structured records, relationships, filters, and numeric totals. " +
   "Search it when recalling something specific would genuinely change your answer, and read only the records you actually need. " +
+  "Database list and search results are summaries for database discovery, not database row content: discover a database, read its schema, then query_database with stable field ids, typed filters, explicit sorts, bounded pagination, and totals; read individual rows by stable record id. Text search and text-document reads retain their own content and revision semantics. " +
+  "For text edits, use the returned document id and revision, reread after a conflict, and retry with the current revision. " +
+  "Treat errors as failures. A successful revision/id with indexSyncPending or projectionPending means canonical content was saved but indexing is pending: report that exact state, do not claim it is indexed, and do not blindly retry a mutation that could create a duplicate. " +
   "Do not enumerate or restate your Knowledge to the user unasked, and never reproduce whole records as filler.";
 
 var CLAY_CONTRACT =
@@ -56,24 +62,35 @@ var OPERATION = { type: "string", description: "Stable retry id formatted label_
 var FIELD = { type: "object", description: "Field with stable id, name, type, required, and type-specific options or reference target." };
 var FILTER = { type: "object", description: "Validated filter: fieldId, op, and value. Supported ops are eq, neq, contains, gt, gte, lt, lte, empty, not-empty." };
 var SORT = { type: "object", description: "Validated sort with fieldId and asc or desc direction." };
+var FIELD_SCHEMA = zod ? zod.object({ id: zod.string(), name: zod.string(), type: zod.string(), required: zod.boolean().optional(), options: zod.any().optional(), target: zod.string().optional(), targetDatabaseId: zod.string().optional(), archived: zod.boolean().optional() }) : null;
+var FILTER_SCHEMA = zod ? zod.object({ fieldId: zod.string(), op: zod.string(), value: zod.any().optional() }) : null;
+var SORT_SCHEMA = zod ? zod.object({ fieldId: zod.string(), direction: zod.enum(["asc", "desc"]) }) : null;
+var VALUES_SCHEMA = zod ? zod.record(zod.string(), zod.any()) : null;
+var VIEW_SCHEMA = zod ? zod.object({ id: zod.string(), name: zod.string(), columns: zod.array(zod.string()), filters: zod.array(FILTER_SCHEMA || zod.any()).optional(), sorts: zod.array(SORT_SCHEMA || zod.any()).optional(), archived: zod.boolean().optional() }) : null;
+var IMPORT_ROW_SCHEMA = zod ? zod.object({ sourceKey: zod.string(), sourcePayload: zod.any(), values: zod.record(zod.string(), zod.any()) }) : null;
+var IMPORT_ROW = IMPORT_ROW_SCHEMA ? { schema: IMPORT_ROW_SCHEMA, description: "Source row with sourceKey, immutable JSON sourcePayload, and typed values keyed by stable schema field id. Record references use sourceNamespace/sourceKey, including forward references within this batch." } : { type: "object", description: "Source row with sourceKey, immutable JSON sourcePayload, and typed values keyed by stable schema field id. Record references use sourceNamespace/sourceKey, including forward references within this batch." };
+var DOCUMENT_ID = { type: "string", description: "Stable document id returned by a text-document tool." };
+var DOCUMENT_REVISION = { type: "string", description: "Revision returned by the most recent text-document read or mutation; required for updates and restore." };
 
 function databaseTools(bound) {
   return [
-    { name: "list_databases", description: "List canonical Knowledge databases, including archived databases when requested, so the Mate can discover and recover them without relying on summary projection.", inputSchema: buildShape({ archived: { type: "boolean" } }, []), handler: handler(bound, "listDatabases") },
-    { name: "create_database", description: "Create a first-class database in this Mate's Knowledge. Defaults to one required title field and a Table view.", inputSchema: buildShape({ name: { type: "string" }, schema: { type: "array", items: FIELD }, operationId: OPERATION }, ["name", "operationId"]), handler: handler(bound, "createDatabase") },
-    { name: "read_database", description: "Read one Knowledge database's current schema, views, revision, and record count.", inputSchema: buildShape({ databaseId: ID, includeArchived: { type: "boolean" } }, ["databaseId"]), handler: handler(bound, "readDatabase") },
+    { name: "list_databases", description: "Discover canonical Knowledge databases, including archived databases when requested. Results are database summaries only, not row content; read a chosen database before querying it.", inputSchema: buildShape({ archived: { type: "boolean" } }, []), handler: handler(bound, "listDatabases") },
+    { name: "create_database", description: "Create a first-class structured database in this Mate's Knowledge. Define typed fields for values, relationships, and numeric totals; use text documents for narrative or multiline material.", inputSchema: buildShape({ name: { type: "string" }, schema: FIELD_SCHEMA ? { schema: zod.array(FIELD_SCHEMA), description: "Typed field descriptors." } : { type: "array", items: FIELD }, operationId: OPERATION }, ["name", "operationId"]), handler: handler(bound, "createDatabase") },
+    { name: "read_database", description: "Read one discovered Knowledge database by stable database id to obtain its current schema, views, revision, and record count before querying rows.", inputSchema: buildShape({ databaseId: ID, includeArchived: { type: "boolean" } }, ["databaseId"]), handler: handler(bound, "readDatabase") },
     { name: "rename_database", description: "Rename a Knowledge database with optimistic revision checking.", inputSchema: buildShape({ databaseId: ID, name: { type: "string" }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "name", "expectedRevision", "operationId"]), handler: handler(bound, "renameDatabase") },
     { name: "archive_database", description: "Recoverably archive a Knowledge database.", inputSchema: buildShape({ databaseId: ID, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "expectedRevision", "operationId"]), handler: handler(bound, "archiveDatabase") },
     { name: "recover_database", description: "Recover an archived Knowledge database.", inputSchema: buildShape({ databaseId: ID, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "expectedRevision", "operationId"]), handler: handler(bound, "recoverDatabase") },
-    { name: "update_database_schema", description: "Replace the schema using stable field ids. Exactly one active title field is required; populated fields cannot be removed or change type and should be archived instead.", inputSchema: buildShape({ databaseId: ID, schema: { type: "array", items: FIELD }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "schema", "expectedRevision", "operationId"]), handler: handler(bound, "updateDatabaseSchema") },
-    { name: "save_table_view", description: "Create or revise a persisted Table view with selected columns, validated filters, and deterministic sorts.", inputSchema: buildShape({ databaseId: ID, view: { type: "object", description: "View with stable id, name, columns, filters, and sorts." }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "view", "expectedRevision", "operationId"]), handler: handler(bound, "saveTableView") },
-    { name: "query_database", description: "Query a bounded deterministic page of records using a saved view or explicit validated filters and sorts. Returns count and numeric sums.", inputSchema: buildShape({ databaseId: ID, viewId: ID, filters: { type: "array", items: FILTER }, sorts: { type: "array", items: SORT }, cursor: { type: "string" }, limit: { type: "number" }, archived: { type: "boolean" } }, ["databaseId"]), handler: handler(bound, "queryDatabase") },
-    { name: "create_database_record", description: "Create a typed record. Values are keyed by stable field id; unknown fields and unsafe keys are rejected.", inputSchema: buildShape({ databaseId: ID, values: { type: "object" }, expectedDatabaseRevision: REVISION, operationId: OPERATION }, ["databaseId", "values", "expectedDatabaseRevision", "operationId"]), handler: handler(bound, "createDatabaseRecord") },
+    { name: "update_database_schema", description: "Replace the schema using stable field ids. Exactly one active title field is required; populated fields cannot be removed or change type and should be archived instead.", inputSchema: buildShape({ databaseId: ID, schema: FIELD_SCHEMA ? { schema: zod.array(FIELD_SCHEMA), description: "Complete typed field descriptor array." } : { type: "array", items: FIELD }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "schema", "expectedRevision", "operationId"]), handler: handler(bound, "updateDatabaseSchema") },
+    { name: "save_table_view", description: "Create or revise a persisted Table view with selected columns, validated filters, and deterministic sorts.", inputSchema: buildShape({ databaseId: ID, view: VIEW_SCHEMA ? { schema: VIEW_SCHEMA, description: "View with stable id, name, columns, filters, and sorts." } : { type: "object", description: "View with stable id, name, columns, filters, and sorts." }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "view", "expectedRevision", "operationId"]), handler: handler(bound, "saveTableView") },
+    { name: "query_database", description: "Query a bounded deterministic page using stable field ids, typed validated filters, explicit sorts, and a cursor. Returns only the requested rows plus count and numeric sums for the same filter scope; do not infer totals from one page.", inputSchema: buildShape({ databaseId: ID, viewId: ID, filters: FILTER_SCHEMA ? { schema: zod.array(FILTER_SCHEMA) } : { type: "array", items: FILTER }, sorts: SORT_SCHEMA ? { schema: zod.array(SORT_SCHEMA) } : { type: "array", items: SORT }, cursor: { type: "string" }, limit: { type: "number" }, archived: { type: "boolean" } }, ["databaseId"]), handler: handler(bound, "queryDatabase") },
+    { name: "create_database_record", description: "Create a typed record. Values are keyed by stable field id; unknown fields and unsafe keys are rejected.", inputSchema: buildShape({ databaseId: ID, values: VALUES_SCHEMA ? { schema: VALUES_SCHEMA } : { type: "object" }, expectedDatabaseRevision: REVISION, operationId: OPERATION }, ["databaseId", "values", "expectedDatabaseRevision", "operationId"]), handler: handler(bound, "createDatabaseRecord") },
     { name: "read_database_record", description: "Read one record with its values, revision, attribution, archive state, and bounded history.", inputSchema: buildShape({ databaseId: ID, recordId: ID }, ["databaseId", "recordId"]), handler: handler(bound, "readDatabaseRecord") },
-    { name: "update_database_record", description: "Update selected typed values using the record revision. Edits to other fields made since a prior save are not overwritten.", inputSchema: buildShape({ databaseId: ID, recordId: ID, values: { type: "object" }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "recordId", "values", "expectedRevision", "operationId"]), handler: handler(bound, "updateDatabaseRecord") },
+    { name: "update_database_record", description: "Update selected typed values using the record revision. Edits to other fields made since a prior save are not overwritten.", inputSchema: buildShape({ databaseId: ID, recordId: ID, values: VALUES_SCHEMA ? { schema: VALUES_SCHEMA } : { type: "object" }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "recordId", "values", "expectedRevision", "operationId"]), handler: handler(bound, "updateDatabaseRecord") },
     { name: "archive_database_record", description: "Recoverably archive one record using its current revision.", inputSchema: buildShape({ databaseId: ID, recordId: ID, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "recordId", "expectedRevision", "operationId"]), handler: handler(bound, "archiveDatabaseRecord") },
     { name: "recover_database_record", description: "Recover one archived record using its current revision.", inputSchema: buildShape({ databaseId: ID, recordId: ID, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "recordId", "expectedRevision", "operationId"]), handler: handler(bound, "recoverDatabaseRecord") },
     { name: "retry_database_sync", description: "Retry the shared append-only Knowledge summary projection after a canonical database mutation reported projectionPending.", inputSchema: buildShape({ databaseId: ID }, ["databaseId"]), handler: handler(bound, "retryDatabaseSync") },
+    { name: "import_database_records", description: "Import up to 100 source rows (256 KiB per batch) into a discovered database using immutable source identities and typed values. Use sourceNamespace/sourceKey references for same-batch or already-imported cross-database links; replay the exact operation and payload after uncertainty, and reread the current database revision before a stale retry.", inputSchema: buildShape({ databaseId: ID, expectedDatabaseRevision: REVISION, operationId: OPERATION, sourceNamespace: { type: "string", description: "Stable source namespace for this import mapping." }, rows: IMPORT_ROW_SCHEMA ? { schema: zod.array(IMPORT_ROW_SCHEMA), description: "At most 100 source rows and 256 KiB of serialized row JSON." } : { type: "array", description: "At most 100 source rows and 256 KiB of serialized row JSON.", items: IMPORT_ROW } }, ["databaseId", "expectedDatabaseRevision", "operationId", "sourceNamespace", "rows"]), handler: handler(bound, "importDatabaseRecords") },
+    { name: "read_database_import_progress", description: "Read bounded source-to-native record mappings by database id and source namespace. Use returned stable record ids for later corrections; this does not read arbitrary filesystem paths or caller-selected owners.", inputSchema: buildShape({ databaseId: ID, sourceNamespace: { type: "string" }, offset: { type: "number" }, limit: { type: "number", description: "Mapping page size from 1 to 100." } }, ["databaseId", "sourceNamespace"]), handler: handler(bound, "readDatabaseImportProgress") },
   ].map(function (tool) { tool.description = MATE_CONTRACT + " " + tool.description; return tool; });
 }
 
@@ -110,6 +127,36 @@ function mateTools(bound) {
       }, ["ref"]),
       handler: handler(bound, "readKnowledge"),
     },
+    {
+      name: "read_knowledge_document",
+      description: MATE_CONTRACT + " Read the complete current Markdown document by its relative path or stable document id, including its current revision.",
+      inputSchema: buildShape({ name: { type: "string", description: "Relative Markdown path under this Mate's Knowledge directory." }, documentId: DOCUMENT_ID }, []),
+      handler: handler(bound, "readKnowledgeDocument"),
+    },
+    {
+      name: "create_knowledge_document",
+      description: MATE_CONTRACT + " Create a new Markdown document at a safe relative path. Use this for narrative or multiline content; it is synchronized into Knowledge search after the canonical save.",
+      inputSchema: buildShape({ name: { type: "string", description: "Relative Markdown path under this Mate's Knowledge directory." }, content: { type: "string", description: "Complete Markdown document content." } }, ["name", "content"]),
+      handler: handler(bound, "createKnowledgeDocument"),
+    },
+    {
+      name: "update_knowledge_document",
+      description: MATE_CONTRACT + " Update an existing Markdown document by relative path or stable document id. The current revision is mandatory, and stale writes are rejected.",
+      inputSchema: buildShape({ name: { type: "string", description: "Relative Markdown path under this Mate's Knowledge directory." }, documentId: DOCUMENT_ID, content: { type: "string", description: "Complete replacement Markdown document content." }, expectedRevision: DOCUMENT_REVISION }, ["content", "expectedRevision"]),
+      handler: handler(bound, "updateKnowledgeDocument"),
+    },
+    {
+      name: "list_knowledge_document_history",
+      description: MATE_CONTRACT + " List recoverable revisions for one Markdown document by relative path or stable document id.",
+      inputSchema: buildShape({ name: { type: "string", description: "Relative Markdown path under this Mate's Knowledge directory." }, documentId: DOCUMENT_ID }, []),
+      handler: handler(bound, "listKnowledgeDocumentHistory"),
+    },
+    {
+      name: "restore_knowledge_document",
+      description: MATE_CONTRACT + " Restore a selected historical Markdown revision. The current revision is mandatory so a concurrent edit cannot be overwritten.",
+      inputSchema: buildShape({ name: { type: "string", description: "Relative Markdown path under this Mate's Knowledge directory." }, documentId: DOCUMENT_ID, version: { type: "string", description: "Version returned by list_knowledge_document_history." }, expectedRevision: DOCUMENT_REVISION }, ["version", "expectedRevision"]),
+      handler: handler(bound, "restoreKnowledgeDocument"),
+    },
   ].concat(databaseTools(bound));
 }
 

package/lib/mate-knowledge-service.js

@@ -15,6 +15,8 @@ var builtinMates = require("./builtin-mates");
 var knowledgeImport = require("./knowledge-import");
 var knowledgeSearch = require("./knowledge-search");
 var mateSync = require("./mate-knowledge-sync");
+var textToolsModule = require("./mate-knowledge-text-tools");
+var mateBoundModule = require("./mate-knowledge-mate-bound");
 
 var MAX_PAGE = 50;
 var DEFAULT_PAGE = 20;
@@ -97,6 +99,7 @@ function attachMateKnowledgeService(ctx) {
   var listMates = context.listMates || function () { return []; };
   var baseDir = context.baseDir;
   var importerCache = new Map();
+  var textTools = textToolsModule.createMateKnowledgeTextTools({ baseDir: baseDir });
 
   function importerForScope(scopeId) {
     if (context.openImporter) return context.openImporter(scopeId);
@@ -379,6 +382,8 @@ function attachMateKnowledgeService(ctx) {
     if (source.session) {
       var manager = project.getSessionManager ? project.getSessionManager() : project.sm;
       if (!manager || !manager.sessions || manager.sessions.get(source.session.localId) !== source.session) return null;
+      if (source.projectOwnerId && source.session.ownerId && source.session.ownerId !== source.projectOwnerId) return null;
+      if (isMultiUser() && (!source.projectOwnerId || source.session.ownerId !== source.projectOwnerId)) return null;
     }
     if (typeof resolveMate !== "function") return null;
     var mate = resolveMate(source.projectOwnerId || null, source.mateId);
@@ -422,36 +427,10 @@ function attachMateKnowledgeService(ctx) {
   // An ordinary Mate's own scope, and nothing else. There is no argument on
   // any tool that could widen it.
   function createMateBound(revalidate, initial) {
-    function ownScope() {
-      return [revalidate().own];
-    }
-    function db(method, args) {
-      var current = revalidate(); if (!current.databaseService || typeof current.databaseService[method] !== "function") throw new Error("Knowledge databases are unavailable for this Mate.");
-      return current.databaseService[method](Object.assign({}, args || {}, { actor: current.actor }));
-    }
-    return {
-      isClay: false,
-      mateId: initial.own.mateId,
-      scopeId: initial.own.scopeId,
-      listKnowledge: function (args) { return listFor(ownScope(), args || {}, false); },
-      searchKnowledge: function (args) { return searchFor(ownScope(), args || {}, false); },
-      readKnowledge: function (args) { return readFor(ownScope(), args || {}, false); },
-      listDatabases: function (args) { return db("list", args); },
-      createDatabase: function (args) { return db("create", args); },
-      readDatabase: function (args) { return db("read", args); },
-      renameDatabase: function (args) { return db("rename", args); },
-      archiveDatabase: function (args) { return db("archive", args); },
-      recoverDatabase: function (args) { return db("recover", args); },
-      updateDatabaseSchema: function (args) { return db("updateSchema", args); },
-      saveTableView: function (args) { return db("saveView", args); },
-      queryDatabase: function (args) { return db("query", args); },
-      createDatabaseRecord: function (args) { return db("createRecord", args); },
-      readDatabaseRecord: function (args) { return db("readRecord", args); },
-      updateDatabaseRecord: function (args) { return db("updateRecord", args); },
-      archiveDatabaseRecord: function (args) { return db("archiveRecord", args); },
-      recoverDatabaseRecord: function (args) { return db("recoverRecord", args); },
-      retryDatabaseSync: function (args) { return db("retryProjection", args); },
-    };
+    return mateBoundModule.createMateBound({
+      revalidate: revalidate, initial: initial, textTools: textTools,
+      listFor: listFor, searchFor: searchFor, readFor: readFor,
+    });
   }
 
   // Every Mate belonging to the same user, resolved fresh on each call so a

package/lib/mate-knowledge-text-tools.js

@@ -0,0 +1,106 @@
+// Session-bound text Knowledge mutations for one authorized Mate.
+//
+// This module deliberately uses the existing portable file store and
+// write-through synchronizer. It never accepts a Mate, owner, or filesystem
+// root from a tool caller; the caller supplies only a relative document name
+// or the stable identity returned by the store.
+
+var crypto = require("crypto");
+var path = require("path");
+var knowledgeFiles = require("./knowledge-file-store");
+var mateSync = require("./mate-knowledge-sync");
+
+function metadataRoot(baseDir, mateDir) {
+  var key = crypto.createHash("sha256").update(path.resolve(mateDir)).digest("hex").slice(0, 24);
+  return path.join(baseDir || path.join(mateDir, ".clay"), "knowledge-documents", key);
+}
+
+function failedSync(summary) {
+  if (!summary) return { indexSyncPending: true, syncError: "Knowledge index synchronization returned no result." };
+  if (summary.failed === 0) return { indexSyncPending: false, syncError: null };
+  var error = summary.errors && summary.errors[0];
+  return { indexSyncPending: true, syncError: error && error.message || "Knowledge index synchronization failed." };
+}
+
+function createMateKnowledgeTextTools(options) {
+  var settings = options || {};
+  var stores = new Map();
+
+  function storeFor(mate) {
+    if (!mate || typeof mate.mateDir !== "string") throw new Error("Knowledge text tools require an authorized Mate.");
+    var directory = path.resolve(mate.mateDir);
+    if (!stores.has(directory)) stores.set(directory, knowledgeFiles.createKnowledgeFileStore(directory, { metaDir: metadataRoot(settings.baseDir, directory) }));
+    return stores.get(directory);
+  }
+
+  function find(store, input) {
+    var args = input || {};
+    var hasName = typeof args.name === "string" && args.name.length > 0;
+    var hasId = typeof args.documentId === "string" && args.documentId.length > 0;
+    if (!hasName && !hasId) throw new Error("A document name or stable document id is required.");
+    var item = null;
+    if (hasId) item = store.list().filter(function (entry) { return entry.id === args.documentId; })[0] || null;
+    if (hasId && !item) throw Object.assign(new Error("Knowledge document not found."), { code: "ENOENT" });
+    if (hasName) {
+      var byName = store.read(args.name);
+      if (item && item.id !== byName.id) throw new Error("The document name and id identify different documents.");
+      item = byName;
+    }
+    if (!item) throw Object.assign(new Error("Knowledge document not found."), { code: "ENOENT" });
+    if (hasId && !hasName) item = store.read(item.name);
+    if (item.itemType !== "text") throw Object.assign(new Error("Only Markdown Knowledge documents are writable through these tools."), { code: "READ_ONLY" });
+    return item;
+  }
+
+  function sync(mate, name, actor) {
+    try {
+      var summary = mateSync.syncMateSource({ mateDir: mate.mateDir, fileName: name, baseDir: settings.baseDir, actor: actor });
+      return failedSync(summary);
+    } catch (error) {
+      return { indexSyncPending: true, syncError: error.message || "Knowledge index synchronization failed." };
+    }
+  }
+
+  function read(mate, args) {
+    var item = find(storeFor(mate), args);
+    return { documentId: item.id, name: item.name, content: item.content, revision: item.revision };
+  }
+
+  function create(mate, args, actor) {
+    var input = args || {};
+    if (typeof input.name !== "string" || !input.name) throw new Error("A document name is required to create a Knowledge document.");
+    if (typeof input.content !== "string") throw new Error("Document content is required.");
+    var store = storeFor(mate);
+    var saved = store.save(input.name, input.content, null);
+    return Object.assign({ documentId: saved.id, name: saved.name, revision: saved.revision }, sync(mate, saved.name, actor));
+  }
+
+  function update(mate, args, actor) {
+    var input = args || {};
+    if (typeof input.expectedRevision !== "string" || !input.expectedRevision) throw Object.assign(new Error("A current document revision is required for updates."), { code: "STALE" });
+    if (typeof input.content !== "string") throw new Error("Document content is required.");
+    var store = storeFor(mate);
+    var current = find(store, input);
+    var saved = store.save(current.name, input.content, input.expectedRevision);
+    return Object.assign({ documentId: saved.id, name: saved.name, revision: saved.revision }, sync(mate, saved.name, actor));
+  }
+
+  function history(mate, args) {
+    var current = find(storeFor(mate), args);
+    return { documentId: current.id, name: current.name, versions: storeFor(mate).history(current.id) };
+  }
+
+  function restore(mate, args, actor) {
+    var input = args || {};
+    if (typeof input.expectedRevision !== "string" || !input.expectedRevision) throw Object.assign(new Error("A current document revision is required for restore."), { code: "STALE" });
+    if (typeof input.version !== "string" || !input.version) throw new Error("A history version is required.");
+    var store = storeFor(mate);
+    var current = find(store, input);
+    var restored = store.restore(current.id, input.version, current.name, input.expectedRevision);
+    return Object.assign({ documentId: restored.id, name: restored.name, revision: restored.revision }, sync(mate, restored.name, actor));
+  }
+
+  return { read: read, create: create, update: update, history: history, restore: restore };
+}
+
+module.exports = { createMateKnowledgeTextTools: createMateKnowledgeTextTools };

package/lib/mates.js

@@ -4,6 +4,8 @@ var path = require("path");
 var crypto = require("crypto");
 var config = require("./config");
 var workspaceColor = require("./mate-workspace-color");
+var avatarCatalog = require("./mate-avatar-catalog");
+var avatarMigration = require("./mate-avatar-migration");
 
 var crisisSafety = require("./crisis-safety");
 var matesPrompts = require("./mates-prompts");
@@ -98,10 +100,12 @@ function loadMates(ctx) {
     var raw = fs.readFileSync(matesFilePath(ctx), "utf8");
     var data = JSON.parse(raw);
     if (!data.mates) data.mates = [];
-    return data;
   } catch (e) {
     return defaultData();
   }
+  // Migration write failures must propagate, never masquerade as an empty registry.
+  if (avatarMigration.migrate(data)) saveMates(ctx, data);
+  return data;
 }
 
 function saveMates(ctx, data) {
@@ -135,6 +139,7 @@ function createMate(ctx, seedData) {
       displayName: null,
       avatarColor: "#5857fc",
       avatarStyle: "imprint",
+      avatarCatalogId: "B" + String(crypto.randomInt(1, 49)).padStart(2, "0"),
       avatarSeed: crypto.randomBytes(4).toString("hex"),
     },
     bio: null,
@@ -142,6 +147,7 @@ function createMate(ctx, seedData) {
     interviewProjectPath: null,
   };
 
+  avatarMigration.normalizeMate(mate);
   data.mates.push(mate);
   saveMates(ctx, data);
 
@@ -205,6 +211,8 @@ function updateMate(ctx, id, updates) {
         if (data.mates[i].primary || data.mates[i].builtinKey === "clay") delete updates.workspaceColor;
         else if (!workspaceColor.valid(updates.workspaceColor)) return { error: "Choose a supported workspace color." };
       }
+      var avatarError = avatarCatalog.validate(updates.profile, data.mates[i]);
+      if (avatarError) return { error: avatarError };
       // Primary mates: protect name and core identity fields
       if (data.mates[i].primary) {
         delete updates.name;
@@ -219,6 +227,7 @@ function updateMate(ctx, id, updates) {
       // Locked built-in artwork is server-managed. Preserve it even when a
       // stale or crafted client submits a replacement profile object.
       if (data.mates[i].profile && data.mates[i].profile.avatarLocked && updates.profile) {
+        updates.profile.avatarCatalogId = data.mates[i].profile.avatarCatalogId || "";
         updates.profile.avatarStyle = data.mates[i].profile.avatarStyle;
         updates.profile.avatarSeed = data.mates[i].profile.avatarSeed;
         updates.profile.avatarColor = data.mates[i].profile.avatarColor;
@@ -229,6 +238,7 @@ function updateMate(ctx, id, updates) {
       for (var j = 0; j < keys.length; j++) {
         data.mates[i][keys[j]] = updates[keys[j]];
       }
+      avatarMigration.normalizeMate(data.mates[i]);
       saveMates(ctx, data);
       return data.mates[i];
     }
@@ -506,6 +516,7 @@ function createBuiltinMate(ctx, builtinKey) {
     interviewProjectPath: null,
   };
 
+  avatarMigration.normalizeMate(mate);
   data.mates.push(mate);
   saveMates(ctx, data);
 
@@ -661,8 +672,8 @@ function syncPrimaryMates(ctx) {
       }
       // Locked avatars are code-managed — refresh them from the def so a
       // built-in's avatar can be updated by changing the source file
-      // (e.g. Clay flipping from a stale Ally asset to the app icon).
-      if (def.avatarLocked) {
+      // User uploads are preserved while canonical library artwork follows the definition.
+      if (def.avatarLocked && !avatarMigration.hasCustom(mate)) {
         if (def.avatarCustom != null && mate.profile.avatarCustom !== def.avatarCustom) {
           mate.profile.avatarCustom = def.avatarCustom; changed = true;
         }