causal-continuity-engine 0.1.2__tar.gz → 0.1.3__tar.gz

{causal_continuity_engine-0.1.2 → causal_continuity_engine-0.1.3}/.github/scripts/verify_distributions.py

@@ -78,6 +78,7 @@ SDIST_SOURCE_TREES = {
     "benchmarks": {".py"},
     IMPORT_PACKAGE: {".py", "py.typed"},
     "docs": {".md", ".png", ".svg"},
+    "examples": {".py"},
     "schemas": {".json"},
     "tests": {".py"},
     "vectors": {".json", ".py"},
@@ -516,7 +517,9 @@ def _source_path_is_allowed(relative: str) -> bool:
     selectors = SDIST_SOURCE_TREES.get(parts[0])
     if selectors is None:
         return False
-    if parts[0] in {"schemas", "tests", "vectors", "verifiers"} and len(parts) != 2:
+    if parts[0] in {
+            "examples", "schemas", "tests", "vectors", "verifiers",
+    } and len(parts) != 2:
         return False
     if parts[0] == "benchmarks" and not (
             len(parts) == 2

{causal_continuity_engine-0.1.2 → causal_continuity_engine-0.1.3}/CHANGELOG.md

@@ -9,6 +9,80 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 No unreleased changes.
 
+## 0.1.3 — 2026-08-09
+
+The deterministic extractor met real prose for the first time and did badly.
+Twenty-two defects were found by running it against actual repository history
+rather than fixtures, and every one is fixed here with a regression test that
+was confirmed to fail against the code it pins. `AD-002` treats this extractor
+as the degradation path rather than the primary one; a degradation path that
+mangles its input is worse than useless, because nothing downstream can tell
+the difference.
+
+### Fixed
+
+- **Statements were fabricated across masked regions.** The gap between a cue
+  word and its clause matched newlines, so it walked over a blanked code fence
+  and joined the text either side — recording "The exporter must stream rows to
+  the client" from a body where those words never appear together. A fabricated
+  statement is worse than a lost one: nothing downstream can tell.
+- **Sentences were truncated at the line wrap.** Every clause rule excluded
+  `\n`, so a sentence wrapped at eighty columns — which is how comment bodies
+  are written — was cut at the break. "must stream rows … instead of" survives
+  as a grammatical clause with its point removed. Identical text on one line
+  extracted in full, so the record depended on the author's editor.
+- **Clauses began and ended mid-word.** An unanchored character budget started
+  the statement wherever the count landed ("stale capsules" recorded as "le
+  capsules"), and the tail bound ended it the same way in 23 of 40 measured
+  cases.
+- **Dotted identifiers truncated or silently dropped statements.** A `.` was
+  always a sentence end, so `generate.py` and `v0.1.2` cut a clause short — and
+  because the forward patterns have a minimum length, "We assume numpy 1.26.4
+  is installed" extracted nothing at all while "We decided to pin pip 26.1.2"
+  recorded the false statement "pin pip 26".
+- **Text nobody wrote became authority.** Code fences, blockquotes, HTML
+  comments and four-space indented blocks were read as the author's own prose.
+  A requirement hidden inside `<!-- ... -->` is invisible in every rendered
+  view, so no reviewer could catch it; a blockquote is by definition someone
+  else's words, frequently quoted in order to disagree with them.
+- **A hidden checklist became actionable open work.** The checklist scan read
+  raw text while every other pattern read the mask, so `- [ ]` items inside a
+  comment or fence arrived as `open` task nodes in the resume packet, needing
+  no injection wording at all.
+- **An invisible character inverted a prohibition.** A zero-width space inside
+  "not" left the sentence identical to a reader while re-typing the constraint
+  as a requirement, so control state mandated what the sentence forbids. Word
+  joiners and soft hyphens behaved the same, and word processors insert soft
+  hyphens routinely. Matching now ignores them while the statement keeps them,
+  so the packet still shows that the text carried them.
+- **Non-ASCII statements collided.** The dedup key discarded every character
+  outside ASCII, so "must not exceed €500" and "must not exceed £500" shared a
+  key and one was dropped. In a script with no ASCII the key was empty, giving
+  every statement the same identity.
+- Markdown decoration was stored inside statements; `must never X` was filed as
+  both a constraint and a requirement; consecutive table rows merged into one
+  statement; and longer or CRLF code fences never found their closer, masking
+  the remainder of the body and discarding every statement after it.
+
+### Added
+
+- `examples/quickstart.py` — the whole arc end to end in a temporary directory:
+  a proof minted by actually running a pinned verifier, accepted for the task
+  it names, refused for one it does not, and checked by the independent
+  verifier, which reports UNVERIFIED without the key and VALID with it.
+- `examples/backfill_github.py` — builds a project from a repository's real
+  history through the REST API, with no webhook, App or public endpoint. This
+  is the instrument that found everything above.
+- A regression test for cross-project rejection in `Memory.promote`.
+
+### Changed
+
+- **Node identity changes for statements containing non-ASCII characters.**
+  `stable_node_id` is derived from the dedup key, so such a statement now
+  hashes to a different id than it did in 0.1.2. A project that re-ingests one
+  records a new node rather than updating the old; the previous node remains,
+  with its history intact. Pure-ASCII projects are unaffected.
+
 ## 0.1.2 — 2026-08-09
 
 A documentation and hygiene release. No engine, schema, proof, or HTTP

{causal_continuity_engine-0.1.2 → causal_continuity_engine-0.1.3}/CITATION.cff

@@ -8,7 +8,7 @@ authors:
   - given-names: Thomas
     family-names: Albrecht
     alias: The Quantum Falcon
-version: 0.1.2
+version: 0.1.3
 date-released: 2026-08-09
 license: Apache-2.0
 repository-code: https://github.com/thequantumfalcon/causal-continuity-engine

{causal_continuity_engine-0.1.2 → causal_continuity_engine-0.1.3}/MANIFEST.in

@@ -4,6 +4,7 @@ include requirements-dev.in requirements-dev.lock
 include .editorconfig .gitattributes .gitignore .gitleaks.toml .pre-commit-config.yaml
 recursive-include causal_continuity_engine *.py py.typed
 recursive-include benchmarks *.py
+recursive-include examples *.py
 recursive-include docs *.md
 include docs/assets/social-preview.png
 include docs/assets/demo.svg

{causal_continuity_engine-0.1.2 → causal_continuity_engine-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: causal-continuity-engine
-Version: 0.1.2
+Version: 0.1.3
 Summary: Causal Continuity Engine - continuity, causal invalidation, and proof for long-running coding agents
 Author: Thomas Albrecht
 License-Expression: Apache-2.0

{causal_continuity_engine-0.1.2 → causal_continuity_engine-0.1.3}/causal_continuity_engine/__init__.py

@@ -7,7 +7,7 @@ authenticated runtime records are not replay-derived (ADR-001). Storage is
 SQLite implementing the PostgreSQL-first relational adjacency design (ADR-011).
 """
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 SCHEMA_VERSIONS = {
     "anchor": "cce.anchor.v1",

{causal_continuity_engine-0.1.2 → causal_continuity_engine-0.1.3}/causal_continuity_engine/extraction.py

@@ -21,6 +21,7 @@ emitted as low-confidence 'proposed' items).
 from __future__ import annotations
 
 import re
+import unicodedata
 from dataclasses import dataclass, field
 
 from .core import canonical_json, strict_json_loads
@@ -50,27 +51,74 @@ class ExtractionResult:
     extractor_version: str = EXTRACTOR_VERSION
 
 
+# Modal patterns ("... must never ...") have to look backwards for the start of
+# the clause, and both edges of that lookback need care on real prose.
+#
+# _CLAUSE_START anchors the beginning to a place a clause can actually begin.
+# A bare `{0,80}?` lookback has no left boundary, so once the clause is longer
+# than the budget the match starts wherever the character count lands — which
+# on real text is reliably mid-word ("stale capsules" arriving as "le
+# capsules").
+#
+# _IN_CLAUSE / _CLAUSE_TAIL treat `.` as a sentence end only when whitespace or
+# the end of the text follows it. A dot inside an identifier — `generate.py`,
+# `v0.1.0`, `README.md` — is ordinary clause content, and excluding it outright
+# truncated statements to the fragment after the dot.
+#
+# The forward-capturing patterns need the same treatment, and failed harder
+# without it: their tails have a minimum length, so a dotted identifier near
+# the start of the clause left too few characters to match and the statement
+# was dropped in silence. "We assume numpy 1.26.4 is installed" extracted
+# nothing at all, and "We decided to pin pip 26.1.2" recorded the false
+# statement "pin pip 26". In this domain those are the common sentences.
+# Markdown soft-wraps: a single newline continues the paragraph, and comment
+# bodies are wrapped at roughly eighty columns by every editor that touches
+# them. Treating any newline as a clause end truncated most real sentences at
+# the wrap — "must stream rows instead of" losing the half that says instead of
+# what. A blank line, list item, heading or quote marker does begin a new
+# logical unit, so those still bound the clause.
+_SOFT_WRAP = r"\n(?![ \t]*(?:\n|[-*+>#|]|\d+[.)]))"
+_CLAUSE_START = r"(?:\A|[\n;:]\s*|\.\s+)"
+_IN_CLAUSE = r"(?:[^.\n;]|\.(?!\s|\Z)|" + _SOFT_WRAP + r")"
+_CLAUSE_TAIL = r"(?:[^.\n]|\.(?!\s|\Z)|" + _SOFT_WRAP + r")"
+
+# The gap between a cue word and the clause it introduces. A plain `\s+` also
+# matches newlines, so it walked across paragraph breaks and across masked
+# regions — stitching "The exporter must" to "stream rows to the client" over a
+# code fence and recording a sentence the author never wrote. Fabricating a
+# statement is worse than dropping one: nothing downstream can tell.
+_GAP = r"(?:[ \t]|" + _SOFT_WRAP + r")+"
+
 # Patterns: (kind, regex, base_confidence)
 _PATTERNS: list[tuple[str, re.Pattern, float]] = [
     ("assumption", re.compile(
-        r"\b(?:we\s+)?assum(?:e|es|ing|ption(?:\s*[:\-])?)\s+(?:that\s+)?(?P<s>[^.\n]{8,300})",
-        re.I), 0.85),
+        r"\b(?:we\s+)?assum(?:e|es|ing|ption(?:\s*[:\-])?)" + _GAP + r"(?:that" + _GAP + r")?(?P<s>"
+        + _CLAUSE_TAIL + r"{8,300}(?!\w))", re.I), 0.85),
     ("assumption", re.compile(
-        r"\b(?:relies|relying|depends?)\s+on\s+(?:the\s+fact\s+that\s+)?(?P<s>[^.\n]{8,300})",
-        re.I), 0.7),
+        r"\b(?:relies|relying|depends?)" + _GAP + r"on" + _GAP
+        + r"(?:the" + _GAP + r"fact" + _GAP + r"that" + _GAP + r")?"
+        + r"(?P<s>" + _CLAUSE_TAIL + r"{8,300}(?!\w))", re.I), 0.7),
     ("assumption", re.compile(
-        r"\b(?:provided|as\s+long\s+as|expects?\s+that)\s+(?P<s>[^.\n]{8,300})", re.I), 0.6),
+        r"\b(?:provided|as\s+long\s+as|expects?\s+that)" + _GAP + r"(?P<s>"
+        + _CLAUSE_TAIL + r"{8,300}(?!\w))", re.I), 0.6),
     ("constraint", re.compile(
-        r"(?P<s>[^.\n;]{0,80}?\b(?:must\s+not|may\s+not|never|shall\s+not|"
-        r"do\s+not\s+ever)\s+[^.\n]{4,300})", re.I), 0.85),
+        _CLAUSE_START + r"(?P<s>" + _IN_CLAUSE +
+        r"{0,120}?\b(?:must\s+not|may\s+not|never|shall\s+not|"
+        r"do\s+not\s+ever)" + _GAP + _CLAUSE_TAIL + r"{4,300}(?!\w))", re.I), 0.85),
     ("requirement", re.compile(
-        r"(?P<s>[^.\n;]{0,80}?\b(?:must|shall|is\s+required\s+to|needs?\s+to)"
-        r"(?!\s+not)\s+[^.\n]{4,300})", re.I), 0.8),
+        _CLAUSE_START + r"(?P<s>" + _IN_CLAUSE +
+        # A prohibition is a constraint and only a constraint; without the
+        # `never` exclusion "must never X" was filed as both, recording the
+        # same sentence twice under two different types.
+        r"{0,120}?\b(?:must|shall|is\s+required\s+to|needs?\s+to)"
+        r"(?!\s+(?:not|never))" + _GAP + _CLAUSE_TAIL + r"{4,300}(?!\w))", re.I), 0.8),
     ("requirement", re.compile(
-        r"\bacceptance\s+criteri(?:a|on)\s*[:\-]\s*(?P<s>[^\n]{4,300})", re.I), 0.9),
+        r"\bacceptance\s+criteri(?:a|on)\s*[:\-]\s*"
+        + r"(?P<s>" + _CLAUSE_TAIL + r"{4,300}(?!\w))", re.I), 0.9),
     ("decision", re.compile(
         r"\b(?:we\s+)?(?:decided|decision(?:\s*[:\-])?|chose|will\s+use|agreed)\s+"
-        r"(?:to\s+|on\s+|that\s+)?(?P<s>[^.\n]{4,300})", re.I), 0.8),
+        r"(?:(?:to|on|that)" + _GAP + r")?"
+        + r"(?P<s>" + _CLAUSE_TAIL + r"{4,300}(?!\w))", re.I), 0.8),
 ]
 
 _INJECTION_PATTERNS = re.compile(
@@ -147,10 +195,24 @@ class DeterministicExtractor:
         # matches (highest confidence wins) so one sentence never yields two
         # near-duplicate variants (e.g. "Acceptance criteria: X must Y" and
         # "X must Y").
+        # Patterns run over prose only; spans and context still quote the
+        # original text, so a report points at what the author actually wrote.
+        # The injection screen above deliberately reads the raw text: a payload
+        # hidden inside a fence is still a payload.
+        # Characters that render as nothing must not change how the text is
+        # READ, but they must still be VISIBLE in what is recorded: a reader
+        # has to be able to see that a sentence carried them. So matching runs
+        # over a copy with them removed, while every statement and span is
+        # sliced from the original through `offsets`. A zero-width space
+        # inside "not" had re-typed a prohibition as a requirement, so control
+        # state mandated what the sentence forbids.
+        visible, offsets = _without_invisibles(text)
+        prose = _prose_only(visible)
         candidates = []
         for kind, pattern, base_conf in _PATTERNS:
-            for m in pattern.finditer(text):
-                statement = _clean(m.group("s"))
+            for m in pattern.finditer(prose):
+                statement = _clean(
+                    text[offsets[m.start("s")]:offsets[m.end("s")]])
                 if not _plausible(statement):
                     result.abstained += 1
                     continue
@@ -193,8 +255,12 @@ class DeterministicExtractor:
                 item.meta["demotion_reason"] = "untrusted source cannot mandate"
             result.items.append(item)
 
-        for m in _CHECKLIST.finditer(text):
-            statement = _clean(m.group("s"))
+        # Masking applies to EVERY extractor. Reading raw text here let a
+        # checklist hidden in an HTML comment or a code fence arrive as
+        # actionable open work — the exact harm the mask exists to prevent.
+        for m in _CHECKLIST.finditer(prose):
+            statement = _clean(
+                text[offsets[m.start("s")]:offsets[m.end("s")]])
             if not _plausible(statement):
                 result.abstained += 1
                 continue
@@ -207,7 +273,7 @@ class DeterministicExtractor:
             # payload arrives as actionable open work rather than as prose.
             result.items.append(Extracted(
                 kind="task", statement=statement,
-                span=m.group(0).strip(),
+                span=text[offsets[m.start()]:offsets[m.end()]].strip(),
                 confidence=_calibrate(0.85, source_authority),
                 criticality="medium", scope=scope,
                 suspected_injection=block_compromised,
@@ -220,16 +286,97 @@ class DeterministicExtractor:
 
 
 def normalize_statement(statement: str) -> str:
-    """Canonical key for deduplication (AD-004)."""
-    s = statement.lower()
-    s = re.sub(r"[^a-z0-9 ]+", " ", s)
+    """Canonical key for deduplication (AD-004).
+
+    Reducing to `[a-z0-9 ]` discarded every character outside ASCII, so two
+    statements collided whenever they differed only in what it threw away:
+    "must not exceed €500" and "must not exceed £500" produced one key, and
+    one of the two rules was dropped as a duplicate. In a non-Latin script the
+    loss was total — every statement reduced to the empty string, so a
+    Japanese or Russian project collapsed its whole control state onto a
+    single node per kind, this key being what seeds `stable_node_id`.
+
+    Compatibility forms are folded first so width and composition variants of
+    the same text still agree. Letters, digits, marks and symbols are kept;
+    only punctuation and separators become spaces.
+    """
+    s = unicodedata.normalize("NFKC", statement).casefold()
+    s = "".join(
+        c if unicodedata.category(c)[0] in "LNMS" else " " for c in s)
     s = re.sub(r"\b(the|a|an|is|are|was|were|be|been|that|this|it|its|of|to|in|on|for)\b",
                " ", s)
     return re.sub(r"\s+", " ", s).strip()
 
 
+# Regions of a comment that are not the author asserting something. A fenced
+# block is code, and code comments are full of modal verbs; a blockquote is
+# someone else's words, frequently quoted in order to disagree with them; an
+# HTML comment renders invisibly, so its text is something no reader of the
+# thread ever saw. Extracting any of them attributes a statement to an author
+# who did not make it — and in the HTML case, to one who could not have read
+# it either.
+#
+# The fence closer is tied to its opener by backreference. Matching a bare
+# three markers meant a longer fence never found its end and masked the rest
+# of the body, silently swallowing the prose that followed; `\r?` does the
+# same for CRLF text. Both failed closed in the wrong direction — losing real
+# statements rather than admitting code.
+_NON_PROSE = (
+    re.compile(r"^[ \t]*(?P<fence>`{3,}|~{3,}).*?"
+               r"(?:^[ \t]*(?P=fence)[`~]*[ \t]*\r?$|\Z)", re.S | re.M),
+    re.compile(r"^[ \t]*>.*$", re.M),
+    re.compile(r"<!--.*?(?:-->|\Z)", re.S),
+    # A four-space indented block is also code, and was masked only when fenced.
+    re.compile(r"(?:^(?:[ ]{4}|\t).*(?:\n|\Z))+", re.M),
+)
+
+# Zero-width and bidirectional formatting characters: invisible to a reader,
+# but they broke `\s`-based word boundaries, so "must no<ZWSP>t" no longer
+# matched the prohibition pattern and was recorded as a requirement instead.
+_INVISIBLE = re.compile(
+    r"[\u00ad\u200b-\u200f\u202a-\u202e\u2060-\u2064\ufeff]")
+
+
+def _without_invisibles(text: str) -> tuple[str, list[int]]:
+    """Text with zero-width characters removed, plus a map back to the source.
+
+    `offsets[i]` is the index in `text` of character `i` of the returned
+    string, with a final entry for the end, so a match on the stripped copy
+    can be sliced out of the original.
+    """
+    kept: list[str] = []
+    offsets: list[int] = []
+    for index, char in enumerate(text):
+        if not _INVISIBLE.match(char):
+            kept.append(char)
+            offsets.append(index)
+    offsets.append(len(text))
+    return "".join(kept), offsets
+
+# Markdown that decorates a line rather than forming part of the statement.
+_LEADING_MARKUP = re.compile(r"^(?:[-*+]\s+|\d+[.)]\s+|#{1,6}\s+|\|\s*)+")
+
+
+def _prose_only(text: str) -> str:
+    """Replace non-prose regions with hard boundaries, preserving offsets.
+
+    Masking to spaces was not a barrier: the gap between a cue word and its
+    clause could walk straight across the blanked region, stitching "The
+    exporter must" to "stream rows to the client" over a code fence and
+    recording a sentence nobody wrote. Masking to newlines makes the region a
+    run of blank lines, which every clause rule already treats as an end.
+    """
+    masked = list(text)
+    for pattern in _NON_PROSE:
+        for match in pattern.finditer(text):
+            for index in range(match.start(), match.end()):
+                masked[index] = "\n"
+    return "".join(masked)
+
+
 def _clean(s: str) -> str:
-    return re.sub(r"\s+", " ", s).strip().rstrip(".;,:")
+    collapsed = re.sub(r"\s+", " ", s).strip()
+    return _LEADING_MARKUP.sub("", collapsed).strip().rstrip(".;,:| ")
 
 
 def _plausible(statement: str) -> bool:

{causal_continuity_engine-0.1.2 → causal_continuity_engine-0.1.3}/causal_continuity_engine.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: causal-continuity-engine
-Version: 0.1.2
+Version: 0.1.3
 Summary: Causal Continuity Engine - continuity, causal invalidation, and proof for long-running coding agents
 Author: Thomas Albrecht
 License-Expression: Apache-2.0

{causal_continuity_engine-0.1.2 → causal_continuity_engine-0.1.3}/causal_continuity_engine.egg-info/SOURCES.txt

@@ -88,6 +88,8 @@ docs/TESTING.md
 docs/adr/ADR-INDEX.md
 docs/assets/demo.svg
 docs/assets/social-preview.png
+examples/backfill_github.py
+examples/quickstart.py
 justfile
 pyproject.toml
 requirements-dev.in

causal_continuity_engine-0.1.3/examples/backfill_github.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""Build a CCE project from a repository's real history, without a webhook.
+
+    GITHUB_TOKEN=$(gh auth token) python examples/backfill_github.py owner/repo
+
+Webhook delivery is the live ingest path, but every event type the engine
+understands is also retrievable from the REST API after the fact. This script
+reads issues and issue comments through the public API, re-shapes them into the
+webhook envelopes `ingest_github` already accepts, and feeds them in — so a
+project can be populated from months of existing history in one pass, on a
+laptop, with no App, tunnel, or public endpoint.
+
+It then prints what the engine extracted and a Resume Packet built from that
+real history. That packet is the thing worth reading: it is the product's
+actual output on real data rather than on fixtures.
+
+Standard library plus this package only. Read-only against GitHub; the project
+is written to a directory you name (default: a temporary one).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import tempfile
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+if not (ROOT / "causal_continuity_engine").is_dir():  # pragma: no cover
+    raise SystemExit("run this script from a checkout of the repository")
+sys.path.append(str(ROOT))
+
+from causal_continuity_engine.engine import Engine  # noqa: E402
+
+API = "https://api.github.com"
+PAGE_SIZE = 100
+
+
+def _get(path: str, token: str | None) -> object:
+    request = urllib.request.Request(
+        f"{API}{path}",
+        headers={
+            "Accept": "application/vnd.github+json",
+            "User-Agent": "cce-backfill-example",
+            **({"Authorization": f"Bearer {token}"} if token else {}),
+        })
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", "replace")[:200]
+        raise SystemExit(
+            f"GitHub returned {exc.code} for {path}: {detail}") from None
+    except urllib.error.URLError as exc:
+        raise SystemExit(f"cannot reach GitHub: {exc.reason}") from None
+
+
+def _paged(path: str, token: str | None, *, pages: int) -> list[dict]:
+    collected: list[dict] = []
+    for page in range(1, pages + 1):
+        joiner = "&" if "?" in path else "?"
+        batch = _get(
+            f"{path}{joiner}per_page={PAGE_SIZE}&page={page}", token)
+        if not isinstance(batch, list) or not batch:
+            break
+        collected.extend(item for item in batch if isinstance(item, dict))
+        if len(batch) < PAGE_SIZE:
+            break
+    return collected
+
+
+def _repository(meta: dict) -> dict:
+    return {"id": meta["id"], "full_name": meta["full_name"]}
+
+
+def _issue_event(issue: dict, meta: dict) -> dict:
+    """Reshape a REST issue into the `issues` webhook envelope."""
+    return {
+        "action": "opened",
+        "repository": _repository(meta),
+        "issue": {
+            "number": issue["number"],
+            "title": issue.get("title") or "",
+            "state": issue.get("state") or "open",
+            "body": issue.get("body") or "",
+            "author_association": issue.get("author_association") or "NONE",
+            "created_at": issue["created_at"],
+            "updated_at": issue.get("updated_at") or issue["created_at"],
+            "labels": [{"name": label.get("name", "")}
+                       for label in issue.get("labels", [])
+                       if isinstance(label, dict)],
+        },
+    }
+
+
+def _comment_event(comment: dict, issue_number: int, meta: dict) -> dict:
+    """Reshape a REST issue comment into the `issue_comment` envelope."""
+    return {
+        "action": "created",
+        "repository": _repository(meta),
+        "issue": {"number": issue_number},
+        "comment": {
+            "id": comment["id"],
+            "body": comment.get("body") or "",
+            "author_association": comment.get("author_association") or "NONE",
+            "created_at": comment["created_at"],
+            "updated_at": comment.get("updated_at") or comment["created_at"],
+        },
+    }
+
+
+def _frontier_event(head_sha: str, meta: dict) -> dict:
+    """A tracked-ref event, so evidence has an observed commit to attach to."""
+    return {
+        "ref": f"refs/heads/{meta.get('default_branch', 'main')}",
+        "before": "0" * 40,
+        "after": head_sha,
+        "created": True,
+        "deleted": False,
+        "forced": False,
+        "commits": [],
+        "repository": _repository(meta),
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("repository", help="owner/repo")
+    parser.add_argument(
+        "--dir", default=None,
+        help="project directory (default: a temporary one, discarded)")
+    parser.add_argument(
+        "--pages", type=int, default=2,
+        help=f"pages of {PAGE_SIZE} issues to read (default: 2)")
+    parser.add_argument(
+        "--token-env", default="GITHUB_TOKEN",
+        help="environment variable holding a token (default: GITHUB_TOKEN)")
+    args = parser.parse_args(argv)
+
+    if "/" not in args.repository:
+        raise SystemExit("repository must be owner/repo")
+    token = os.environ.get(args.token_env)
+    if not token:
+        print(f"no {args.token_env} set — using unauthenticated requests,"
+              " which are rate limited to 60/hour", file=sys.stderr)
+
+    print(f"reading {args.repository} ...")
+    meta = _get(f"/repos/{args.repository}", token)
+    if not isinstance(meta, dict):
+        raise SystemExit("unexpected repository response")
+    head = _get(
+        f"/repos/{args.repository}/commits/{meta['default_branch']}", token)
+    head_sha = head["sha"] if isinstance(head, dict) else "0" * 40
+
+    issues = _paged(
+        f"/repos/{args.repository}/issues?state=all", token, pages=args.pages)
+    # The issues endpoint returns pull requests too; they arrive again through
+    # their own event type, so keep this pass to genuine issues.
+    issues = [issue for issue in issues if "pull_request" not in issue]
+    comments = _paged(
+        f"/repos/{args.repository}/issues/comments", token, pages=args.pages)
+    print(f"  {len(issues)} issues, {len(comments)} comments,"
+          f" head {head_sha[:8]}")
+
+    holder = args.dir or tempfile.mkdtemp(prefix="cce-backfill-")
+    workdir = Path(holder)
+    workdir.mkdir(parents=True, exist_ok=True)
+    engine = Engine(workdir / "cce.db", tenant_id="ten_backfill",
+                    workdir=workdir)
+    try:
+        project = engine.create_project(
+            meta["name"], project_id="prj_backfill",
+            repository=meta["full_name"], repository_id=meta["id"])
+        project_id = project["project_id"] if isinstance(project, dict) \
+            else "prj_backfill"
+
+        events: list[tuple[str, str, dict]] = [
+            ("push", f"backfill-frontier-{head_sha[:8]}",
+             _frontier_event(head_sha, meta))]
+        for issue in issues:
+            events.append((
+                "issues", f"backfill-issue-{issue['number']}",
+                _issue_event(issue, meta)))
+        for comment in comments:
+            number = int(
+                str(comment.get("issue_url", "")).rsplit("/", 1)[-1] or 0)
+            if number:
+                events.append((
+                    "issue_comment", f"backfill-comment-{comment['id']}",
+                    _comment_event(comment, number, meta)))
+
+        nodes = invalidations = conflicts = 0
+        for event_name, delivery_id, payload in events:
+            report = engine.ingest_github(
+                project_id, event_name, delivery_id, payload)
+            if report:
+                nodes += len(report.get("nodes", []))
+                invalidations += len(report.get("invalidations", []))
+                conflicts += len(report.get("conflicts", []))
+        print(f"  ingested {len(events)} events -> {nodes} node(s),"
+              f" {invalidations} invalidation(s), {conflicts} conflict(s)")
+
+        print("\n== What the extractor typed as control state")
+        for entity in ("assumption", "constraint", "requirement", "decision"):
+            found = engine.graph.current(
+                project_id, entity, tenant_id=engine.tenant_id)
+            for node in found[:5]:
+                statement = (node.get("data", {}).get("statement")
+                             or node.get("data", {}).get("title") or "")
+                print(f"  [{entity}/{node.get('status')}] {statement[:96]}")
+            if found:
+                print(f"  ... {len(found)} {entity}(s) total")
+
+        print("\n== Resume Packet from real history")
+        print(engine.resume_packet(
+            project_id, token_budget=1500, fmt="markdown"))
+
+        print(f"\nproject kept at {workdir}" if args.dir else
+              f"\ntemporary project at {workdir} (delete when done)")
+    finally:
+        engine.close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())