Skip to content

Commit edeb386

Browse files
fix(knowledge): bind card reads to checkout revisions
Carry revision and raw-byte digest through generated reads and pagination. Reject observed checkout drift before delivering content while keeping direct current reads explicit. Agent-assisted-by: Codex (implementation) Agent-assisted-by: Codex (independent internal review) Signed-off-by: jiangkuaixue123 <jiangxiaozhou111@163.com>
1 parent 3ce2137 commit edeb386

10 files changed

Lines changed: 145 additions & 16 deletions

File tree

‎docs/external-channels.md‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,8 @@ a wheel, or `evidence/`.
4141

4242
## Setting one up
4343

44-
You supply a checkout, an interpreter, and the backend it serves:
44+
You supply a checkout, an interpreter, and the backend it serves. The `git`
45+
executable must be available for read-time revision checks:
4546

4647
```bash
4748
git clone https://gitcode.com/cann/cannbot-knowledge.git ~/src/cannbot-knowledge
@@ -102,16 +103,21 @@ inferrsi cannbot search "CeilDivision 向上取整" --platform a2 --limit 100
102103
inferrsi cannbot read ops/ascendc/apis/utils_api/cpp_stdlib/math_functions/ceil_division
103104
```
104105

105-
The generated `open` command includes `--sha256 <card_sha256>`. Use that command
106-
and retain the same digest with `--page 2` (and later pages): a changed card is
107-
rejected. Every successful read returns the digest of the full card bytes.
106+
The generated `open` command includes `--revision <revision>` and
107+
`--sha256 <card_sha256>`. Retain both with `--page 2` and later pages. A changed
108+
checkout revision returns `version_mismatch`, even if the card bytes did not
109+
change; changed bytes are rejected even if HEAD did not change. The worker
110+
checks HEAD before and after reading, within the read timeout, and refuses an
111+
observed revision change. This is a drift check on a mutable checkout, not an
112+
atomic snapshot or a service for retrieving old versions. Every successful read
113+
returns the observed checkout revision and digest of the full card bytes.
108114
The upstream CLI uses `card_sha256` for a parsed metadata/body fingerprint;
109115
this adapter preserves it as `source_card_sha256`. Before emitting a selected
110116
hit, it verifies the source fingerprint using the approved checkout's parser
111117
and computes `card_sha256` over those same raw bytes. It returns neither the
112118
bytes nor private filesystem paths in search results.
113-
A locator-only read returns the current card and its digest, without promising
114-
continuity with an earlier search or page. A card digest does not validate its
119+
A locator-only read returns the current card, revision and digest, without
120+
promising continuity with an earlier search or page. A card digest does not validate its
115121
cited resources or make it eligible as campaign evidence.
116122

