memgres 0.12.0__tar.gz → 0.12.2__tar.gz

{memgres-0.12.0 → memgres-0.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgres
-Version: 0.12.0
+Version: 0.12.2
 Summary: Drop-in memory for AI agents: one Postgres, lexical + semantic recall, diff-versioned history, GDPR-erasable.
 Author: mozgsml
 License-Expression: MIT

{memgres-0.12.0 → memgres-0.12.2}/memgres/_version.py

@@ -8,4 +8,4 @@ here at release; nowhere else carries the number.
 PEP 440: a ``.devN`` suffix marks an unreleased build ahead of the last tag.
 """
 
-__version__ = "0.12.0"
+__version__ = "0.12.2"

{memgres-0.12.0 → memgres-0.12.2}/memgres/links.py

@@ -52,19 +52,11 @@ from typing import Dict, List, Optional
 # edges so they are visible, never resolved — we do not own the address space.
 KNOWN_SCHEMES = ("idea", "file")
 
-# An ltree path: labels of [A-Za-z0-9_-] joined by dots. Deliberately strict —
-# this is what tells a path apart from a slug belonging to another store, and
-# from prose that happens to sit in double brackets.
-#
-# The hyphen is there because PATHS MAY CONTAIN ONE. Postgres has allowed `-` in
-# ltree labels since 13 (the minimum this project supports), `write` accepts such
-# a path without complaint, and real corpora are full of them —
-# `infra.servers.video-production`. While this pattern rejected the hyphen the
-# two halves of the product disagreed about what a path is: the link was stored
-# as prose, `_classify` returned "ignore", and the edge did not even become a
-# DANGLING one. It vanished, and `memory_links` answered "nothing points here",
-# which reads as a fact about the corpus rather than as a parser that quit.
-_PATH = re.compile(r"^[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*$")
+# What a path is lives in `paths.py`, so the parser and the store cannot drift
+# apart again — that drift is exactly what dropped every hyphenated link before
+# 0.12.0. Kept under the old name because the rest of this module reads better
+# with it.
+from .paths import PATH_RE as _PATH
 
 _LINK = re.compile(r"\[\[([^\[\]\n]+)\]\]")
 _FENCE = re.compile(r"```.*?```|~~~.*?~~~", re.S)

{memgres-0.12.0 → memgres-0.12.2}/memgres/mcp_server.py

@@ -32,8 +32,10 @@ from typing_extensions import Annotated
 
 try:  # mcp SDK >= 2.0 renamed the module fastmcp -> mcpserver
     from mcp.server.mcpserver import Context
+    from mcp.server.mcpserver.exceptions import ToolError
 except ImportError:  # mcp SDK 1.x
     from mcp.server.fastmcp import Context
+    from mcp.server.fastmcp.exceptions import ToolError
 
 from . import admin, identity
 from .config import Config, load
@@ -59,7 +61,11 @@ SourceArg = Annotated[Optional[str], Field(
                 "sender -> recipient, date, subject; messenger, who with whom, date; "
                 "machine + project + session/transcript for an agent run; full URL + "
                 "date read. 'email', 'the meeting', 'the user said' is not one — "
-                "nothing can be reached through it, so the fact can only be believed.")]
+                "nothing can be reached through it, so the fact can only be believed. "
+                "It is recorded on THIS revision, not on the memory: a memory has no "
+                "single origin, its edits do. So a later read does not carry it — "
+                "`memory_blame` says where a given line came from, `memory_history` "
+                "where each revision did.")]
 ReasonArg = Annotated[Optional[str], Field(
     default=None,
     description="Why this write happened — what changed and why, in one line. Kept "
@@ -269,6 +275,40 @@ def _mcp(name: str, instructions: Optional[str] = None):
     return server
 
 
+# Refusals whose text is written FOR the caller and safe to show them: what is
+# missing, which namespace to name, why the diff did not apply, what they may
+# not do. Everything else — a psycopg error, a bug — stays masked, because those
+# messages carry schema and internals rather than instructions.
+_SPEAKABLE = (ValueError, PermissionError, LookupError)
+
+
+def _speaking(fn):
+    """Re-raise a domain refusal as the SDK's own error type, which is the only
+    kind whose message reaches the client.
+
+    Everything else the SDK catches becomes `Error executing tool <name>` with no
+    detail — and that is what the caller sees. The refusals here are written to
+    be read: "this deployment requires `source` … as an ADDRESS", "you can reach
+    2 namespaces, name the one you mean". Masking them turns a fixable mistake
+    into a mystery, and an agent that cannot see the reason repeats the same call
+    — which is exactly what happened: five identical edits in a row, then the
+    same on reads, against a server that was explaining itself into the void.
+    """
+    import functools
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        try:
+            return fn(*args, **kwargs)
+        except ToolError:
+            raise
+        except _SPEAKABLE as e:
+            # `from e` keeps the original in the server log, where the traceback
+            # belongs; the client gets the sentence, not the stack.
+            raise ToolError(str(e)) from e
+    return wrapper
+
+
 def _mem(m) -> dict:
     return m.to_dict(stringify_dates=True)      # MCP layer needs plain strings
 
@@ -292,6 +332,12 @@ def build_server(cfg: Optional[Config] = None):
     _worker, cfg, backend = wire_server(cfg, embedder)
     mcp = _mcp("memgres", instructions=_instruction_text())
 
+    def tool(*d_args, **d_kwargs):
+        """`mcp.tool()`, but the refusal text survives the trip to the client."""
+        def deco(fn):
+            return mcp.tool(*d_args, **d_kwargs)(_speaking(fn))
+        return deco
+
     import os as _os
 
     # The control-plane tools. `auto` registers them wherever there are
@@ -389,7 +435,7 @@ def build_server(cfg: Optional[Config] = None):
         """
         return identity.resolve(conn, cfg, token)
 
-    @mcp.tool()
+    @tool()
     def memory_write(body: Optional[str] = None, id: Optional[str] = None,
                      at: Optional[str] = None,
                      if_moved: IfMovedArg = "error",
@@ -445,7 +491,7 @@ def build_server(cfg: Optional[Config] = None):
                 reason=reason, valid_at=valid_at, space=space,
                 space_id=space_id))
 
