diff --git a/.gitattributes b/.gitattributes index 372df16..99c50b8 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1 +1,3 @@ +# Preserve output-only terminal recording bytes for scriptreplay. +docs/demos/stable-vocabulary/output.log -text whitespace=cr-at-eol docs/demos/single-occurrence.log whitespace=cr-at-eol diff --git a/docs/demos/stable-vocabulary/README.md b/docs/demos/stable-vocabulary/README.md new file mode 100644 index 0000000..307dbec --- /dev/null +++ b/docs/demos/stable-vocabulary/README.md @@ -0,0 +1,13 @@ +# Builder demonstration + +Base `64e484528d1b7f6955dbdff01e9d4e2c2a367464` versus this candidate, +same private Reaction and firing input with an explicitly supplied neutral +instance namespace. Watch vocabulary derived from the instance base disappear while the firing identity +stays identical; an unpublished term refuses. No HTTP, credentials or graph writes. + +Reproduce: `python3 docs/demos/stable-vocabulary/demo.py`. +Replay the output-only terminal recording: +`scriptreplay --log-out output.log --log-timing timing.log`. +The small sanitized recording is retained in Git because this repository has no +established external demo destination. This proves source builders, not deployed +shape/native-reader compatibility or instance-allocation policy. diff --git a/docs/demos/stable-vocabulary/demo.py b/docs/demos/stable-vocabulary/demo.py new file mode 100644 index 0000000..80ba4b8 --- /dev/null +++ b/docs/demos/stable-vocabulary/demo.py @@ -0,0 +1,35 @@ +#!/usr/bin/env python3 +"""Same isolated builder input at base and candidate; no network or graph writes.""" +import importlib.util +from pathlib import Path +import subprocess +import sys +import tempfile +ROOT = Path(__file__).resolve().parents[3] +sys.path.insert(0, str(ROOT)) +import graph_sink # noqa: E402 — source-tree demo resolves its repository root +BASE = '64e484528d1b7f6955dbdff01e9d4e2c2a367464' +REACTION = {'label': 'fixture', 'condition': 'ASK {}', 'schedule': 'PT1M', + 'severity': 'info', 'action': ['notice'], 'owner': 'fixture', 'comment': 'fixture'} +EVENT = {'event_id': 'event-1', 'item': 'https://example.test/focus', 'observed_at': 1790400000} +def measure(label, module): + sink = module.QuipuFiringSink('https://unused.example.test', None, REACTION, ns='urn:fixture:') + bodies = sink.reaction_turtle() + sink.firing_turtle(EVENT) + old = any('<' + sink.ns + name + '>' in bodies for name in graph_sink._VOCABULARY) + identity = module.firing_iri('fixture', EVENT['event_id'], 'urn:fixture:') + print(f'{label}: instance-base vocabulary present={old}; firing={identity}', flush=True) + assert old == (label == 'base') + return identity +with tempfile.TemporaryDirectory() as tmp: + path = Path(tmp) / 'baseline.py' + path.write_bytes(subprocess.check_output(['git', '-C', str(ROOT), 'show', BASE + ':graph_sink.py'])) + spec = importlib.util.spec_from_file_location('baseline_graph_sink', path) + baseline = importlib.util.module_from_spec(spec) + spec.loader.exec_module(baseline) + assert measure('base', baseline) == measure('candidate', graph_sink) + try: + graph_sink.term('UnpublishedTerm') + except KeyError: + print('PASS: identical instance identity; unknown vocabulary refuses without a fallback.') + else: + raise AssertionError('unknown term accepted') diff --git a/docs/demos/stable-vocabulary/output.log b/docs/demos/stable-vocabulary/output.log new file mode 100644 index 0000000..6ef3905 --- /dev/null +++ b/docs/demos/stable-vocabulary/output.log @@ -0,0 +1,6 @@ +Script started on 2026-11-13 12:38:15-05:00 [COMMAND="python3 docs/demos/stable-vocabulary/demo.py" ] +base: instance-base vocabulary present=True; firing=urn:fixture:firing-64ff47bd29c61b7f94725b397f331d54 +candidate: instance-base vocabulary present=False; firing=urn:fixture:firing-64ff47bd29c61b7f94725b397f331d54 +PASS: identical instance identity; unknown vocabulary refuses without a fallback. + +Script done on 2026-11-13 12:38:15-05:00 [COMMAND_EXIT_CODE="0"] diff --git a/docs/demos/stable-vocabulary/timing.log b/docs/demos/stable-vocabulary/timing.log new file mode 100644 index 0000000..5b4bcf8 --- /dev/null +++ b/docs/demos/stable-vocabulary/timing.log @@ -0,0 +1,3 @@ +0.051196 105 +0.000015 111 +0.000003 83 diff --git a/docs/stable-vocabulary.md b/docs/stable-vocabulary.md new file mode 100644 index 0000000..a2402b4 --- /dev/null +++ b/docs/stable-vocabulary.md @@ -0,0 +1,32 @@ +# Stable writer vocabulary + +Reaction and ReactionFiring exports use 14 exact published ownership mappings. +Classes and owner/schedule/severity belong to Quipu; the other mapped properties +belong to Camayoc core. The independent snapshot in +`tests/fixtures/chaski-ownership.json` comes from public ownership.json SHA256 +`a389be53b74259d0c515ff6db16d602474dc5fe38dc6cc47f0f54a2d1347d34e`. +Unknown writer terms refuse; the instance namespace is not a vocabulary fallback. + +Historical readers accept exact legacy and published spellings. GitHub readers +also retain explicit read-only references to unpublished GitHub terms, pending +vocabulary ownership. No new ownership is inferred from a common prefix. +Duplicate event identity or completion aliases refuse rather than acknowledge +ambiguous evidence. Already completed legacy recovery is read-only and retains +its actual predicate; a new recovery uses canonical resolvedAt. + +This source change does not migrate deployment identities, stored data or frozen +events. Instance defaults remain unchanged pending the separate install-identity +contract. A neutral explicitly supplied namespace in the demo isolates vocabulary +from that outstanding identity work; it is not a new allocation policy. + +The graph receiver scope now includes the vocabulary version. Previously bound +original deliveries and recoveries refuse before setup or replay across this +boundary; their frozen payload and binding remain intact. IMPORTANT: older +unbound attempted outbox rows predate receiver bindings and cannot prove which +encoding was sent. Runtime adoption must inspect and disposition those rows, +existing bound debt, registration/shape compatibility and rollback before any +upgrade. This PR authorizes no drain, retry, rebinding or runtime activation. + +Run the private builder demo with `python3 docs/demos/stable-vocabulary/demo.py`. +Its base/candidate recording is in the adjacent directory; it proves builder +output and identity preservation, not native-store admission or deployment. diff --git a/github_routes.py b/github_routes.py index 5bd8691..fec0cff 100644 --- a/github_routes.py +++ b/github_routes.py @@ -51,6 +51,36 @@ import yaml AEGIS = "http://aegis.gastown.local/ontology/" + +# Read-only ownership crosswalk a389be53; unmapped GitHub terms stay explicit +# historical read references pending the vocabulary-owner child. No writer uses it. +_READ_TERMS = {'Verdict': 'https://w3id.org/intigraph/quipu/ns#Verdict', + 'commitSha': 'https://w3id.org/intigraph/camayoc/delivery/ns#commitSha', + 'evidenceHash': 'https://w3id.org/intigraph/camayoc/core/ns#evidenceHash', + 'occurredAt': 'https://w3id.org/intigraph/camayoc/delivery/ns#occurredAt', + 'outcome': 'https://w3id.org/intigraph/camayoc/core/ns#outcome', + 'predicateId': 'https://w3id.org/intigraph/camayoc/core/ns#predicateId', + 'reviewState': 'https://w3id.org/intigraph/camayoc/delivery/ns#reviewState', + 'signature': 'https://w3id.org/intigraph/camayoc/core/ns#signature', + 'targetRef': 'https://w3id.org/intigraph/camayoc/core/ns#targetRef', + 'tier': 'https://w3id.org/intigraph/camayoc/core/ns#tier', + 'verifier': 'https://w3id.org/intigraph/camayoc/core/ns#verifier'} + + +def _read_pattern(subject, name, obj): + legacy = AEGIS + name + canonical = _READ_TERMS.get(name) + if canonical is None: + return f"{subject} <{legacy}> {obj} . " + return (f"{{ {{ {subject} <{canonical}> {obj} }} UNION " + f"{{ {subject} <{legacy}> {obj} }} }} ") + + +def _read_class(subject, name): + canonical = _READ_TERMS.get(name) + legacy = f"{subject} a <{AEGIS + name}> . " + return (f"{{ {{ {subject} a <{canonical}> }} UNION {{ {legacy} }} }} " + if canonical is not None else legacy) SCHEMA = "chaski.github.work-request/v1" WAIT, READY = "WAIT", "READY" KINDS = ("review", "merge", "outside-contribution", "triage", "install", "announce", "conflict", "merge-stalled") @@ -390,43 +420,53 @@ def _q(text: str) -> str: def activity_query(graph: str, repo: str, since: str) -> str: if not IRI.match(graph) or not REPO.match(repo): raise ValueError("invalid graph or repo") - opt = "".join(f" OPTIONAL {{ ?a aegis:{p} ?{v} }}" for p, v in ( + opt = "".join(" OPTIONAL { " + _read_pattern("?a", p, "?"+v) + "}" for p, v in ( ("githubActorLogin", "actor"), ("commitSha", "sha"), ("githubState", "state"), ("githubMerged", "merged"), ("githubDraft", "draft"), ("githubBaseRef", "base"), ("githubStatus", "status"), ("githubConclusion", "conclusion"), ("githubRunAttempt", "attempt"), ("reviewState", "review"), ("githubPrerelease", "pre"), ("githubMergeable", "mergeable"), ("githubMergeableState", "mergeable_state"), ("githubBaseSha", "base_sha"))) - eopt = "".join(f" OPTIONAL {{ ?e aegis:{p} ?{v} }}" for p, v in ( + eopt = "".join(" OPTIONAL { " + _read_pattern("?e", p, "?"+v) + "}" for p, v in ( ("githubNumber", "num"), ("githubAuthorLogin", "author"), ("githubName", "name"), ("githubTagName", "tag"), ("githubUrl", "url"), ("githubCreatedAt", "created"))) - return ("PREFIX aegis: <%s> SELECT ?a ?kind ?at ?actor ?sha ?state ?merged ?draft ?base ?status " + return ("SELECT ?a ?kind ?at ?actor ?sha ?state ?merged ?draft ?base ?status " "?conclusion ?attempt ?review ?pre ?e ?etype ?num ?author ?name ?tag ?url ?thread ?tnum " - "?mergeable ?mergeable_state ?base_sha ?created " - "WHERE { GRAPH <%s> { ?repo aegis:githubFullName %s . " - "?a a aegis:GitHubActivity ; aegis:inGitHubRepository ?repo ; aegis:githubEventKind ?kind ; " - "aegis:occurredAt ?at ; aegis:aboutGitHubEntity ?e . FILTER(STR(?at) >= %s) " - "?e a ?etype . FILTER(STRSTARTS(STR(?etype), \"%sGitHub\"))%s%s " - "OPTIONAL { ?e aegis:onGitHubThread ?thread . ?thread aegis:githubNumber ?tnum } } }" - % (AEGIS, graph, _q(repo), _q(since), AEGIS, opt, eopt)) + "?mergeable ?mergeable_state ?base_sha ?created WHERE { GRAPH <"+graph+"> { " + + _read_pattern("?repo", "githubFullName", _q(repo)) + + _read_class("?a", "GitHubActivity") + + _read_pattern("?a", "inGitHubRepository", "?repo") + + _read_pattern("?a", "githubEventKind", "?kind") + + _read_pattern("?a", "occurredAt", "?at") + + _read_pattern("?a", "aboutGitHubEntity", "?e") + + "FILTER(STR(?at) >= "+_q(since)+") ?e a ?etype . " + + "FILTER(STRSTARTS(STR(?etype), "+_q(AEGIS+"GitHub")+"))"+opt+eopt + + " OPTIONAL { "+_read_pattern("?e", "onGitHubThread", "?thread") + + _read_pattern("?thread", "githubNumber", "?tnum")+" } } }") def verdict_query(repo: str, predicate: str = REVIEW_PREDICATE) -> str: - """Stored signed review verdicts about this repo's PRs, in any graph. The - graph is not trusted: every candidate goes through /verdict/verify.""" + """Candidates only; every row still requires native signature verification.""" if not REPO.match(repo): raise ValueError("invalid repo") - return ("PREFIX aegis: <%s> SELECT ?v ?target ?outcome ?hash ?tier ?verifier ?sig WHERE { GRAPH ?g { " - "?v a aegis:Verdict ; aegis:predicateId ?pred ; aegis:targetRef ?target ; aegis:outcome ?outcome ; " - "aegis:evidenceHash ?hash ; aegis:verifier ?verifier ; aegis:signature ?sig . " - "OPTIONAL { ?v aegis:tier ?tier } FILTER(STR(?pred) = %s) " - "FILTER(STRSTARTS(STR(?target), %s)) } }" % (AEGIS, _q(predicate), _q(f"github:pr:{repo}#"))) + fields = (("predicateId", "pred"), ("targetRef", "target"), ("outcome", "outcome"), + ("evidenceHash", "hash"), ("verifier", "verifier"), ("signature", "sig")) + return ("SELECT ?v ?target ?outcome ?hash ?tier ?verifier ?sig WHERE { GRAPH ?g { " + + _read_class("?v", "Verdict") + + "".join(_read_pattern("?v", name, "?"+variable) for name, variable in fields) + + "OPTIONAL { "+_read_pattern("?v", "tier", "?tier")+" } " + + "FILTER(STR(?pred) = "+_q(predicate)+") " + + "FILTER(STRSTARTS(STR(?target), "+_q(f"github:pr:{repo}#")+")) } }") def author_query(graph: str, repo: str) -> str: - return ("PREFIX aegis: <%s> SELECT ?pr ?agent WHERE { GRAPH <%s> { ?repo aegis:githubFullName %s . " - "?pr a aegis:GitHubPullRequest ; aegis:inGitHubRepository ?repo . } " - "GRAPH ?g { ?pr aegis:authoredByAgent ?agent } }" % (AEGIS, graph, _q(repo))) + if not IRI.match(graph) or not REPO.match(repo): + raise ValueError("invalid graph or repo") + return ("SELECT ?pr ?agent WHERE { GRAPH <"+graph+"> { " + + _read_pattern("?repo", "githubFullName", _q(repo)) + + _read_class("?pr", "GitHubPullRequest") + + _read_pattern("?pr", "inGitHubRepository", "?repo") + + " } GRAPH ?g { "+_read_pattern("?pr", "authoredByAgent", "?agent")+" } }") class QuipuFacts: diff --git a/graph_sink.py b/graph_sink.py index 67f9561..4294431 100644 --- a/graph_sink.py +++ b/graph_sink.py @@ -29,12 +29,25 @@ import socket import urllib.request +# Instance identity stays deployment-selected until its separate migration. NS = "http://aegis.gastown.local/ontology/" -# The quechua twin of the TERMS this sink reads (aegis-9dpcta). Only terms move: -# firing, reaction and focus IRIs stay under NS, because instance identity does -# not change in the transition. The served quipu does not honour -# owl:equivalentClass on reads, so the read-back names both term IRIs itself. -QUECHUA_NS = "https://scbrown.github.io/quechua/ns#" +QUECHUA_NS = "https://scbrown.github.io/quechua/ns#" # historical read alias +CORE = "https://w3id.org/intigraph/camayoc/core/ns#" +QUIPU = "https://w3id.org/intigraph/quipu/ns#" +QUECHUA = "https://w3id.org/intigraph/quechua/ns#" +# ownership.json SHA256 a389be53b74259d0c515ff6db16d602474dc5fe38dc6cc47f0f54a2d1347d34e. +_VOCABULARY = {**{name: QUIPU + name for name in + ("Reaction", "ReactionFiring", "owner", "schedule", "severity")}, + **{name: CORE + name for name in ("action", "condition", "eventId", "eventTypes", + "firedBy", "focus", "startedAt", "triggerKind", "resolvedAt")}} +VOCABULARY_VERSION = "intigraph-owned-a389be53/v1" + + +def term(name): + """An exact published vocabulary owner; never use the instance base.""" + return _VOCABULARY[name] + + USER_AGENT = "chaski/0.2" # A caller KIND of its own, so the emitter's writes are separable from chaski's # rule reads in quipu's per-caller accounting. @@ -120,16 +133,16 @@ def reaction_turtle(self) -> str: kind = r.get("trigger_kind", "schedule") if kind not in {"schedule", "event"}: raise ValueError("reaction trigger kind must be schedule or event") - event_types = (f" <{self.ns}eventTypes> {_lit(r['event_types'])} ;\n" + event_types = (f" <{term('eventTypes')}> {_lit(r['event_types'])} ;\n" if kind == "event" else "") return ( - f"<{self.reaction_iri()}> a <{self.ns}Reaction> ;\n" + f"<{self.reaction_iri()}> a <{term('Reaction')}> ;\n" f" {_lit(r['label'])} ;\n" - f" <{self.ns}triggerKind> {_lit(kind)} ; <{self.ns}schedule> {_lit(r['schedule'])} ;\n" + f" <{term('triggerKind')}> {_lit(kind)} ; <{term('schedule')}> {_lit(r['schedule'])} ;\n" f"{event_types}" - f" <{self.ns}condition> {_lit(r['condition'])} ;\n" - f" <{self.ns}severity> {_lit(r['severity'])} ; <{self.ns}action> {actions} ;\n" - f" <{self.ns}owner> {_lit(r['owner'])} ;\n" + f" <{term('condition')}> {_lit(r['condition'])} ;\n" + f" <{term('severity')}> {_lit(r['severity'])} ; <{term('action')}> {actions} ;\n" + f" <{term('owner')}> {_lit(r['owner'])} ;\n" f" {_lit(r['comment'])} .\n" ) @@ -138,13 +151,17 @@ def firing_turtle(self, event: dict) -> str: started = started.replace(microsecond=0).isoformat().replace("+00:00", "Z") focus = event["item"] if "://" in event["item"] else f"{self.ns}{event['item']}" return ( - f"<{firing_iri(self.reaction['label'], event['event_id'], self.ns)}> a <{self.ns}ReactionFiring> ;\n" - f" <{self.ns}firedBy> <{self.reaction_iri()}> ;\n" - f" <{self.ns}focus> <{focus}> ;\n" - f" <{self.ns}startedAt> \"{started}\"^^ ;\n" - f" <{self.ns}eventId> {_lit(event['event_id'])} .\n" + f"<{firing_iri(self.reaction['label'], event['event_id'], self.ns)}> a <{term('ReactionFiring')}> ;\n" + f" <{term('firedBy')}> <{self.reaction_iri()}> ;\n" + f" <{term('focus')}> <{focus}> ;\n" + f" <{term('startedAt')}> \"{started}\"^^ ;\n" + f" <{term('eventId')}> {_lit(event['event_id'])} .\n" ) + def _term_aliases(self, name): + return tuple(dict.fromkeys((term(name), NS + name, self.ns + name, + QUECHUA_NS + name, QUECHUA + name))) + def _expand(self, term): """Expand a compact IRI from a quipu /query answer to a full IRI. @@ -166,21 +183,21 @@ def _expand(self, term): def _received(self, event: dict) -> bool: iri = firing_iri(self.reaction["label"], event["event_id"], self.ns) - # Legacy OR quechua eventId, as a UNION of two single bound patterns (one - # request). Not a (p1|p2) path: the served quipu drops literal objects - # there (aegis-sxlptn), and eventId is a literal. - q = (f"SELECT ?e WHERE {{ {{ <{iri}> <{self.ns}eventId> ?e }} UNION " - f"{{ <{iri}> <{QUECHUA_NS}eventId> ?e }} }}") + # Explicit UNION preserves literal values on older native readers. + alternatives = [f"{{ <{iri}> <{predicate}> ?e }}" + for predicate in self._term_aliases("eventId")] + q = "SELECT ?e WHERE { " + " UNION ".join(alternatives) + " }" out = self._post("/query", {"query": q}) rows = out.get("rows") - if rows is None: + if out.get("error") or not isinstance(rows, list) or out.get("truncated", False) is not False: raise ConnectionError(f"read-back returned no rows field: {str(out)[:200]}") - return any(str(r.get("e")) == event["event_id"] for r in rows) + return len(rows) == 1 and isinstance(rows[0], dict) and rows[0].get("e") == event["event_id"] def setup_present(self) -> bool: """Direct type read-back for a one-shot's retained setup receipt.""" - query = (f"SELECT ?type WHERE {{ <{self.reaction_iri()}> a ?type . " - f"FILTER(?type = <{self.ns}Reaction>) }}") + types = ", ".join("<" + value + ">" for value in self._term_aliases("Reaction")) + query = (f"SELECT (STR(?kind) AS ?type) WHERE {{ <{self.reaction_iri()}> a ?kind . " + f"FILTER(?kind IN ({types})) }}") req = urllib.request.Request( self.base + "/query", data=json.dumps({"query": query}).encode(), headers={"Content-Type": "application/json", "User-Agent": USER_AGENT, @@ -190,8 +207,8 @@ def setup_present(self) -> bool: rows = out.get("rows") if out.get("error") or out.get("truncated") or not isinstance(rows, list): raise ConnectionError("setup read-back UNKNOWN") - expected = self.ns + "Reaction" - if any(not isinstance(row, dict) or self._expand(row.get("type")) != expected for row in rows): + expected = self._term_aliases("Reaction") + if any(not isinstance(row, dict) or self._expand(row.get("type")) not in expected for row in rows): raise ConnectionError("setup read-back has unexpected type") return bool(rows) @@ -216,33 +233,35 @@ def deliver(self, event: dict) -> None: def delivery_scope(self) -> dict: return {"kind": "quipu", "base": self.base, "namespace": self.ns, - "reaction": self.reaction["label"]} + "reaction": self.reaction["label"], "vocabulary": VOCABULARY_VERSION} def prepare_recovery(self, event: dict) -> dict: prior = event["prior"] if prior["emitter"] != self.reaction["label"]: raise ConnectionError("prior graph reaction identity changed") iri = firing_iri(prior["emitter"], prior["event_id"], self.ns) - out = self._post("/query", {"query": f"SELECT ?p ?e WHERE {{ <{iri}> ?p ?e }}"}) + out = self._post("/query", {"query": f"SELECT (STR(?predicate) AS ?p) ?e WHERE {{ <{iri}> ?predicate ?e }}"}) rows = out.get("rows") - if not isinstance(rows, list): + if (out.get("error") or out.get("truncated", False) is not False + or not isinstance(rows, list) or any(not isinstance(row, dict) for row in rows)): raise ConnectionError("prior firing read-back unavailable") - predicates = {self.ns + "eventId": self.ns, QUECHUA_NS + "eventId": QUECHUA_NS} + predicates = self._term_aliases("eventId") matches = [r for r in rows if self._expand(r.get("p")) in predicates] if len(matches) != 1 or matches[0].get("e") != prior["event_id"]: raise ConnectionError("missing or ambiguous prior graph firing") - namespace = predicates[self._expand(matches[0]["p"])] - prior_ends = [_datetime_value(r["e"]) for r in rows - if self._expand(r.get("p")) == namespace + "resolvedAt"] - receipt = {"iri": iri, "predicate": namespace + "resolvedAt", + prior_ends = [(self._expand(r.get("p")), _datetime_value(r["e"])) for r in rows + if self._expand(r.get("p")) in self._term_aliases("resolvedAt")] + receipt = {"iri": iri, "predicate": term("resolvedAt"), "delivery_scope": self.delivery_scope()} if prior_ends: if len(prior_ends) != 1: raise ConnectionError("ambiguous prior graph recovery") - ended = dt.datetime.fromisoformat(prior_ends[0].replace("Z", "+00:00")) + predicate, prior_end = prior_ends[0] + ended = dt.datetime.fromisoformat(prior_end.replace("Z", "+00:00")) if ended.tzinfo is None or ended.timestamp() > event["resolved_at"]: raise ConnectionError("prior graph recovery is not authoritative") - receipt["already_ended"] = prior_ends[0] + receipt["predicate"] = predicate # read-only reuse of an already completed legacy effect + receipt["already_ended"] = prior_end return receipt def resolve(self, event: dict) -> None: diff --git a/scheduled_catalogue_adapter.py b/scheduled_catalogue_adapter.py index ec5533f..637afda 100644 --- a/scheduled_catalogue_adapter.py +++ b/scheduled_catalogue_adapter.py @@ -21,12 +21,14 @@ from weekly_projection import WeeklyScheduledProjection SCHEMA = 'https://schema.org/' -QUECHUA = 'https://scbrown.github.io/quechua/ns#' +QUECHUA = 'https://w3id.org/intigraph/quechua/ns#' +LEGACY_QUECHUA = 'https://scbrown.github.io/quechua/ns#' # read compatibility TYPE = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type' ATTRIBUTES = [TYPE, *[SCHEMA+x for x in ('name', 'identifier', 'location', 'target', 'potentialAction', 'eventSchedule', 'repeatFrequency', 'scheduleTimezone', 'startDate', 'byDay', 'startTime')], - QUECHUA+'sourceKind', QUECHUA+'owner', QUECHUA+'enabled'] + *[namespace+name for namespace in (QUECHUA, LEGACY_QUECHUA) + for name in ('sourceKind', 'owner', 'enabled')]] def _pairs(pairs): diff --git a/test_github_routes.py b/test_github_routes.py index 7bf0a13..e9252e4 100644 --- a/test_github_routes.py +++ b/test_github_routes.py @@ -438,7 +438,10 @@ def test_queries_are_bounded_to_the_one_graph_and_validated(): with pytest.raises(ValueError): gr.activity_query("https://camayoc.local/operational/github", 'x/y" } DROP', "2026") vq = gr.verdict_query(REPO) - assert "a aegis:Verdict" in vq and "aegis:signature ?sig" in vq and '"github:pr:intigraph/camayoc#"' in vq + assert "" in vq + assert "" in vq + assert " ?sig" in vq + assert '"github:pr:intigraph/camayoc#"' in vq def test_config_refuses_unknown_fields_and_needs_members(): @@ -488,7 +491,7 @@ def do_POST(self): # noqa: N802 "as_of": {"tx": 7, "at": "2026-10-27T18:55:00Z", "basis": "recorded"}} else: q = body["query"] - rows = (author_rows if "authoredByAgent" in q else verdict_rows if "aegis:Verdict" in q + rows = (author_rows if "authoredByAgent" in q else verdict_rows if "SELECT ?v ?target" in q else activity_rows) out = {"rows": rows} data = json.dumps(out).encode() diff --git a/test_graph_sink.py b/test_graph_sink.py index 5c696c1..4a0c444 100644 --- a/test_graph_sink.py +++ b/test_graph_sink.py @@ -99,14 +99,14 @@ def test_started_at_is_the_frozen_observed_at_and_focus_is_an_iri(self): ttl = next(iter(self.q.firings().values())) self.assertIn('"2026-09-26T05:20:00Z"^^', ttl) ns = "http://aegis.gastown.local/ontology/" - self.assertIn(f"<{ns}focus> <{ns}aegis-abc123>", ttl) + self.assertIn(f"<{gs.term('focus')}> <{ns}aegis-abc123>", ttl) def test_the_reaction_is_written_once_and_is_typed(self): self.sink.deliver(EVENT) self.sink.deliver({**EVENT, "event_id": "sha256:bb"}) reactions = [v for k, v in self.q.snapshots.items() if k.startswith("chaski:reaction:")] self.assertEqual(len(reactions), 1) - self.assertIn("", reactions[0]) + self.assertIn(f"<{gs.term('Reaction')}>", reactions[0]) self.assertIn('"alert"', reactions[0]) def test_an_empty_answer_is_indeterminate_not_success(self): @@ -272,7 +272,7 @@ def test_the_read_back_is_one_request_a_union_and_no_join(self): def test_instance_identity_stays_under_the_legacy_namespace(self): self.assertTrue(self.firing.startswith(gs.NS + "firing-")) - self.assertIn(f"<{gs.NS}eventId>", self.sink.firing_turtle(EVENT)) # writers unchanged + self.assertIn(f"<{gs.term('eventId')}>", self.sink.firing_turtle(EVENT)) class Provenance(unittest.TestCase): diff --git a/test_recovery.py b/test_recovery.py index f19725a..21d62e7 100644 --- a/test_recovery.py +++ b/test_recovery.py @@ -271,6 +271,33 @@ def test_graph_namespace_and_endpoint_changes_refuse(self): self.assertEqual(self.send(sink), (0, 1)) self.assertIsNone(self.conn.execute("SELECT delivered_at FROM recovery_outbox").fetchone()[0]) + def test_graph_vocabulary_upgrade_fences_a_lost_original_answer(self): + sink = FakeGraph() + old_scope = sink.delivery_scope() + del old_scope['vocabulary'] + self.conn.execute("UPDATE outbox SET delivery_scope=?,attempts=1,last_error='lost answer'", + (json.dumps(old_scope),)) + before = self.conn.execute("SELECT payload,delivery_scope FROM outbox").fetchall() + with patch.object(sink, 'deliver', side_effect=AssertionError('old firing replay')), \ + patch.object(sink, 'setup', side_effect=AssertionError('old setup replay')): + self.assertEqual(em.deliver_pending(self.conn, sink, 102, 'control'), (0, 1)) + self.assertEqual(self.conn.execute("SELECT payload,delivery_scope FROM outbox").fetchall(), before) + self.assertIsNone(self.conn.execute("SELECT delivered_at FROM outbox").fetchone()[0]) + + def test_graph_vocabulary_upgrade_does_not_reinterpret_a_frozen_old_scope(self): + sink = FakeGraph() + old_scope = sink.delivery_scope() + del old_scope['vocabulary'] + self.conn.execute("UPDATE outbox SET delivery_scope=?,delivered_at=102", + (json.dumps(old_scope),)) + before = self.conn.execute("SELECT payload FROM outbox").fetchall() + self.recover() + with patch.object(sink, 'prepare_recovery', side_effect=AssertionError('old scope read')), \ + patch.object(sink, 'setup', side_effect=AssertionError('old scope write')): + self.assertEqual(self.send(sink), (0, 1)) + self.assertEqual(self.conn.execute("SELECT payload FROM outbox").fetchall(), before) + self.assertIsNone(self.conn.execute("SELECT delivered_at FROM recovery_outbox").fetchone()[0]) + PRIOR = {"event_id": "prior-id", "emitter": "control", "item": "one", "observed_at": 100} EVENT = {"event_id": "resolved-id", "prior": PRIOR, "resolved_at": 200} @@ -305,7 +332,7 @@ def _post(self, path, body): self.lost = False raise ConnectionError("lost graph answer") return {"asserted": 0 if len(self.writes) > 1 else 1} - return {"rows": self.rows if "?p ?e" in body["query"] else self.ends} + return {"rows": self.rows if "?predicate ?e" in body["query"] else self.ends} class SinkRecovery(unittest.TestCase): @@ -351,7 +378,7 @@ def test_graph_sets_only_exact_ended_predicate_and_retries_noop(self): body = sink.writes[0] self.assertEqual(body, sink.writes[1]) self.assertEqual(body["entity"], firing_iri("control", "prior-id")) - self.assertEqual(body["predicate"], NS + "resolvedAt") + self.assertEqual(body["predicate"], "https://w3id.org/intigraph/camayoc/core/ns#resolvedAt") self.assertEqual(body["value"]["datatype"], "http://www.w3.org/2001/XMLSchema#dateTime") self.assertEqual(body["source"], "chaski:recovery:resolved-id") @@ -381,9 +408,9 @@ def test_graph_compact_prefixes_name_the_same_firing(self): sink = FakeGraph() sink.rows = [{"p": prefix + "eventId", "e": PRIOR["event_id"]}] receipt = sink.prepare_recovery(EVENT) - self.assertEqual(receipt["predicate"], NS + "resolvedAt") + self.assertEqual(receipt["predicate"], "https://w3id.org/intigraph/camayoc/core/ns#resolvedAt") sink.resolve({**EVENT, "receipt": receipt}) - self.assertEqual(sink.writes[0]["predicate"], NS + "resolvedAt") + self.assertEqual(sink.writes[0]["predicate"], "https://w3id.org/intigraph/camayoc/core/ns#resolvedAt") def test_graph_compact_prior_close_is_still_recognised(self): sink = FakeGraph() diff --git a/test_stable_vocabulary.py b/test_stable_vocabulary.py new file mode 100644 index 0000000..7e765d5 --- /dev/null +++ b/test_stable_vocabulary.py @@ -0,0 +1,108 @@ +"""Canonical writer terms and exact historical graph receipts, without HTTP.""" +import unittest +import json +from pathlib import Path +from unittest import mock + +import graph_sink as gs +import github_routes +import scheduled_catalogue_adapter as catalogue +from types import SimpleNamespace + +OLD = 'http://aegis.gastown.local/ontology/' +CORE = 'https://w3id.org/intigraph/camayoc/core/ns#' +QP = 'https://w3id.org/intigraph/quipu/ns#' +REACTION = {'label': 'fixture', 'condition': 'ASK {}', 'schedule': 'PT1M', + 'severity': 'info', 'action': ['notice'], 'owner': 'fixture', 'comment': 'fixture'} +PRIOR = {'emitter': 'fixture', 'event_id': 'event-1'} + + +class StableVocabulary(unittest.TestCase): + def sink(self, ns=OLD): + return gs.QuipuFiringSink('https://unused.example.test', None, REACTION, ns=ns) + + def test_writer_terms_match_the_published_crosswalk_and_unknown_refuses(self): + rows = json.loads((Path(__file__).parent / 'tests/fixtures/chaski-ownership.json').read_text()) + self.assertEqual({gs.NS + name: iri for name, iri in gs._VOCABULARY.items()}, + {row['old']: row['new'] for row in rows}) + with self.assertRaises(KeyError): + gs.term('UnpublishedTerm') + + def test_mapped_terms_are_independent_of_the_instance_namespace(self): + sink = self.sink('urn:fixture:') + reaction = sink.reaction_turtle() + firing = sink.firing_turtle({'event_id': 'event-1', 'item': 'https://example.test/focus', + 'observed_at': 1790400000}) + self.assertIn('', reaction) + self.assertIn('<'+QP+'Reaction>', reaction) + self.assertIn('<'+QP+'ReactionFiring>', firing) + self.assertIn('<'+CORE+'eventId>', firing) + self.assertNotIn(OLD, reaction+firing) + self.assertNotIn('scbrown.github.io/quechua', reaction+firing) + + def test_new_recovery_of_old_firing_writes_canonical_resolved_at(self): + sink = self.sink() + with mock.patch.object(sink, '_post', return_value={ + 'rows': [{'p': OLD+'eventId', 'e': PRIOR['event_id']}]}): + receipt = sink.prepare_recovery({'prior': PRIOR, 'resolved_at': 1790400100}) + self.assertEqual(receipt['predicate'], CORE+'resolvedAt') + + def test_duplicate_canonical_and_legacy_event_identity_refuses(self): + sink = self.sink() + with mock.patch.object(sink, '_post', return_value={'rows': [ + {'p': OLD+'eventId', 'e': PRIOR['event_id']}, + {'p': CORE+'eventId', 'e': PRIOR['event_id']}]}): + with self.assertRaises(ConnectionError): + sink.prepare_recovery({'prior': PRIOR, 'resolved_at': 1790400100}) + + def test_completed_old_recovery_is_read_only_and_keeps_its_exact_predicate(self): + sink = self.sink() + ended = {'value': '2026-09-26T05:20:00Z', + 'datatype': 'http://www.w3.org/2001/XMLSchema#dateTime'} + with mock.patch.object(sink, '_post', return_value={'rows': [ + {'p': OLD+'eventId', 'e': PRIOR['event_id']}, + {'p': OLD+'resolvedAt', 'e': ended}]}): + receipt = sink.prepare_recovery({'prior': PRIOR, 'resolved_at': 1790400100}) + with mock.patch.object(sink, '_post', return_value={'rows': [{'e': ended}]}) as post: + sink.resolve({'receipt': receipt, 'resolved_at': 1790400100, 'event_id': 'end-1'}) + self.assertEqual(receipt['predicate'], OLD+'resolvedAt') + self.assertEqual([call.args[0] for call in post.call_args_list], ['/query']) + + def test_delivery_scope_records_the_vocabulary_boundary(self): + self.assertEqual(self.sink().delivery_scope()['vocabulary'], 'intigraph-owned-a389be53/v1') + + def test_truncated_or_error_answers_do_not_establish_exact_recovery(self): + sink = self.sink() + for extra in ({'truncated': True}, {'error': 'partial result'}): + with self.subTest(extra=extra), mock.patch.object(sink, '_post', return_value={ + 'rows': [{'p': OLD+'eventId', 'e': PRIOR['event_id']}], **extra}): + with self.assertRaises(ConnectionError): + sink.prepare_recovery({'prior': PRIOR, 'resolved_at': 1790400100}) + + def test_duplicate_event_readback_does_not_acknowledge_delivery(self): + sink = self.sink() + with mock.patch.object(sink, '_post', return_value={'rows': [ + {'e': PRIOR['event_id']}, {'e': PRIOR['event_id']}]}): + self.assertFalse(sink._received(PRIOR)) + + def test_github_readers_name_both_exact_spellings_for_every_mapped_term(self): + queries = ' '.join((github_routes.activity_query('https://example.test/graph', 'owner/repo', '2026'), + github_routes.verdict_query('owner/repo'), + github_routes.author_query('https://example.test/graph', 'owner/repo'))) + for name, canonical in github_routes._READ_TERMS.items(): + self.assertIn('<'+canonical+'>', queries) + self.assertIn('<'+OLD+name+'>', queries) + self.assertIn('UNION', queries) + self.assertIn('<'+OLD+'GitHubActivity>', queries) # unmapped vocabulary stays read-only legacy + + def test_catalogue_routes_old_and_published_quechua_changes_without_a_read(self): + projection = SimpleNamespace(graph='https://example.test/jobs', + scope=SimpleNamespace(job='urn:fixture:job')) + for base in (catalogue.QUECHUA, catalogue.LEGACY_QUECHUA): + request = {'now': 1, 'route': [{'graph': projection.graph, + 'attribute': base+'enabled', 'entity': projection.scope.job}]} + self.assertEqual(catalogue.changes(projection, None, request)['items'], [projection.scope.job]) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/fixtures/chaski-ownership.json b/tests/fixtures/chaski-ownership.json new file mode 100644 index 0000000..ff01bbe --- /dev/null +++ b/tests/fixtures/chaski-ownership.json @@ -0,0 +1,160 @@ +[ + { + "old": "http://aegis.gastown.local/ontology/Reaction", + "new": "https://w3id.org/intigraph/quipu/ns#Reaction", + "owner": "quipu/ns", + "declared_in": [], + "referenced_in": [ + "camayoc/core/ns", + "quipu/ns" + ] + }, + { + "old": "http://aegis.gastown.local/ontology/ReactionFiring", + "new": "https://w3id.org/intigraph/quipu/ns#ReactionFiring", + "owner": "quipu/ns", + "declared_in": [], + "referenced_in": [ + "quipu/ns" + ] + }, + { + "old": "http://aegis.gastown.local/ontology/action", + "new": "https://w3id.org/intigraph/camayoc/core/ns#action", + "owner": "camayoc/core/ns", + "declared_in": [ + "camayoc/core/ns" + ], + "referenced_in": [ + "camayoc/core/ns", + "quipu/ns" + ] + }, + { + "old": "http://aegis.gastown.local/ontology/condition", + "new": "https://w3id.org/intigraph/camayoc/core/ns#condition", + "owner": "camayoc/core/ns", + "declared_in": [ + "camayoc/core/ns" + ], + "referenced_in": [ + "camayoc/core/ns", + "quipu/ns" + ] + }, + { + "old": "http://aegis.gastown.local/ontology/eventId", + "new": "https://w3id.org/intigraph/camayoc/core/ns#eventId", + "owner": "camayoc/core/ns", + "declared_in": [ + "camayoc/core/ns" + ], + "referenced_in": [ + "camayoc/core/ns", + "quipu/ns" + ] + }, + { + "old": "http://aegis.gastown.local/ontology/eventTypes", + "new": "https://w3id.org/intigraph/camayoc/core/ns#eventTypes", + "owner": "camayoc/core/ns", + "declared_in": [ + "camayoc/core/ns" + ], + "referenced_in": [ + "camayoc/core/ns", + "quipu/ns" + ] + }, + { + "old": "http://aegis.gastown.local/ontology/firedBy", + "new": "https://w3id.org/intigraph/camayoc/core/ns#firedBy", + "owner": "camayoc/core/ns", + "declared_in": [ + "camayoc/core/ns" + ], + "referenced_in": [ + "camayoc/core/ns", + "quipu/ns" + ] + }, + { + "old": "http://aegis.gastown.local/ontology/focus", + "new": "https://w3id.org/intigraph/camayoc/core/ns#focus", + "owner": "camayoc/core/ns", + "declared_in": [ + "camayoc/core/ns" + ], + "referenced_in": [ + "camayoc/core/ns", + "quipu/ns" + ] + }, + { + "old": "http://aegis.gastown.local/ontology/owner", + "new": "https://w3id.org/intigraph/quipu/ns#owner", + "owner": "quipu/ns", + "declared_in": [], + "referenced_in": [ + "camayoc/personal-media/ns", + "quipu/ns" + ] + }, + { + "old": "http://aegis.gastown.local/ontology/resolvedAt", + "new": "https://w3id.org/intigraph/camayoc/core/ns#resolvedAt", + "owner": "camayoc/core/ns", + "declared_in": [ + "camayoc/core/ns" + ], + "referenced_in": [ + "camayoc/core/ns", + "quipu/ns" + ] + }, + { + "old": "http://aegis.gastown.local/ontology/schedule", + "new": "https://w3id.org/intigraph/quipu/ns#schedule", + "owner": "quipu/ns", + "declared_in": [], + "referenced_in": [ + "camayoc/core/ns", + "camayoc/homelab-infra/ns", + "quipu/ns" + ] + }, + { + "old": "http://aegis.gastown.local/ontology/severity", + "new": "https://w3id.org/intigraph/quipu/ns#severity", + "owner": "quipu/ns", + "declared_in": [], + "referenced_in": [ + "camayoc/homelab-infra/ns", + "quipu/ns" + ] + }, + { + "old": "http://aegis.gastown.local/ontology/startedAt", + "new": "https://w3id.org/intigraph/camayoc/core/ns#startedAt", + "owner": "camayoc/core/ns", + "declared_in": [ + "camayoc/core/ns" + ], + "referenced_in": [ + "camayoc/core/ns", + "quipu/ns" + ] + }, + { + "old": "http://aegis.gastown.local/ontology/triggerKind", + "new": "https://w3id.org/intigraph/camayoc/core/ns#triggerKind", + "owner": "camayoc/core/ns", + "declared_in": [ + "camayoc/core/ns" + ], + "referenced_in": [ + "camayoc/core/ns", + "quipu/ns" + ] + } +]