Skip to content

Add TLA+ formal model checked on the Oracle runner - #87

Merged
sloik merged 1 commit into
masterfrom
formal/tla-oracle
Nov 13, 2026
Merged

sloik merged 1 commit into
masterfrom
formal/tla-oracle

Conversation

@sloik

@sloik sloik commented Nov 13, 2026

Copy link
Copy Markdown
Owner

Adds a TLA+ formal model of this library's public semantics, checked by TLC on the shared Oracle ARM64 runner.

What's in it

  • formal/*.tla and *.cfg: a finite model with named laws and invariants. formal/README.md maps each invariant to the Swift API it abstracts and states the model's limits.
  • formal/*.<mutant>.cfg: seeded bugs, each of which a named invariant must catch. run_tlc.sh fails if any mutant passes, so the invariants are shown to be able to fail.
  • .github/workflows/oracle-tla.yml: runs formal/run_tlc.sh on [self-hosted, Linux, ARM64, oracle, swift-tla, OptionalAPI].
    • It runs only on pushes to master and on manual dispatch.
    • A root-owned job-start guard on the host rejects every other ref, event, fork or repo before any step runs.
    • There is no pull_request trigger, and the hosted macOS Swift CI is unchanged.

TLC run on Oracle (this branch)

PASS  OptionalCoreLaws.ap_ignores_none_value.cfg  (mutant caught by ApNoneValue)
PASS  OptionalCoreLaws.async_fold_wrong_none_case.cfg  (mutant caught by AsyncAgreesWithSync)
PASS  OptionalCoreLaws.cast_ignores_type.cfg  (mutant caught by CastOtherTypeIsNone)
PASS  OptionalCoreLaws.cfg  (7200 distinct states found)
PASS  OptionalCoreLaws.coalesce_last_wins.cfg  (mutant caught by CoalesceIsFirstSome)
PASS  OptionalCoreLaws.decode_junk_becomes_some.cfg  (mutant caught by DecodeFailureIsNone)
PASS  OptionalCoreLaws.filter_keeps_all.cfg  (mutant caught by FilterKeepsIffPredicate)
PASS  OptionalCoreLaws.flatten_inner_none_becomes_some.cfg  (mutant caught by FlattenCases)
PASS  OptionalCoreLaws.nonewhen_same_as_somewhen.cfg  (mutant caught by NoneWhenComplementsSomeWhen)
PASS  OptionalCoreLaws.or_eager.cfg  (mutant caught by OrIsLazy)
PASS  OptionalEffectsLaws.cfg  (6720 distinct states found)
PASS  OptionalEffectsLaws.recover_always_calls.cfg  (mutant caught by RecoverIsLazy)
PASS  OptionalEffectsLaws.recover_replaces_nonempty.cfg  (mutant caught by RecoverKeepsNonEmpty)
PASS  OptionalEffectsLaws.sequence_skips_none.cfg  (mutant caught by SequenceAllOrNothing)
PASS  OptionalEffectsLaws.throw_error_built_eagerly.cfg  (mutant caught by ErrorBuiltLazily)
PASS  OptionalEffectsLaws.traverse_no_short_circuit.cfg  (mutant caught by TraverseShortCircuits)
PASS  OptionalEffectsLaws.try_error_becomes_some.cfg  (mutant caught by TryIsNoneWhenOrThrowThrows)
PASS  OptionalEffectsLaws.when_some_runs_on_none.cfg  (mutant caught by WhenSomeRunsIffSome)
TLC summary: 18 passed, 0 failed

Findings (behaviour of the Swift code, not changed here)

None: every modelled law holds for the code as read.

After merge

The merge push runs the Oracle job. If it doesn't run, use Actions → Oracle TLA verification → Run workflow on master.

Part of SPEC-ARGO-188 (owner request 2026-11-13). Runner runbook: Argo _System/oracle/swift-tla/README.md.

https://claude.ai/code/session_01HynYeNc83VZiXQP71aaZQ1

formal/ holds a finite TLA+ model of the library's public semantics, seeded
mutants that must be caught, and run_tlc.sh. oracle-tla.yml runs it on the
self-hosted Oracle ARM64 runner only on master pushes and manual dispatch.

Claude-Session: https://claude.ai/code/session_01HynYeNc83VZiXQP71aaZQ1
@sloik
sloik merged commit 6fab70c into master Nov 13, 2026
2 checks passed
@sloik
sloik deleted the formal/tla-oracle branch November 13, 2026 12:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant