Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

71.5 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Tests for JSON and restricted-Python memory extraction output protocols."""

import json
from types import SimpleNamespace
from unittest.mock import AsyncMock, MagicMock, patch

import pytest

from openviking.session.memory.account_templates import memory_template_data
from openviking.session.memory.dataclass import (
    MemoryField,
    MemoryFile,
    MemoryTypeSchema,
    ResolvedOperations,
)
from openviking.session.memory.extract_loop import ExtractLoop
from openviking.session.memory.extraction_output_protocol import (
    ExtractionOutputContext,
    create_extraction_output_protocol,
)
from openviking.session.memory.memory_isolation_handler import RoleScope
from openviking.session.memory.memory_type_registry import (
    MemoryTypeRegistry,
    resolve_memory_templates_dir,
)
from openviking.session.memory.merge_op import FieldType, MergeOp
from openviking.session.memory.page_id_map import PageIdMap
from openviking.session.memory.schema_model_generator import SchemaModelGenerator


def _preference_schema(*, operation_mode: str = "upsert") -> MemoryTypeSchema:
    return MemoryTypeSchema(
        memory_type="preferences",
        description="User preferences",
        directory="viking://user/{{ user_space }}/memories/preferences",
        filename_template="{{ topic }}.md",
        operation_mode=operation_mode,
        fields=[
            MemoryField(
                name="topic",
                field_type=FieldType.STRING,
                merge_op=MergeOp.IMMUTABLE,
            ),
            MemoryField(
                name="content",
                field_type=FieldType.STRING,
                merge_op=MergeOp.PATCH,
            ),
            MemoryField(
                name="score",
                field_type=FieldType.INT64,
                merge_op=MergeOp.SUM,
            ),
        ],
    )


def _project_schema() -> MemoryTypeSchema:
    return MemoryTypeSchema(
        memory_type="projects",
        description="Projects",
        directory="viking://user/{{ user_space }}/memories/projects",
        filename_template="{{ name }}.md",
        fields=[
            MemoryField(
                name="name",
                field_type=FieldType.STRING,
                merge_op=MergeOp.IMMUTABLE,
            ),
            MemoryField(
                name="content",
                field_type=FieldType.STRING,
                merge_op=MergeOp.REPLACE,
            ),
        ],
    )


def _renameable_entity_schema() -> MemoryTypeSchema:
    return MemoryTypeSchema(
        memory_type="entities",
        description="Entities",
        directory="viking://user/{{ user_space }}/memories/entities",
        filename_template="{{ category }}/{{ name }}.md",
        fields=[
            MemoryField(
                name="category",
                field_type=FieldType.STRING,
                merge_op=MergeOp.REPLACE,
            ),
            MemoryField(
                name="name",
                field_type=FieldType.STRING,
                merge_op=MergeOp.REPLACE,
            ),
            MemoryField(
                name="content",
                field_type=FieldType.STRING,
                merge_op=MergeOp.PATCH,
            ),
        ],
    )


def _profile_schema() -> MemoryTypeSchema:
    return MemoryTypeSchema(
        memory_type="profile",
        description="User profile",
        directory="viking://user/{{ user_space }}/memories",
        filename_template="profile.md",
        fields=[
            MemoryField(
                name="content",
                field_type=FieldType.STRING,
                merge_op=MergeOp.PATCH,
            )
        ],
    )


def _context(
    schemas: list[MemoryTypeSchema],
    *,
    files: list[MemoryFile] | None = None,
    link_enabled: bool = False,
    role_scope: RoleScope | None = None,
    available_tools: tuple[str, ...] = ("read",),
    template_context: dict[str, str] | None = None,
) -> ExtractionOutputContext:
    config = SimpleNamespace(memory=SimpleNamespace(link_enabled=link_enabled))
    with patch("openviking_cli.utils.config.get_openviking_config", return_value=config):
        operations_model = SchemaModelGenerator(
            schemas, template_context=template_context
        ).create_structured_operations_model(role_scope)
    page_id_map = PageIdMap()
    read_file_contents = {}
    for memory_file in files or []:
        read_file_contents[memory_file.uri] = memory_file
        page_id_map.get_page_id(memory_file.uri)
    return ExtractionOutputContext(
        operations_model=operations_model,
        schemas=tuple(schemas),
        page_id_map=page_id_map,
        read_file_contents=read_file_contents,
        link_enabled=link_enabled,
        role_scope=role_scope,
        available_tools=available_tools,
        template_context=dict(template_context or {}),
    )


def _existing_preference(uri: str, topic: str, content: str, score: int = 0) -> MemoryFile:
    return MemoryFile(
        uri=uri,
        memory_type="preferences",
        content=content,
        extra_fields={
            "topic": topic,
            "score": score,
            "version": 7,
            "_uri": uri,
        },
    )


def _bind(protocol, context: ExtractionOutputContext) -> str:
    protocol.render_contract(context)
    return protocol.render_new_bindings(context, source="test read")


def test_json_protocol_preserves_stable_parser_and_empty_contract():
    context = _context([_preference_schema()])
    protocol = create_extraction_output_protocol("json")

    operations, error = protocol.parse(
        '{"preferences": [], "delete_ids": [], "ignored": true}', context
    )

    assert error is None
    assert operations.model_dump() == {"preferences": [], "delete_ids": []}
    assert '"preferences": []' in protocol.render_final_instruction(context)
    assert '"delete_ids": []' in protocol.render_final_instruction(context)

    assert protocol.parse('{"memory_operations": [{"type": "edit"}]}', context) == (
        None,
        "No expected fields found; got fields: memory_operations",
    )


def test_python_contract_and_bindings_expose_only_selected_schema_fields():
    uri = "viking://user/alice/memories/preferences/editor.md"
    body = 'Use Vim\n  Keep "quotes", tabs\tand 中文; literal \\n.'
    context = _context(
        [_preference_schema()],
        files=[_existing_preference(uri, "editor", body, 2)],
    )
    protocol = create_extraction_output_protocol("python")

    contract = protocol.render_contract(context)
    bindings = protocol.render_new_bindings(context, source="search then read")

    assert "sdk.create_preferences" in contract
    assert "sdk.create_projects" not in contract
    record = json.loads(bindings.split("\n", 1)[1])
    assert record == {
        "object_name": "preferences_1",
        "memory_type": "preferences",
        "fields": {"topic": "editor", "score": 2, "content": body},
    }
    assert "Existing-memory records are input context only." in contract
    assert "Use each object_name as an already-bound variable" in contract
    assert "sdk.existing" not in contract
    assert "sdk.existing(" not in bindings
    assert protocol.binding_name(uri) == record["object_name"]
    assert "version" not in bindings
    assert uri not in bindings
    assert protocol.render_new_bindings(context, source="duplicate read") == ""


def test_python_update_preserves_unchanged_mutable_identity_fields():
    uri = "viking://user/alice/memories/entities/person/阿珍.md"
    file = MemoryFile(
        uri=uri,
        memory_type="entities",
        content="大学室友",
        extra_fields={"category": "person", "name": "阿珍"},
    )
    context = _context([_renameable_entity_schema()], files=[file])
    protocol = create_extraction_output_protocol("python")
    _bind(protocol, context)

    operations, error = protocol.parse(
        "entities_1.update(name='陈静娴')\nsdk.commit()",
        context,
    )

    assert error is None
    assert operations.entities[0].category == "person"
    assert operations.entities[0].name == "陈静娴"


def test_python_contract_includes_link_rules_when_enabled():
    context = _context([_preference_schema()], link_enabled=True)
    protocol = create_extraction_output_protocol("python")

    contract = protocol.render_contract(context)

    assert "## Link Rules" in contract
    assert "obj.link(target" in contract
    assert "weight=0.5" in contract
    assert "description=''" in contract
    assert "match_text" in contract
    assert "obj_a.link(" in contract
    assert "assign the create/set call to a variable first" in contract


@pytest.mark.parametrize("language", ["en", "zh-CN"])
@pytest.mark.parametrize(
    ("memory_type", "field_name"),
    [("preferences", "topic"), ("entities", "category"), ("events", "event_name")],
)
def test_python_contract_renders_builtin_field_descriptions_like_json(
    language, memory_type, field_name
):
    registry = MemoryTypeRegistry(load_schemas=False)
    registry.load_from_yaml(str(resolve_memory_templates_dir() / f"{memory_type}.yaml"))
    schema = registry.get(memory_type)
    original = next(field.description for field in schema.fields if field.name == field_name)
    assert "{{ language }}" in original
    context = _context([schema], template_context={"language": language})

    python_contract = create_extraction_output_protocol("python").render_contract(context)
    json_contract = create_extraction_output_protocol("json").render_contract(context)
    json_schema = json.loads(json_contract.split("```json\n", 1)[1].split("```", 1)[0])
    model_ref = json_schema["properties"][memory_type]["items"]["$ref"].rsplit("/", 1)[1]
    rendered = json_schema["$defs"][model_ref]["properties"][field_name]["description"]

    assert " ".join(rendered.split()) in python_contract
    assert language in rendered
    assert "{{ language }}" not in python_contract
    assert "{% if language" not in python_contract
    assert ("Use lowercase with underscores" in rendered) == (language == "en")
    assert (
        next(field.description for field in schema.fields if field.name == field_name) == original
    )


def test_python_field_description_keeps_dsl_patch_instructions():
    schema = _preference_schema()
    schema.fields[1].description = "Write content in {{ language.upper() }}."
    context = _context([schema], template_context={"language": "en"})

    protocol = create_extraction_output_protocol("python")
    contract = protocol.render_contract(context)

    assert "content [editable string: obj.field.edit/drop/update]: Write content in EN." in contract
    assert "obj.content.edit(search=..., replace=...)" in contract
    assert "PATCH operation for" not in contract
    assert "Use a DELETE block" not in contract
    assert "copied verbatim" in contract
    assert "occur exactly once" in contract
    assert "## Patch Context Rules" in protocol.render_context_rules(context)


@pytest.mark.parametrize("output_format", ["python", "json"])
def test_output_contract_preserves_core_add_only_and_upsert_capabilities(output_format):
    context = _context([_preference_schema(operation_mode="add_only")], available_tools=())
    protocol = create_extraction_output_protocol(output_format)
    contract = protocol.render_contract(context)
    rules = protocol.render_reference_rules(context)
    assert "Create new memories only, with complete field values" in contract + rules
    assert protocol.render_context_rules(context) == ""
    for unsupported in (
        "obj.update",
        "obj.content.edit",
        "obj.content.drop",
        "replacement=",
    ):
        assert unsupported not in contract + rules + protocol.render_final_instruction(context)
    assert "delete_ids" not in rules + protocol.render_final_instruction(context)

    program = (
        'sdk.create_preferences(topic="editor", content="""Use Vim""", score=1)\nsdk.commit()'
        if output_format == "python"
        else '{"preferences": [{"page_id": 100, "topic": "editor", "content": "Use Vim", "score": 1}]}'
    )
    operations, error = protocol.parse(program, context)
    assert error is None
    assert operations.preferences[0].content == "Use Vim"

    # A mixed batch must retain upsert/delete support, without teaching patches
    # from an add-only schema or exposing inspection tools it does not have.
    mixed = _context(
        [_preference_schema(operation_mode="add_only"), _project_schema()], available_tools=()
    )
    rules = protocol.render_reference_rules(mixed)
    contract = protocol.render_contract(mixed)
    assert "replacement" in rules
    assert "preserving every unaffected fact" in rules
    assert protocol.render_context_rules(mixed) == ""
    if output_format == "python":
        assert "obj.content.update(" in contract
        assert "obj.delete(replacement=None)" in contract
        assert "obj.content.edit" not in contract
        assert "obj.content.drop" not in contract
        assert "call the available native" not in contract.lower()
        assert "never drop a unique fact" in rules
    else:
        assert "When editing an existing item" in rules
        assert "DELETE blocks" not in rules


@pytest.mark.asyncio
@pytest.mark.parametrize("language", ["en", "zh-CN"])
async def test_default_python_extract_loop_passes_language_to_field_descriptions(language):
    schema = _preference_schema()
    schema.description = "Preferences in {{ language }}."
    schema.fields[1].description = "Write content in {{ language }}."
    provider = MagicMock()
    provider.get_memory_schemas.return_value = [schema]
    provider.get_output_language.return_value = language
    provider.get_tools.return_value = []
    provider.get_extract_context.return_value = SimpleNamespace(page_id_map=PageIdMap())
    provider.read_file_contents = {}
    provider.instruction.return_value = "Extract memory operations."
    provider.prefetch = AsyncMock(return_value=[])
    vlm = SimpleNamespace(
        model="test-model", get_completion_async=AsyncMock(return_value="sdk.commit()")
    )
    loop = ExtractLoop(vlm=vlm, viking_fs=MagicMock(), context_provider=provider, max_iterations=1)
    empty = ResolvedOperations(upsert_operations=[], delete_file_contents=[], errors=[])
    loop.resolve_operations = AsyncMock(return_value=(empty, []))
    loop._check_unread_existing_files = AsyncMock(return_value={})
    # Exercise the default protocol selection rather than explicitly choosing Python.
    config = SimpleNamespace(memory=SimpleNamespace(link_enabled=False))
    with (
        patch("openviking.session.memory.extract_loop.get_openviking_config", return_value=config),
        patch("openviking_cli.utils.config.get_openviking_config", return_value=config),
    ):
        operations, _ = await loop.run()

    assert operations is empty
    prompt = vlm.get_completion_async.call_args.kwargs["messages"][0]["content"]
    assert "restricted Python memory SDK" in prompt
    assert f"Preferences in {language}." in prompt
    assert f"Write content in {language}." in prompt
    assert "{{ language }}" not in prompt
    assert "## Read Format Rules" not in prompt
    assert "## Patch Context Rules" in prompt


def test_python_contract_omits_link_rules_when_disabled():
    context = _context([_preference_schema()], link_enabled=False)
    protocol = create_extraction_output_protocol("python")

    contract = protocol.render_contract(context)

    assert "## Link Rules" not in contract
    assert "obj.link(...) is unavailable" in contract


def test_python_protocol_compiles_extracted_code_from_fence():
    context = _context([_preference_schema()])
    protocol = create_extraction_output_protocol("python")
    compiled = []

    def record_compile(self, code):
        compiled.append(code)
        return context.operations_model(preferences=[], delete_ids=[])

    with patch(
        "openviking.session.memory.extraction_output_protocol.python_protocol._PythonProgramCompiler.compile",
        autospec=True,
        side_effect=record_compile,
    ):
        operations, error = protocol.parse("```python\nsdk.commit()\n```", context)

    assert error is None
    assert operations is not None
    # The fenced code (not the raw fence wrapper) is what gets compiled.
    assert compiled == ["sdk.commit()"]


def test_json_protocol_preserves_tool_result_context_shape():
    context = _context([_preference_schema()])
    protocol = create_extraction_output_protocol("json")
    result = {"memory_type": "preferences", "content": "1\tUse Vim"}

    messages = protocol.render_tool_result_messages(
        context,
        call_id="call-1",
        tool_name="read",
        params={"uri": "viking://user/alice/memories/preferences/editor.md"},
        result=result,
        source="tool call",
    )

    assert messages == [
        {
            "role": "user",
            "content": json.dumps(
                {
                    "tool_call_name": "read",
                    "args": {"uri": "viking://user/alice/memories/preferences/editor.md"},
                    "result": result,
                },
                ensure_ascii=False,
            ),
        }
    ]


def test_python_protocol_renders_search_result_as_read_tool_comment():
    uri_a = "viking://user/alice/memories/entities/person/tim.md"
    uri_b = "viking://user/alice/memories/entities/person/maria.md"
    context = _context([_preference_schema()])
    protocol = create_extraction_output_protocol("python")

    messages = protocol.render_tool_result_messages(
        context,
        call_id="call-1",
        tool_name="search",
        params={"query": "tim maria"},
        result=[{"uri": uri_a, "score": 0.9}, {"uri": uri_b, "score": 0.8}],
        source="tool call",
    )

    assert len(messages) == 1
    content = messages[0]["content"]
    assert content.startswith("# Search")
    assert "query='tim maria'" in content
    assert "read them with the read tool" in content
    assert f"# - {uri_a}" in content
    assert f"# - {uri_b}" in content
    # Search yields no content, so it must not register an existing object.
    assert "sdk.existing(" not in content
    assert protocol.binding_name(uri_a) is None
    assert protocol.binding_name(uri_b) is None
    assert "search_results" not in content
    assert "0.9" not in content


def test_python_protocol_renders_empty_search_result_as_comment():
    context = _context([_preference_schema()])
    protocol = create_extraction_output_protocol("python")

    messages = protocol.render_tool_result_messages(
        context,
        call_id="call-1",
        tool_name="search",
        params={"query": "nobody"},
        result=[],
        source="tool call",
    )

    assert messages[0]["content"] == "# Search query='nobody' found no memory files."


def test_python_protocol_search_comment_omits_read_tool_when_unavailable():
    uri = "viking://user/alice/memories/entities/person/tim.md"
    # eager_prefetch preloads everything and exposes no tools to the model.
    context = _context([_preference_schema()], available_tools=())
    protocol = create_extraction_output_protocol("python")

    messages = protocol.render_tool_result_messages(
        context,
        call_id="call-1",
        tool_name="search",
        params={"query": "tim"},
        result=[{"uri": uri, "score": 0.9}],
        source="prefetch",
    )

    content = messages[0]["content"]
    assert "read them with the read tool" not in content
    assert "there is no read tool" in content
    assert "treat anything not shown above as new" in content
    assert f"# - {uri}" in content


def test_python_protocol_renders_read_result_directly_as_existing_binding():
    uri = "viking://user/alice/memories/preferences/editor.md"
    context = _context(
        [_preference_schema()],
        files=[_existing_preference(uri, "editor", "Use Vim\nKeep plugins small", 2)],
    )
    protocol = create_extraction_output_protocol("python")
    protocol.render_contract(context)

    messages = protocol.render_tool_result_messages(
        context,
        call_id="call-1",
        tool_name="read",
        params={"uri": uri, "offset": 1, "limit": 1},
        result={
            "memory_type": "preferences",
            "topic": "editor",
            "score": 2,
            "content": "2\tKeep plugins small",
            "page_id": 1,
            "memory_maintenance_notice": {
                "maintenance_required": True,
                "guidance": "choose split or compact",
            },
        },
        source="tool call",
    )

    assert len(messages) == 1
    content = messages[0]["content"]
    assert content.startswith("# Existing memory loaded by tool call")
    record = json.loads(content.split("\n", 1)[1].split("\n# Memory maintenance notice:", 1)[0])
    assert record["object_name"] == "preferences_1"
    assert record["fields"]["content"] == "Keep plugins small"
    assert "sdk.existing(" not in content
    assert "2\\tKeep plugins small" not in content
    assert "Use Vim" not in content
    assert "tool_call_name" not in content
    assert "page_id" not in content
    assert uri not in content
    assert "# Memory maintenance notice:" in content
    assert '"maintenance_required": true' in content
    assert "estimated_tokens" not in content
    assert "content_characters" not in content
    assert "choose split or compact" in content

    reread = protocol.render_tool_result_messages(
        context,
        call_id="call-2",
        tool_name="read",
        params={"uri": uri},
        result={"content": "Use Neovim\nKeep plugins small"},
        source="tool call",
    )
    updated_record = json.loads(reread[0]["content"].split("\n", 1)[1])
    assert updated_record["object_name"] == record["object_name"]
    assert updated_record["fields"]["content"] == "Use Neovim\nKeep plugins small"
    assert protocol.render_new_bindings(context, source="after reread") == ""


def test_python_protocol_converts_prefetch_tool_messages_without_duplicating_read_content():
    uri = "viking://user/alice/memories/preferences/editor.md"
    source_uri = "viking://user/alice/memories/trajectories/source.md"
    context = _context(
        [_preference_schema()],
        files=[_existing_preference(uri, "editor", "Use Vim", 2)],
    )
    protocol = create_extraction_output_protocol("python")
    protocol.render_contract(context)
    prefetched = [
        {"role": "user", "content": "Conversation History"},
        {
            "role": "user",
            "content": json.dumps(
                {
                    "tool_call_name": "search",
                    "args": {"query": "editor"},
                    "result": [{"uri": uri, "score": 0.9}],
                }
            ),
        },
        {
            "role": "user",
            "content": json.dumps(
                {
                    "tool_call_name": "read",
                    "args": {"uri": uri},
                    "result": {
                        "memory_type": "preferences",
                        "topic": "editor",
                        "score": 2,
                        "content": "1\tUse Vim",
                    },
                }
            ),
        },
    ]
    prefetched.append(
        {
            "role": "user",
            "content": json.dumps(
                {
                    "tool_call_name": "read",
                    "args": {"uri": source_uri},
                    "result": {
                        "context_role": "candidate_source_trajectory",
                        "content": "Read-only source trajectory",
                    },
                }
            ),
        }
    )

    messages = protocol.render_prefetch_messages(prefetched, context)
    combined = "\n".join(message["content"] for message in messages)

    assert messages[0]["content"] == "Conversation History"
    # Search only yields URIs, so it renders as a read-tool comment, not a binding.
    assert "read them with the read tool" in combined
    assert f"# - {uri}" in combined
    assert "search_results = [" not in combined
    # Only the writable memory gets an object reference; source trajectories stay read-only.
    assert '"object_name": "preferences_1"' in combined
    assert "sdk.existing(" not in combined
    assert combined.count("Use Vim") == 1
    assert "tool_call_name" not in combined
    assert '"result"' not in combined
    assert "Read-only context; this is not a mutable memory object." in combined
    assert protocol.binding_name(source_uri) is None

    operations, error = protocol.parse(
        'preferences_1.content.edit(search="Use Vim", replace="Use Neovim")\nsdk.commit()',
        context,
    )
    assert error is None
    assert operations.model_dump()["preferences"][0]["content"]["blocks"] == [
        {"search": "Use Vim", "replace": "Use Neovim"}
    ]
    operations, error = protocol.parse(
        'candidate_source_trajectory.content.update("not allowed")', context
    )
    assert operations is None and "unknown name" in error


def test_python_contract_uses_set_for_single_file_schema_and_create_for_collection():
    context = _context(
        [_profile_schema(), _preference_schema()],
        role_scope=RoleScope(user_ids=["alice"], peer_ids=["bob"]),
    )
    protocol = create_extraction_output_protocol("python")

    contract = protocol.render_contract(context)

    assert "sdk.set_profile" in contract
    assert "- sdk.create_profile(*," not in contract
    assert (
        "profile is a SINGLETON per identity: sdk.create_profile() does not exist, and "
        "sdk.set_profile() must appear AT MOST ONCE for each identity"
    ) in contract
    assert (
        "Current identity peer_id='bob': exactly one "
        "sdk.set_profile(peer_id='bob', ...) call; combine every person and section"
    ) in contract
    assert "Memory type rules:" in contract
    assert "User profile" in contract
    assert "sdk.create_preferences" in contract
    assert "sdk.set_preferences" not in contract
    assert "canonical = sdk.create_<type>(...)" in contract
    assert "duplicate_1.delete(replacement=canonical)" in contract
    assert "Identity fields (primary key): peer_id." in contract
    assert "Identity fields (primary key): peer_id, topic." in contract
    assert "Current self identity: exactly one sdk.set_profile() call without peer_id" in contract


def test_python_reserved_existing_retry_explains_new_replacement_binding():
    protocol = create_extraction_output_protocol("python")

    retry = protocol.render_format_retry(
        "Line 3: sdk.existing() is reserved for system-provided bindings"
    )

    assert "object_name from the system-provided existing-memory context record" in retry
    assert "already-bound variable" in retry
    assert "canonical = sdk.create_<type>(...)" in retry
    assert "duplicate_1.delete(replacement=canonical)" in retry


def test_python_string_literal_retry_pushes_triple_quotes():
    protocol = create_extraction_output_protocol("python")

    retry = protocol.render_format_retry("Line 33: invalid syntax. Perhaps you forgot a comma?")

    assert "offending line is shown above" in retry
    assert 'triple-quoted string ("""...""")' in retry


def test_python_non_string_syntax_error_omits_quote_guidance():
    protocol = create_extraction_output_protocol("python")

    retry = protocol.render_format_retry("Line 3: unexpected indent")

    assert "offending line is shown above" not in retry


def test_resolution_repair_matches_protocol_output_shape():
    issues = [
        {
            "memory_type": "events",
            "page_id": 100,
            "reason_code": "no_writable_target",
            "reason": "range out of bounds",
            "operation": {"event_name": "yoga_class_started", "ranges": "99"},
        }
    ]

    json_repair = create_extraction_output_protocol("json").render_resolution_repair(issues)
    assert "ONLY one JSON object" in json_repair
    assert "yoga_class_started" in json_repair

    python_repair = create_extraction_output_protocol("python").render_resolution_repair(issues)
    assert "sdk.create_events" in python_repair
    assert "Output only Python code." in python_repair
    assert "JSON object" not in python_repair


def _kebab_schema() -> MemoryTypeSchema:
    return MemoryTypeSchema(
        memory_type="project-notes",
        description="Project notes",
        directory="viking://user/{{ user_space }}/memories/project-notes",
        filename_template="{{ project_name }}.md",
        fields=[
            MemoryField(
                name="project_name",
                field_type=FieldType.STRING,
                merge_op=MergeOp.IMMUTABLE,
            ),
            MemoryField(
                name="note-body",
                field_type=FieldType.STRING,
                merge_op=MergeOp.PATCH,
            ),
        ],
    )


def test_python_contract_aliases_non_identifier_schema_names():
    context = _context([_kebab_schema()])
    protocol = create_extraction_output_protocol("python")

    contract = protocol.render_contract(context)

    # Method/parameter names are folded to valid identifiers on the DSL surface.
    assert "sdk.create_project_notes(" in contract
    assert "note_body" in contract
    assert "sdk.create_project-notes" not in contract


def test_python_compiles_aliased_names_back_to_real_schema():
    context = _context([_kebab_schema()])
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse(
        """