-    @mcp.tool()
+    @tool()
     def memory_get(id: Optional[str] = None, at: Optional[str] = None,
                    if_moved: Literal["follow", "error"] = "follow",
                    lines: Optional[str] = None,
@@ -461,6 +507,10 @@ def build_server(cfg: Optional[Config] = None):
         The answer carries `usage`: how often this memory has surfaced in search
         (`recalled`) and been fetched (`gets`), and when each last happened.
 
+        It carries NO `source`/`valid_at`, and that is deliberate: provenance
+        belongs to a revision, not to the document. Ask `memory_blame` where a
+        particular line came from, or `memory_history` where each revision did.
+
         `lines` ("40-80", "5", "1,10-12") returns only part of a long body. The
         answer is then marked `partial`, carries `total_lines`, and has NO
         `content_hash` — do not send a slice back as a whole `body`, or
@@ -471,7 +521,7 @@ def build_server(cfg: Optional[Config] = None):
                                          if_moved=if_moved, lines=lines,
                                          space=space, space_id=space_id))
 
-    @mcp.tool()
+    @tool()
     def memory_recall(query: str, k: int = 10,
                       mode: Literal["lexical", "semantic", "hybrid", "auto"] = "auto",
                       match: Optional[Literal["any", "all"]] = None,
@@ -515,7 +565,7 @@ def build_server(cfg: Optional[Config] = None):
                         snippet=snippet, full_body=full_body, bodies=bodies,
                         match_tags=match_tags, space=space, space_id=space_id)]
 
-    @mcp.tool()
+    @tool()
     def memory_list(path_prefix: Optional[str] = None,
                     tags: Optional[List[str]] = None, limit: int = 50,
                     offset: int = 0, bodies: bool = False,
@@ -543,7 +593,7 @@ def build_server(cfg: Optional[Config] = None):
                 limit=limit, offset=offset, bodies=bodies,
                 match_tags=match_tags, space=space, space_id=space_id)
 
-    @mcp.tool()
+    @tool()
     def memory_tags(prefix: Optional[str] = None, k: int = 50,
                     space: Spaces = None, space_id: Spaces = None,
                     ctx: Context = None) -> List[dict]:
