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
1 change: 1 addition & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
docs/demos/single-occurrence.log whitespace=cr-at-eol
10 changes: 10 additions & 0 deletions docs/demos/single-occurrence.log
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
Script started on 2026-11-13 16:29:28-05:00 [COMMAND=".venv/bin/python scripts/demo-single-occurrence.py --before /tmp/dearing-vk5/chaski-base.py" <not executed on terminal>]
BASE: REFUSED adapter configuration version unsupported
CANDIDATE at 599 verdict BLOCKED next 600
CANDIDATE at 600 verdict UNBLOCKED next None
CANDIDATE at 601 verdict UNBLOCKED next None
CANDIDATE at 86400 verdict UNBLOCKED next None
One original run identity across all due observations; no rebasing.
Fixture only; no reader process, graph, signing key or scheduler access.

Script done on 2026-11-13 16:29:28-05:00 [COMMAND_EXIT_CODE="0"]
20 changes: 20 additions & 0 deletions docs/demos/single-occurrence.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Single-occurrence adapter demo

Base `64e484528d1b7f6955dbdff01e9d4e2c2a367464` refuses adapter version3.
The candidate accepts the same pinned configuration, sets one deadline, and
retains the original run identity after that deadline without recurrence.
Candidate projection SHA256: `1fc27c0205159f6fe00f5b94ea2ae07cc876a29e29cf0eaa32f9e6a35606af1e`.

[Recording](single-occurrence.log), [timing](single-occurrence.timing).
Download both and replay with `scriptreplay --log-out single-occurrence.log --log-timing single-occurrence.timing`.
The log is a readable transcript too; no inline player is claimed.

```sh
git show 64e484528d1b7f6955dbdff01e9d4e2c2a367464:scheduled_catalogue_adapter.py > /tmp/catalogue-base.py
python scripts/demo-single-occurrence.py --before /tmp/catalogue-base.py
```

Uses the real config loader plus a pure typed-catalogue fixture. Before loader
uses current sibling imports; no reader process, graph, signing key or receiver
is invoked. This is source behavior, not runtime execution or admission.
The small sanitized recording follows the repository's existing demo storage.
7 changes: 7 additions & 0 deletions docs/demos/single-occurrence.timing
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
0.243415 57
0.000093 43
0.000058 46
0.000022 46
0.000026 48
0.000002 69
0.000071 74
13 changes: 13 additions & 0 deletions docs/scheduled-catalogue-adapter.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,3 +66,16 @@ It shows two initial reads, no extra idle reads, one new read on the next slot,
and retained deadline/outbox after deleting the required identity. The fake
reader asserts exact list-only argv. No graph, job execution, signing key,
profile or schedule is activated. The demo reuses development test fixtures.

Version 3 pins `SingleOccurrenceProjection`: the common fields plus exactly
`repeat_count: 1`, with no interval or weekday fields. The typed declaration
reader must return `repeat_count: 1` and `interval_s: null`. Its RDF Schedule
uses integer `schema:repeatCount` 1; other counts and mixed forms refuse.

The sole deadline is the pinned UTC anchor. Activation cannot be later than
that anchor. Once due, observations retain exactly that original signed run
identity and publish no next deadline. Late discovery never rebases it or
creates a catch-up slot. The existing durable outbox/slot receiver deduplicates
redelivery; the paired Shuttle policy must accept only this one slot and
apply its normal lateness check. No graph read failure becomes an empty success,
and no configuration change grants executable or identity admission.
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ py-modules = [
"chaski_version", "chaski_prime", "chaski_prime_state", "chaski_primer",
"alertmanager_sink", "async_scheduled_sink", "change_frames", "change_stream", "chaski", "command_sink",
"consumer_lease", "deadline_heap", "demo", "emitter", "external_event", "failure_family_adapter",
"fixed_outcome_executor", "github_routes", "github_work", "graph_sink", "incremental", "once", "scheduled_catalogue_adapter", "scheduled_event_sink", "scheduled_projection", "scheduled_receiver", "scheduled_sink_factory", "shuttle_process_port", "slot_receiver", "state_key_migration", "wall_clock_schedule", "weekly_projection",
"fixed_outcome_executor", "github_routes", "github_work", "graph_sink", "incremental", "once", "scheduled_catalogue_adapter", "scheduled_event_sink", "scheduled_projection", "scheduled_receiver", "scheduled_sink_factory", "shuttle_process_port", "single_occurrence_projection", "slot_receiver", "state_key_migration", "wall_clock_schedule", "weekly_projection",
]

[tool.pytest.ini_options]
Expand Down
8 changes: 5 additions & 3 deletions scheduled_catalogue_adapter.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
import sys
import time