sdk.create_project_notes(
    project_name="atlas",
    note_body=\"\"\"Kickoff on 2023-06-09.\"\"\",
)
sdk.commit()
""",
        context,
    )

    assert error is None, error
    dumped = operations.model_dump()
    # Real schema name and real field name are preserved in the operations.
    assert dumped["project-notes"] == [
        {"page_id": 100, "project_name": "atlas", "note-body": "Kickoff on 2023-06-09."}
    ]


def test_python_edits_aliased_field_on_existing_object():
    existing = MemoryFile(
        uri="viking://user/alice/memories/project-notes/atlas.md",
        memory_type="project-notes",
        content="",
        extra_fields={
            "project_name": "atlas",
            "note-body": "Kickoff on 2023-06-09.",
            "version": 3,
            "_uri": "x",
        },
    )
    context = _context([_kebab_schema()], files=[existing])
    protocol = create_extraction_output_protocol("python")

    bindings = _bind(protocol, context)
    # Existing-object binding exposes the field under its identifier alias.
    record = json.loads(bindings.split("\n", 1)[1])
    assert record["fields"]["note_body"] == "Kickoff on 2023-06-09."
    assert "note-body" not in record["fields"]

    var = record["object_name"]
    operations, error = protocol.parse(
        f"""
{var}.note_body.edit(search=\"\"\"Kickoff on 2023-06-09.\"\"\", replace=\"\"\"Kickoff moved to 2023-07-01.\"\"\")
sdk.commit()
""",
        context,
    )

    assert error is None, error
    edited = operations.model_dump()["project-notes"]
    assert edited and edited[0]["page_id"] == 1


def _schema_named(memory_type: str, field_names: list[str]) -> MemoryTypeSchema:
    return MemoryTypeSchema(
        memory_type=memory_type,
        description=memory_type,
        directory=f"viking://user/{{{{ user_space }}}}/memories/{memory_type}",
        filename_template="{{ name }}.md",
        fields=[
            MemoryField(name=name, field_type=FieldType.STRING, merge_op=MergeOp.PATCH)
            for name in field_names
        ],
    )


def test_python_rejects_colliding_memory_type_aliases():
    # 'project-notes' and 'project_notes' both fold to the same DSL alias.
    context = _context(
        [_schema_named("project-notes", ["name"]), _schema_named("project_notes", ["name"])]
    )
    protocol = create_extraction_output_protocol("python")

    with pytest.raises(ValueError, match="same Python DSL alias"):
        protocol.render_contract(context)


def test_python_rejects_colliding_field_aliases():
    # 'note-body' and 'note_body' collide within one schema.
    context = _context([_schema_named("notes", ["note-body", "note_body"])])
    protocol = create_extraction_output_protocol("python")

    with pytest.raises(ValueError, match="same Python DSL alias"):
        protocol.render_contract(context)


def test_python_parse_rejects_colliding_aliases_without_render():
    # Collision must be caught even when parse() runs without render_contract().
    context = _context(
        [_schema_named("project-notes", ["name"]), _schema_named("project_notes", ["name"])]
    )
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse("sdk.commit()", context)

    assert operations is None
    assert "same Python DSL alias" in error


def test_python_syntax_error_includes_offending_source_line():
    context = _context([_preference_schema()])
    protocol = create_extraction_output_protocol("python")

    # A double-quoted summary that itself embeds a double quote ends the string
    # early; the compiler should surface the real offending line, not just the
    # misleading "forgot a comma" hint.
    _operations, error = protocol.parse(
        'sdk.create_preferences(topic="x", content="he saw "Little Women" today", score=1)',
        context,
    )

    assert error is not None
    assert "invalid Python syntax" in error
    assert "Little Women" in error
    assert "^" in error


@pytest.mark.parametrize("ending", ["sdk.commit(", "sdk.commit())"])
@pytest.mark.parametrize(
    "wrapper", ["{}", "```python\n{}\n```", "Explanation\n```python\n{}\n```\nDone."]
)
def test_python_rejects_invalid_program_containing_fenced_example(ending, wrapper):
    context = _context([_profile_schema()])
    protocol = create_extraction_output_protocol("python")
    program = (
        'sdk.set_profile(content="""Example:\n```python\nsdk.commit()\n```\n'
        f'Keep this example.""")\n{ending}'
    )

    operations, error = protocol.parse(wrapper.format(program), context)

    assert operations is None
    assert error is not None