@@ -558,7 +608,7 @@ def build_server(cfg: Optional[Config] = None):
             return _store(conn).tags(_token(ctx), prefix=prefix, k=k,
                                      space=space, space_id=space_id)
 
-    @mcp.tool()
+    @tool()
     def memory_links(id: Optional[str] = None, at: Optional[str] = None,
                      direction: Literal["in", "out", "both"] = "both",
                      space: Optional[str] = None, space_id: Optional[str] = None,
@@ -579,7 +629,7 @@ def build_server(cfg: Optional[Config] = None):
                                       at=at or None, direction=direction,
                                       space=space, space_id=space_id)
 
-    @mcp.tool()
+    @tool()
     def memory_server_info(ctx: Context = None) -> dict:
         """The server's version + schema_version and its effective limits and
         capabilities (write ceilings, embed provider/model/dim, available recall
@@ -589,7 +639,7 @@ def build_server(cfg: Optional[Config] = None):
         dim = embedder.dim if embedder is not None else None
         return server_info(cfg, embed_dim=dim)
 
-    @mcp.tool()
+    @tool()
     def memory_blame(id: Optional[str] = None, at: Optional[str] = None,
                      grouped: bool = True, lines: Optional[str] = None,
                      space: Optional[str] = None, space_id: Optional[str] = None,
@@ -609,7 +659,7 @@ def build_server(cfg: Optional[Config] = None):
             return s.annotate(tok, id, lines=want, at=at, space=space,
                               space_id=space_id)
 
-    @mcp.tool()
+    @tool()
     def memory_history(id: Optional[str] = None, at: Optional[str] = None,
                        space: Optional[str] = None,
                        space_id: Optional[str] = None,
@@ -622,7 +672,7 @@ def build_server(cfg: Optional[Config] = None):
             return _store(conn).history(_token(ctx), id, at=at,
                                         space=space, space_id=space_id)
 
-    @mcp.tool()
+    @tool()
     def memory_move(new_path: str, id: Optional[str] = None,
                     at: Optional[str] = None,
                     if_moved: Literal["error", "follow"] = "error",
@@ -638,7 +688,7 @@ def build_server(cfg: Optional[Config] = None):
                                           reason=reason, space=space,
                                           space_id=space_id))
 
-    @mcp.tool()
+    @tool()
     def memory_forget(id: Optional[str] = None, at: Optional[str] = None,
                       space: Optional[str] = None,
                       space_id: Optional[str] = None,
@@ -652,7 +702,7 @@ def build_server(cfg: Optional[Config] = None):
                 _token(ctx), id, at=at, space=space, space_id=space_id)}
 
     # ─── identity: spaces & tokens (open/managed modes) ─────────────────────
-    @mcp.tool()
+    @tool()
     def memory_list_spaces(ctx: Context = None) -> List[dict]:
         """List the namespaces you can reach — your own plus any shared with you —
         with each one's id, name, description, permission, and your `alias` for it
@@ -661,7 +711,7 @@ def build_server(cfg: Optional[Config] = None):
         with pool.connection() as conn, conn.transaction():
             return identity.list_spaces(conn, _uid(conn, _token(ctx)))
 
-    @mcp.tool()
+    @tool()
     def memory_create_space(name: str, description: str = "",
                             instruction: str = "",
                             ctx: Context = None) -> dict:
@@ -675,7 +725,7 @@ def build_server(cfg: Optional[Config] = None):
                 description=description, instruction=instruction)
         return {"id": nsid, "name": name}
 
-    @mcp.tool()
+    @tool()
     def memory_set_alias(alias: str, space_id: str,
                          ctx: Context = None) -> dict:
         """Give a namespace a name of your own, for when a bare name is ambiguous
@@ -688,7 +738,7 @@ def build_server(cfg: Optional[Config] = None):
             identity.create_alias(conn, uid, alias, space_id)
         return {"alias": alias, "space_id": space_id}
 
-    @mcp.tool()
+    @tool()
     def memory_drop_alias(alias: str,
                           ctx: Context = None) -> dict:
         """Remove one of your namespace aliases. The namespace itself is
