diff --git a/alembic/versions/0108_trigger_leaves_the_stored_title.py b/alembic/versions/0108_trigger_leaves_the_stored_title.py new file mode 100644 index 0000000..869d04c --- /dev/null +++ b/alembic/versions/0108_trigger_leaves_the_stored_title.py @@ -0,0 +1,64 @@ +"""trigger_leaves_the_stored_title — a snippet's and lesson's title is its name (milestone 427) + +Revision ID: 0108 +Revises: 0107 +Create Date: 2026-09-23 + +Snippets and lessons stored their title as `subject — trigger`, because the +join is what makes these kinds rank on the situation they apply to (#2485) and +the stored title WAS the embedded one. Every surface that shows a title then +showed the trigger too: menu lines, lists and search rows ran to 1,500–3,000 +characters, and an injected repeat spent all of it again. + +The trigger's home is `data` (decision #4157), and since this milestone the +join happens at embed time (`embeddings.document_title`). This revision +rewrites the rows already stored. + +EXACT-SUFFIX, READ FROM THE ROW'S OWN MIRROR. A title is only rewritten when +it ends with `' — ' || `, so a subject that legitimately +contains an em dash is never cut, and a row whose title and mirror disagree — +hand-edited through the generic note door — is left alone. Such a row still +embeds correctly (`document_title` is idempotent) and merely shows its old +title; that is the right way round for a data migration to fail. + +NO RE-EMBED, AND `updated_at` IS NOT TOUCHED. The embedded text is identical +before and after, so the vectors are already right. The startup backfill +re-embeds any row whose `updated_at` is newer than its vectors, and a raw +UPDATE that leaves `updated_at` alone is what keeps this from queueing the +whole snippet corpus for work that would produce the same numbers. There is +no database trigger on `updated_at`; it is set by the ORM only. +""" +from alembic import op + +revision = "0108" +down_revision = "0107" +branch_labels = None +depends_on = None + +# kind → the `data` key its trigger is mirrored under (embeddings._TRIGGER_DATA_KEYS). +_KINDS = (("snippet", "when_to_use"), ("lesson", "when_to_apply")) +_SEP = " — " + + +def upgrade() -> None: + for note_type, key in _KINDS: + op.execute(f""" + UPDATE notes + SET title = btrim(left(title, length(title) - length('{_SEP}' || (data->>'{key}')))) + WHERE note_type = '{note_type}' + AND coalesce(btrim(data->>'{key}'), '') <> '' + AND right(title, length('{_SEP}' || (data->>'{key}'))) = '{_SEP}' || (data->>'{key}') + """) + + +def downgrade() -> None: + # Recompose, on the same condition inverted: only where the trigger is not + # already on the end, so a downgrade run twice cannot double it. + for note_type, key in _KINDS: + op.execute(f""" + UPDATE notes + SET title = title || '{_SEP}' || (data->>'{key}') + WHERE note_type = '{note_type}' + AND coalesce(btrim(data->>'{key}'), '') <> '' + AND right(title, length('{_SEP}' || (data->>'{key}'))) <> '{_SEP}' || (data->>'{key}') + """) diff --git a/frontend/src/api/snippets.ts b/frontend/src/api/snippets.ts index 0931e14..95274a8 100644 --- a/frontend/src/api/snippets.ts +++ b/frontend/src/api/snippets.ts @@ -91,6 +91,9 @@ export interface SnippetListItem { * hit can be flagged as being in a DIFFERENT language than the file being * written, which is a shape to adapt rather than code to paste. */ language?: string; + /** When to reach for it, projected from the `data` mirror. The title is the + * name alone since milestone 427, so this is where the situation lives. */ + when_to_use?: string; /** Always present from the backend, zero-filled for records with no events. */ usage?: SnippetUsage; /** Present on the detail record; the list feed carries it when a check has diff --git a/frontend/src/views/SnippetListView.vue b/frontend/src/views/SnippetListView.vue index 599448c..660d090 100644 --- a/frontend/src/views/SnippetListView.vue +++ b/frontend/src/views/SnippetListView.vue @@ -189,11 +189,18 @@ const onLocationInput = onSearchInput; onMounted(loadSnippets); -/** Titles are stored as "name — when to reach for it"; split for display. */ -function splitTitle(title: string): { name: string; when: string } { - const idx = title.indexOf(" — "); - if (idx === -1) return { name: title, when: "" }; - return { name: title.slice(0, idx), when: title.slice(idx + 3) }; +/** A row's name and when-to-use. The title is the name alone since milestone + * 427 and the situation arrives as `when_to_use`; a title composed before then + * ("name — when to reach for it") is split, so either shape reads the same. */ +function nameAndWhen(s: { title: string; when_to_use?: string }): { name: string; when: string } { + const when = s.when_to_use || ""; + if (when && s.title.endsWith(` — ${when}`)) { + return { name: s.title.slice(0, -(when.length + 3)), when }; + } + if (when) return { name: s.title, when }; + const idx = s.title.indexOf(" — "); + if (idx === -1) return { name: s.title, when: "" }; + return { name: s.title.slice(0, idx), when: s.title.slice(idx + 3) }; } function languageOf(tags: string[]): string { @@ -313,7 +320,7 @@ function driftTitle(s: SnippetListItem): string {
- {{ splitTitle(s.title).name }} + {{ nameAndWhen(s).name }}
{{ Math.round(g.top_score * 100) }}% alike @@ -413,11 +420,11 @@ function driftTitle(s: SnippetListItem): string { :class="{ on: selectedIds.has(s.id) }" aria-hidden="true" > - {{ splitTitle(s.title).name }} + {{ nameAndWhen(s).name }} {{ languageOf(s.tags) }}
-

- {{ splitTitle(s.title).when }} +

+ {{ nameAndWhen(s).when }}

Updated {{ new Date(s.updated_at).toLocaleDateString() }} @@ -458,7 +465,7 @@ function driftTitle(s: SnippetListItem): string { :class="{ chosen: canonicalId === s.id }" > - {{ splitTitle(s.title).name }} + {{ nameAndWhen(s).name }} {{ canonicalId === s.id ? "keep" : "fold in" }}
diff --git a/src/scribe/mcp/tools/lessons.py b/src/scribe/mcp/tools/lessons.py index 24d46c9..0a35b1f 100644 --- a/src/scribe/mcp/tools/lessons.py +++ b/src/scribe/mcp/tools/lessons.py @@ -168,6 +168,7 @@ async def create_lesson( dup = await dedup_svc.find_duplicate_note( uid, title, body, project_id=project_id or None, is_task=False, note_type=lessons_svc.LESSON_NOTE_TYPE, + data=lessons_svc.compose_data(what, when_to_apply), ) if dup is not None: return dedup_svc.duplicate_response(dup, "lesson") diff --git a/src/scribe/mcp/tools/snippets.py b/src/scribe/mcp/tools/snippets.py index f9a0b47..3b5b4b9 100644 --- a/src/scribe/mcp/tools/snippets.py +++ b/src/scribe/mcp/tools/snippets.py @@ -176,7 +176,9 @@ async def create_snippet( raise ValueError("create_snippet requires a non-empty name and code") uid = current_user_id() - title = snippets_svc.compose_title(name, when_to_use) + # The NAME is the title (milestone 427); the trigger rides in `data` and + # joins the title only in the embedded document. + title = name.strip() body = snippets_svc.compose_body( code=code, language=language, signature=signature, when_to_use=when_to_use, repo=repo, path=path, symbol=symbol, @@ -190,6 +192,7 @@ async def create_snippet( # location and code before it compares prose (#2518). code=code, locations=snippets_svc.resolve_locations(repo, path, symbol, locations), + data=snippets_svc.compose_data(name=name, when_to_use=when_to_use), ) if dup is not None: return dedup_svc.duplicate_response(dup, "snippet") diff --git a/src/scribe/routes/lessons.py b/src/scribe/routes/lessons.py index 9137796..c9241a3 100644 --- a/src/scribe/routes/lessons.py +++ b/src/scribe/routes/lessons.py @@ -149,6 +149,7 @@ async def create_lesson_route(): project_id=project_id, is_task=False, note_type=lessons_svc.LESSON_NOTE_TYPE, + data=lessons_svc.compose_data(what, when_to_apply), ) if dup is not None: return jsonify(dedup_svc.duplicate_response(dup, "lesson")), 409 diff --git a/src/scribe/routes/snippets.py b/src/scribe/routes/snippets.py index 585d803..e748b94 100644 --- a/src/scribe/routes/snippets.py +++ b/src/scribe/routes/snippets.py @@ -96,7 +96,7 @@ async def create_snippet_route(): if not data.get("force"): dup = await dedup_svc.find_duplicate_note( uid, - snippets_svc.compose_title(name, data.get("when_to_use", "")), + name.strip(), snippets_svc.compose_body( code=data.get("code", ""), language=data.get("language", ""), @@ -119,6 +119,9 @@ async def create_snippet_route(): data.get("repo", ""), data.get("path", ""), data.get("symbol", ""), data.get("locations"), ), + data=snippets_svc.compose_data( + name=name, when_to_use=data.get("when_to_use", ""), + ), ) if dup is not None: return jsonify(dedup_svc.duplicate_response(dup, "snippet")), 409 diff --git a/src/scribe/services/dedup.py b/src/scribe/services/dedup.py index 90101e6..f03ef70 100644 --- a/src/scribe/services/dedup.py +++ b/src/scribe/services/dedup.py @@ -248,6 +248,7 @@ async def find_duplicate_note( note_type: str = "note", code: str = "", locations: list[dict] | None = None, + data: dict | None = None, ) -> DuplicateMatch | None: """Best near-duplicate of (title, body) within the same owner + project + kind, or None. Title match first (cheap, exact), then — for snippets — the @@ -258,6 +259,11 @@ async def find_duplicate_note( `code` and `locations` are the snippet's structured fields. They are ignored for every other kind, and passing them is what lets the gate compare ARTEFACTS rather than descriptions of artefacts (#2518). + + `data` is the candidate's structured mirror. For a snippet or lesson it + carries the trigger, which the TITLE no longer does (milestone 427): the + title check compares names, and the semantic check rebuilds the embedded + document from `data`. """ norm = " ".join((title or "").split()).lower() @@ -309,7 +315,11 @@ async def find_duplicate_note( # section. Capped so one pathological paste can't turn a save into # dozens of searches — a duplicate past the cap is the duplicate # report's job, not the gate's. - for query in embeddings_svc.chunk_document(title, body)[:_GATE_MAX_CHUNKS]: + # The EMBEDDED title (milestone 427): a snippet or lesson is stored + # under its name and embedded under `name — trigger`, so the query + # document is built the way the corpus was, from `data`. + doc_title = embeddings_svc.document_title(title, note_type, data, body) + for query in embeddings_svc.chunk_document(doc_title, body)[:_GATE_MAX_CHUNKS]: # Scope the semantic check the same way as the title check: a record # in project P compares only to P; a project-less (orphan) record # compares only to other orphans (orphan_only), NOT across every diff --git a/src/scribe/services/embeddings.py b/src/scribe/services/embeddings.py index 1361c18..fe1675e 100644 --- a/src/scribe/services/embeddings.py +++ b/src/scribe/services/embeddings.py @@ -214,10 +214,12 @@ TRIGGER_SEP = " — " def trigger_title(subject: str | None, trigger: str | None) -> str: """`{subject} — {trigger}` — the title half of a situation-keyed document. - ONE definition, because this join had three. `rule_document` built it for - rules, `snippets.compose_title` for snippets, and milestone 385 needed a - fourth for lessons — the shape #3207 records, where a fix or an improvement - then has to be found in N places by someone who does not know N. + ONE definition, because this join had three — rules, snippets, and a + fourth for lessons (milestone 385) — the shape #3207 records, where a fix + or an improvement then has to be found in N places by someone who does not + know N. Since milestone 427 it builds EMBEDDED titles only: `rule_document` + for rules and `document_title` for snippets and lessons. No stored title + carries it. WHY THE JOIN MATTERS AT ALL, measured in note #2485: the snippet was the only sharp record in the corpus — a 0.153 top-to-second gap against @@ -265,6 +267,51 @@ def untrigger_title(title: str | None, trigger: str | None) -> str: return title +# The `data` key each trigger-keyed note kind mirrors its trigger under. Rules +# are not here: they keep the trigger in a column and `rule_document` builds +# their document from it. +_TRIGGER_DATA_KEYS = {"snippet": "when_to_use", "lesson": "when_to_apply"} + + +def document_title( + title: str | None, note_type: str | None, data: dict | None = None, + body: str | None = None, +) -> str | None: + """The title a note is EMBEDDED under — its stored title, plus its trigger. + + Milestone 427. A snippet's or lesson's STORED title is its subject alone; + the trigger lives in `data` (decision #4157). It still has to reach the + vector — the `subject — trigger` join is what makes these kinds rank on + the situation they apply to (#2485) — so it is joined HERE, at embed time, + rather than being carried in a title every listing then has to show. + + IDEMPOTENT, and that is what makes the migration safe: a title that is + already composed (a row not yet migrated, an old backup restored) is + untriggered first, so it comes out the same and never doubled. The text is + byte-identical to what these kinds were embedded as before, so no vector + moves and the floors tuned against them stay calibrated. + + `body` is the fallback when the mirror is missing, read by the kind's own + parser — the same degrade-to-the-body each kind's reader already has. + Every other kind, and a record with no trigger, keeps its title as-is. + """ + key = _TRIGGER_DATA_KEYS.get(note_type or "") + if key is None: + return title + trigger = ((data or {}).get(key) or "").strip() if isinstance(data, dict) else "" + if not trigger and body: + from types import SimpleNamespace + if note_type == "lesson": + from scribe.services.lessons import lesson_trigger + trigger = lesson_trigger(SimpleNamespace(data=None, body=body)) + else: + from scribe.services.snippets import parse_snippet_fields + trigger = parse_snippet_fields(title or "", body).get("when_to_use", "") + if not trigger: + return title + return trigger_title(untrigger_title(title, trigger), trigger) + + # --- chunking (#280): the document shape ------------------------------------ # # bge-small reads at most 512 tokens and fastembed silently truncates the rest, @@ -1081,10 +1128,14 @@ async def backfill_note_embeddings() -> None: ) success = 0 for note_id in notes_to_embed: - row = await _current_row((Note.user_id, Note.title, Note.body), Note.id, note_id) + row = await _current_row( + (Note.user_id, Note.title, Note.body, Note.note_type, Note.data), Note.id, note_id, + ) if row is None: continue # deleted between the scan and here - user_id, title, body = row + user_id, title, body, note_type, data = row + # The EMBEDDED title, as the write path builds it (milestone 427). + title = document_title(title, note_type, data, body) if not chunk_document(title, body): continue await upsert_note_embedding(note_id, user_id, title, body) diff --git a/src/scribe/services/knowledge.py b/src/scribe/services/knowledge.py index efb0ea8..05a311e 100644 --- a/src/scribe/services/knowledge.py +++ b/src/scribe/services/knowledge.py @@ -267,6 +267,11 @@ def _note_to_item(note: Note, chunks: dict[int, dict] | None = None) -> dict: trigger = (note.data or {}).get("when_to_apply") if note.data else None if trigger: item["when_to_apply"] = trigger + # A snippet's, for the same reason — and since milestone 427 the title no + # longer carries it, so without this a list shows names with no situation. + usage = (note.data or {}).get("when_to_use") if note.data else None + if usage: + item["when_to_use"] = usage verdict = (note.data or {}).get("verification") if note.data else None if verdict and verdict.get("status"): diff --git a/src/scribe/services/lessons.py b/src/scribe/services/lessons.py index 0f8080f..9a5a5bd 100644 --- a/src/scribe/services/lessons.py +++ b/src/scribe/services/lessons.py @@ -26,20 +26,23 @@ while staying a note in every other respect. WHERE THE TRIGGER LIVES (decision #4157, milestone 385 step 1) In ``notes.data`` under ``when_to_apply``, written through a named parameter and -mirrored into the title and the head of the body — the shape snippets already -use for ``when_to_use``. Not a column on ``notes``. +mirrored into the head of the body — the shape snippets already use for +``when_to_use``. Not a column on ``notes``. Since milestone 427 it is NOT in the +stored title: the title is the lesson's subject, and the trigger joins it only +in the embedded document (``embeddings.document_title``). That decision was measured rather than assumed. The whole snippet corpus — 164 of 164 — carries a ``when_to_use`` with **no guard anywhere**, which refutes the premise that an unenforced field gets skipped. What it does NOT show is that -an agent types a title convention correctly: ``compose_title`` builds the title +an agent types a title convention correctly: the service composed the title from the parameter, so what is at 100% is a named structured field. A column would have bought enforceability at the price of deciding, for every note kind at once, a question nothing had measured. -The mirror is what makes the vector sharp, and it is why nothing re-embeds: -``chunk_document`` is untouched, so ``CHUNKER_VERSION`` does not move. The -trigger reaches the document by being in the text, exactly as a snippet's is. +The trigger in the document is what makes the vector sharp. It reaches it +twice — in the embedded title, joined at embed time, and in the body's first +line — which is the text these kinds were always embedded as, so nothing +re-embeds and ``CHUNKER_VERSION`` does not move. WHAT A LESSON INHERITS, AND THE CELLS LEFT EMPTY ON PURPOSE (#3163) @@ -207,36 +210,17 @@ def sole_source(sources: list[int] | None) -> int | None: return ids[0] if len(ids) == 1 else None -def compose_title(what: str, when_to_apply: str = "") -> str: - """`{what} — {when it applies}`, the half of the document that ranks. - - Built HERE rather than asked of the caller, and that distinction is the - whole evidence base for this design: the snippet corpus is at 100% on its - trigger because a service composes the title from a named parameter, not - because agents type separators reliably. A caller made to spell the - convention is the option milestone 385 step 1 rejected. - - The join is `embeddings.trigger_title` — shared with rules and snippets, so - the three kinds that rank on a trigger cannot drift apart in how they say - so. - """ - from scribe.services.embeddings import trigger_title - - return trigger_title(what, when_to_apply) - - def compose_body( insight: str, when_to_apply: str = "", learned_from: list[int] | None = None, ) -> str: """The lesson body — the trigger line first, the insight after. - The mirror of `compose_title` on the other half of the document, and the - reason the pair is what makes a lesson findable: `chunk_document` joins - them as `{title}\\n{body}`, so a lesson composed here states WHEN IT - APPLIES in the title and again in the first line of the body. That is the - twice-in-a-short-document shape note #2485 measured as the only sharp one - in the corpus, reached the way a snippet reaches it — by being in the text - — rather than by a second document builder at embed time. + The trigger's home in the text of the document, and half of what makes a + lesson findable: `chunk_document` joins `{embedded title}\\n{body}`, and + the embedded title is `what — when it applies` (`embeddings.document_title`, + milestone 427), so the document states WHEN IT APPLIES in the title and + again in the first line of the body. That is the twice-in-a-short-document + shape note #2485 measured as the only sharp one in the corpus. `**When to apply:**` rather than plain text: the body is the READABLE form, `data` is the queryable mirror, and `_BODY_TRIGGER_RE` reads this @@ -275,23 +259,23 @@ def lesson_document( what: str, when_to_apply: str = "", insight: str = "", learned_from: list[int] | None = None, ) -> tuple[str, str]: - """The (title, body) a lesson is STORED — and therefore embedded — as. + """The (title, body) a lesson is STORED as. - One call so the two halves cannot be composed apart. A lesson whose title - carried the trigger and whose body did not would embed as an ordinary - note wearing a label, and nothing would report it: the record would look - right in every listing and simply never be retrieved at the moment it - applies. + One call so the two halves cannot be composed apart. The body's first line + carries the trigger; a lesson without it (and without the `data` mirror) + would embed as an ordinary note wearing a label, and nothing would report + it: the record would look right in every listing and simply never be + retrieved at the moment it applies. - Deliberately returns what is STORED, not a separate embed-time shape. - Rules need `rule_document` because a rule keeps its trigger in a column - and its title is a plain name, so the sharp document has to be synthesised - for the ranker and exists nowhere else. A lesson follows the snippet - instead — the stored record IS the sharp document — which is why nothing - re-embeds and `CHUNKER_VERSION` does not move. + The title is the SUBJECT alone (milestone 427). It used to carry the + trigger too, so the stored record was itself the sharp document — and every + listing, menu and search row then showed a title that ran to kilobytes. + The trigger now joins the title at embed time (`embeddings.document_title`, + reading `data`), producing the same text as before, so nothing re-embeds + and `CHUNKER_VERSION` does not move. """ return ( - compose_title(what, when_to_apply), + (what or "").strip(), compose_body(insight, when_to_apply, learned_from), ) diff --git a/src/scribe/services/notes.py b/src/scribe/services/notes.py index 165eaee..fe3c1b6 100644 --- a/src/scribe/services/notes.py +++ b/src/scribe/services/notes.py @@ -115,11 +115,17 @@ def embed_note(note) -> None: try: import asyncio - from scribe.services.embeddings import upsert_note_embedding + from scribe.services.embeddings import document_title, upsert_note_embedding # Chunking and the empty-record gate live inside upsert_note_embedding — - # one path for every writer (#280). + # one path for every writer (#280). The title is the EMBEDDED one: a + # snippet's or lesson's trigger joins its name here, not in the stored + # title (milestone 427). asyncio.create_task( - upsert_note_embedding(note.id, note.user_id, note.title, note.body) + upsert_note_embedding( + note.id, note.user_id, + document_title(note.title, note.note_type, note.data, note.body), + note.body, + ) ) except RuntimeError: pass # no running loop — a sync caller, not a failure diff --git a/src/scribe/services/plugin_context.py b/src/scribe/services/plugin_context.py index 320adcf..cda7e84 100644 --- a/src/scribe/services/plugin_context.py +++ b/src/scribe/services/plugin_context.py @@ -27,7 +27,11 @@ from scribe.services import projects as projects_svc from scribe.services import shape_ledger as shape_ledger_svc from scribe.services import snippets as snippets_svc from scribe.services.access import label_shared_items, owner_names_for -from scribe.services.embeddings import semantic_search_notes, semantic_search_rules +from scribe.services.embeddings import ( + document_title, + semantic_search_notes, + semantic_search_rules, +) from scribe.services.lessons import LESSON_NOTE_TYPE from scribe.services.note_usage import record_surfaced from scribe.services.rule_usage import record_rule_surfaced @@ -88,8 +92,10 @@ def _menu_name(title: str | None, note_type: str | None, data=None, body: str | def _menu_passage(title: str | None, chunk_text: str | None, name: str = "") -> str: """The matched chunk on one line, without the title it was embedded under. - Every chunk is `title\nsection` (`embeddings.embedding_text`), so the title - prefix is stripped exactly. A chunk that WAS only the title — a short + Every chunk is `title\nsection` (`embeddings.embedding_text`), and `title` + here must be the EMBEDDED one (`embeddings.document_title`) — for a snippet + or lesson that is `name — trigger`, not the stored name — so the prefix is + stripped exactly. A chunk that WAS only the title — a short record, or the head chunk of one — matched on the title, and for a trigger-keyed kind the part of it the name line no longer shows is the trigger: that is returned, because it is precisely what matched. @@ -1235,7 +1241,10 @@ async def build_autoinject_hint( # queries and so are not in this search's report. No fallback to the # body's opening: on a menu that would be a line of preamble dressed as # a reason, and a reader cannot tell the two apart once indented alike. - passage = _menu_passage(note.title, (menu_chunks.get(nid) or {}).get("text"), name) + passage = _menu_passage( + document_title(note.title, note.note_type, note.data, note.body), + (menu_chunks.get(nid) or {}).get("text"), name, + ) if passage: lines.append(f"> ↳ {passage}") @@ -2324,6 +2333,10 @@ async def build_write_path_hint( # (#4364): the line is built from facts, not from # re-reading its own marker. "name": _menu_name(note.title, note.note_type, note.data, note.body), + # What its chunks are prefixed with, for stripping. + "doc_title": document_title( + note.title, note.note_type, note.data, note.body, + ), "seen": int(note.id) in excluded, # Carried, not re-read off the rendered marker. The # marker is prose assembled for a human and it already @@ -2510,7 +2523,8 @@ async def build_write_path_hint( if item.get("seen"): continue passage = _menu_passage( - item.get("title"), (wp_chunks.get(int(item["id"])) or {}).get("text"), + item.get("doc_title") or item.get("title"), + (wp_chunks.get(int(item["id"])) or {}).get("text"), item.get("name") or "", ) if passage: diff --git a/src/scribe/services/snippets.py b/src/scribe/services/snippets.py index 2873f5d..fbc4d7a 100644 --- a/src/scribe/services/snippets.py +++ b/src/scribe/services/snippets.py @@ -54,18 +54,6 @@ UNSET: object = object() # --- serialize: structured fields -> note (title/body/tags) ------------------ -def compose_title(name: str, when_to_use: str = "") -> str: - """`name — when to use` (or just `name` when no usage note is given). - - The join itself lives in `embeddings.trigger_title`, which rules and - lessons build their titles from too. Kept as a named function here because - it is this module's public vocabulary and callers say `compose_title`. - """ - from scribe.services.embeddings import trigger_title - - return trigger_title(name, when_to_use) - - def compose_tags(language: str = "", tags: list[str] | None = None) -> list[str]: """Language (lowercased) first, then the `snippet` marker, then caller tags — de-duplicated, order preserved.""" @@ -741,7 +729,7 @@ async def create_snippet( locations = resolve_locations(repo, path, symbol, locations) note = await notes_svc.create_note( user_id, - title=compose_title(name, when_to_use), + title=name.strip(), body=compose_body( code=code, language=language, signature=signature, when_to_use=when_to_use, locations=locations, @@ -898,7 +886,7 @@ async def update_snippet( provenance = cur.get("provenance") fields: dict = { - "title": compose_title(merged["name"], merged["when_to_use"]), + "title": (merged["name"] or "").strip(), "body": compose_body( code=merged["code"], language=merged["language"], signature=merged["signature"], when_to_use=merged["when_to_use"], diff --git a/tests/helpers.py b/tests/helpers.py index f3b6090..54d7271 100644 --- a/tests/helpers.py +++ b/tests/helpers.py @@ -212,10 +212,10 @@ def fake_snippet(**attrs) -> MagicMock: def fake_lesson(**attrs) -> MagicMock: """A stand-in lesson: a note whose `note_type` is what makes it one. - The title carries the trigger because `compose_title` builds it that way — - `{what} — {when it applies}` — so a menu line rendering only the title is - already showing the reader when this lesson applies. Tests that used a bare - title here would be testing a record the product cannot create. + The title is the subject alone and the trigger lives in `data`, because + that is the record the product creates (milestone 427) — the trigger joins + the title only in the embedded document. A default whose title carried the + trigger would be testing a row only an un-migrated database holds. The check fields and `arose_from_id` are explicitly None for the reason `fake_snippet`'s `data` is: `update_note` reads `verify_with` and @@ -223,12 +223,11 @@ def fake_lesson(**attrs) -> MagicMock: auto-created MagicMock attribute is truthy — so a default lesson driven through the update path would take a branch no real record takes. """ - attrs.setdefault( - "title", - "Give absolutely-positioned siblings an explicit stacking order — " - "placing two absolutely-positioned elements in the same area", - ) - attrs.setdefault("data", {"when_to_apply": "two absolute siblings overlap"}) + attrs.setdefault("title", "Give absolutely-positioned siblings an explicit stacking order") + attrs.setdefault("data", { + "what": "Give absolutely-positioned siblings an explicit stacking order", + "when_to_apply": "placing two absolutely-positioned elements in the same area", + }) attrs.setdefault("status", None) attrs.setdefault("arose_from_id", None) attrs.setdefault("verify_with", None) diff --git a/tests/test_backfill_reads_current_text.py b/tests/test_backfill_reads_current_text.py index 999ca5d..6668a2a 100644 --- a/tests/test_backfill_reads_current_text.py +++ b/tests/test_backfill_reads_current_text.py @@ -56,7 +56,7 @@ async def test_the_backfill_embeds_the_text_as_it_is_now_not_as_it_was_scanned() with ( patch.object(emb, "async_session", return_value=_ctx(scan)), patch.object(emb, "_current_row", - AsyncMock(return_value=(42, "T", *edited))), + AsyncMock(return_value=(42, "T", *edited, "note", None))), patch.object(emb, "upsert_note_embedding", AsyncMock()) as upsert, patch.object(emb.asyncio, "sleep", AsyncMock()), ): @@ -75,7 +75,7 @@ async def test_a_record_deleted_between_the_scan_and_the_loop_is_skipped(): with ( patch.object(emb, "async_session", return_value=_ctx(scan)), patch.object(emb, "_current_row", - AsyncMock(side_effect=[None, (42, "T", "body")])), + AsyncMock(side_effect=[None, (42, "T", "body", "note", None)])), patch.object(emb, "upsert_note_embedding", AsyncMock()) as upsert, patch.object(emb.asyncio, "sleep", AsyncMock()), ): @@ -99,7 +99,7 @@ async def test_a_record_whose_text_outran_its_vectors_is_re_embedded(): with ( patch.object(emb, "async_session", return_value=_ctx(scan)), - patch.object(emb, "_current_row", AsyncMock(return_value=(42, "T", "b"))), + patch.object(emb, "_current_row", AsyncMock(return_value=(42, "T", "b", "note", None))), patch.object(emb, "upsert_note_embedding", AsyncMock()) as upsert, patch.object(emb.asyncio, "sleep", AsyncMock()), ): @@ -119,7 +119,7 @@ async def test_a_task_logged_since_its_vectors_is_re_embedded(): with ( patch.object(emb, "async_session", return_value=_ctx(scan)), - patch.object(emb, "_current_row", AsyncMock(return_value=(42, "T", "b"))), + patch.object(emb, "_current_row", AsyncMock(return_value=(42, "T", "b", "note", None))), patch.object(emb, "upsert_note_embedding", AsyncMock()) as upsert, patch.object(emb.asyncio, "sleep", AsyncMock()), ): diff --git a/tests/test_chunking.py b/tests/test_chunking.py index e775119..10d881a 100644 --- a/tests/test_chunking.py +++ b/tests/test_chunking.py @@ -306,7 +306,7 @@ async def test_backfill_reembeds_notes_with_a_stale_chunker_version(): with ( patch.object(emb, "async_session", return_value=ctx), patch.object(emb, "_current_row", - AsyncMock(return_value=(42, "stale-version", "body"))), + AsyncMock(return_value=(42, "stale-version", "body", "note", None))), patch.object(emb, "upsert_note_embedding", AsyncMock()) as upsert, patch.object(emb.asyncio, "sleep", AsyncMock()), ): diff --git a/tests/test_derived_mirror_generic_door.py b/tests/test_derived_mirror_generic_door.py index 7d70e68..95af1c5 100644 --- a/tests/test_derived_mirror_generic_door.py +++ b/tests/test_derived_mirror_generic_door.py @@ -164,11 +164,11 @@ def _lesson_body(trigger, insight="Read the job log.", sources=None): @pytest.mark.asyncio async def test_a_body_write_moves_a_lessons_trigger_with_it(): - from scribe.services.lessons import TRIGGER_KEY, compose_title + from scribe.services.lessons import TRIGGER_KEY what = "Read the job log before waiting longer" note = fake_lesson( - title=compose_title(what, NEW_TRIGGER), + title=what, data={TRIGGER_KEY: "a CI run is slow", "what": what}, project_id=None, ) @@ -183,13 +183,16 @@ async def test_a_body_write_moves_a_lessons_trigger_with_it(): @pytest.mark.asyncio async def test_a_subject_containing_an_em_dash_still_splits(): """Why `untrigger_title` is given the trigger instead of splitting on the - separator: a subject may legitimately contain one.""" - from scribe.services.lessons import TRIGGER_KEY, compose_title + separator: a subject may legitimately contain one. The title here is an + UN-MIGRATED one, still carrying its trigger (milestone 427), because that + is the row the inverse still has to read correctly.""" + from scribe.services.embeddings import trigger_title + from scribe.services.lessons import TRIGGER_KEY what = "A wait with no deadline — the shape, not the symptom" trigger = "you are about to await something crossing a process boundary" note = fake_lesson( - title=compose_title(what, trigger), data=None, project_id=None, + title=trigger_title(what, trigger), data=None, project_id=None, ) await _update(note, body=_lesson_body(trigger)) assert note.data["what"] == what @@ -202,10 +205,10 @@ async def test_dropping_the_provenance_line_drops_it_from_the_mirror(): the failure this recompose exists to prevent, not a courtesy — the opposite call from a snippet's `verification`, which is carried because it was never in the body to delete.""" - from scribe.services.lessons import SOURCES_KEY, compose_title + from scribe.services.lessons import SOURCES_KEY note = fake_lesson( - title=compose_title("Something learned", "a situation"), + title="Something learned", data={SOURCES_KEY: [999]}, project_id=None, ) @@ -229,7 +232,7 @@ async def test_an_explicit_data_wins_for_a_lesson_too(): async def test_a_lesson_title_change_reaches_the_mirror(): """A lesson's subject lives in its title, so a title edit is a trigger for recomposition exactly as it is for a snippet's name.""" - from scribe.services.lessons import TRIGGER_KEY, compose_title + from scribe.services.lessons import TRIGGER_KEY trigger = "two absolute siblings overlap" note = fake_lesson( @@ -237,7 +240,7 @@ async def test_a_lesson_title_change_reaches_the_mirror(): data={TRIGGER_KEY: trigger, "what": "the old subject"}, project_id=None, ) - await _update(note, title=compose_title("the new subject", trigger)) + await _update(note, title="the new subject") assert note.data["what"] == "the new subject" assert note.data[TRIGGER_KEY] == trigger diff --git a/tests/test_integration_lesson_kind.py b/tests/test_integration_lesson_kind.py index ef2162f..9d907cf 100644 --- a/tests/test_integration_lesson_kind.py +++ b/tests/test_integration_lesson_kind.py @@ -67,7 +67,7 @@ async def test_a_lesson_is_a_row_the_database_accepts(owner_id): value, and stays correct if it is gated with it.""" lesson = await notes_svc.create_note( owner_id, - title=lessons_svc.compose_title(SUBJECT, TRIGGER), + title=SUBJECT, body=f"**When to apply:** {TRIGGER}\n\nOne change at a time.", note_type=lessons_svc.LESSON_NOTE_TYPE, data={lessons_svc.TRIGGER_KEY: TRIGGER}, @@ -83,7 +83,8 @@ async def test_a_lesson_is_a_row_the_database_accepts(owner_id): # and the readable body — because the vector is built from the text and # the queries are built from the mirror. assert lessons_svc.lesson_trigger(stored) == TRIGGER - assert stored.title == f"{SUBJECT} — {TRIGGER}" + # The subject alone (milestone 427): the trigger is in `data` and the body. + assert stored.title == SUBJECT assert "**When to apply:**" in (stored.body or "") @@ -97,7 +98,7 @@ async def test_a_lesson_is_not_a_task(owner_id): """ lesson = await notes_svc.create_note( owner_id, - title=lessons_svc.compose_title(SUBJECT, TRIGGER), + title=SUBJECT, body="One change at a time.", note_type=lessons_svc.LESSON_NOTE_TYPE, ) diff --git a/tests/test_lesson_document_shape.py b/tests/test_lesson_document_shape.py index b868aad..21af5de 100644 --- a/tests/test_lesson_document_shape.py +++ b/tests/test_lesson_document_shape.py @@ -1,4 +1,4 @@ -"""The document a lesson is embedded as (milestone 385 step 3). +"""The document a lesson is embedded as (milestone 385 step 3; milestone 427). WHY THIS IS THE STEP THAT DECIDES THE MILESTONE @@ -7,26 +7,20 @@ as ordinary prose is a note wearing a label: it would look right in every listing and simply never be retrieved at the moment it applies, and nothing anywhere would report that. -WHY THERE IS NO `lesson_document()` BESIDE `rule_document()` +WHERE THE SHARP SHAPE LIVES -The step anticipated one. There isn't, and the difference is where the sharp -shape LIVES rather than whether it exists. +A snippet, which note #2485 measured as the only sharp record in the corpus (a +0.153 top-to-second gap against 0.010–0.023 for everything else), is sharp +because its document states its purpose twice: `name — when to use` as the +title, and again as the body's first line. A lesson follows the snippet. -A rule keeps its trigger in a column and its title is a plain name, so the -`{title} — {trigger}` document has to be synthesised at embed time and exists -nowhere else — that is what `rule_document` is for. A snippet, which note #2485 -measured as the only sharp record in the corpus (a 0.153 top-to-second gap -against 0.010–0.023 for everything else), gets there the other way: its STORED -title is already the join and its stored body already opens with the trigger, -so the ordinary `title\\nbody` join is the sharp document. A lesson follows the -snippet, which is what step 1 decided and step 2 built. +Until milestone 427 that `subject — trigger` title was also the STORED title, +so every listing, menu and search row showed the trigger too — kilobytes of it. +Now the stored title is the subject, and `embeddings.document_title` joins the +trigger back from `data` at embed time. The embedded TEXT is what it always +was, which is the property these guards pin: nothing re-embeds, and the floors +tuned against these vectors stay calibrated. -The consequence worth stating: `chunk_document` is untouched, so -`CHUNKER_VERSION` does not move and nothing re-embeds. The step's "Re-embed" -section describes a change this design does not make. - -These guards therefore assert the composed record, then assert that the generic -chunker turns it into the intended document — the two halves of the same claim. No similarity number is asserted anywhere: a threshold pins the embedder's behaviour rather than this code's, and breaks on a model change that is not a regression. @@ -34,18 +28,46 @@ regression. from __future__ import annotations from scribe.services import lessons as lessons_svc -from scribe.services.embeddings import chunk_document, embedding_text +from scribe.services.embeddings import chunk_document, document_title, embedding_text TRIGGER = "a test fails on code you believe is correct" SUBJECT = "Suspect the guard before the code" INSIGHT = "Check whether the assertion still describes the property it was written for." +def _embedded(what: str, trigger: str, insight: str) -> tuple[str, str]: + """The (title, body) the write path EMBEDS a lesson as — built the way + `notes.embed_note` builds it, from what `create_lesson` stores.""" + title, body = lessons_svc.lesson_document(what, trigger, insight) + data = lessons_svc.compose_data(what, trigger) + return document_title(title, lessons_svc.LESSON_NOTE_TYPE, data, body), body + + +def test_the_stored_title_is_the_subject_alone(): + """Milestone 427. The trigger lives in `data` and the body's first line; the + title a listing shows is what the lesson is ABOUT.""" + title, _ = lessons_svc.lesson_document(SUBJECT, TRIGGER, INSIGHT) + assert title == SUBJECT + + +def test_the_embedded_document_is_the_one_it_always_was(): + """THE no-re-embed guard. The document text must be byte-identical to what + a lesson embedded as when its stored title carried the trigger — and an + un-migrated row, whose stored title still does, must come out the same + rather than with the trigger twice.""" + legacy_title = f"{SUBJECT} — {TRIGGER}" + title, body = _embedded(SUBJECT, TRIGGER, INSIGHT) + assert title == legacy_title + + data = lessons_svc.compose_data(SUBJECT, TRIGGER) + assert document_title(legacy_title, lessons_svc.LESSON_NOTE_TYPE, data, body) == legacy_title + + def test_the_trigger_appears_twice_in_the_document(): - """THE guard. Purpose stated twice in a short document is the entire - measured cause of a snippet's sharpness, and it is the one property that - distinguishes a lesson's vector from a plain note's.""" - title, body = lessons_svc.lesson_document(SUBJECT, TRIGGER, INSIGHT) + """Purpose stated twice in a short document is the entire measured cause of + a snippet's sharpness, and it is the one property that distinguishes a + lesson's vector from a plain note's.""" + title, body = _embedded(SUBJECT, TRIGGER, INSIGHT) document = embedding_text(title, body) assert document.count(TRIGGER) == 2 @@ -55,22 +77,28 @@ def test_the_trigger_appears_twice_in_the_document(): def test_the_document_leads_with_when_it_applies(): - """The title is `{what} — {when}` and the body's FIRST line restates it, so - the opening of the document is about the situation rather than the topic. - A lesson buried behind a paragraph of narrative would rank on the - narrative.""" - title, body = lessons_svc.lesson_document(SUBJECT, TRIGGER, INSIGHT) + """The embedded title is `{what} — {when}` and the body's FIRST line + restates it, so the opening of the document is about the situation rather + than the topic.""" + title, body = _embedded(SUBJECT, TRIGGER, INSIGHT) assert title == f"{SUBJECT} — {TRIGGER}" assert body.splitlines()[0] == f"**When to apply:** {TRIGGER}" +def test_the_trigger_reaches_the_document_even_without_the_mirror(): + """A row whose `data` lost its mirror still embeds sharply: the trigger is + read back from the body, the same fallback `lesson_trigger` has.""" + title, body = lessons_svc.lesson_document(SUBJECT, TRIGGER, INSIGHT) + assert document_title(title, lessons_svc.LESSON_NOTE_TYPE, None, body) == ( + f"{SUBJECT} — {TRIGGER}" + ) + + def test_a_short_lesson_is_exactly_one_chunk(): """`chunk_document`'s first contract line: a record inside the window - yields one chunk identical to the historical `title\\nbody`. A lesson that - split into several would spread the trigger's weight across vectors that - each carry less of it.""" - title, body = lessons_svc.lesson_document(SUBJECT, TRIGGER, INSIGHT) + yields one chunk identical to the historical `title\\nbody`.""" + title, body = _embedded(SUBJECT, TRIGGER, INSIGHT) chunks = chunk_document(title, body) assert len(chunks) == 1 @@ -78,26 +106,15 @@ def test_a_short_lesson_is_exactly_one_chunk(): def test_a_long_lesson_keeps_the_trigger_on_every_chunk(): - """The narrative question, answered by the chunker rather than by holding - the story out of the record. - - `rule_document` excludes a rule's `why` because long dated narrative made - sixteen dev-logs land on the centroid of "development". That finding - predates chunking (#280): a body over budget is now split, and EVERY chunk - is prefixed with the title — which for a lesson carries the trigger. So the - story occupies its own vectors instead of averaging itself into the - trigger's, and each of those vectors is still anchored to when the lesson - applies. - - This is why the insight stays in the body where a reader can see it. Holding - it out would cost the reader the only part that explains the lesson, to buy - a sharpness the chunker already provides. + """Every chunk is prefixed with the embedded title, which carries the + trigger — so a long story occupies its own vectors instead of averaging + itself into the trigger's, and each is still anchored to when it applies. """ narrative = "\n\n".join( f"## Section {i}\n" + ("An unrelated sentence about deployment. " * 40) for i in range(6) ) - title, body = lessons_svc.lesson_document(SUBJECT, TRIGGER, narrative) + title, body = _embedded(SUBJECT, TRIGGER, narrative) chunks = chunk_document(title, body) assert len(chunks) > 1, "the fixture must actually exceed the chunk budget" @@ -106,10 +123,8 @@ def test_a_long_lesson_keeps_the_trigger_on_every_chunk(): def test_a_lesson_with_no_trigger_still_embeds(): """Degrades to title + insight, the way a rule with no trigger does — less - sharply, and still findable. That is an argument for prompting hard for a - trigger at write time, not for padding the document with whatever text is - to hand.""" - title, body = lessons_svc.lesson_document(SUBJECT, "", INSIGHT) + sharply, and still findable.""" + title, body = _embedded(SUBJECT, "", INSIGHT) assert title == SUBJECT assert body == INSIGHT @@ -119,8 +134,7 @@ def test_a_lesson_with_no_trigger_still_embeds(): def test_the_composed_body_is_the_one_the_reader_is_parsed_back_from(): """`compose_body` writes the trigger line and `lesson_trigger` reads it. A lesson whose mirror in `data` is missing still answers correctly, so the - two must agree on the exact markdown — which is why neither is written by - hand at a call site.""" + two must agree on the exact markdown.""" from types import SimpleNamespace _, body = lessons_svc.lesson_document(SUBJECT, TRIGGER, INSIGHT) @@ -130,10 +144,8 @@ def test_the_composed_body_is_the_one_the_reader_is_parsed_back_from(): def test_the_title_and_body_are_composed_by_one_call(): - """`lesson_document` returns both halves so they cannot be built apart. A - title carrying the trigger over a body that does not would embed as an - ordinary note, and every listing would still look correct.""" + """`lesson_document` returns both halves so they cannot be built apart.""" assert lessons_svc.lesson_document(SUBJECT, TRIGGER, INSIGHT) == ( - lessons_svc.compose_title(SUBJECT, TRIGGER), + SUBJECT, lessons_svc.compose_body(INSIGHT, TRIGGER), ) diff --git a/tests/test_lesson_kind.py b/tests/test_lesson_kind.py index 25fdd2a..7753af7 100644 --- a/tests/test_lesson_kind.py +++ b/tests/test_lesson_kind.py @@ -29,7 +29,6 @@ from types import SimpleNamespace from scribe.services import knowledge as knowledge_svc from scribe.services import lessons as lessons_svc -from scribe.services import snippets as snippets_svc from scribe.services.embeddings import trigger_title @@ -76,15 +75,18 @@ def test_one_join_builds_every_trigger_title(): expected = f"{subject} — {trigger}" assert trigger_title(subject, trigger) == expected - assert lessons_svc.compose_title(subject, trigger) == expected - assert snippets_svc.compose_title(subject, trigger) == expected + # The two note kinds reach it through the EMBEDDED title (milestone 427), + # from their own mirror key — never a hand-rolled join. + from scribe.services.embeddings import document_title + assert document_title(subject, "lesson", {"when_to_apply": trigger}) == expected + assert document_title(subject, "snippet", {"when_to_use": trigger}) == expected def test_a_subject_with_no_trigger_degrades_to_the_subject(): """It still embeds, just less sharply — an argument for backfilling triggers, not for padding the title with whatever text is to hand.""" assert trigger_title("debounce", "") == "debounce" - assert lessons_svc.compose_title(" debounce ") == "debounce" + assert lessons_svc.lesson_document(" debounce ")[0] == "debounce" assert trigger_title("", "when it applies") == "when it applies" diff --git a/tests/test_lesson_rest_door.py b/tests/test_lesson_rest_door.py index d853696..f2f8301 100644 --- a/tests/test_lesson_rest_door.py +++ b/tests/test_lesson_rest_door.py @@ -214,13 +214,13 @@ def test_the_payload_reads_back_the_composed_fields(): """A caller that wrote `when_to_apply` reads `when_to_apply` back, not a body it has to parse.""" from tests.helpers import fake_lesson - from scribe.services.lessons import compose_body, compose_title, lesson_to_dict + from scribe.services.lessons import compose_body, lesson_to_dict what = "Read the job log before waiting longer" trigger = "a CI run has sat in_progress longer than its suite takes" note = fake_lesson( id=7, - title=compose_title(what, trigger), + title=what, body=compose_body("The work is usually done.", trigger, [4181]), data={"what": what, "when_to_apply": trigger, "taught_by": [4181]}, project_id=None, diff --git a/tests/test_lesson_write_path.py b/tests/test_lesson_write_path.py index 19d8b96..03a7159 100644 --- a/tests/test_lesson_write_path.py +++ b/tests/test_lesson_write_path.py @@ -117,7 +117,8 @@ async def test_the_duplicate_gate_runs_before_anything_is_created(): @pytest.mark.asyncio async def test_the_gate_compares_the_composed_document_not_the_raw_fields(): """What reaches the gate is the title and body a lesson will actually be - stored as. Comparing `what` alone would miss that the trigger is half the + stored as, plus the `data` its EMBEDDED title is built from (milestone + 427). Comparing `what` alone would miss that the trigger is half the document, and would judge two lessons alike that rank nothing alike.""" _user_id_ctx.set(7) gate = AsyncMock(return_value=None) @@ -128,8 +129,9 @@ async def test_the_gate_compares_the_composed_document_not_the_raw_fields(): await create_lesson(what=SUBJECT, when_to_apply=TRIGGER, insight="Look.") title, body = gate.await_args.args[1], gate.await_args.args[2] - assert title == f"{SUBJECT} — {TRIGGER}" + assert title == SUBJECT assert body.startswith(f"**When to apply:** {TRIGGER}") + assert gate.await_args.kwargs["data"]["when_to_apply"] == TRIGGER assert gate.await_args.kwargs["note_type"] == "lesson" @@ -157,9 +159,11 @@ def test_a_lesson_is_judged_at_the_trigger_dominated_bar(): @pytest.mark.asyncio async def test_an_update_recomposes_both_halves_of_the_document(): - """A new trigger has to reach the title AND the head of the body. Patching - one would leave a lesson that reads correctly and ranks on the old - situation — the failure mode with no symptom.""" + """A new trigger has to reach the mirror AND the head of the body — the two + places the embedded document reads it from (milestone 427). Patching one + would leave a lesson that reads correctly and ranks on the old situation — + the failure mode with no symptom. The title stays the subject, even when + the stored one was an un-migrated composed title.""" _user_id_ctx.set(7) stored = _stub_note( title=f"{SUBJECT} — {TRIGGER}", @@ -172,7 +176,7 @@ async def test_an_update_recomposes_both_halves_of_the_document(): await lessons_svc.update_lesson(7, 1, when_to_apply="a guard goes red") fields = updated.await_args.kwargs - assert fields["title"] == f"{SUBJECT} — a guard goes red" + assert fields["title"] == SUBJECT assert fields["body"].startswith("**When to apply:** a guard goes red") assert fields["data"]["when_to_apply"] == "a guard goes red" diff --git a/tests/test_services_snippets.py b/tests/test_services_snippets.py index 357c677..10ab94f 100644 --- a/tests/test_services_snippets.py +++ b/tests/test_services_snippets.py @@ -2,10 +2,18 @@ from scribe.services import snippets as s -def test_compose_title_with_and_without_usage(): - assert s.compose_title("debounce", "rate-limit a callback") == "debounce — rate-limit a callback" - assert s.compose_title(" debounce ", "") == "debounce" - assert s.compose_title("debounce") == "debounce" +def test_the_embedded_title_joins_the_trigger_the_stored_one_does_not_carry(): + """Milestone 427: stored title = name; the trigger joins it at embed time, + idempotently, so an old composed title comes out the same.""" + from scribe.services.embeddings import document_title + + data = {"name": "debounce", "when_to_use": "rate-limit a callback"} + assert document_title("debounce", "snippet", data) == "debounce — rate-limit a callback" + assert document_title("debounce — rate-limit a callback", "snippet", data) == ( + "debounce — rate-limit a callback" + ) + assert document_title("debounce", "snippet", {"name": "debounce"}) == "debounce" + assert document_title("a — note", "note", data) == "a — note" def test_compose_tags_lowercases_language_and_dedups(): @@ -32,7 +40,7 @@ def test_compose_body_bare_code_only(): def test_parse_round_trips_a_composed_snippet(): - title = s.compose_title("useDebouncedRef", "debounce a reactive ref") + title = "useDebouncedRef" body = s.compose_body( code="const x = 1", language="ts", signature="useDebouncedRef(v, ms)", when_to_use="debounce a reactive ref", repo="scribe", @@ -241,9 +249,9 @@ def test_data_and_body_round_trip_to_the_same_fields(): name, when, sig, lang = ("debounce", "rate-limit a callback", "debounce(fn, ms)", "ts") locs = [{"repo": "web", "path": "src/util.ts", "symbol": "debounce"}] - # compose_body takes no `name` — the name lives in the title — so the two - # serializers get their own argument lists rather than a shared spread. - title = s.compose_title(name, when) + # compose_body takes no `name` — the name IS the title (milestone 427) — so + # the two serializers get their own argument lists rather than a shared spread. + title = name body = s.compose_body(code="const x = 1", language=lang, signature=sig, when_to_use=when, locations=locs, merged_from=[41, 42]) tags = s.compose_tags(lang)