def test_memory_schema_identity_fields_follow_scope_and_uri_template():
    entities = MemoryTypeSchema(
        memory_type="entities",
        directory="viking://user/{{ user_space }}/memories/entities",
        filename_template="{{ category|lower }}/{{ name|lower }}.md",
        fields=[
            MemoryField(name="category", field_type=FieldType.STRING),
            MemoryField(name="name", field_type=FieldType.STRING),
            MemoryField(name="content", field_type=FieldType.STRING),
        ],
    )
    preferences = MemoryTypeSchema(
        memory_type="preferences",
        directory="viking://user/{{ user_space }}/memories/preferences",
        filename_template="{{ user }}/{{ topic }}.md",
        fields=[
            MemoryField(name="user", field_type=FieldType.STRING),
            MemoryField(name="topic", field_type=FieldType.STRING),
            MemoryField(name="content", field_type=FieldType.STRING),
        ],
    )

    assert _profile_schema().identity_fields() == ("peer_id",)
    assert preferences.identity_fields() == ("peer_id", "user", "topic")
    assert entities.identity_fields() == ("peer_id", "category", "name")


def test_memory_schema_identity_fields_ignore_jinja_token_collisions():
    # `year` and `context` appear only inside a filter/function/attribute
    # expression, never as referenced variables, so they must not be treated
    # as identity fields. Only `ranges` and `event_name` are real references.
    events = MemoryTypeSchema(
        memory_type="events",
        directory="viking://user/{{ user_space }}/memories/events",
        filename_template="{{ extract_context.get_year(ranges) }}/{{ event_name }}.md",
        fields=[
            MemoryField(name="event_name", field_type=FieldType.STRING),
            MemoryField(name="ranges", field_type=FieldType.STRING),
            MemoryField(name="year", field_type=FieldType.STRING),
            MemoryField(name="context", field_type=FieldType.STRING),
            MemoryField(name="content", field_type=FieldType.STRING),
        ],
    )

    assert events.identity_fields() == ("peer_id", "event_name", "ranges")


