cjm-markdown-decompose-core 0.0.11__py3-none-any.whl

cjm_markdown_decompose_core/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.11"

cjm_markdown_decompose_core/extract.py

@@ -0,0 +1,174 @@
+"""Map parsed Markdown onto dev-graph-schema nodes (coarse tier).
+
+This is the dev-domain binding: it turns a `ParsedMarkdown` into a `NoteNode`
+(one coarse node per file) carrying the frontmatter-derived identity/metadata,
+with the body's `[[wiki-links]]` available as `REFERENCES` edges. The pure
+parsing it builds on (`parse`) stays schema-free; this module is where the
+markdown corpus meets the dev schema.
+"""
+
+import datetime
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from cjm_context_graph_primitives.provenance import SourceRef
+from cjm_dev_graph_schema.nodes import NoteNode
+
+from .parse import parse_markdown, ParsedMarkdown
+from .relations import harvest_relations
+from .sections import decompose_sections
+
+
+def _json_safe(
+    value: Any,  # A parsed-frontmatter value (PyYAML may produce date/datetime, nested)
+) -> Any:  # The same value with date/datetime coerced to ISO strings (recursively)
+    """Coerce frontmatter values to JSON-serializable forms for the graph wire dict.
+
+    PyYAML parses `date: 2023-8-21` into a Python `datetime.date` (and timestamps
+    into `datetime`), which the metadata passthrough carries verbatim and the graph
+    store then can't JSON-encode. Dates are stable identity-irrelevant metadata, so
+    ISO strings are the faithful wire form (the memory corpus never hit this — it has
+    no date frontmatter; the blog posts do)."""
+    if isinstance(value, datetime.date):  # also catches datetime.datetime (a subclass)
+        return value.isoformat()
+    if isinstance(value, dict):
+        return {k: _json_safe(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_json_safe(v) for v in value]
+    return value
+
+
+def slug_from(
+    path: str,                       # The file path
+    frontmatter: Dict[str, Any],     # Parsed frontmatter
+    corpus_root: Optional[str] = None,  # Root to make the fallback slug relative to
+) -> str:  # Stable note slug
+    """Derive the stable slug: frontmatter `name` if present, else the path.
+
+    The fallback is the corpus-relative path without extension (or the bare stem
+    when no root is given) — stable as long as the file does not move, which is
+    why an explicit frontmatter `name` is preferred for content that outlives its
+    location.
+
+    SSG convention (Quarto/Hugo/…): a `<dir>/index.md` file is identified by its
+    DIRECTORY — the permalink — not the literal `index` stem. Otherwise every
+    post in a `posts/<slug>/index.md` tree collapses onto one `index` slug (the
+    corpus-findings identity collision). The post's stable identity is its
+    directory path relative to the corpus root."""
+    name = frontmatter.get("name")
+    if isinstance(name, str) and name.strip():
+        return name.strip()
+    p = Path(path)
+    # `<dir>/index.md` → identify by the directory (permalink); else drop the suffix.
+    ident = p.parent if p.stem.lower() == "index" else p.with_suffix("")
+    if corpus_root:
+        try:
+            rel = ident.relative_to(corpus_root)
+        except ValueError:
+            rel = Path(ident.name)
+        # A root-level `index.md` relativizes to "." — fall back to the dir name.
+        return rel.as_posix() if rel != Path(".") else ident.name
+    return ident.name
+
+
+def title_from(
+    slug: str,                    # The note slug
+    frontmatter: Dict[str, Any],  # Parsed frontmatter
+) -> str:  # Display title
+    """Derive a display title: explicit frontmatter `title`, else the slug titleized."""
+    title = frontmatter.get("title")
+    if isinstance(title, str) and title.strip():
+        return title.strip()
+    return slug.replace("-", " ").replace("_", " ").strip().title()
+
+
+def note_type_from(
+    frontmatter: Dict[str, Any],  # Parsed frontmatter
+) -> Optional[str]:  # Memory category (user | feedback | project | reference) or None
+    """Read the memory category from `metadata.type` (None when absent)."""
+    meta = frontmatter.get("metadata")
+    if isinstance(meta, dict):
+        t = meta.get("type")
+        if isinstance(t, str) and t.strip():
+            return t.strip()
+    return None
+
+
+def note_from_parsed(
+    path: str,                # The file path (provenance locator)
+    content_hash: str,        # Content hash over the file bytes
+    parsed: ParsedMarkdown,   # The parsed document
+    corpus_root: Optional[str] = None,  # Root for the fallback slug
+    profile: Optional[str] = None,      # Relationship-harvest profile (None = auto-detect)
+    with_sections: bool = False,        # Also decompose the body into Section nodes (notes corpus; off for the memory/dev corpus)
+    lossless: bool = False,             # Lossless body-on-graph mode (memory corpus): verbatim per-section `raw` spans + level-0 preamble + verbatim `frontmatter_raw`, so the file round-trips byte-for-byte (M1). Implies sectioning
+) -> NoteNode:  # The coarse Note node
+    """Build a coarse `NoteNode` from already-parsed Markdown.
+
+    Beyond the coarse identity/metadata, the per-source-type relationship
+    harvesters (`relations`) add the corpus's real relationship signals —
+    categories, series membership, cross-post links, aliases — selected by the
+    detected (or given) source profile. A cross-post link to THIS post's own
+    section is dropped (a self-reference is not a cross-post edge).
+
+    Body content comes on-graph in one of two opt-in modes. `with_sections`
+    (Scope A, the notes corpus) decomposes the body into navigable `Section` nodes
+    at the section grain. `lossless` (M1, the high-stakes memory corpus) is the
+    stronger form: it sections too, but each section carries its heading-inclusive
+    verbatim `raw` span and the Note carries the verbatim `frontmatter_raw`, so the
+    file reconstructs byte-for-byte (`frontmatter_raw + ''.join(s.raw in order)`).
+    Both are off for plain coarse ingestion."""
+    fm = parsed.frontmatter
+    slug = slug_from(path, fm, corpus_root)
+    description = fm.get("description")
+    rel = harvest_relations(parsed, profile)
+    own = {slug, Path(path).parent.name}  # this post's own permalink (both namespaces)
+    cross = [(p, a) for (p, a) in rel.cross_post_refs if p not in own]
+    note = NoteNode(
+        slug=slug,
+        title=title_from(slug, fm),
+        path=path,
+        content_hash=content_hash,
+        description=description.strip() if isinstance(description, str) else "",
+        note_type=note_type_from(fm),
+        references=list(parsed.wiki_links),
+        metadata={k: _json_safe(v) for k, v in fm.items()
+                  if k not in ("name", "title", "description", "metadata")},
+        categories=rel.categories,
+        series_refs=rel.series_refs,
+        aliases=rel.aliases,
+        cross_post_refs=cross,
+        frontmatter_raw=parsed.frontmatter_raw if lossless else "",
+    )
+    if with_sections or lossless:
+        note.sections = decompose_sections(parsed.body, note.id, path, lossless=lossless)
+    return note
+
+
+def note_from_text(
+    path: str,                          # The file path (provenance locator)
+    text: str,                          # The full document text
+    corpus_root: Optional[str] = None,  # Root for the fallback slug
+    profile: Optional[str] = None,      # Relationship-harvest profile (None = auto-detect)
+    with_sections: bool = False,        # Also decompose the body into Section nodes
+    lossless: bool = False,             # Lossless body-on-graph mode (memory corpus); see note_from_parsed
+) -> NoteNode:  # The coarse Note node
+    """Parse + map in one step from in-memory text (hashes the UTF-8 bytes)."""
+    return note_from_parsed(path, SourceRef.compute_hash(text.encode("utf-8")),
+                            parse_markdown(text), corpus_root, profile, with_sections, lossless)
+
+
+def note_from_file(
+    path: str,                          # Path to the Markdown file
+    corpus_root: Optional[str] = None,  # Root for the fallback slug
+    profile: Optional[str] = None,      # Relationship-harvest profile (None = auto-detect)
+    with_sections: bool = False,        # Also decompose the body into Section nodes
+    lossless: bool = False,             # Lossless body-on-graph mode (memory corpus); see note_from_parsed
+) -> NoteNode:  # The coarse Note node
+    """Read a Markdown file and map it to a coarse `NoteNode`.
+
+    The content hash is computed over the raw file bytes (faithful to the file as
+    stored); the text is decoded as UTF-8 for parsing."""
+    raw = Path(path).read_bytes()
+    return note_from_parsed(path, SourceRef.compute_hash(raw),
+                            parse_markdown(raw.decode("utf-8")), corpus_root, profile, with_sections, lossless)

cjm_markdown_decompose_core/ingest.py

@@ -0,0 +1,53 @@
+"""Flatten decomposed notes into graph elements for idempotent extension.
+
+The pure (queue-free) half of putting a corpus on the graph: turn `NoteNode`s
+into the `(nodes, edges)` wire-dict lists that `cjm_context_graph_layer.ops.
+extend_graph` commits. The queue/capability wiring itself is the projection-CLI
+driver's concern (it owns the JobQueue + graph-storage capability); keeping the
+flattening here makes it reusable and unit-testable without a running graph.
+"""
+
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+from cjm_dev_graph_schema.nodes import NoteNode, SeriesNode, TopicNode
+
+
+def corpus_graph_elements(
+    notes: Iterable[NoteNode],  # Decomposed notes
+    aliases: Optional[Dict[str, str]] = None,  # Confirmed {drifted-slug: canonical-slug} link aliases
+) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:  # (node wire dicts, edge wire dicts)
+    """Collect notes into the node + edge wire-dict lists `extend_graph` expects.
+
+    One `Note` node per file plus its relationship edges — `REFERENCES`
+    (`[[wiki-links]]` + cross-post links), `TAGGED` (categories), `IN_SERIES`
+    (series membership) — and, when the note was decomposed `with_sections`, its
+    `Section` nodes + `HAS_SECTION`/`PART_OF` edges (the body content + hierarchy).
+    The shared facet nodes (`Topic` per category, `Series` per series) are emitted
+    ONCE, deduped across the corpus, so independent notes sharing a category/series
+    converge on one node. Deterministic ids make the result idempotent under
+    `extend_graph` — re-ingesting collides into verified no-ops rather than
+    duplicating.
+
+    A confirmed `aliases` map resolves drifted link slugs to their canonical note
+    before the edge is built, so a once-dangling `[[wiki-link]]` (or cross-post
+    link) lands on the real note (slug-drift rot healed on-graph, file untouched)."""
+    nodes: List[Dict[str, Any]] = []
+    edges: List[Dict[str, Any]] = []
+    topics: Dict[str, None] = {}   # distinct category keys (first-seen order)
+    series: Dict[str, None] = {}   # distinct series keys (first-seen order)
+    for n in notes:
+        nodes.append(n.to_graph_node())
+        edges.extend(n.reference_edges(aliases))
+        edges.extend(n.cross_post_edges(aliases))
+        edges.extend(n.tagged_edges())
+        edges.extend(n.series_edges())
+        for sec in n.sections:
+            nodes.append(sec.to_graph_node())
+            edges.extend(sec.structural_edges())
+        for c in n.categories:
+            topics.setdefault(c, None)
+        for s in n.series_refs:
+            series.setdefault(s, None)
+    nodes.extend(TopicNode(key=k).to_graph_node() for k in topics)
+    nodes.extend(SeriesNode(key=k).to_graph_node() for k in series)
+    return nodes, edges

cjm_markdown_decompose_core/parse.py

@@ -0,0 +1,113 @@
+"""Schema-free Markdown parsing (stdlib + PyYAML).
+
+Splits YAML frontmatter from the body, extracts `[[wiki-links]]`, and reads
+ATX headings. Carries NO graph-schema dependency on purpose — this is the
+genuinely-general layer, reusable for any Markdown corpus (memory files today,
+blog posts tomorrow). The dev-domain binding lives in `extract`.
+"""
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+import yaml
+
+# A frontmatter block is a leading `---` line, YAML, and a closing `---` line.
+_FRONTMATTER_RE = re.compile(r"\A---[ \t]*\r?\n(.*?)\r?\n---[ \t]*\r?\n?", re.DOTALL)
+# `[[target]]` wiki-link; the target is the inner text (a slug), trimmed.
+_WIKI_LINK_RE = re.compile(r"\[\[([^\[\]]+?)\]\]")
+# ATX heading: 1-6 leading `#`, then the text.
+_HEADING_RE = re.compile(r"^(#{1,6})[ \t]+(.*?)[ \t]*#*[ \t]*$", re.MULTILINE)
+# Code spans, stripped before wiki-link extraction so QUOTED example syntax
+# (`[[wiki-link]]` in prose ABOUT links) is not mistaken for a real reference:
+# fenced blocks first (multi-line), then inline backtick runs (single-line).
+_FENCED_CODE_RE = re.compile(r"```.*?```", re.DOTALL)
+_INLINE_CODE_RE = re.compile(r"(`+)(?:.+?)\1")
+
+
+@dataclass
+class ParsedMarkdown:
+    """The structural decomposition of one Markdown document."""
+    frontmatter: Dict[str, Any] = field(default_factory=dict)  # Parsed YAML frontmatter ({} if none)
+    body: str = ""                                             # Document body (frontmatter stripped)
+    wiki_links: List[str] = field(default_factory=list)       # `[[link]]` targets, de-duplicated in first-seen order
+    headings: List[Tuple[int, str]] = field(default_factory=list)  # (level, text) per ATX heading, in document order
+    frontmatter_raw: str = ""                                 # The VERBATIM frontmatter prefix (fences + YAML + trailing newline); "" when none. `frontmatter_raw + body == original text`, so it is the lossless round-trip source for the frontmatter (the parsed `frontmatter` dict is a derived projection)
+
+
+def split_frontmatter(
+    text: str,  # Full document text
+) -> Tuple[Optional[str], str]:  # (raw frontmatter YAML or None, body)
+    """Split a leading `---`-delimited YAML frontmatter block from the body.
+
+    Returns `(None, text)` when there is no frontmatter (the body is the whole
+    document); the leading delimiter must be the very first thing in the file."""
+    m = _FRONTMATTER_RE.match(text)
+    if not m:
+        return None, text
+    return m.group(1), text[m.end():]
+
+
+def parse_frontmatter(
+    raw: Optional[str],  # Raw frontmatter YAML (from split_frontmatter), or None
+) -> Dict[str, Any]:  # Parsed mapping ({} when absent or non-mapping)
+    """Parse frontmatter YAML into a dict (empty dict when absent).
+
+    Non-mapping frontmatter (a bare scalar/list) yields `{}` — frontmatter is a
+    metadata mapping by convention; anything else is ignored rather than guessed."""
+    if not raw or not raw.strip():
+        return {}
+    loaded = yaml.safe_load(raw)
+    return loaded if isinstance(loaded, dict) else {}
+
+
+def strip_code(
+    body: str,  # Document body
+) -> str:  # Body with fenced + inline code spans blanked
+    """Blank out fenced + inline code spans (replaced with a space, length-agnostic).
+
+    Wiki-link extraction runs on the result so that `[[link]]` written inside
+    backticks — example syntax in notes that DISCUSS links, not a real reference —
+    is never picked up as an edge (the corpus-findings extraction false positive)."""
+    return _INLINE_CODE_RE.sub(" ", _FENCED_CODE_RE.sub(" ", body))
+
+
+def extract_wiki_links(
+    body: str,  # Document body
+) -> List[str]:  # `[[link]]` targets, de-duplicated in first-seen order
+    """Extract `[[wiki-link]]` targets from the body, de-duplicated, order-preserved.
+
+    The target is the trimmed inner text (a note slug); code spans are stripped
+    first so quoted example syntax is excluded. Order and de-duplication are stable
+    so the resulting REFERENCES edge set is deterministic across re-extraction."""
+    seen: Dict[str, None] = {}
+    for m in _WIKI_LINK_RE.finditer(strip_code(body)):
+        target = m.group(1).strip()
+        if target:
+            seen.setdefault(target, None)
+    return list(seen)
+
+
+def extract_headings(
+    body: str,  # Document body
+) -> List[Tuple[int, str]]:  # (level, text) per ATX heading, in document order
+    """Extract ATX headings (`#`..`######`) as (level, text) pairs."""
+    return [(len(m.group(1)), m.group(2).strip()) for m in _HEADING_RE.finditer(body)]
+
+
+def parse_markdown(
+    text: str,  # Full document text
+) -> ParsedMarkdown:  # The structural decomposition
+    """Parse a Markdown document into frontmatter + body + wiki-links + headings."""
+    raw_fm, body = split_frontmatter(text)
+    # The verbatim frontmatter prefix is everything `split_frontmatter` consumed
+    # (the leading `---` fence, YAML, closing fence, trailing newline) — i.e. the
+    # bytes before `body`. Reconstructed losslessly as `text[:len(text)-len(body)]`
+    # so that `frontmatter_raw + body == text` holds by construction ("" when none).
+    return ParsedMarkdown(
+        frontmatter=parse_frontmatter(raw_fm),
+        body=body,
+        wiki_links=extract_wiki_links(body),
+        headings=extract_headings(body),
+        frontmatter_raw=text[:len(text) - len(body)],
+    )

cjm_markdown_decompose_core/project.py

@@ -0,0 +1,253 @@
+"""Projections from the decomposed content back out to files.
+
+The first projection is the `MEMORY.md` index: one line per note, grouped by
+category, with each line derived from the note's own frontmatter (title +
+description). This is the self-hosting payoff in miniature — the index becomes a
+PROJECTION of a single source of truth (each note) rather than a file edited by
+hand. Operates on `NoteNode`s, whether they come straight from `extract` or from
+a graph query.
+"""
+
+import os
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+from cjm_dev_graph_schema.nodes import NoteNode, SectionNode
+
+# Default category section order + display headings for the memory index.
+DEFAULT_SECTION_ORDER = ("project", "feedback", "reference", "user")
+_SECTION_HEADINGS = {
+    "project": "Project",
+    "feedback": "Feedback",
+    "reference": "Reference",
+    "user": "User",
+}
+_UNCATEGORIZED = "Other"
+
+
+def note_index_line(
+    note: NoteNode,  # The note to render
+) -> str:  # One Markdown index line: "- [Title](file.md) — description"
+    """Render one index line from a note's frontmatter-derived fields."""
+    link = os.path.basename(note.path)
+    line = f"- [{note.title}]({link})"
+    if note.description:
+        line += f" — {note.description}"
+    return line
+
+
+def _node_field(
+    node: Any,        # A queried graph node (typed GraphNode or wire dict)
+    key: str,         # Property name
+    default: Any = None,
+) -> Any:  # The property value
+    """Read one property from a queried node, tolerating GraphNode or wire dict."""
+    props = node.properties if hasattr(node, "properties") else node.get("properties", {})
+    return props.get(key, default)
+
+
+def note_view_from_graph_node(
+    node: Any,  # A queried `Note` graph node (typed GraphNode or wire dict)
+) -> NoteNode:  # An index-relevant NoteNode reconstructed from the graph
+    """Reconstruct an index-relevant `NoteNode` from a queried graph node.
+
+    Carries the fields the index needs (title / description / path / note_type);
+    `references` are an edge query, not needed for the index, so they are left
+    empty. This is what closes the self-hosting loop — the projection reads the
+    GRAPH, not the in-memory extraction."""
+    return NoteNode(
+        slug=_node_field(node, "slug", "") or "",
+        title=_node_field(node, "title", "") or "",
+        path=_node_field(node, "path", "") or "",
+        content_hash="",
+        description=_node_field(node, "description", "") or "",
+        note_type=_node_field(node, "note_type"),
+    )
+
+
+def render_memory_index_from_graph_nodes(
+    nodes: Iterable[Any],  # Queried `Note` graph nodes (typed GraphNode or wire dicts)
+    **kwargs: Any,         # Forwarded to render_memory_index (title / section_order / preamble)
+) -> str:  # The rendered MEMORY.md text
+    """Render the memory index FROM queried graph nodes (the self-hosting path)."""
+    return render_memory_index((note_view_from_graph_node(n) for n in nodes), **kwargs)
+
+
+def render_memory_index(
+    notes: Iterable[NoteNode],                 # The notes to index
+    title: str = "# Project Memory",           # Top-level document title
+    section_order: Iterable[str] = DEFAULT_SECTION_ORDER,  # Category order for sections
+    preamble: Optional[str] = None,            # Optional prose inserted under the title
+) -> str:  # The rendered MEMORY.md text
+    """Render a `MEMORY.md` index: notes grouped by category, one line each.
+
+    Deterministic: notes are bucketed by `note_type`, sections emitted in
+    `section_order` (any leftover categories appended alphabetically, then an
+    `Other` bucket for notes without a category), and lines within a section
+    sorted by title. Same notes in -> same text out (so a regenerate is a clean
+    idempotent overwrite)."""
+    buckets: Dict[str, List[NoteNode]] = {}
+    for n in notes:
+        buckets.setdefault(n.note_type or _UNCATEGORIZED, []).append(n)
+
+    ordered = list(section_order)
+    leftovers = sorted(k for k in buckets if k not in ordered and k != _UNCATEGORIZED)
+    section_keys = [k for k in ordered if k in buckets] + leftovers
+    if _UNCATEGORIZED in buckets:
+        section_keys.append(_UNCATEGORIZED)
+
+    parts: List[str] = [title]
+    if preamble:
+        parts.append(preamble.strip())
+    for key in section_keys:
+        heading = _SECTION_HEADINGS.get(key, key.title())
+        lines = [note_index_line(n) for n in sorted(buckets[key], key=lambda n: n.title.lower())]
+        parts.append(f"## {heading}\n" + "\n".join(lines))
+
+    return "\n\n".join(parts) + "\n"
+
+
+# --- Onboarding surface (the MEMORY.md-as-projection reframe) -----------------
+#
+# A different projection from `render_memory_index`: instead of ENUMERATING every
+# note (which pays session budget for mostly task-conditional content), emit a
+# radically-minimal resident core + a MAP of how to pull the rest from the graph
+# on demand. Domain-neutral: the graph-specific prose (how to query THIS graph,
+# the guardrails) is injected by the driver; the core only assembles the structure
+# + the coverage map + the terse push-core lines.
+
+_DEFAULT_INTRO = (
+    "> Project knowledge lives in a **context graph**, not this file. This is your MAP "
+    "+ the few things to know *before* querying. Pull the rest on demand — don't expect "
+    "it enumerated here."
+)
+_DEFAULT_HOW_TO_QUERY = (
+    "## How to query\n"
+    "Use your read-only graph query tool: `relevant \"<your task>\"` ranks nearby nodes; "
+    "`show <id>` drills into one node + its neighbours; `state` is an overview."
+)
+_DEFAULT_HOW_TO_PULL = (
+    "## How to pull\n"
+    "1. At task start, run `relevant \"<task>\"` — it ranks by structural nearness "
+    "(decisions, notes, code, cross-links), richer than any static list.\n"
+    "2. `show <id>` for a node's STRUCTURE — title + neighbours, NOT its body; `read <id>` DELIVERS\n"
+    "   the verbatim body. Pull BOTH on any node you are about to act on.\n"
+    "3. If a landmark above names your area, use its query hint as a starting point.\n"
+    "4. Treat what you pull as the live source of truth; this surface is only the map."
+)
+
+
+def first_sentence(
+    text: str,         # The full description text
+    limit: int = 220,  # Hard character cap when no sentence boundary is found
+) -> str:  # A terse one-line hook
+    """A deterministic terse hook: the description's first sentence, capped.
+
+    The frontmatter `description` is a full recall-abstract (it feeds relevance, so we
+    keep it whole there); the onboarding surface needs a terse navigational hook, so
+    take the first sentence (else hard-cap with an ellipsis). Same text in -> same hook."""
+    t = " ".join((text or "").split())
+    if not t:
+        return ""
+    best = -1
+    for sep in (". ", "; "):
+        i = t.find(sep)
+        if 0 < i <= limit and (best < 0 or i < best):
+            best = i
+    if best > 0:
+        return t[:best + 1].rstrip()
+    return (t[:limit].rstrip() + "…") if len(t) > limit else t
+
+
+def render_onboarding_surface(
+    notes: Iterable[NoteNode],              # All Note nodes (the coverage map + push-core lookup)
+    push_slugs: Iterable[str],              # Allowlist of slugs rendered inline as the resident PUSH core
+    landmarks: Iterable[Tuple[str, str]],   # (label, query-hint) coverage pointers (NOT an enumeration)
+    arc_lead: str,                          # The live arc-lead anchor (one line)
+    *,
+    title: str = "# Project Memory — Onboarding Surface",  # Document title
+    intro: str = _DEFAULT_INTRO,                # Orientation prose under the title
+    how_to_query: str = _DEFAULT_HOW_TO_QUERY,  # Graph-specific "how to query" section (driver overrides)
+    how_to_pull: str = _DEFAULT_HOW_TO_PULL,    # The pull-discipline section
+    push_hooks: Optional[Dict[str, str]] = None,  # slug -> terse COMPLETE hook (else first_sentence fallback)
+    coverage: Optional[str] = None,             # Pre-rendered AUTO landmark subsection (whole-graph facets), appended under the curated map
+) -> str:  # The rendered onboarding-surface markdown
+    """Render the onboarding surface: orientation + how-to-query + resident PUSH core + landmark map + how-to-pull.
+
+    The push core renders one line per allowlisted slug (title + an explicit terse hook
+    — else the description's first sentence — + a `show <id>` pull-hint for the full node,
+    the exact-node analogue of a landmark's `relevant` cluster hint); the landmark map
+    lists coverage pointers + per-category counts (the territory, not its contents).
+    Deterministic for a given (notes, seeds) — a regenerate is a clean idempotent overwrite.
+    Graph-specific prose is injected via `how_to_query` so the core stays domain-neutral.
+
+    A push node's `description` is a full recall-abstract that often BURIES the actionable
+    point, so truncating it can mislead (e.g. severing "NEVER delete the journal"); the
+    explicit `push_hooks` hook is a terse COMPLETE statement — `show <id>` fetches the rest."""
+    notes = list(notes)
+    by_slug = {n.slug: n for n in notes}
+    counts: Dict[str, int] = {}
+    for n in notes:
+        counts[n.note_type or "other"] = counts.get(n.note_type or "other", 0) + 1
+    total = sum(counts.values())
+
+    parts: List[str] = [f"{title}\n\n{intro}", how_to_query]
+    hooks = push_hooks or {}
+    push_lines: List[str] = []
+    for s in push_slugs:
+        if s not in by_slug:
+            push_lines.append(f"- _(push node not found on-graph: {s})_")
+            continue
+        n = by_slug[s]
+        push_lines.append(f"- **{n.title}** — {hooks.get(s) or first_sentence(n.description)}  ↳ `show {n.id}`")
+    parts.append("## Resident core (read me)\n- " + arc_lead + "\n" + "\n".join(push_lines))
+    cov = ", ".join(f"{k}:{v}" for k, v in sorted(counts.items()))
+    lm = "\n".join(f"- **{label}** → `relevant \"{hint}\"`" for label, hint in landmarks)
+    landmark_section = ("## Landmark map — what's on-graph (coverage, not enumeration)\n"
+                        f"_~{total} notes ({cov}); query a landmark to pull its cluster:_\n" + lm)
+    if coverage:  # the auto-derived whole-graph facets (curated map stays; this augments it)
+        landmark_section += "\n\n" + coverage.strip()
+    parts.append(landmark_section)
+    parts.append(how_to_pull)
+    return "\n\n".join(parts) + "\n"
+
+
+# --- Lossless note round-trip (M1: memory bodies on-graph) --------------------
+#
+# The inverse of `lossless` decomposition: reassemble a note's exact file text
+# from its verbatim parts — the Note's `frontmatter_raw` plus every Section's
+# heading-inclusive `raw` span in document order. PURE concatenation, no
+# canonical-seam emission (prose derives nothing, unlike code's imports/ordering),
+# so the result is byte-for-byte the original file when the note was decomposed
+# `lossless=True`. This is M1's content-fidelity gate (file -> graph -> file ==
+# file) and the read leg of authoring memory on-graph (M2).
+
+def render_note_text(
+    frontmatter_raw: str,             # The note's verbatim frontmatter prefix ("" when none)
+    sections: Iterable[SectionNode],  # The note's Section nodes (any order; sorted by `order` here)
+) -> str:  # The reconstructed file text
+    """Reassemble a note's exact file text from its verbatim parts (lossless mode).
+
+    `frontmatter_raw + ''.join(s.raw for s in sorted-by-order)`. Requires sections
+    decomposed `lossless=True` (each carries its heading-inclusive `raw` span, with
+    a level-0 preamble at order 0); a Scope-A section set has empty `raw` and will
+    NOT round-trip — that is the mode boundary, not a bug."""
+    ordered = sorted(sections, key=lambda s: s.order)
+    return frontmatter_raw + "".join(s.raw for s in ordered)
+
+
+def note_text_from_graph_nodes(
+    note_node: Any,                # The queried `Note` graph node (typed GraphNode or wire dict)
+    section_nodes: Iterable[Any],  # The note's queried `Section` graph nodes
+) -> str:  # The reconstructed file text (the self-hosting round-trip path)
+    """Reconstruct a note's file text FROM the graph (frontmatter_raw + ordered raw spans).
+
+    Reads `frontmatter_raw` off the Note and each Section's `raw`/`order` off the
+    queried nodes — the projection reads the GRAPH, not the in-memory extraction
+    (the same loop-closing move as `render_memory_index_from_graph_nodes`)."""
+    frontmatter_raw = _node_field(note_node, "frontmatter_raw", "") or ""
+    spans = sorted(
+        ((int(_node_field(s, "order", 0) or 0), _node_field(s, "raw", "") or "")
+         for s in section_nodes),
+        key=lambda t: t[0],
+    )
+    return frontmatter_raw + "".join(raw for _, raw in spans)