117123
`find --platform` overrides the grant's upstream platform. If neither supplies
@@ -151,7 +157,7 @@ silent.
151157
"status": "stable", "platforms": ["a2", "a3"],
152158
"card_sha256": "<raw-byte-sha256>",
153159
"source_card_sha256": "<upstream-card-fingerprint>",
154-
"open": "inferrsi cannbot read ops/... --sha256 <card_sha256>"}]
160+
"open": "inferrsi cannbot read ops/... --sha256 <card_sha256> --revision <revision>"}]
155161
}]
156162
```
157163

‎src/inferrsi/apps/cannbot/__init__.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,9 +97,11 @@ def search(
9797
read_prefix="inferrsi cannbot read",
9898
)
9999

100-
def read(self, locator: str, *, expected_sha256: str | None = None) -> str:
100+
def read(self, locator: str, *, expected_sha256: str | None = None,
101+
expected_revision: str | None = None) -> str:
101102
payload = self._project.read(
102103
locator, expected_sha256=expected_sha256, root=self.root,
104+
expected_revision=expected_revision,
103105
timeout=max(self.timeout, 15.0),
104106
)
105107
return str(payload.get("text") or "")

‎src/inferrsi/apps/cannbot/project.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,7 @@ def search(
208208

209209

210210
def read(locator: str, *, page: int = 1, expected_sha256: str | None = None,
211+
expected_revision: str | None = None,
211212
root: Path | None = None, timeout: float = 15.0) -> dict:
212213
if not isinstance(locator, str) or not locator.strip():
213214
raise ChannelFailure("cannbot read needs a locator from a search result")
@@ -217,9 +218,16 @@ def read(locator: str, *, page: int = 1, expected_sha256: str | None = None,
217218
not isinstance(expected_sha256, str) or not re.fullmatch(r"[0-9a-f]{64}", expected_sha256)
218219
):
219220
raise ChannelFailure("cannbot expected_sha256 must be a lowercase 64-hex digest")
221+
if expected_revision is not None and (
222+
not isinstance(expected_revision, str)
223+
or not re.fullmatch(r"[0-9a-f]{40}", expected_revision)
224+
):
225+
raise ChannelFailure("cannbot expected_revision must be a full lowercase Git revision")
220226
arguments = {"locator": locator, "page": page}
221227
if expected_sha256:
222228
arguments["expected_sha256"] = expected_sha256
229+
if expected_revision:
230+
arguments["expected_revision"] = expected_revision
223231
return _run(load_grant(root), "read", arguments, timeout=timeout)
224232

225233

‎src/inferrsi/apps/cannbot/read_worker.py‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -286,9 +286,36 @@ def search(upstream, arguments, *, timeout=60):
286286
}
287287

288288

289-
def read(upstream, arguments):
289+
def _revision(upstream, *, timeout):
290+
# Inherited repository-selection variables must not redirect this check.
291+
environment = {key: value for key, value in os.environ.items()
292+
if not key.startswith("GIT_")}
293+
try:
294+
result = capture(
295+
["git", "-C", str(upstream), "rev-parse", "--verify", "HEAD"],
296+
cwd=str(upstream), timeout=timeout, environment=environment,
297+
)
298+
except OutputLimitError:
299+
_fail("cannbot revision output exceeded 2 MiB")
300+
revision = result.stdout.decode("ascii", "replace").strip()
301+
if result.returncode or not re.fullmatch(r"[0-9a-f]{40}", revision):
302+
_fail("Cannot determine the approved cannbot checkout revision",
303+
state="version_mismatch")
304+
return revision
305+
306+
307+
def read(upstream, arguments, *, timeout=15):
308+
deadline = time.monotonic() + timeout
309+
revision = _revision(upstream, timeout=max(0, deadline - time.monotonic()))
310+
expected_revision = arguments.get("expected_revision")
311+
if expected_revision and revision != expected_revision:
312+
_fail("The cannbot revision changed since the search; search again",
313+
state="version_mismatch")
290314
locator = arguments["locator"]
291315
body = _card_bytes(upstream, locator)
316+
if _revision(upstream, timeout=max(0, deadline - time.monotonic())) != revision:
317+
_fail("The cannbot revision changed during the read; search again",
318+
state="version_mismatch")
292319
digest = hashlib.sha256(body).hexdigest()
293320
# Search reports what it matched; read reports what it actually returned.
294321
# Without both, a card edited between the two is served under the old
@@ -308,6 +335,7 @@ def read(upstream, arguments):
308335
return {
309336
"state": "ok",
310337
"locator": locator,
338+
"revision": revision,
311339
"page": page,
312340
"pages": max(1, (len(lines) + size - 1) // size),
313341
"line_count": len(lines),
@@ -328,7 +356,7 @@ def read(upstream, arguments):
328356
elif action == "search":
329357
result = search(upstream, arguments, timeout=timeout)
330358
elif action == "read":
331-
result = read(upstream, arguments)
359+
result = read(upstream, arguments, timeout=timeout)
332360
else:
333361
_fail("Unknown cannbot read action")
334362
except SystemExit:

‎src/inferrsi/apps/cli/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -317,6 +317,7 @@ def main(argv: list[str] | None = None) -> int:
317317
else:
318318
result = cannbot.project.read(
319319
args.locator, page=args.page, expected_sha256=args.sha256,
320+
expected_revision=args.revision,
320321
)
321322
_print(result)
322323
return 0

‎src/inferrsi/apps/cli/arguments.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,9 @@ def parser() -> argparse.ArgumentParser:
154154
"card changed since then",
155155
)
156156
cannbot_read.add_argument("--page", type=int, default=1)
157+
cannbot_read.add_argument(
158+
"--revision", help="Expected full checkout revision from a search result",
159+
)
157160
agents = commands.add_parser("agents", help="Record native host fresh-session handoffs")
158161
agent_actions = agents.add_subparsers(dest="agent_action", required=True)
159162
prepare = agent_actions.add_parser("prepare", help="Freeze a task for the current host")

‎src/inferrsi/knowledge/channels.py‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ class ChannelHit:
101101
card_sha256: str = ""
102102
source_card_sha256: str = ""
103103

104-
def view(self, *, read_prefix: str) -> dict:
104+
def view(self, *, read_prefix: str, revision: str | None = None) -> dict:
105105
record: dict[str, Any] = {
106106
"locator": self.locator,
107107
"title": self.title,
@@ -122,6 +122,8 @@ def view(self, *, read_prefix: str) -> dict:
122122
argv = [*shlex.split(read_prefix), self.locator]
123123
if self.card_sha256:
124124
argv.extend(["--sha256", self.card_sha256])
125+
if revision:
126+
argv.extend(["--revision", revision])
125127
record["open"] = shlex.join(argv)
126128
return record
127129

@@ -144,7 +146,10 @@ def view(self) -> dict:
144146
record["score_scale"] = self.score_scale
145147
record["count"] = len(self.items)
146148
if self.items:
147-
record["items"] = [item.view(read_prefix=self.read_prefix) for item in self.items]
149+
record["items"] = [
150+
item.view(read_prefix=self.read_prefix, revision=self.status.revision)
151+
for item in self.items
152+
]
148153
return record
149154

150155

@@ -166,7 +171,8 @@ def search(
166171
self, query: str, *, platform: str | None, limit: int, request: ChannelRequest
167172
) -> ChannelResult: ...
168173

169-
def read(self, locator: str, *, expected_sha256: str | None = None) -> str: ...
174+
def read(self, locator: str, *, expected_sha256: str | None = None,
175+
expected_revision: str | None = None) -> str: ...
170176

171177

172178
@dataclass

‎tests/test_cannbot_boundaries.py‎

Lines changed: 72 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,17 @@ def discovery():
3030
"index": {"built_repository_state": {"commit": REVISION}}}
3131

3232

33+
def commit_revision(source):
34+
subprocess.run(
35+
["git", "-C", str(source), "-c", "user.name=Synthetic Fixture",
36+
"-c", "user.email=fixture@example.invalid", "-c", "commit.gpgsign=false",
37+
"commit", "--allow-empty", "-qm", "synthetic revision"], check=True,
38+
)
39+
return subprocess.check_output(
40+
["git", "-C", str(source), "rev-parse", "HEAD"], text=True,
41+
).strip()
42+
43+
3344
@pytest.fixture
3445
def upstream(tmp_path, monkeypatch):
3546
home = tmp_path / "home"
@@ -42,7 +53,8 @@ def upstream(tmp_path, monkeypatch):
4253
(root / ".git").mkdir()
4354
monkeypatch.chdir(root)
4455
source = tmp_path / "upstream"
45-
(source / ".git").mkdir(parents=True)
56+
subprocess.run(["git", "init", "-q", str(source)], check=True)
57+
monkeypatch.setattr(sys.modules[__name__], "REVISION", commit_revision(source))
4658
(source / "knowledge/ops").mkdir(parents=True)
4759
card = source / "knowledge/ops/card.md"
4860
card.write_text("\n".join(f"synthetic line {i}" for i in range(401)))
@@ -160,10 +172,12 @@ def test_read_binds_all_pages_to_search_digest(upstream):
160172
hit = json.loads(result.stdout)["external"][0]["items"][0]
161173
opened = cli(*shlex.split(hit["open"])[1:])
162174
body = json.loads(opened.stdout)
175+
assert body["revision"] == REVISION
163176
assert body["card_sha256"] == hit["card_sha256"]
164177
assert body["has_more"]
165178
page = cli(*shlex.split(hit["open"])[1:], "--page", "2")
166179
assert json.loads(page.stdout)["card_sha256"] == hit["card_sha256"]
180+
assert json.loads(page.stdout)["revision"] == REVISION
167181
card.write_text("changed")
168182
changed = cli(*shlex.split(hit["open"])[1:], "--page", "2")
169183
assert changed.returncode != 0
@@ -181,6 +195,63 @@ def test_read_refuses_path_escape(upstream):
181195
assert "not knowledge" not in result.stdout + result.stderr
182196

183197

198+
@pytest.mark.parametrize("page", [1, 2])
199+
def test_read_rejects_revision_drift_with_unchanged_card(upstream, page):
200+
source, script, card = upstream
201+
script.write_text(
202+
"import json, sys\n"
203+
f"print(json.dumps({discovery()!r} if sys.argv[1] == 'discover' "
204+
f"else {search_payload(card)!r}))\n"
205+
)
206+
found = json.loads(cli("find", "synthetic", "--json").stdout)["external"][0]
207+
hit = found["items"][0]
208+
assert f"--revision {found['revision']}" in hit["open"]
209+
changed_revision = commit_revision(source)
210+
assert changed_revision != found["revision"]
211+
result = cli(*shlex.split(hit["open"])[1:], "--page", str(page))
212+
assert result.returncode != 0
213+
assert "revision changed since the search" in result.stderr
214+
assert "synthetic line" not in result.stdout + result.stderr
215+
current = project.read(hit["locator"], page=page)
216+
assert current["revision"] == changed_revision
217+
assert current["card_sha256"] == hit["card_sha256"]
218+
219+
220+
def test_read_rejects_revision_change_during_read(upstream, monkeypatch, capsys):
221+
from inferrsi.apps.cannbot import read_worker
222+
223+
source, _, _ = upstream
224+
original = read_worker._card_bytes
225+
226+
def changing_card(root, locator):
227+
raw = original(root, locator)
228+
commit_revision(source)
229+
return raw
230+
231+
monkeypatch.setattr(read_worker, "_card_bytes", changing_card)
232+
with pytest.raises(SystemExit):
233+
read_worker.read(source, {"locator": "ops/card", "expected_revision": REVISION})
234+
result = json.loads(capsys.readouterr().out)
235+
assert result["state"] == "version_mismatch"
236+
assert "text" not in result
237+
238+
239+
def test_read_uses_approved_checkout_not_inherited_git_directory(upstream, monkeypatch):
240+
source, _, _ = upstream
241+
monkeypatch.setenv("GIT_DIR", str(source / "nonexistent-git-directory"))
242+
assert project.read("ops/card", expected_revision=REVISION)["revision"] == REVISION
243+
244+
245+
@pytest.mark.parametrize("revision", ["", "HEAD", "abc", "A" * 40, "a" * 39, 42])
246+
def test_read_rejects_invalid_expected_revision_before_worker(monkeypatch, revision):
247+
def unexpected(*args, **kwargs):
248+
pytest.fail("invalid revision started a worker")
249+
250+
monkeypatch.setattr(project, "_run", unexpected)
251+
with pytest.raises(project.ChannelFailure, match="expected_revision"):
252+
project.read("ops/card", expected_revision=revision)
253+
254+
184255
def test_native_fingerprint_and_raw_byte_digest_are_distinct(upstream):
185256
_, script, card = upstream
186257
native = script.parent / "retrieval/index.py"

‎tests/test_cannbot_channel_acceptance.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -147,8 +147,10 @@ def test_read_returns_one_pinned_card():
147147
entry = next(item for item in result["external"] if item["channel"] == "cannbot-knowledge")
148148
hit = entry["items"][0]
149149
locator = hit["locator"]
150-
card = _run("cannbot", "read", locator, "--sha256", hit["card_sha256"])
150+
card = _run("cannbot", "read", locator, "--sha256", hit["card_sha256"],
151+
"--revision", entry["revision"])
151152
assert card["card_sha256"] == hit["card_sha256"]
153+
assert card["revision"] == entry["revision"]
152154
assert card["state"] == "ok"
153155
assert card["locator"] == locator
154156
assert card["text"].strip()

‎tests/test_knowledge_channels.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,9 @@ def test_hit_carries_score_scale_and_sha(corpus):
119119
hit = result["external"][0]["items"][0]
120120
assert hit["score_scale"] == "fake/v1"
121121
assert hit["card_sha256"] == "ab" * 32
122-
assert hit["open"] == "fake read ops/x/card --sha256 " + "ab" * 32
122+
assert hit["open"] == (
123+
"fake read ops/x/card --sha256 " + "ab" * 32 + " --revision " + "deadbeef" * 5
124+
)
123125

124126

125127
def test_failure_is_a_state_not_empty_list(corpus):

0 commit comments

Comments
 (0)