@pytest.mark.parametrize(
    "content",
    [
        "Engineer",
        'Config:\n```nginx\nadd_header Cache-Control "no-cache";\n```\nDone.',
        "Example:\n```python\nsdk.commit()\n```\nKeep this example.",
        "Use the literal ``` marker.",
        "```text\nfirst\n```\n```python\nsdk.commit()\n```",
    ],
)
@pytest.mark.parametrize(
    "wrapper",
    ["{}", "```python\n{}\n```", "Explanation\n```python\n{}\n```\nDone."],
)
def test_python_set_single_file_memory_compiles_to_same_operations_as_json(content, wrapper):
    context = _context([_profile_schema()])
    python_protocol = create_extraction_output_protocol("python")
    json_protocol = create_extraction_output_protocol("json")

    python_operations, python_error = python_protocol.parse(
        wrapper.format(f'sdk.set_profile(content="""{content}""")\nsdk.commit()'),
        context,
    )
    json_operations, json_error = json_protocol.parse(
        json.dumps({"profile": [{"page_id": 100, "content": content}], "delete_ids": []}),
        context,
    )

    assert python_error is None
    assert json_error is None
    assert python_operations.model_dump() == json_operations.model_dump()


def test_python_commit_is_optional():
    context = _context([_profile_schema()])
    protocol = create_extraction_output_protocol("python")

    # A program without a trailing sdk.commit() is accepted as-is.
    without_commit, error = protocol.parse("sdk.set_profile(content='Engineer')", context)
    assert error is None
    assert without_commit.model_dump()["profile"][0]["content"] == "Engineer"

    # An empty program means "no changes".
    empty_operations, empty_error = protocol.parse("", context)
    assert empty_error is None
    assert empty_operations.model_dump() == {"profile": [], "delete_ids": []}