from single_occurrence_projection import SingleOccurrenceProjection
from scheduled_projection import MAX_TIME, ScheduledProjection
from scheduled_receiver import ExecutionScope
from weekly_projection import WeeklyScheduledProjection
Expand Down Expand Up @@ -75,14 +76,15 @@ def load_config(path, digest):
raise ValueError('configuration changed')
config = _decode(raw)
_keys(config, ('version', 'projection', 'reader'))
if type(config['version']) is not int or config['version'] not in (1, 2):
if type(config['version']) is not int or config['version'] not in (1, 2, 3):
raise ValueError('adapter configuration version unsupported')
fields = ('scope', 'graph', 'target', 'owner', 'anchor_s', 'timezone', 'effective_at')
_keys(config['projection'], fields + (('interval_s',) if config['version'] == 1
else ('weekday', 'local_time')))
else ('weekday', 'local_time') if config['version'] == 2
else ('repeat_count',)))
projection = dict(config['projection'])
projection['scope'] = ExecutionScope(**projection['scope'])
kind = ScheduledProjection if config['version'] == 1 else WeeklyScheduledProjection
kind = {1: ScheduledProjection, 2: WeeklyScheduledProjection, 3: SingleOccurrenceProjection}[config['version']]
pinned = kind(**projection)
reader = config['reader']
_keys(reader, ('executable', 'root', 'env', 'timeout_s', 'output_limit'))
Expand Down
52 changes: 52 additions & 0 deletions scripts/demo-single-occurrence.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
"""One actual adapter configuration plus pure projection; no graph or command execution."""

import argparse
from dataclasses import asdict
import hashlib
import importlib.util
import json
from pathlib import Path
import sys
import tempfile

ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT))
current = importlib.import_module("scheduled_catalogue_adapter")
fixture = importlib.import_module("test_single_occurrence_projection")
projection, catalogue = fixture.projection, fixture.catalogue

args = argparse.ArgumentParser()
args.add_argument("--before", type=Path)
args = args.parse_args()
p = projection()
with tempfile.TemporaryDirectory() as folder:
path = Path(folder) / "config.json"
config = dict(
version=3,
projection=asdict(p),
reader=dict(executable="/unused/st", root=folder, env={}, timeout_s=2, output_limit=1048576),
)
path.write_text(json.dumps(config))
path.chmod(0o600)
digest = hashlib.sha256(path.read_bytes()).hexdigest()
if args.before:
spec = importlib.util.spec_from_file_location("scheduled_adapter_before", args.before)
before = importlib.util.module_from_spec(spec)
spec.loader.exec_module(before)
try:
before.load_config(str(path), digest)
except ValueError as exc:
print("BASE: REFUSED", str(exc))
else:
raise AssertionError("base unexpectedly accepted adapter v3")
loaded, _ = current.load_config(str(path), digest)
identities = []
for now in (599, 600, 601, 86400):
out = loaded.evaluate(catalogue(p), now)
record = out["records"][0]
print("CANDIDATE at", now, "verdict", record["verdict"], "next", out["next_checks"][p.scope.job])
if "event_id" in record:
identities.append(record["event_id"])
assert len(set(identities)) == 1
print("One original run identity across all due observations; no rebasing.")
print("Fixture only; no reader process, graph, signing key or scheduler access.")
79 changes: 79 additions & 0 deletions single_occurrence_projection.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
"""One pinned UTC occurrence; existing durable receiver owns execution/publication."""

from dataclasses import dataclass
import math

from scheduled_projection import MAX_TIME, _text, validated_job, validate_pins
from scheduled_receiver import ExecutionScope, run_id


@dataclass(frozen=True)
class SingleOccurrenceProjection:
scope: ExecutionScope
graph: str
target: str
owner: str
anchor_s: int
timezone: str
effective_at: int
repeat_count: int

def __post_init__(self):
validate_pins(self.scope, self.graph, self.target, self.owner, self.anchor_s, self.timezone, self.effective_at)
if type(self.repeat_count) is not int or self.repeat_count != 1:
raise ValueError("one explicit occurrence required")
if self.effective_at > self.anchor_s:
raise ValueError("activation cannot reinterpret a historical occurrence")

def evaluate(self, catalogue, now):
if type(now) not in (int, float) or not 0 <= now <= MAX_TIME or not math.isfinite(now):
raise ValueError("bounded trusted current UTC time required")
job = validated_job(catalogue, self.graph, self.scope)
fields = {
"iri",
"name",
"revision",
"owner",
"enabled",
"host",
"target",
"event",
"schedule",
"interval_s",
"anchor_s",
"timezone",
"repeat_count",
}
pins = dict(
revision=self.scope.revision,
host=self.scope.host,
target=self.target,
owner=self.owner,
anchor_s=self.anchor_s,
timezone=self.timezone,
)
if (
set(job) != fields
or type(job["enabled"]) is not bool
or job["interval_s"] is not None
or type(job["repeat_count"]) is not int
or job["repeat_count"] != 1
or type(job["anchor_s"]) is not int
or not all(_text(job[k]) for k in ("name", "event", "schedule"))
or any(job[k] != v for k, v in pins.items())
):
raise ValueError("declaration differs from pinned single occurrence and scope")
record = dict(item=self.scope.job, owner=self.owner, verdict="BLOCKED")
deadline = None
if job["enabled"]:
if now < self.anchor_s:
deadline = self.anchor_s
else:
# Never advance/rebase the slot. Late execution admission remains
# the signed receiver's decision; no fresh catch-up identity.
record.update(
verdict="UNBLOCKED",
event_id=run_id(self.scope, self.anchor_s),
evidence="One declared UTC occurrence; no recurrence or slot rebasing.",
)
return dict(version=1, scope=[self.scope.job], records=[record], next_checks={self.scope.job: deadline})
22 changes: 22 additions & 0 deletions test_scheduled_catalogue_adapter.py
Original file line number Diff line number Diff line change
Expand Up @@ -248,3 +248,25 @@ def test_projection_configuration_requires_an_object_not_pairs(setup):
config["projection"] = list(config["projection"].items())
result = run()
assert result.returncode == 2 and not result.stdout and count(counter) == 0