@@ -698,7 +748,7 @@ def build_server(cfg: Optional[Config] = None):
             return {"dropped": identity.drop_alias(conn, uid, alias)}
 
     if cfg.key_mode == "managed":
-        @mcp.tool()
+        @tool()
         def memory_enroll(key: EnrollKeyArg, ctx: Context = None) -> dict:
             """Claim an account with a one-time enrollment key.
 
@@ -734,7 +784,7 @@ def build_server(cfg: Optional[Config] = None):
                            "tools you can now use are not showing yet.")
             return out
 
-    @mcp.tool()
+    @tool()
     def memory_issue_token(permission: str = "write", space: Optional[str] = None,
                            space_id: Optional[str] = None, label: str = "",
                            expires_days: Optional[int] = None,
@@ -789,7 +839,7 @@ def build_server(cfg: Optional[Config] = None):
         out.update({"permission": permission, "namespace_id": nsid})
         return out
 
-    @mcp.tool()
+    @tool()
     def memory_request_access(space_id: str, permission: str = "read",
                               ctx: Context = None) -> dict:
         """Ask the owner of a namespace to let you in.
@@ -804,14 +854,14 @@ def build_server(cfg: Optional[Config] = None):
                                         namespace_id=space_id,
                                         permission=permission)
 
-    @mcp.tool()
+    @tool()
     def memory_list_tokens(ctx: Context = None) -> List[dict]:
         """List your tokens (metadata only — never the secret)."""
         with pool.connection() as conn, conn.transaction():
             out = identity.list_tokens(conn, _admin_uid(conn, _token(ctx)))
         return _iso(out, *_TOKEN_TIMES)
 
-    @mcp.tool()
+    @tool()
     def memory_revoke_token(token_id: str,
                             ctx: Context = None) -> dict:
         """Revoke one of your tokens by id (kills it immediately)."""
@@ -822,7 +872,7 @@ def build_server(cfg: Optional[Config] = None):
                 raise identity.AuthError("not your token")
             return {"revoked": identity.revoke_token(conn, token_id)}
 
-    @mcp.tool()
+    @tool()
     def memory_whoami(ctx: Context = None) -> dict:
         """Who you are and what you may do: user id, service role, this
         credential's permission ceiling and namespace scope, plus the
@@ -834,7 +884,7 @@ def build_server(cfg: Optional[Config] = None):
     # ─── control plane: provisioning (authorized in `admin`, not here) ───────
     if admin_surface:
 
-        @mcp.tool()
+        @tool()
         def memory_admin_list_users(role: Optional[str] = None, limit: int = 50,
                                     offset: int = 0,
                                     ctx: Context = None) -> List[dict]:
@@ -846,7 +896,7 @@ def build_server(cfg: Optional[Config] = None):
                                        role=role, limit=limit, offset=offset)
             return _iso(out, "created_at")
 
-        @mcp.tool()
+        @tool()
         def memory_admin_create_user(name: str = "", description: str = "",
                                      role: str = "user",
                                      can_create_namespace: bool = False,
@@ -872,7 +922,7 @@ def build_server(cfg: Optional[Config] = None):
                                         department=department, position=position)
             return {"id": uid}
 
-        @mcp.tool()
+        @tool()
         def memory_admin_edit_user(user_id: str,
                                    name: Optional[str] = None,
                                    description: Optional[str] = None,
@@ -891,7 +941,7 @@ def build_server(cfg: Optional[Config] = None):
                     conn, _principal(conn, _token(ctx)), user_id=user_id,
                     **{k: v for k, v in fields.items() if v is not None})
 
-        @mcp.tool()
+        @tool()
         def memory_admin_set_can_create_namespace(user_id: str, allowed: bool,
                                                   ctx: Context = None) -> dict:
             """Grant or withdraw a user's right to create namespaces. Without it
@@ -902,7 +952,7 @@ def build_server(cfg: Optional[Config] = None):
                     conn, _principal(conn, _token(ctx)),
                     user_id=user_id, allowed=allowed)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_set_role(user_id: str, role: str,
                                   ctx: Context = None) -> dict:
             """Set a user's service role (user | user_manager | superadmin).
@@ -912,7 +962,7 @@ def build_server(cfg: Optional[Config] = None):
                 return admin.set_role(conn, _principal(conn, _token(ctx)),
                                       user_id=user_id, role=role)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_list_namespaces(owner_user_id: Optional[str] = None,
                                          limit: int = 50, offset: int = 0,
                                          ctx: Context = None) -> List[dict]:
@@ -925,7 +975,7 @@ def build_server(cfg: Optional[Config] = None):
                     owner_user_id=owner_user_id, limit=limit, offset=offset)
             return _iso(out, "created_at")
 
-        @mcp.tool()
+        @tool()
         def memory_admin_create_namespace(name: str, owner_user_id: str,
                                           description: str = "",
                                           instruction: str = "",
@@ -940,7 +990,7 @@ def build_server(cfg: Optional[Config] = None):
                     description=description, instruction=instruction)
             return {"id": nsid}
 
-        @mcp.tool()
+        @tool()
         def memory_admin_edit_namespace(space_id: str,
                                         description: Optional[str] = None,
                                         instruction: Optional[str] = None,
@@ -959,7 +1009,7 @@ def build_server(cfg: Optional[Config] = None):
                     namespace_id=space_id, description=description,
                     instruction=instruction, name=name)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_count_orphans(ctx: Context = None) -> dict:
             """How many memories are stranded in the pre-identity namespace.
             `single` mode stores everything under one nameless namespace; after a
@@ -969,7 +1019,7 @@ def build_server(cfg: Optional[Config] = None):
             with pool.connection() as conn:
                 return admin.count_orphans(conn, _principal(conn, _token(ctx)))
 
-        @mcp.tool()
+        @tool()
         def memory_admin_adopt_orphans(space_id: str,
                                        ctx: Context = None) -> dict:
             """Move every stranded `single`-mode memory into a real namespace.
@@ -981,7 +1031,7 @@ def build_server(cfg: Optional[Config] = None):
                     conn, _principal(conn, _token(ctx)),
                     namespace_id=space_id, vectors=backend)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_add_member(space_id: str, user_id: str,
                                     permission: str = "read",
                                     ctx: Context = None) -> dict:
@@ -994,7 +1044,7 @@ def build_server(cfg: Optional[Config] = None):
                                         namespace_id=space_id, user_id=user_id,
                                         permission=permission)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_remove_member(space_id: str, user_id: str,
                                        ctx: Context = None) -> dict:
             """Take a shared namespace away again. `removed: false` means they
@@ -1009,7 +1059,7 @@ def build_server(cfg: Optional[Config] = None):
                 return admin.remove_member(conn, _principal(conn, _token(ctx)),
                                            namespace_id=space_id, user_id=user_id)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_transfer_namespace(
                 space_id: str, new_owner_user_id: str,
                 keep_previous_owner: Optional[str] = "admin",
@@ -1028,7 +1078,7 @@ def build_server(cfg: Optional[Config] = None):
                     new_owner_user_id=new_owner_user_id,
                     keep_previous_owner=keep_previous_owner)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_list_requests(space_id: str,
                                        ctx: Context = None) -> List[dict]:
             """Pending requests to join a namespace you administer — who asked,
@@ -1038,7 +1088,7 @@ def build_server(cfg: Optional[Config] = None):
                                           namespace_id=space_id)
             return _iso(out, "created_at")
 
-        @mcp.tool()
+        @tool()
         def memory_admin_decide_access(request_id: str, approve: bool = True,
                                        expect_permission: Optional[str] = None,
                                        ctx: Context = None) -> dict:
@@ -1056,7 +1106,7 @@ def build_server(cfg: Optional[Config] = None):
                                     expect_permission=expect_permission)
             return {"request_id": request_id, "approved": approve}
 
-        @mcp.tool()
+        @tool()
         def memory_admin_set_disabled(user_id: str, disabled: bool = True,
                                       ctx: Context = None) -> dict:
             """Switch an account off, or back on.