def test_python_rejects_create_for_single_file_and_set_for_collection():
    context = _context([_profile_schema(), _preference_schema()])
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse(
        "sdk.create_profile(content='Engineer')\nsdk.commit()", context
    )
    assert operations is None
    assert "use sdk.set_profile()" in error

    operations, error = protocol.parse(
        "sdk.set_preferences(topic='editor', content='Use Vim', score=1)\nsdk.commit()",
        context,
    )
    assert operations is None
    assert "use sdk.create_preferences()" in error


def test_python_rejects_repeated_single_file_set_for_same_peer_scope():
    context = _context(
        [_profile_schema()],
        role_scope=RoleScope(user_ids=["alice"], peer_ids=["bob"]),
    )
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse(
        """
sdk.set_profile(peer_id="bob", content="Engineer")
sdk.set_profile(peer_id="bob", content="Musician")
sdk.commit()
""",
        context,
    )

    assert operations is None
    assert "duplicate profile identity (peer_id='bob')" in error
    assert "may be called only once for peer 'bob'" in error
    assert "combine all people and content sections" in error


def test_python_rejects_repeated_single_file_set_for_self_scope():
    context = _context([_profile_schema()])
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse(
        """
sdk.set_profile(content="Engineer")
sdk.set_profile(content="Musician")
sdk.commit()
""",
        context,
    )

    assert operations is None
    assert "may be called only once for self" in error


def test_python_allows_one_single_file_set_per_peer_scope():
    context = _context(
        [_profile_schema()],
        role_scope=RoleScope(user_ids=["alice"], peer_ids=["bob", "carol"]),
    )
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse(
        """
sdk.set_profile(peer_id="bob", content="Engineer")
sdk.set_profile(peer_id="carol", content="Musician")
sdk.commit()
""",
        context,
    )

    assert error is None
    assert operations.model_dump()["profile"] == [
        {"peer_id": "bob", "page_id": 100, "content": "Engineer"},
        {"peer_id": "carol", "page_id": 101, "content": "Musician"},
    ]


def test_python_create_compiles_to_same_operations_as_json():
    context = _context([_preference_schema()])
    python_protocol = create_extraction_output_protocol("python")
    json_protocol = create_extraction_output_protocol("json")

    python_operations, python_error = python_protocol.parse(
        """
topic = "editor".upper().lower()
score = len([1, 2]) + 1
sdk.create_preferences(
    topic=topic,
    content=f"Use {topic}",
    score=score,
    ignored=unknown_name_that_must_not_be_evaluated,
)
sdk.commit()
""",
        context,
    )
    json_operations, json_error = json_protocol.parse(
        """
{
  "preferences": [
    {"page_id": 100, "topic": "editor", "content": "Use editor", "score": 3}
  ],
  "delete_ids": []
}
""",
        context,
    )

    assert python_error is None
    assert json_error is None
    assert python_operations.model_dump() == json_operations.model_dump()


def test_python_create_avoids_existing_page_id_collisions():
    context = _context([_preference_schema()])
    context.page_id_map.register_new_page_id("viking://existing/100.md", 100)
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse(
        "sdk.create_preferences(topic='editor', content='Use Vim', score=1)\nsdk.commit()",
        context,
    )

    assert error is None
    assert operations.model_dump()["preferences"][0]["page_id"] == 101


def test_python_protocol_includes_dynamic_peer_id_field():
    schema = _preference_schema()
    context = _context(
        [schema],
        role_scope=RoleScope(user_ids=["alice"], peer_ids=["bob", "carol"]),
    )
    protocol = create_extraction_output_protocol("python")

    contract = protocol.render_contract(context)
    operations, error = protocol.parse(
        "sdk.create_preferences(peer_id='bob', topic='editor', content='Use Vim', score=1)\nsdk.commit()",
        context,
    )

    assert "peer_id: str" in contract
    assert "Available peer_id values in this session: bob, carol" in contract
    assert error is None
    assert operations.model_dump()["preferences"][0]["peer_id"] == "bob"


def test_python_existing_binding_exposes_but_does_not_update_dynamic_peer_id():
    schema = _preference_schema()
    memory_file = _existing_preference(
        "viking://user/alice/peers/bob/memories/preferences/editor.md",
        "editor",
        "Use Vim",
    )
    memory_file.extra_fields["peer_id"] = "bob"
    context = _context(
        [schema],
        files=[memory_file],
        role_scope=RoleScope(user_ids=["alice"], peer_ids=["bob", "carol"]),
    )
    protocol = create_extraction_output_protocol("python")

    bindings = _bind(protocol, context)
    operations, error = protocol.parse(
        "preferences_1.update(peer_id='carol')\npreferences_1.content.update('Use Emacs')\nsdk.commit()",
        context,
    )

    assert json.loads(bindings.split("\n", 1)[1])["fields"]["peer_id"] == "bob"
    assert error is None
    item = operations.model_dump()["preferences"][0]
    assert item["content"] == "Use Emacs"
    assert item["peer_id"] is None


def test_python_existing_updates_emit_patch_blocks_and_accumulate_sum_delta():
    uri = "viking://user/alice/memories/preferences/editor.md"
    context = _context(
        [_preference_schema()],
        files=[_existing_preference(uri, "editor", "Use Vim\nDark theme\nTabs", 10)],
    )
    protocol = create_extraction_output_protocol("python")
    _bind(protocol, context)

    operations, error = protocol.parse(
        """
preferences_1.content.edit(search="Use Vim", replace="Use Neovim")
preferences_1.update(score=2)
preferences_1.content.drop(text="Tabs")
preferences_1.update(
    topic="ignored immutable change",
    score=3,
    unknown_field="ignored",
    another_unknown=unknown_name_that_must_not_be_evaluated,
)
sdk.commit()
""",
        context,
    )

    assert error is None
    # edit/drop are emitted as StrPatch blocks (applied later by the shared path),
    # while SUM deltas still accumulate at compile time.
    item = operations.model_dump()["preferences"][0]
    assert item["page_id"] == 1
    assert item["topic"] == "editor"
    assert item["score"] == 5
    assert item["content"]["blocks"] == [
        {"search": "Use Vim", "replace": "Use Neovim"},
        {"delete": "Tabs"},
    ]


def test_python_patch_preserves_unescaped_markers_in_blocks():
    uri = "viking://user/alice/memories/preferences/editor.md"
    context = _context(
        [_preference_schema()],
        files=[_existing_preference(uri, "editor", "<<<<<<< literal", 0)],
    )
    protocol = create_extraction_output_protocol("python")
    _bind(protocol, context)

    operations, error = protocol.parse(
        r"""
preferences_1.content.edit(search=r"\<<<<<<< literal", replace="plain")
sdk.commit()
""",
        context,
    )

    assert error is None
    blocks = operations.model_dump()["preferences"][0]["content"]["blocks"]
    assert blocks == [{"search": r"\<<<<<<< literal", "replace": "plain"}]


