[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M760MN4Y9199ARAY85DWD08X":3,"skill-same:01M760MN4Y9199ARAY85DWD08X":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M760MN4Y9199ARAY85DWD08X","tla-formal-validation",null,"Required for any change to the core orchestrations (the durable session orchestration, session hydration and dehydration, and the Workflow controller and store). Teaches how to model the change in TLA+, update the existing models, run TLC with the repo runner, read the results, turn a counterexample into a fix and a regression test, and record the binding to the code.","microsoft\u002FPilotSwarm","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M69A6RNK492A5JSNBTXANKX5",16,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Ftla-formal-validation\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: tla-formal-validation\ndescription: Required for any change to the core orchestrations (the durable session orchestration, session hydration and dehydration, and the Workflow controller and store). Teaches how to model the change in TLA+, update the existing models, run TLC with the repo runner, read the results, turn a counterexample into a fix and a regression test, and record the binding to the code.\n---\n\n# TLA+ formal validation of the orchestrations\n\nPilotSwarm has two core orchestrations, the durable session orchestration and the Workflow\ncontroller, and a session hydration and dehydration path that moves a session between workers.\nAll three are durable, replayed and concurrent. A change to any of them must be checked with\nTLA+ before it ships. The models live in\n[`docs\u002Fformal\u002F`](..\u002F..\u002F..\u002Fdocs\u002Fformal\u002FREADME.md); that index maps each area to its models,\nits code, the head the models are bound to, and the last full run.\n\nA TLC result is a **bounded** check of a **model**. It is never a proof that the code is\ncorrect. Say what was checked, at which bounds, against which code head, and what was not.\n\n## When this skill is required\n\nUse it for any change that adds, removes, reorders or changes the meaning of a durable step,\na store transaction, a lock, a compare-and-swap, a timer, a retry, a cancellation or a\nlifecycle rule in:\n\n| Orchestration | Code | Models |\n|---|---|---|\n| Durable session orchestration | `packages\u002Fsdk\u002Fsrc\u002Forchestration.ts`, `packages\u002Fsdk\u002Fsrc\u002Forchestration\u002F`, frozen `orchestration_*.ts` \u002F `orchestration_*\u002F`, `orchestration-registry.ts`, and the durable contracts of their activities | `docs\u002Fformal\u002Fsession-orchestration\u002F` |\n| Session hydration and dehydration | the dehydrate, hydrate and checkpoint activities and the snapshot commit in `packages\u002Fsdk\u002Fsrc\u002Fsession-proxy.ts` and `session-manager.ts`; the orchestration's dehydrate and rehydrate paths (the hydration section of `orchestration\u002Flifecycle.ts`); `shouldRehydrate` timers; rehydration messages carried across continue-as-new; the blob and session-store contracts they rely on | `docs\u002Fformal\u002Fsession-orchestration\u002F` (the rehydration notice, timers and the snapshot step); add a module there, or a new folder for a larger change |\n| Workflow controller and store | `packages\u002Fsdk\u002Fsrc\u002Fworkflow\u002Fruntime.ts`, `store.ts`, `parallel.ts`, run admission in `service.ts`, the test-run (definition-test) path and the agent-host spawn path | `docs\u002Fformal\u002Fworkflow\u002F**` |\n\nA new orchestration version always needs this skill (see the \"New orchestration version\"\nstep in `.github\u002Fcopilot-instructions.md`). Pure UI, docs, prompts and logging changes that\ntouch no durable step do not.\n\nA change of the latest version also needs it: model the hand-off from the previous latest\n(what its continue-as-new input carries, what the new version reads, the KV it shares,\nunread queue messages, and a history in flight that must still replay on its own version),\nand how the deploy reaches it (duroxide does not route by version, so a worker without the\nnew version fails its items after repeated attempts). `VersionHandoff` and `RollingDeploy`\nin `docs\u002Fformal\u002Fsession-orchestration\u002F` are the pattern.\n\n## The method\n\nWork in this order. Each step names what it produces.\n\n1. **Read the code at a pinned commit.** Record the full SHA. Read the actual functions,\n   transactions and yields; do not model from memory or from comments. Produces: a list of\n   actors, durable state, steps and the transactions that order them.\n2. **Reuse before you add.** Find the model that already covers the area (the index lists\n   them). Extend or update it. Write a new module only for a boundary no model has. Keep\n   models small: one module checks one group of boundaries.\n3. **Design first, then the code.** For a new feature, first model the *intended* design (the\n   agreed rules) and check it; findings may change the design. Then bind the model to the\n   implementation: add the code's real behavior as switches (for example the code's path\n   versus the rule's path) and check both.\n4. **Abstract specification and refinement (for larger features).** Write a small module of\n   the intended behavior and check the detailed model against it as a TLC `PROPERTY`\n   (`Abs!Spec` with a refinement mapping). The fork + join models do this.\n5. **Table the cases** (next sections) with bounds small enough to finish.\n6. **Run TLC with the repo runner** and classify every result.\n7. **Turn every unexpected result into a finding**, then a fix and a regression test.\n8. **Write the correspondence notes**: for each model action, the code file:line at the bound\n   head, and whether it is code behavior, a rule to evaluate, or a model simplification.\n9. **Re-run after fixes** and update the folder README and the index.\n\n## Case tables and generated settings\n\nA case is a row in its folder's tables, never a hand-written file:\n\n- `cases.tsv`: `case_id\u003CTAB>case_id.cfg\u003CTAB>Module`, the cases to run, in order (a batch may list a\n  subset of `cases.json`, in the same order).\n- `cases.json`: one record per case: its expected result, its note and, under `tlc`, its TLC\n  settings (`comment`, `spec`, `constants`, `invariants`, `properties`, optional `view`, `deadlock`,\n  and `layout` only where the case departs from its module's template).\n- `tlc-templates.json`: per module, the order of its constants, the indentation and the layout.\n- `cases-retired.json`: cases whose code no longer exists, each with its reason; kept for the\n  record, never run.\n\nThe TLC settings files (`\u003Ccase>.cfg`) are **generated, never committed**\n(`docs\u002Fformal\u002F.gitignore`). `docs\u002Fformal\u002Ftlc_cases.py` renders them; `run-tlc.sh` and\n`check-packet.sh` call it before they read them.\n\n```bash\npython3 docs\u002Fformal\u002Ftlc_cases.py gen docs\u002Fformal\u002F\u003Cfolder>      # write the settings to look at them\npython3 docs\u002Fformal\u002Ftlc_cases.py gen --with-retired --all      # every folder, retired cases too\npython3 docs\u002Fformal\u002Ftlc_cases.py import docs\u002Fformal\u002F\u003Cfolder>   # table .cfg files written by hand\npython3 docs\u002Fformal\u002Ftlc_cases.py retire docs\u002Fformal\u002F\u003Cfolder> \u003Ccase_id> \"\u003Creason>\"\n```\n\n- A folder with `gen-cases.py` (the case table is a Python list there): edit the list and run the\n  script; it writes `cases.tsv`, `cases.json` and `tlc-templates.json` through `tlc_cases.attach()`.\n  Retire a case by listing it in the script's `RETIRED`. Never edit its `cases.json` by hand.\n- Any other folder: edit `cases.json` and `cases.tsv` (or write the settings by hand, then `import`).\n- A new model: write its settings as before, then `import`; the template comes from them.\n\n## Case taxonomy\n\nEvery case is one record in `cases.json` and one line in `cases.tsv`. Name the expected result\nin the record's `expected` and in its first comment line (`tlc.comment`).\n\n| Kind | Expected | Purpose |\n|---|---|---|\n| holds (safety) | PASS | Invariants hold in every reachable state of the bounded model. |\n| liveness | PASS | Something good eventually happens **under stated fairness** (`WF_vars(...)` on named actions). Name every fairness assumption. Free choices (cancel, stop, pause) are never forced, so check only properties conditioned on them (`stopReq ~> ...`). |\n| deliberate fault | violation of a named rule | One protection removed on purpose (a `Fault` constant). Proves the rule is not vacuous. Never a product defect. |\n| comparison | PASS or violation | A rejected or alternative design, or the code before a fix, run beside the rule to show the difference. |\n| witness | violation of a `W_...` predicate | Forbids a behavior you expect to be reachable; the violation proves it is reachable. |\n| refinement | PASS | The detailed model implements the abstract specification. |\n| implementation-shaped | violation (code) and PASS (fix) | When review or TLC finds a code divergence: one case reproduces the current code and must fail, one models the fix and must pass. |\n\n## Writing models and cases\n\n- Group `VARIABLES` by owner: store, work (effects, children), controller, history (ghost\n  flags read by no action). Every action states every variable it does not change\n  (`UNCHANGED`); check each new branch.\n- Split each durable activity into its transaction and its recorded result. A worker crash\n  between them re-runs the activity; bound it with `MaxCrash`. A replay is no step.\n- Name a fault or a code path with a constant; never edit the rule to make a case pass.\n- Guard every function application whose argument may be outside the domain with `IF`; do\n  not rely on short-circuit evaluation. Parenthesize mixed `\u002F\\` and `\\\u002F`, and `[][P]_v` when\n  `P` starts with a quantifier. Assign a primed variable before you read it.\n- Every case states `CHECK_DEADLOCK TRUE` or `CHECK_DEADLOCK FALSE` (`tlc.deadlock`). Use `TRUE` for safety\n  cases of a model with an explicit idle\u002Fdone stutter, so a stuck state is reported. Use\n  `FALSE` for fault and hazard cases.\n- Module names use letters and digits; case ids use `[a-z0-9.-]`. The runner rejects others.\n- Size each case to finish within the per-case limit (default 300 s at `-workers 2 -Xmx2g`).\n  Liveness cases cost more than safety cases: use the smallest bounds that still reach the\n  behavior, and say in the case note which bound you cut and why it still covers it.\n- A witness or a comparison is useless if its configuration cannot reach the behavior. Give\n  the values diversity (for example two branches that may succeed in either order).\n\n## Running TLC\n\nEach model folder has `run-tlc.sh` (tla2tools v1.7.4, TLC 2.19, pinned by sha256),\n`check-packet.sh` and `SHA256SUMS` (the committed inputs only: no `.cfg`). Both scripts are\nbyte-identical in every folder; change them everywhere at once. They need Java 17+ and Python 3.\n\n```bash\ncd docs\u002Fformal\u002F\u003Cfolder>\n.\u002Fcheck-packet.sh                                   # generate, guard, CHECK_DEADLOCK, hashes\nTLA_TOOLS=\u002Fpath\u002Fto\u002Ftools .\u002Frun-tlc.sh \u002Ftmp\u002Ftlc-out  # generate, SANY first, then every case\n# TLC_CASE_SECONDS=1200 only for a case documented as long\n```\n\nBoth find `tlc_cases.py` in the folder or above it. To run a folder on another machine (a\npacket), copy the folder, put `tlc_cases.py` in it, cut `cases.tsv` (and `cases.json`) to the\ncases to run, regenerate `SHA256SUMS`, and run `check-packet.sh`. The runner records the\ngenerator's and every settings file's sha256 in `\u003Cout>\u002Fgenerated.sha256`.\n\nRun TLC locally or on demand, on an isolated machine, with the repo runner. TLC does not run in\nCI yet. The script's exit code is not the verdict. Read\n`\u003Cout>\u002Fexecutions.tsv` and each case's `tlc.log`:\n\n| rc | Meaning |\n|---|---|\n| 0 | No violation in the bounded search: PASS. |\n| 12 | Safety violation: the log names the invariant and prints the trace. |\n| 13 | Liveness violation: the log prints a lasso (states, then a back edge or stuttering). |\n| 124 | Timed out: PARTIAL. Never a PASS, even with no violation so far. Shrink the case or give it a longer documented limit. |\n| other | Setup error (parse, ASSUME, Java): VOID. Fix the packet, not the verdict. |\n\nCompare each result with its expectation. Report the counts separately: PASS, expected\nviolations, unexpected results, PARTIAL and VOID.\n\n## From a counterexample to a fix\n\n1. Read the trace step by step: the actions, and the variables that changed at the last step.\n   For liveness, name the loop entry, the back edge and the fairness that should have forced\n   progress.\n2. Decide which it is: a **model error** (the model, a case or a bound is wrong: fix it and\n   record it), a **design finding** (the intended rule is wrong or missing: take it to the\n   design owner), or a **code finding** (the code departs from the rule).\n3. For a code finding: map each trace step to code (file:line at the head), state the rule it\n   breaks, propose the fix, and add an implementation-shaped case pair (code fails, fix passes).\n4. Add a regression test to the repo's suites that **fails without the fix** and passes with\n   it (see `.github\u002Fskills\u002Fadd-test\u002FSKILL.md`). A TLC counterexample alone is not a\n   reproduced defect.\n5. Re-run the affected cases and every case of each changed module.\n\nA model that misses a defect that review found is a finding too: the rule was too narrow.\nStrengthen the invariant, add the case, and record it.\n\n## Binding and correspondence\n\nEach folder README states: what the models cover; the code they are bound to (file:line at a\nnamed full commit); the case taxonomy and expected results; and a results summary (date, head,\ncounts, PARTIALs). Keep a `CORRESPONDENCE-\u003Chead8>.md` table per bound head: model action or\ndefinition, code file:line, and a label: **Code behavior**, **Rule to evaluate** or **Model\nsimplification**. When the code moves, re-read it, update the table and the head, and re-run.\nNever claim that a model covers a code version it was not checked against.\n\n## Before you finish\n\n- `.\u002Fcheck-packet.sh` passes in every changed folder; `SHA256SUMS` is regenerated last, over the\n  committed inputs only. No `.cfg` is committed; `python3 docs\u002Fformal\u002Ftlc_cases.py check --all`\n  (after `gen --with-retired --all`) shows that every case's settings generate.\n- The folder README and `docs\u002Fformal\u002FREADME.md` show the new head, date and counts.\n- Every unexpected result is classified, and every code finding has a fix and a regression\n  test that fails without it.\n- The PR description lists the cases run, their results, the PARTIALs and what is not covered.\n- `npm run check:privacy` passes; models and notes hold no deployment identifiers.\n","# TLA+ formal validation of the orchestrations\n\nPilotSwarm has two core orchestrations, the durable session orchestration and the Workflow\ncontroller, and a session hydration and dehydration path that moves a session between workers.\nAll three are durable, replayed and concurrent. A change to any of them must be checked with\nTLA+ before it ships. The models live in\n[`docs\u002Fformal\u002F`](..\u002F..\u002F..\u002Fdocs\u002Fformal\u002FREADME.md); that index maps each area to its models,\nits code, the head the models are bound to, and the last full run.\n\nA TLC result is a **bounded** check of a **model**. It is never a proof that the code is\ncorrect. Say what was checked, at which bounds, against which code head, and what was not.\n\n## When this skill is required\n\nUse it for any change that adds, removes, reorders or changes the meaning of a durable step,\na store transaction, a lock, a compare-and-swap, a timer, a retry, a cancellation or a\nlifecycle rule in:\n\n| Orchestration | Code | Models |\n|---|---|---|\n| Durable session orchestration | `packages\u002Fsdk\u002Fsrc\u002Forchestration.ts`, `packages\u002Fsdk\u002Fsrc\u002Forchestration\u002F`, frozen `orchestration_*.ts` \u002F `orchestration_*\u002F`, `orchestration-registry.ts`, and the durable contracts of their activities | `docs\u002Fformal\u002Fsession-orchestration\u002F` |\n| Session hydration and dehydration | the dehydrate, hydrate and checkpoint activities and the snapshot commit in `packages\u002Fsdk\u002Fsrc\u002Fsession-proxy.ts` and `session-manager.ts`; the orchestration's dehydrate and rehydrate paths (the hydration section of `orchestration\u002Flifecycle.ts`); `shouldRehydrate` timers; rehydration messages carried across continue-as-new; the blob and session-store contracts they rely on | `docs\u002Fformal\u002Fsession-orchestration\u002F` (the rehydration notice, timers and the snapshot step); add a module there, or a new folder for a larger change |\n| Workflow controller and store | `packages\u002Fsdk\u002Fsrc\u002Fworkflow\u002Fruntime.ts`, `store.ts`, `parallel.ts`, run admission in `service.ts`, the test-run (definition-test) path and the agent-host spawn path | `docs\u002Fformal\u002Fworkflow\u002F**` |\n\nA new orchestration version always needs this skill (see the \"New orchestration version\"\nstep in `.github\u002Fcopilot-instructions.md`). Pure UI, docs, prompts and logging changes that\ntouch no durable step do not.\n\nA change of the latest version also needs it: model the hand-off from the previous latest\n(what its continue-as-new input carries, what the new version reads, the KV it shares,\nunread queue messages, and a history in flight that must still replay on its own version),\nand how the deploy reaches it (duroxide does not route by version, so a worker without the\nnew version fails its items after repeated attempts). `VersionHandoff` and `RollingDeploy`\nin `docs\u002Fformal\u002Fsession-orchestration\u002F` are the pattern.\n\n## The method\n\nWork in this order. Each step names what it produces.\n\n1. **Read the code at a pinned commit.** Record the full SHA. Read the actual functions,\n   transactions and yields; do not model from memory or from comments. Produces: a list of\n   actors, durable state, steps and the transactions that order them.\n2. **Reuse before you add.** Find the model that already covers the area (the index lists\n   them). Extend or update it. Write a new module only for a boundary no model has. Keep\n   models small: one module checks one group of boundaries.\n3. **Design first, then the code.** For a new feature, first model the *intended* design (the\n   agreed rules) and check it; findings may change the design. Then bind the model to the\n   implementation: add the code's real behavior as switches (for example the code's path\n   versus the rule's path) and check both.\n4. **Abstract specification and refinement (for larger features).** Write a small module of\n   the intended behavior and check the detailed model against it as a TLC `PROPERTY`\n   (`Abs!Spec` with a refinement mapping). The fork + join models do this.\n5. **Table the cases** (next sections) with bounds small enough to finish.\n6. **Run TLC with the repo runner** and classify every result.\n7. **Turn every unexpected result into a finding**, then a fix and a regression test.\n8. **Write the correspondence notes**: for each model action, the code file:line at the bound\n   head, and whether it is code behavior, a rule to evaluate, or a model simplification.\n9. **Re-run after fixes** and update the folder README and the index.\n\n## Case tables and generated settings\n\nA case is a row in its folder's tables, never a hand-written file:\n\n- `cases.tsv`: `case_id\u003CTAB>case_id.cfg\u003CTAB>Module`, the cases to run, in order (a batch may list a\n  subset of `cases.json`, in the same order).\n- `cases.json`: one record per case: its expected result, its note and, under `tlc`, its TLC\n  settings (`comment`, `spec`, `constants`, `invariants`, `properties`, optional `view`, `deadlock`,\n  and `layout` only where the case departs from its module's template).\n- `tlc-templates.json`: per module, the order of its constants, the indentation and the layout.\n- `cases-retired.json`: cases whose code no longer exists, each with its reason; kept for the\n  record, never run.\n\nThe TLC settings files (`\u003Ccase>.cfg`) are **generated, never committed**\n(`docs\u002Fformal\u002F.gitignore`). `docs\u002Fformal\u002Ftlc_cases.py` renders them; `run-tlc.sh` and\n`check-packet.sh` call it before they read them.\n\n```bash\npython3 docs\u002Fformal\u002Ftlc_cases.py gen docs\u002Fformal\u002F\u003Cfolder>      # write the settings to look at them\npython3 docs\u002Fformal\u002Ftlc_cases.py gen --with-retired --all      # every folder, retired cases too\npython3 docs\u002Fformal\u002Ftlc_cases.py import docs\u002Fformal\u002F\u003Cfolder>   # table .cfg files written by hand\npython3 docs\u002Fformal\u002Ftlc_cases.py retire docs\u002Fformal\u002F\u003Cfolder> \u003Ccase_id> \"\u003Creason>\"\n```\n\n- A folder with `gen-cases.py` (the case table is a Python list there): edit the list and run the\n  script; it writes `cases.tsv`, `cases.json` and `tlc-templates.json` through `tlc_cases.attach()`.\n  Retire a case by listing it in the script's `RETIRED`. Never edit its `cases.json` by hand.\n- Any other folder: edit `cases.json` and `cases.tsv` (or write the settings by hand, then `import`).\n- A new model: write its settings as before, then `import`; the template comes from them.\n\n## Case taxonomy\n\nEvery case is one record in `cases.json` and one line in `cases.tsv`. Name the expected result\nin the record's `expected` and in its first comment line (`tlc.comment`).\n\n| Kind | Expected | Purpose |\n|---|---|---|\n| holds (safety) | PASS | Invariants hold in every reachable state of the bounded model. |\n| liveness | PASS | Something good eventually happens **under stated fairness** (`WF_vars(...)` on named actions). Name every fairness assumption. Free choices (cancel, stop, pause) are never forced, so check only properties conditioned on them (`stopReq ~> ...`). |\n| deliberate fault | violation of a named rule | One protection removed on purpose (a `Fault` constant). Proves the rule is not vacuous. Never a product defect. |\n| comparison | PASS or violation | A rejected or alternative design, or the code before a fix, run beside the rule to show the difference. |\n| witness | violation of a `W_...` predicate | Forbids a behavior you expect to be reachable; the violation proves it is reachable. |\n| refinement | PASS | The detailed model implements the abstract specification. |\n| implementation-shaped | violation (code) and PASS (fix) | When review or TLC finds a code divergence: one case reproduces the current code and must fail, one models the fix and must pass. |\n\n## Writing models and cases\n\n- Group `VARIABLES` by owner: store, work (effects, children), controller, history (ghost\n  flags read by no action). Every action states every variable it does not change\n  (`UNCHANGED`); check each new branch.\n- Split each durable activity into its transaction and its recorded result. A worker crash\n  between them re-runs the activity; bound it with `MaxCrash`. A replay is no step.\n- Name a fault or a code path with a constant; never edit the rule to make a case pass.\n- Guard every function application whose argument may be outside the domain with `IF`; do\n  not rely on short-circuit evaluation. Parenthesize mixed `\u002F\\` and `\\\u002F`, and `[][P]_v` when\n  `P` starts with a quantifier. Assign a primed variable before you read it.\n- Every case states `CHECK_DEADLOCK TRUE` or `CHECK_DEADLOCK FALSE` (`tlc.deadlock`). Use `TRUE` for safety\n  cases of a model with an explicit idle\u002Fdone stutter, so a stuck state is reported. Use\n  `FALSE` for fault and hazard cases.\n- Module names use letters and digits; case ids use `[a-z0-9.-]`. The runner rejects others.\n- Size each case to finish within the per-case limit (default 300 s at `-workers 2 -Xmx2g`).\n  Liveness cases cost more than safety cases: use the smallest bounds that still reach the\n  behavior, and say in the case note which bound you cut and why it still covers it.\n- A witness or a comparison is useless if its configuration cannot reach the behavior. Give\n  the values diversity (for example two branches that may succeed in either order).\n\n## Running TLC\n\nEach model folder has `run-tlc.sh` (tla2tools v1.7.4, TLC 2.19, pinned by sha256),\n`check-packet.sh` and `SHA256SUMS` (the committed inputs only: no `.cfg`). Both scripts are\nbyte-identical in every folder; change them everywhere at once. They need Java 17+ and Python 3.\n\n```bash\ncd docs\u002Fformal\u002F\u003Cfolder>\n.\u002Fcheck-packet.sh                                   # generate, guard, CHECK_DEADLOCK, hashes\nTLA_TOOLS=\u002Fpath\u002Fto\u002Ftools .\u002Frun-tlc.sh \u002Ftmp\u002Ftlc-out  # generate, SANY first, then every case\n# TLC_CASE_SECONDS=1200 only for a case documented as long\n```\n\nBoth find `tlc_cases.py` in the folder or above it. To run a folder on another machine (a\npacket), copy the folder, put `tlc_cases.py` in it, cut `cases.tsv` (and `cases.json`) to the\ncases to run, regenerate `SHA256SUMS`, and run `check-packet.sh`. The runner records the\ngenerator's and every settings file's sha256 in `\u003Cout>\u002Fgenerated.sha256`.\n\nRun TLC locally or on demand, on an isolated machine, with the repo runner. TLC does not run in\nCI yet. The script's exit code is not the verdict. Read\n`\u003Cout>\u002Fexecutions.tsv` and each case's `tlc.log`:\n\n| rc | Meaning |\n|---|---|\n| 0 | No violation in the bounded search: PASS. |\n| 12 | Safety violation: the log names the invariant and prints the trace. |\n| 13 | Liveness violation: the log prints a lasso (states, then a back edge or stuttering). |\n| 124 | Timed out: PARTIAL. Never a PASS, even with no violation so far. Shrink the case or give it a longer documented limit. |\n| other | Setup error (parse, ASSUME, Java): VOID. Fix the packet, not the verdict. |\n\nCompare each result with its expectation. Report the counts separately: PASS, expected\nviolations, unexpected results, PARTIAL and VOID.\n\n## From a counterexample to a fix\n\n1. Read the trace step by step: the actions, and the variables that changed at the last step.\n   For liveness, name the loop entry, the back edge and the fairness that should have forced\n   progress.\n2. Decide which it is: a **model error** (the model, a case or a bound is wrong: fix it and\n   record it), a **design finding** (the intended rule is wrong or missing: take it to the\n   design owner), or a **code finding** (the code departs from the rule).\n3. For a code finding: map each trace step to code (file:line at the head), state the rule it\n   breaks, propose the fix, and add an implementation-shaped case pair (code fails, fix passes).\n4. Add a regression test to the repo's suites that **fails without the fix** and passes with\n   it (see `.github\u002Fskills\u002Fadd-test\u002FSKILL.md`). A TLC counterexample alone is not a\n   reproduced defect.\n5. Re-run the affected cases and every case of each changed module.\n\nA model that misses a defect that review found is a finding too: the rule was too narrow.\nStrengthen the invariant, add the case, and record it.\n\n## Binding and correspondence\n\nEach folder README states: what the models cover; the code they are bound to (file:line at a\nnamed full commit); the case taxonomy and expected results; and a results summary (date, head,\ncounts, PARTIALs). Keep a `CORRESPONDENCE-\u003Chead8>.md` table per bound head: model action or\ndefinition, code file:line, and a label: **Code behavior**, **Rule to evaluate** or **Model\nsimplification**. When the code moves, re-read it, update the table and the head, and re-run.\nNever claim that a model covers a code version it was not checked against.\n\n## Before you finish\n\n- `.\u002Fcheck-packet.sh` passes in every changed folder; `SHA256SUMS` is regenerated last, over the\n  committed inputs only. No `.cfg` is committed; `python3 docs\u002Fformal\u002Ftlc_cases.py check --all`\n  (after `gen --with-retired --all`) shows that every case's settings generate.\n- The folder README and `docs\u002Fformal\u002FREADME.md` show the new head, date and counts.\n- Every unexpected result is classified, and every code finding has a fix and a regression\n  test that fails without it.\n- The PR description lists the cases run, their results, the PARTIALs and what is not covered.\n- `npm run check:privacy` passes; models and notes hold no deployment identifiers.\n",{"name":5,"description":7},"main","7ee6eff4333dba9512363bc67d1fe177d9568636",".github\u002Fskills\u002Ftla-formal-validation",10,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-15 00:36:04",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add microsoft\u002FPilotSwarm --skill tla-formal-validation",{"tool":39,"command":40},"bunx","bunx skills add microsoft\u002FPilotSwarm --skill tla-formal-validation",{"tool":42,"command":43},"pnpm","pnpm dlx skills add microsoft\u002FPilotSwarm --skill tla-formal-validation","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Ftla-formal-validation\u002FSKILL.md",true,[],[48,55,62,69,76,83],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":19},"01M760N7TCZBTY635MYZQ8YAB0","workflow-testing","Load before you test a Workflow with mocked effects — the test, test_respond and test_advance operations, fixtures, interception ids, valid answers, the virtual clock, test evidence and what a test run does not prove.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Fpackages\u002Fsdk\u002Fplugins\u002Fworkflow\u002Ftest-mode-skills\u002Fworkflow-testing\u002FSKILL.md",[],[],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":19},"01M760N4RKD6BMYPGHD490SNN2","workflow-tools","Every argument of the Workflow tools, testing a revision, package definitions and the refusals you can fix. Load when a Workflow tool's short description is not enough.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Fpackages\u002Fsdk\u002Fplugins\u002Fworkflow\u002Fskills\u002Fworkflow-tools\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M760N1P2VTGVE6C4N5WF3FVR","workflow-reference","Field reference for Workflow YAML (root keys, every state type, bindings, outputs, runtime error codes), what the engine guarantees, and a review fan-out example. For design, call load_skill with name workflow-authoring.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Fpackages\u002Fsdk\u002Fplugins\u002Fworkflow\u002Fskills\u002Fworkflow-reference\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M760MZ5CFSAX4FYMEXZJBGM2","workflow-patterns","Load when one Workflow must run different nodes in its branches at the same time (a different prompt or model for each branch), or loops back to a state (a polling loop). Named branches, the router pattern, examples that compile.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Fpackages\u002Fsdk\u002Fplugins\u002Fworkflow\u002Fskills\u002Fworkflow-patterns\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M760MWKBDJFEECRFAF3BAVQ2","workflow-authoring","Load before you create, edit, publish or run a Workflow (pilotswarm.dev\u002Fv1) — choosing states, bounded graphs, bindings, typed contracts, agent and parallel states, the lifecycle and failure diagnosis.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Fpackages\u002Fsdk\u002Fplugins\u002Fworkflow\u002Fskills\u002Fworkflow-authoring\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":105},"01M69A9CY8CXHED3AFC8DAT9G0","pilotswarm-three-tier","Reference for adding a Tier 3 worker AKS cluster to a PilotSwarm deployment. Covers provisioning, identity, Dockerfile changes, entrypoint, manifests, and verification.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Ftemplates\u002Fbuilder-agents\u002Fskills\u002Fpilotswarm-three-tier\u002FSKILL.md",[],[90,91,92,93,94,95,96,97,98,99,100,101,102,103,104],"pilotswarm three tier","three","identity","cluster","for","deployment","dockerfile","worker","manifests","verification","changes","aks","entrypoint","provisioning","reference","2026-11-10 10:12:30"]