@@ -1070,7 +1120,7 @@ def build_server(cfg: Optional[Config] = None):
                 return admin.set_disabled(conn, _principal(conn, _token(ctx)),
                                           user_id=user_id, disabled=disabled)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_list_members(space_id: str,
                                       ctx: Context = None) -> List[dict]:
             """Who can reach a namespace — the owner first, then everyone shared
@@ -1080,7 +1130,7 @@ def build_server(cfg: Optional[Config] = None):
                                          namespace_id=space_id)
             return _iso(out, "created_at")
 
-        @mcp.tool()
+        @tool()
         def memory_admin_issue_token(user_id: str, permission: str = "write",
                                      space_id: Optional[str] = None,
                                      label: str = "",
@@ -1112,7 +1162,7 @@ def build_server(cfg: Optional[Config] = None):
                 out["warning"] = minted["warning"]
             return out
 
-        @mcp.tool()
+        @tool()
         def memory_admin_create_enrollment(
                 user_id: str, permission: str = "write",
                 space_id: Optional[str] = None, label: str = "",
@@ -1146,7 +1196,7 @@ def build_server(cfg: Optional[Config] = None):
             out["expires_at"] = out["expires_at"].isoformat()
             return admin.deliver_key(out, cfg.token_sink)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_list_enrollments(user_id: Optional[str] = None,
                                           ctx: Context = None) -> List[dict]:
             """Enrollment keys and what became of them — `state` is pending,
@@ -1158,7 +1208,7 @@ def build_server(cfg: Optional[Config] = None):
                                              user_id=user_id)
             return _iso(out, "created_at", "expires_at", "used_at", "revoked_at")
 
-        @mcp.tool()
+        @tool()
         def memory_admin_revoke_enrollment(enrollment_id: str,
                                            ctx: Context = None) -> dict:
             """Kill an unredeemed enrollment key. False means it was already
@@ -1169,7 +1219,7 @@ def build_server(cfg: Optional[Config] = None):
                     conn, _principal(conn, _token(ctx)),
                     enrollment_id=enrollment_id)}
 
-        @mcp.tool()
+        @tool()
         def memory_admin_list_tokens(user_id: str,
                                      ctx: Context = None) -> List[dict]:
             """A user's tokens — metadata only, never the secret."""
@@ -1178,7 +1228,7 @@ def build_server(cfg: Optional[Config] = None):
                                         user_id=user_id)
             return _iso(out, *_TOKEN_TIMES)
 
-        @mcp.tool()
+        @tool()
         def memory_admin_revoke_token(token_id: str,
                                       ctx: Context = None) -> dict:
             """Kill any user's token immediately. False means it was already

memgres-0.12.2/memgres/paths.py

@@ -0,0 +1,49 @@
+"""What a tree path is — in ONE place.
+
+The shape was written down twice before, in the link parser and in whatever SQL
+happened to cast a string to `ltree`, and the two disagreed: a hyphen was legal
+to store and illegal to link, so half the links in a real corpus silently
+vanished (fixed in 0.12.0). This module exists so a third definition does not
+appear.
+
+It also gives the check a place to happen BEFORE the value reaches Postgres. An
+unvalidated prefix arrived at the database as `%s::ltree` and came back as
+`psycopg.errors.SyntaxError: ltree syntax error at character 1` — a message
+about our schema, not about their input, and one the caller can do nothing with.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+# Labels of word characters (letters in ANY script, digits, underscore) or
+# hyphens, joined by dots.
+#
+# Two things had to be widened here, each because a real path was being called
+# invalid. The hyphen: Postgres has allowed it in ltree labels since 13, the
+# minimum this project supports. Non-ASCII letters: `ops.тариф` stores and reads
+# perfectly well, and an existing test says so — a check that rejected it would
+# have made a working path unwritable, which is worse than the error it prevents.
+#
+# The parser for `[[links]]` uses the SAME alphabet on purpose. When it was
+# narrower, every hyphenated link was dropped as prose; a narrower rule here
+# would recreate that, only for Cyrillic.
+PATH_RE = re.compile(r"^[\w-]+(\.[\w-]+)*$", re.UNICODE)
+
+
+def is_path(value: Optional[str]) -> bool:
+    return bool(value) and bool(PATH_RE.match(value))
+
+
+def check_path(value: Optional[str], field: str = "path") -> Optional[str]:
+    """Return `value` unchanged, or raise ValueError naming the field and the
+    shape. Empty/None passes — "no path given" is not a malformed one."""
+    if value is None or value == "":
+        return value
+    if not PATH_RE.match(value):
+        raise ValueError(
+            f"`{field}` is not a tree path: {value!r}. A path is labels of "
+            f"letters (any script), digits, `_` or `-` joined by dots, like "
+            f"`ops.memory.onboarding` — no spaces, slashes or leading dots.")
+    return value