def test_python_field_edit_chain_emits_blocks_in_order():
    uri = "viking://user/alice/memories/preferences/editor.md"
    context = _context(
        [_preference_schema()],
        files=[_existing_preference(uri, "editor", "Use Vim\nDark theme", 0)],
    )
    protocol = create_extraction_output_protocol("python")
    _bind(protocol, context)

    operations, error = protocol.parse(
        """
preferences_1.content.edit(search="Use Vim", replace="Use Neovim").drop(text="Dark theme")
sdk.commit()
""",
        context,
    )

    assert error is None
    blocks = operations.model_dump()["preferences"][0]["content"]["blocks"]
    assert blocks == [
        {"search": "Use Vim", "replace": "Use Neovim"},
        {"delete": "Dark theme"},
    ]


@pytest.mark.parametrize("supersedes", [None, "", "older_pattern"])
def test_python_experience_supersedes_is_optional(supersedes):
    registry = MemoryTypeRegistry(load_schemas=False)
    registry.load_from_yaml(str(resolve_memory_templates_dir() / "experiences.yaml"))
    schema = registry.get("experiences")
    schema = registry._parse_memory_type(memory_template_data(schema))
    context = _context([schema])
    protocol = create_extraction_output_protocol("python")
    argument = "" if supersedes is None else f", supersedes={supersedes!r}"

    operations, error = protocol.parse(
        f"sdk.create_experiences(experience_name='pattern', content='insight'{argument})\n"
        "sdk.commit()",
        context,
    )

    assert error is None
    assert operations.model_dump()["experiences"][0]["supersedes"] == supersedes
    assert "supersedes is optional; may be omitted" in protocol.render_contract(context)


@pytest.mark.parametrize(
    "filename_template, verb", [("{{ topic }}.md", "create"), ("fixed.md", "set")]
)
def test_python_optional_fields_do_not_relax_required_fields(filename_template, verb):
    schema = _preference_schema()
    schema.filename_template = filename_template
    schema.fields[1].init_value = "initial content"
    schema.fields[-1] = MemoryField(
        name="score", field_type=FieldType.INT64, merge_op=MergeOp.SUM, required=False
    )
    context = _context([schema])
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse(
        f"sdk.{verb}_preferences(topic='editor', content='Use Vim')\nsdk.commit()", context
    )
    assert error is None
    assert operations.model_dump()["preferences"][0]["score"] is None

    operations, error = protocol.parse(
        f"sdk.{verb}_preferences(topic='editor')\nsdk.commit()", context
    )
    assert operations is None
    assert "missing: content" in error


@pytest.mark.parametrize("memory_type", ["experiences", "entities"])
@pytest.mark.parametrize("method", ['edit(search="old", replace="new")', 'drop(text="old")'])
def test_python_builtin_content_edit_accepts_replace_but_keeps_update_guidance(memory_type, method):
    registry = MemoryTypeRegistry(load_schemas=False)
    registry.load_from_yaml(str(resolve_memory_templates_dir() / f"{memory_type}.yaml"))
    schema = registry.get(memory_type)
    assert schema is not None
    context = _context(
        [schema],
        files=[
            MemoryFile(
                uri=f"viking://user/alice/memories/{memory_type}/one.md",
                memory_type=memory_type,
                content="old text",
                extra_fields=(
                    {"experience_name": "one", "supersedes": ""}
                    if memory_type == "experiences"
                    else {"category": "concept", "name": "one"}
                ),
            )
        ],
    )
    protocol = create_extraction_output_protocol("python")
    _bind(protocol, context)
    operations, error = protocol.parse(f"{memory_type}_1.content.{method}", context)

    assert error is None
    assert operations is not None
    assert operations.model_dump()[memory_type][0]["content"]["blocks"]
    if memory_type == "experiences":
        contract = protocol.render_contract(context)
        rules = protocol.render_reference_rules(context)
        assert "obj.content.update(" in contract
        assert "obj.content.edit(" not in contract
        assert "obj.content.drop(" not in contract
        assert "delete(replacement=canonical)" in rules
        assert "never drop a unique fact" in rules
        operations, error = protocol.parse(
            'experiences_1.content.update("complete new value")', context
        )
        assert error is None
        assert operations.model_dump()[memory_type][0]["content"] == "complete new value"


def test_python_field_update_replaces_whole_field():
    uri = "viking://user/alice/memories/preferences/editor.md"
    context = _context(
        [_preference_schema()],
        files=[_existing_preference(uri, "editor", "Use Vim\nDark theme", 0)],
    )
    protocol = create_extraction_output_protocol("python")
    _bind(protocol, context)

    operations, error = protocol.parse(
        '''
preferences_1.content.update("""# Editor
- Use Neovim""")
sdk.commit()
''',
        context,
    )

    assert error is None
    assert operations.model_dump()["preferences"][0]["content"] == "# Editor\n- Use Neovim"


def test_python_field_edit_emits_block_even_when_search_absent():
    # Matching/rejection is now the shared validation path's job (json parity),
    # so parse() succeeds and just emits the block; a bad snippet no longer fails
    # the whole program at compile time.
    uri = "viking://user/alice/memories/preferences/editor.md"
    context = _context(
        [_preference_schema()],
        files=[_existing_preference(uri, "editor", "Use Vim", 0)],
    )
    protocol = create_extraction_output_protocol("python")
    _bind(protocol, context)

    operations, error = protocol.parse(
        """
preferences_1.content.edit(search="Prefers Neovim", replace="Prefers Emacs")
sdk.commit()
""",
        context,
    )

    assert error is None
    blocks = operations.model_dump()["preferences"][0]["content"]["blocks"]
    assert blocks == [{"search": "Prefers Neovim", "replace": "Prefers Emacs"}]


def test_python_unknown_field_is_silently_ignored():
    uri = "viking://user/alice/memories/preferences/editor.md"
    context = _context(
        [_preference_schema()],
        files=[_existing_preference(uri, "editor", "Use Vim", 0)],
    )
    protocol = create_extraction_output_protocol("python")
    _bind(protocol, context)

    operations, error = protocol.parse(
        "preferences_1.field.edit(search='Use Vim', replace='Use Neovim')\nsdk.commit()",
        context,
    )

    # Unknown field access is a no-op: the statement compiles without
    # touching server state and the whole program still commits.
    assert error is None
    assert operations is not None
    assert operations.preferences == []


def test_python_unknown_field_does_not_block_sibling_updates():
    uri = "viking://user/alice/memories/preferences/editor.md"
    context = _context(
        [_preference_schema()],
        files=[_existing_preference(uri, "editor", "Use Vim", 0)],
    )
    protocol = create_extraction_output_protocol("python")
    _bind(protocol, context)

    operations, error = protocol.parse(
        """
preferences_1.bogus.update("ignored")
preferences_1.bogus.edit(search="Use Vim", replace="Use Neovim")
preferences_1.bogus.drop(text="Tabs")
preferences_1.content.edit(search="Use Vim", replace="Use Neovim")
sdk.commit()
""",
        context,
    )

    assert error is None
    item = operations.model_dump()["preferences"][0]
    # The bogus field is silently dropped; the real content edit still applies.
    assert item["content"]["blocks"] == [
        {"search": "Use Vim", "replace": "Use Neovim"},
    ]


def test_python_field_edit_emits_block_regardless_of_uniqueness():
    # Uniqueness enforcement now lives in the shared validation path, so parse()
    # just emits the block; matching (and any non-unique rejection) happens later.
    uri = "viking://user/alice/memories/preferences/editor.md"
    context = _context(
        [_preference_schema()],
        files=[_existing_preference(uri, "editor", "Use Vim\nUse Vim", 0)],
    )
    protocol = create_extraction_output_protocol("python")
    _bind(protocol, context)

    operations, error = protocol.parse(
        "preferences_1.content.edit(search='Use Vim', replace='Use Neovim')\nsdk.commit()",
        context,
    )

    assert error is None
    blocks = operations.model_dump()["preferences"][0]["content"]["blocks"]
    assert blocks == [{"search": "Use Vim", "replace": "Use Neovim"}]


