Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -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
13 changes: 13 additions & 0 deletions docs/demos/stable-vocabulary/README.md
Original file line number Diff line number Diff line change
@@ -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.
35 changes: 35 additions & 0 deletions docs/demos/stable-vocabulary/demo.py
Original file line number Diff line number Diff line change
@@ -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')
6 changes: 6 additions & 0 deletions docs/demos/stable-vocabulary/output.log
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
Script started on 2026-11-13 12:38:15-05:00 [COMMAND="python3 docs/demos/stable-vocabulary/demo.py" <not executed on terminal>]
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"]
3 changes: 3 additions & 0 deletions docs/demos/stable-vocabulary/timing.log
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
0.051196 105
0.000015 111
0.000003 83
32 changes: 32 additions & 0 deletions docs/stable-vocabulary.md
Original file line number Diff line number Diff line change
@@ -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.
80 changes: 60 additions & 20 deletions github_routes.py
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down Expand Up @@ -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:
Expand Down
Loading
Loading