{memgres-0.12.0 → memgres-0.12.2}/memgres/store.py

@@ -35,6 +35,7 @@ from . import identity
 from .config import Config
 from .delimiters import write_warnings
 from .lines import parse_line_spec
+from .paths import check_path
 from .diffing import DiffConflict, apply_diff, byte_len, content_hash, make_diff
 from .embeddings import Embedder, get_embedder
 from .links import parse_links, rewrite_targets
@@ -250,12 +251,21 @@ class Memory:
     # Provenance of the REVISION this call just wrote — never of the memory,
     # which has no single source: `source`/`reason`/`valid_at` live on the
     # history row because different edits speak to different origins and dates.
-    # So these are set by `write` and stay None on a read, where the question
-    # belongs to `history`/`blame`. Echoed back because a required field that the
-    # answer does not confirm is a field whose absence nobody notices: four edits
-    # in a row went out with an empty `source` and every reply looked fine.
+    # Echoed back on a write because a required field the answer does not confirm
+    # is a field whose absence nobody notices: four edits in a row went out with
+    # an empty `source` and every reply looked fine.
+    #
+    # `is_write` decides whether they are SERIALIZED at all, and that is the
+    # point: a read used to emit `"source": null`, which does not read as "this
+    # memory has no such field" but as "the value was there and is now gone".
+    # Two readers in a row concluded the field was being silently dropped and
+    # went looking for the bug — one of them spent a day on it and wrote the
+    # workaround into memory. So on a read the keys are ABSENT, and the question
+    # they answer belongs to `history`/`blame`, where the answer is per-revision
+    # and per-line rather than one value pretending to describe the document.
     source: Optional[str] = None
     valid_at: object = None
+    is_write: bool = False
 
     def to_dict(self, *, stringify_dates: bool = False) -> dict:
         """Serialize for an API layer. ``stringify_dates`` str()-coerces the
@@ -263,9 +273,8 @@ class Memory:
         datetimes itself, so the HTTP layer passes them through raw)."""
         def d(v):
             return (str(v) if v is not None else None) if stringify_dates else v
-        return {"id": self.id, "content_hash": self.content_hash, "body": self.body,
+        out = {"id": self.id, "content_hash": self.content_hash, "body": self.body,
                 "title": self.title, "tags": self.tags, "path": self.path,
-                "source": self.source, "valid_at": d(self.valid_at),
                 "seq": self.seq, "created_at": d(self.created_at),
                 "updated_at": d(self.updated_at), "expires_at": d(self.expires_at),
                 "created": self.created, "moved_from": self.moved_from,
@@ -275,6 +284,12 @@ class Memory:
                            "last_recall_at": d(self.usage["last_recall_at"]),
                            "last_get_at": d(self.usage["last_get_at"])}
                           if self.usage else None)}
+        if self.is_write:
+            # Only here: the provenance of the revision just written, confirmed
+            # back to its author. A read carries no such keys (see `is_write`).
+            out["source"] = self.source
+            out["valid_at"] = d(self.valid_at)
+        return out
 
 
 def _sha(text: str) -> str:
@@ -625,6 +640,7 @@ class Store:
             # stored one way and filtered another.
             tags = normalize_tags(tags)
             valid_at = _as_date(valid_at)
+            check_path(path, "path")
             if id is None and at is None:
                 self._check_path_free(ns, path, if_moved)
                 m = self._create(ns, author, body, path, tags, source, reason,
@@ -641,7 +657,8 @@ class Store:
             # diff can introduce the stray tag just as a whole body can.
             m.warnings = write_warnings(m.body)
             # The revision's own provenance, straight back to whoever wrote it.
-            m.source, m.valid_at = source, valid_at
+            # `is_write` is what puts these on the wire; a read leaves them off.
+            m.source, m.valid_at, m.is_write = source, valid_at, True
             return m
 
     def _check_path_free(self, ns: str, path: Optional[str],