@pytest.mark.parametrize(
    "operation",
    [
        "preferences_1.content.edit(search='Use Vim', replace='Use Neovim')",
        "preferences_1.content.drop(text='Dark theme')",
    ],
)
def test_python_field_edit_and_drop_are_standalone_statements(operation: str):
    uri = "viking://user/alice/memories/preferences/editor.md"
    context = _context(
        [_preference_schema()],
        files=[_existing_preference(uri, "editor", "Use Vim\nDark theme")],
    )
    protocol = create_extraction_output_protocol("python")
    _bind(protocol, context)

    operations, error = protocol.parse(f"x = {operation}\nsdk.commit()", context)

    assert operations is None
    assert "must be standalone statements" in error


def test_python_delete_replacement_and_links_compile_with_page_id_remapping():
    duplicate = _existing_preference(
        "viking://user/alice/memories/preferences/duplicate.md",
        "duplicate",
        "duplicate content",
    )
    project = MemoryFile(
        uri="viking://user/alice/memories/projects/openviking.md",
        memory_type="projects",
        content="Memory platform",
        extra_fields={"name": "openviking"},
    )
    context = _context(
        [_preference_schema(), _project_schema()],
        files=[duplicate, project],
        link_enabled=True,
    )
    protocol = create_extraction_output_protocol("python")
    _bind(protocol, context)

    operations, error = protocol.parse(
        """
canonical = sdk.create_preferences(topic="editor", content="Use Neovim", score=1)
preferences_1.link(projects_1, match_text="editor")
preferences_1.delete(replacement=canonical)
sdk.commit()
""",
        context,
    )

    assert error is None
    payload = operations.model_dump()
    assert payload["preferences"] == [
        {"page_id": 100, "topic": "editor", "content": "Use Neovim", "score": 1}
    ]
    assert payload["delete_ids"] == [{"delete_page_id": 1, "replacement_page_id": 100}]
    assert payload["links"] == [
        {
            "f": 100,
            "t": 2,
            "link_type": "related_to",
            "weight": 0.5,
            "match_text": "editor",
            "description": "",
        }
    ]


def test_python_update_after_delete_restores_object_and_delete_after_update_discards_update():
    first = _existing_preference(
        "viking://user/alice/memories/preferences/first.md", "first", "old one"
    )
    second = _existing_preference(
        "viking://user/alice/memories/preferences/second.md", "second", "old two"
    )
    context = _context([_preference_schema()], files=[first, second])
    protocol = create_extraction_output_protocol("python")
    _bind(protocol, context)

    operations, error = protocol.parse(
        """
preferences_1.delete()
preferences_1.update(content="restored")
preferences_2.update(content="discarded")
preferences_2.delete()
preferences_1.link(preferences_2) if False else None
sdk.commit()
""",
        context,
    )

    assert error is not None
    assert operations is None

    operations, error = protocol.parse(
        """
preferences_1.delete()
preferences_1.update(content="restored")
preferences_2.update(content="discarded")
preferences_2.delete()
sdk.commit()
""",
        context,
    )
    assert error is None
    payload = operations.model_dump()
    assert payload["preferences"] == [
        {"page_id": 1, "topic": "first", "content": "restored", "score": None}
    ]
    assert payload["delete_ids"] == [{"delete_page_id": 2, "replacement_page_id": None}]


@pytest.mark.parametrize(
    ("program", "message"),
    [
        ("sdk.commit()\nsdk.commit()", "final statement"),
        ("for item in []:\n    pass\nsdk.commit()", "only assignments"),
        ("sdk.existing(memory_type='preferences')\nsdk.commit()", "reserved"),
        ("sdk.create_preferences(topic='x', content='y')\nsdk.commit()", "missing: score"),
        (
            "x = sdk.create_preferences(topic='x', content='y', score=1)\nx.delete()\nsdk.commit()",
            "cannot be deleted",
        ),
        (
            "obj = sdk.create_preferences(topic='x', content='y', score=1)\n"
            "obj.content.edit(search='y', replace='z')\nsdk.commit()",
            "can only patch an existing memory",
        ),
        (
            "sdk.replace(search='x', replacement='y')\nsdk.commit()",
            "unknown SDK method sdk.replace()",
        ),
        (
            "x = sdk.create_preferences(topic='x', content='y', score=1)\n"
            "x.content.update('a', 'b')\nsdk.commit()",
            "exactly one positional argument",
        ),
        (
            "x = sdk.create_preferences(topic='x', content='y', score=1)\nstr(x)\nsdk.commit()",
            "memory objects cannot be converted",
        ),
        (
            "x = sdk.create_preferences(topic='x', content='y', score=1)\nitems = [x]\nsdk.commit()",
            "memory objects cannot be stored",
        ),
        (
            "x = sdk.create_preferences(topic='x', content='y', score=1)\ntext = f'{x}'\nsdk.commit()",
            "memory objects cannot be formatted",
        ),
        (
            "x = sdk.create_preferences(topic='x', content='y', score=1)\nx.update(content=x)\nsdk.commit()",
            "memory objects cannot be used as business field values",
        ),
        (
            "sdk.create_preferences(topic='x', content='y', score=1).update(content='z')\nsdk.commit()",
            "assign a new memory object",
        ),
        ("import os\nsdk.commit()", "only assignments"),
        ("sdk.commit()\nprint('after')", "final statement"),
    ],
)
def test_python_rejects_invalid_or_unsafe_programs(program: str, message: str):
    context = _context([_preference_schema()])
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse(program, context)

    assert operations is None
    assert message in error


def test_python_rejects_delete_for_add_only_schema():
    memory_file = _existing_preference(
        "viking://user/alice/memories/preferences/editor.md", "editor", "Use Vim"
    )
    context = _context([_preference_schema(operation_mode="add_only")], files=[memory_file])
    protocol = create_extraction_output_protocol("python")
    _bind(protocol, context)

    operations, error = protocol.parse("preferences_1.delete()\nsdk.commit()", context)

    assert operations is None
    assert "delete() is unavailable" in error


def test_python_rejects_add_only_delete_when_another_schema_enables_deletes():
    memory_file = _existing_preference(
        "viking://user/alice/memories/preferences/editor.md", "editor", "Use Vim"
    )
    context = _context(
        [_preference_schema(operation_mode="add_only"), _project_schema()],
        files=[memory_file],
    )
    protocol = create_extraction_output_protocol("python")
    _bind(protocol, context)

    operations, error = protocol.parse("preferences_1.delete()\nsdk.commit()", context)

    assert operations is None
    assert "delete() is unavailable" in error


def test_python_aliases_non_identifier_memory_type_instead_of_raising():
    schema = _preference_schema()
    schema.memory_type = "user-preferences"
    context = _context([schema])
    protocol = create_extraction_output_protocol("python")

    contract = protocol.render_contract(context)
    assert "sdk.set_user_preferences(" in contract or "sdk.create_user_preferences(" in contract
    assert "user-preferences" not in contract.split("Memory type rules")[0]


def test_python_accepts_one_fence_with_surrounding_text():
    context = _context([_preference_schema()])
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse("```python\nsdk.commit()\n```", context)
    assert error is None
    assert operations.model_dump() == {"preferences": [], "delete_ids": []}

    operations, error = protocol.parse("Explanation\n```python\nsdk.commit()\n```", context)
    assert error is None
    assert operations.model_dump() == {"preferences": [], "delete_ids": []}


def test_python_accepts_trace_style_explanation_around_program():
    context = _context(
        [_preference_schema()],
        files=[
            _existing_preference(
                "viking://user/alice/memories/preferences/editor.md",
                "editor",
                "Use Vim",
            )
        ],
    )
    protocol = create_extraction_output_protocol("python")
    _bind(protocol, context)

    operations, error = protocol.parse(
        """Update the existing preference.
```python
preferences_1.content.edit(search="Use Vim", replace="Use Neovim")
sdk.commit()
```
The program above applies the requested update.""",
        context,
    )

    assert error is None
    blocks = operations.model_dump()["preferences"][0]["content"]["blocks"]
    assert blocks == [{"search": "Use Vim", "replace": "Use Neovim"}]