def test_version_three_one_occurrence_uses_real_reader_and_no_new_slot(setup):
p, config, _, report, counter, _, run = setup
config['version'] = 3
config['projection'].pop('interval_s')
config['projection'].update(repeat_count=1, effective_at=p.anchor_s)
body = catalogue(p)
body['jobs'][0].update(interval_s=None, repeat_count=1)
report.write_text(json.dumps(body))
assert run().returncode == 0 and count(counter) == 0
for now in (p.anchor_s, p.anchor_s+600, p.anchor_s+86400):
result = run(dict(now=now, items=[p.scope.job], changes=[]))
assert result.returncode == 0, result.stderr
out = json.loads(result.stdout)
from scheduled_receiver import run_id
assert out['records'][0]['event_id'] == run_id(p.scope, p.anchor_s)
assert out['next_checks'] == {p.scope.job: None}
body['jobs'][0]['repeat_count'] = 2
report.write_text(json.dumps(body))
result = run(dict(now=p.anchor_s, items=[p.scope.job], changes=[]))
assert result.returncode == 2 and not result.stdout
112 changes: 112 additions & 0 deletions test_single_occurrence_projection.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
from dataclasses import replace
import pytest

from emitter import Emitter, connect, observe
from scheduled_receiver import ExecutionScope, run_id
from single_occurrence_projection import SingleOccurrenceProjection


def projection():
return SingleOccurrenceProjection(
ExecutionScope("urn:test:job", "r1", "urn:test:host", "a" * 64, "test-agent", "urn:test:workflow"),
"urn:test:graph",
"urn:test:manifest",
"test-owner",
600,
"UTC",
500,
1,
)


def catalogue(p):
return dict(
schema_version=1,
source="declarations_only",
graph=p.graph,
membership=dict(status="required_identities_verified", required=[p.scope.job]),
executable_admission="UNKNOWN",
signed_run_status="UNKNOWN",
firing_eligibility="UNKNOWN",
jobs=[
dict(
iri=p.scope.job,
name="fixture",
revision=p.scope.revision,
owner=p.owner,
enabled=True,
host=p.scope.host,
target=p.target,
event="urn:test:event",
schedule="urn:test:schedule",
interval_s=None,
anchor_s=p.anchor_s,
timezone=p.timezone,
repeat_count=1,
)
],
)


def test_one_deadline_and_one_identity_even_after_missed_or_repeated_observations():
p = projection()
for now in (0, 500, 599.999):
out = p.evaluate(catalogue(p), now)
assert out["records"][0]["verdict"] == "BLOCKED"
assert out["next_checks"] == {p.scope.job: 600}
for now in (600, 601, 660, 86400, 253402300799):
out = p.evaluate(catalogue(p), now)
assert out["records"][0]["event_id"] == run_id(p.scope, 600)
assert out["next_checks"] == {p.scope.job: None}


def test_real_outbox_deduplicates_original_identity_across_restart(tmp_path):
p = projection()
e = Emitter("one-slot", ["unused"], 60, p.owner, event="scheduled", baseline_emits=True)
path = tmp_path / "state.sqlite"
for now in (599, 600, 601, 86400):
conn = connect(path)
try:
out = p.evaluate(catalogue(p), now)
observe(conn, e, out["records"], now, scope=set(out["scope"]))
finally:
conn.close()
conn = connect(path)
try:
rows = conn.execute("SELECT event_id FROM outbox").fetchall()
assert [r[0] for r in rows] == [run_id(p.scope, 600)]
finally:
conn.close()


@pytest.mark.parametrize(
"key,value",
[
("repeat_count", 2),
("repeat_count", True),
("interval_s", 60),
("anchor_s", 601),
("anchor_s", True),
("owner", "other"),
],
)
def test_changed_declaration_is_unknown_not_empty(key, value):
p = projection()
body = catalogue(p)
body["jobs"][0][key] = value
with pytest.raises(ValueError):
p.evaluate(body, 600)


def test_disabled_has_no_deadline_and_missing_membership_is_unknown():
p = projection()
body = catalogue(p)
body["jobs"][0]["enabled"] = False
assert p.evaluate(body, 600)["records"][0]["verdict"] == "BLOCKED"
assert p.evaluate(body, 600)["next_checks"][p.scope.job] is None
body["membership"]["required"] = []
with pytest.raises(ValueError):
p.evaluate(body, 600)
for kwargs in (dict(effective_at=601), dict(repeat_count=True), dict(repeat_count=2)):
with pytest.raises(ValueError):
replace(p, **kwargs)
Loading