diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..372df16 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +docs/demos/single-occurrence.log whitespace=cr-at-eol diff --git a/docs/demos/single-occurrence.log b/docs/demos/single-occurrence.log new file mode 100644 index 0000000..87059a3 --- /dev/null +++ b/docs/demos/single-occurrence.log @@ -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" ] +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"] diff --git a/docs/demos/single-occurrence.md b/docs/demos/single-occurrence.md new file mode 100644 index 0000000..e073f10 --- /dev/null +++ b/docs/demos/single-occurrence.md @@ -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. diff --git a/docs/demos/single-occurrence.timing b/docs/demos/single-occurrence.timing new file mode 100644 index 0000000..8378087 --- /dev/null +++ b/docs/demos/single-occurrence.timing @@ -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 diff --git a/docs/scheduled-catalogue-adapter.md b/docs/scheduled-catalogue-adapter.md index cf49c1d..a4a07d8 100644 --- a/docs/scheduled-catalogue-adapter.md +++ b/docs/scheduled-catalogue-adapter.md @@ -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. diff --git a/pyproject.toml b/pyproject.toml index a0f5963..c4e22d6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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] diff --git a/scheduled_catalogue_adapter.py b/scheduled_catalogue_adapter.py index d4bc5fe..ec5533f 100644 --- a/scheduled_catalogue_adapter.py +++ b/scheduled_catalogue_adapter.py @@ -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 @@ -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')) diff --git a/scripts/demo-single-occurrence.py b/scripts/demo-single-occurrence.py new file mode 100644 index 0000000..5dc2ed6 --- /dev/null +++ b/scripts/demo-single-occurrence.py @@ -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.") diff --git a/single_occurrence_projection.py b/single_occurrence_projection.py new file mode 100644 index 0000000..da8df23 --- /dev/null +++ b/single_occurrence_projection.py @@ -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}) diff --git a/test_scheduled_catalogue_adapter.py b/test_scheduled_catalogue_adapter.py index d622724..894ed74 100644 --- a/test_scheduled_catalogue_adapter.py +++ b/test_scheduled_catalogue_adapter.py @@ -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 diff --git a/test_single_occurrence_projection.py b/test_single_occurrence_projection.py new file mode 100644 index 0000000..b230bc6 --- /dev/null +++ b/test_single_occurrence_projection.py @@ -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)