@pytest.mark.parametrize(
    ("call", "error_fragment"),
    [
        ("sdk.read('viking://user/alice/memories/preferences/editor.md')", "sdk.read()"),
        ("read('viking://user/alice/memories/preferences/editor.md')", "function 'read'"),
        ("sdk.search('editor')", "sdk.search()"),
        ("search('editor')", "function 'search'"),
    ],
)
def test_python_read_search_errors_keep_native_tools_available_for_retry(
    call: str, error_fragment: str
):
    protocol = create_extraction_output_protocol("python")
    context = _context([_preference_schema()])

    operations, error = protocol.parse(
        f"item = {call}\nsdk.commit()",
        context,
    )

    assert operations is None
    assert error_fragment in error
    assert protocol.keep_tools_enabled_after_parse_error(error)
    retry = protocol.render_format_retry(error)
    assert "native read tool" in retry
    assert "Do not emit sdk.search(), sdk.read()" in retry


def test_python_sdk_read_error_takes_priority_over_reassigning_existing_binding():
    uri = "viking://user/alice/memories/preferences/editor.md"
    context = _context(
        [_preference_schema()],
        files=[_existing_preference(uri, "editor", "Use Vim")],
    )
    protocol = create_extraction_output_protocol("python")
    _bind(protocol, context)

    operations, error = protocol.parse(f"preferences_1 = sdk.read({uri!r})\nsdk.commit()", context)

    assert operations is None
    assert "unknown SDK method sdk.read()" in error
    assert protocol.keep_tools_enabled_after_parse_error(error)


def test_python_object_read_error_keeps_native_tools_available_for_retry():
    uri = "viking://user/alice/memories/preferences/editor.md"
    context = _context(
        [_preference_schema()],
        files=[_existing_preference(uri, "editor", "Use Vim")],
    )
    protocol = create_extraction_output_protocol("python")
    _bind(protocol, context)

    operations, error = protocol.parse("preferences_1.read()\nsdk.commit()", context)

    assert operations is None
    assert "unknown memory method read()" in error
    assert protocol.keep_tools_enabled_after_parse_error(error)


@pytest.mark.parametrize(
    "program",
    [
        "```python\nsdk.commit()\n```\n```python\nsdk.commit()\n```",
        "Explanation\n```python\nsdk.commit()\n```\n```text\nextra\n```",
    ],
)
def test_python_rejects_multiple_fences(program: str):
    context = _context([_preference_schema()])
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse(program, context)
    assert operations is None
    assert "only one complete" in error


@pytest.mark.parametrize(
    "program",
    [
        "```python\nsdk.commit()```",
        "```python\nsdk.commit()",
        "Explanation\n```python\nsdk.commit()",
    ],
)
def test_python_accepts_single_recoverable_fence_variants(program: str):
    context = _context([_preference_schema()])
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse(program, context)

    assert error is None
    assert operations.model_dump() == {"preferences": [], "delete_ids": []}


def test_python_unclosed_fence_still_rejects_truncated_python():
    context = _context([_preference_schema()])
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse("```python\npreferences_1.update(", context)

    assert operations is None
    assert "invalid Python syntax" in error


def test_python_rejects_bare_markdown_with_actionable_error():
    context = _context([_preference_schema()])
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse(
        "# Caroline\n- Transgender woman (as of 2023-06-09)", context
    )

    assert operations is None
    assert "bare Markdown, not a Python SDK program" in error
    assert "leading zeros" not in error
    retry = protocol.render_format_retry(error)
    assert "Markdown memory content inside quoted SDK arguments" in retry


def test_python_accepts_update_only_program_with_markdown_content():
    # A valid program that only uses obj.update() (no literal "sdk." token) and
    # embeds Markdown bullets in a triple-quoted string must not be mistaken for
    # bare Markdown just because a comment starts with "# " and bullets appear.
    uri = "viking://user/alice/memories/preferences/editor.md"
    context = _context(
        [_preference_schema()],
        files=[_existing_preference(uri, "editor", "# Editor\n- Use Vim")],
    )
    protocol = create_extraction_output_protocol("python")
    _bind(protocol, context)

    program = (
        "# Merge updates to the editor preference\n"
        'preferences_1.update(content="""# Editor\n'
        "A friend of Dave's who is involved in music.\n"
        "## Key Facts\n"
        "- Enjoys Japanese culture (as of 2023-10-19)\n"
        "- Relaxes by taking long walks\n"
        '""")'
    )

    operations, error = protocol.parse(program, context)

    assert error is None
    assert "# Editor" in operations.model_dump()["preferences"][0]["content"]


def test_python_rejects_huge_string_multiplication_before_allocation():
    context = _context([_profile_schema()])
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse(
        'sdk.set_profile(content="x" * 1_000_000_000)\nsdk.commit()',
        context,
    )

    assert operations is None
    assert "size limit" in error


def test_python_rejects_huge_string_multiplication_reversed_operands():
    context = _context([_profile_schema()])
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse(
        'sdk.set_profile(content=1_000_000_000 * "x")\nsdk.commit()',
        context,
    )

    assert operations is None
    assert "size limit" in error


def test_python_allows_small_string_repetition():
    context = _context([_profile_schema()])
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse(
        "sdk.set_profile(content='ab' * 3)\nsdk.commit()",
        context,
    )

    assert error is None
    assert operations.model_dump()["profile"][0]["content"] == "ababab"


def test_python_rejects_multiplication_between_two_non_literals():
    context = _context([_preference_schema()])
    protocol = create_extraction_output_protocol("python")

    # Multiplying a non-literal local value by a non-literal local value has
    # no bounded literal to repeat and must not be evaluated.
    operations, error = protocol.parse(
        "a = 'ab'\nn = 3\nsdk.create_preferences(topic='x', score=1, content=a * n)\nsdk.commit()",
        context,
    )

    assert operations is None
    assert "multiplication is only supported" in error


def test_python_rejects_numeric_multiplication():
    context = _context([_profile_schema()])
    protocol = create_extraction_output_protocol("python")

    # Number * number cannot repeat a literal and is useless for memory content.
    operations, error = protocol.parse(
        "sdk.set_profile(content=str(2 * 3))\nsdk.commit()",
        context,
    )

    assert operations is None
    assert "multiplication is only supported" in error


def test_python_rejects_huge_join_before_allocation():
    context = _context([_profile_schema()])
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse(
        'sdk.set_profile(content="".join(["xxxxxxxxxx"] * 200_000))\nsdk.commit()',
        context,
    )

    assert operations is None
    assert "size limit" in error


def test_python_rejects_huge_replace_before_allocation():
    context = _context([_profile_schema()])
    protocol = create_extraction_output_protocol("python")

    # 'x' occurs 1000 times; replacing each with a 10000-char string would
    # inflate the result to ~10MB. The projected-size check must reject it
    # before str.replace builds the string.
    operations, error = protocol.parse(
        'sdk.set_profile(content=("x" * 1000).replace("x", "y" * 10000))\nsdk.commit()',
        context,
    )

    assert operations is None
    assert "size limit" in error


def test_python_allows_small_replace():
    context = _context([_profile_schema()])
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse(
        'sdk.set_profile(content="a-b-c".replace("-", " "))\nsdk.commit()',
        context,
    )

    assert error is None
    assert operations.model_dump()["profile"][0]["content"] == "a b c"


def test_python_rejects_fstring_width_format_spec():
    context = _context([_profile_schema()])
    protocol = create_extraction_output_protocol("python")

    # A width format spec turns a small integer literal into a huge padded string
    # with no repeat operator; format specs are disallowed.
    operations, error = protocol.parse(
        "sdk.set_profile(content=f\"{'x':>1000001}\")\nsdk.commit()",
        context,
    )

    assert operations is None
    assert "format spec" in error


def test_python_allows_plain_fstring():
    context = _context([_profile_schema()])
    protocol = create_extraction_output_protocol("python")

    operations, error = protocol.parse(
        'name = "Ada"\nsdk.set_profile(content=f"# {name}")\nsdk.commit()',
        context,
    )

    assert error is None
    assert operations.model_dump()["profile"][0]["content"] == "# Ada"


def test_python_rejects_string_percent_formatting():
    context = _context([_profile_schema()])
    protocol = create_extraction_output_protocol("python")

    # "%1000001s" % "x" pads to ~1M chars via a width field, no repeat operator.
    operations, error = protocol.parse(
        'sdk.set_profile(content="%1000001s" % "x")\nsdk.commit()',
        context,
    )

    assert operations is None
    assert "%-formatting is not allowed" in error