{"owner":"temporalio","repo":"temporal","hasSkills":true,"totalSkillsCount":8,"totalTokensCount":7431,"categories":["plugin-manifest","cursor-rule","anthropic-skill","root-instruction","copilot-instructions"],"hasMcp":false,"mcpConfig":null,"found":["tools/sql/README.md",".cursor/rules/review.mdc",".claude/skills/review/SKILL.md","AGENTS.md",".github/copilot-instructions.md","tools/fairsim/README.md","tools/elasticsearch/README.md","tools/cassandra/README.md"],"skills":{"tools/sql/README.md":"## Using the SQL schema tool\n \nThis package contains the tooling for temporal sql operations. The tooling itself is agnostic of the storage engine behind\nthe sql interface. So, this same tool can be used against, say, OracleDB and MySQLDB\n\n## For localhost development\n``` \nSQL_USER=$USERNAME SQL_PASSWORD=$PASSWD make install-schema-mysql\n```\n\n## For production\n\n### Create the binary\n- Run `make temporal-sql-tool` on the root of repositroy\n- You should see an executable `temporal-sql-tool`\n- Temporal officially support MySQL and Postgres for SQL. \n- For other SQL database, you can add it easily as we do for MySQL/Postgres following our code in sql-extensions  \n\n### Do one time database creation and schema setup for a new cluster\n\n- All command below are taking MySQL as example. For postgres, simply use with \"--plugin postgres12\" and \"--schema-name postgresql/v12/temporal\" & \"--schema-name postgresql/v12/visibility\"\n\n```\n./temporal-sql-tool --ep $SQL_HOST -p $port --db temporal --plugin mysql8 create\n./temporal-sql-tool --ep $SQL_HOST -p $port --db temporal_visibility --plugin mysql8 create\n```\n\n```\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal setup-schema -v 0.0 -- this sets up just the schema version tables with initial version of 0.0\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal update-schema --schema-name mysql/v8/temporal -- upgrades your schema with the embedded schema\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal update-schema -d ./schema/mysql/v8/temporal/versioned -- Or upgrades your schema by providing your schema\n\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal_visibility setup-schema -v 0.0 -- this sets up just the schema version tables with initial version of 0.0 for visibility\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal_visibility update-schema --schema-name mysql/v8/visibility -- upgrades your schema with the embedded schema for visibility\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal_visibility update-schema -d ./schema/mysql/v8/visibility/versioned  -- Or upgrades your schema by providing your schema for visibility\n```\n\n### Update schema as part of a release\nYou can only upgrade to a new version after the initial setup done above.\n\n```\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal update-schema -d ./schema/mysql/v8/temporal/versioned -v x.x    -- executes the upgrade to version x.x\n\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal_visibility update-schema -d ./schema/mysql/v8/visibility/versioned -v x.x    -- executes the upgrade to version x.x\n```\n\n",".cursor/rules/review.mdc":"---\ndescription: Code review guidelines - apply when reviewing code or suggesting changes\nglobs: \"**/*.go\"\nalwaysApply: false\n---\n\n# Code Review Guidelines\n\n@.github/copilot-instructions.md\n",".claude/skills/review/SKILL.md":"---\nname: review\ndescription: Review code for common issues. Use when reviewing PRs, suggesting code changes, or when user asks to review code.\nallowed-tools: Read, Grep, Glob\n---\n\n# Code Review Skill\n\n@.github/copilot-instructions.md\n","AGENTS.md":"You are an experienced developer working on the temporal project. Your task is to review code, fix a bug, or implement a new feature while adhering to the project's best practices and development guidelines. Your background is in distributed systems, database engines, and scalable platforms.\n\nBefore starting the implementation or review of any request, you MUST REVIEW the sections below and the [code guidelines](.github/copilot-instructions.md).\n\n## Project Structure\n\n- `/api`: proto definitions and generated code\n- `/chasm`: library for Chasm (Coordinated Heterogeneous Application State Machines)\n- `/client`: client libraries for inter-service communication between frontend/history/matching etc.\n- `/cmd`: CLI commands and main applications\n- `/common`: modules shared across all services\n- `/common/dynamicconfig`: dynamic configuration library\n- `/common/membership`: cluster membership management\n- `/common/metrics`: metrics definition and library\n- `/common/namespace`: namespace cache and utilities\n- `/common/nexus`: Nexus service client and utilities\n- `/common/persistence`: persistence layer abstractions and implementations\n- `/components`: nexus components\n- `/config`: configuration files and templates\n- `/docs`: documentation\n- `/proto`: proto definitions for internal services\n- `/schema`: database schema definitions for core databases store and visibility store\n- `/service`: main services (frontend, history, matching, worker, etc.)\n- `/service/frontend`: frontend service implementation\n- `/service/history`: history service implementation\n- `/service/matching`: matching service implementation\n- `/service/worker`: worker service implementation\n\n## Development Commands\n\n- Fast Go linting (changed packages): `make lint-code-fast`\n- Full Go linting (all packages): `make lint-code`\n- Formatting imports: `make fmt-imports`\n- Code generation: `make proto`\n- Update API proto: `make update-go-api`\n- Always include `-tags test_dep` when running tests. Include the `integration` tag only for integration tests.\n\n## Development Workflow\n\n1. Inspect surrounding code, tests, and configuration before making changes.\n2. Implement the change using existing patterns and regenerate code when interface definitions change, including changes to `.proto` files or code annotated with `//go:generate`.\n3. Determine the relevant test commands from repository documentation and build configuration, then run those tests and `make lint-code-fast` after code changes.\n",".github/copilot-instructions.md":"# Code Guidelines\n\nThese rules apply when authoring or reviewing code; the Behavior Review and Review Feedback Style sections apply only when reviewing code.\nExpress each rule as a concise, direct statement of the expected code or review behavior.\n\n## 1. Behavior Review\n\nThe main question of a review is whether the code under review changes Temporal's behavior in the way it intends, and whether it changes Temporal's behavior in any way it does not intend. Behavior includes internal behavior that users do not observe directly, such as persisted state, tasks, and RPCs between services.\n\n- Read the commit messages and, if there is a PR, its title and description, and state the change to Temporal's behavior that they intend. If there is a PR and its description does not say what the PR is intended to change and why, report that as a finding, infer the intended change from the commit messages and the diff, and continue.\n- Read the diff. Then read every changed file completely, together with the code that calls the changed code and the code it calls. Skip generated code (e.g. `*.pb.go`, mocks).\n- Try to find existing code that does something related: code that the description says the change mirrors or replaces, code that does the same thing for another execution type or service, and code paths that the change adds to or bypasses. Read it. The change should either behave like this code or differ from it for a reason.\n- For each condition the reference code checks, each configuration it reads, each side effect it performs and each metric it emits, determine whether the change does the same. If the change bypasses a code path, determine what that code path guaranteed and whether the change still guarantees it. Each difference is a finding unless the PR description or commit messages explain why it is intended. An intended difference is still a finding if its consequence is harmful.\n- Judge whether the apparently intended behavior is right for Temporal: whether it is consistent with the guarantees and conventions of the system and of the related existing code. Report it if not.\n- For each new code path, determine what happens under the default configuration, when a request is retried or delivered twice, when it runs concurrently with other operations on the same state, and when it fails or its response is lost after each step. Determine whether the server and its callers can still make progress in each case.\n- Behavior can be wrong because of code outside the diff, for example a configuration default, a check that exists only on another code path, or a caller that relies on a field being set. Follow each new code path back to the source of its inputs and forward to the consumers of its outputs.\n- A `TODO` records a gap; it does not make the gap acceptable. Report the gap if its consequence matters once the change is released.\n- A test that asserts a behavior shows that the author intended the behavior, not that the behavior is correct.\n- Identify intended behavior that no test covers, and tests that would still pass if the corresponding implementation were reverted. Then review the code against the remaining guidelines.\n- Report behavior findings before code findings. For each behavior finding, state the condition, what happens, what the reference code does, and why it matters. A behavior difference that can lose data, leave an execution unable to make progress, or remove a guarantee that the server provides elsewhere is at least `med`.\n\n## 2. Structural Simplicity\n\n- Designs minimize branches, special cases, indirection, and moving parts.\n- Every line contributes to the implementation or verifies behavior in a test.\n- Tests contain only the setup and complexity needed to exercise the behavior in scope.\n- Tests use deterministic inputs unless randomness is the behavior under test.\n- Tests assert only the behavior in scope; they assume that unrelated operations work. For example, a test that is not about `TerminateWorkflowExecution` assumes that operation works.\n- Values assigned immediately before use are used without redundant nil checks.\n- Packages export only identifiers required by their callers.\n\n## 3. Go Conventions\n\n- Getter names omit the `Get` prefix: use `func (a *Activity) Store()` rather than `GetStore()`.\n- Implementation names omit the `Impl` suffix.\n- Test names place their descriptive name directly after `Test`: use `TestRetry` rather than `Test_Retry`.\n- Names omit package-name stuttering: package `activity` uses `Status` rather than `ActivityStatus`.\n- Map lookups and other operations that return a presence boolean use the comma-ok pattern rather than nil checks.\n- Defaults use `cmp.Or` when zero means \"unset\"; it returns the first non-zero argument. Side-effecting or expensive fallbacks use an `if` statement because all arguments are evaluated.\n\n## 4. Testing Correctness and Reliability\n\nBefore writing, reviewing, or running tests, read and follow the [testing guide](../docs/development/testing.md) for setup, assertions, polling, parallelization, and test helpers.\n\n- Subtests use their own `t` parameter rather than the parent's `t` or `s.T()`.\n- Tests use a table-driven structure when multiple cases exercise the same behavior. Every case has a descriptive name and runs as a subtest.\n- Tests compare a function's complete result with an expected value rather than asserting each field separately; field-level assertions are reserved for cases where only part of the result is relevant.\n- A goroutine that maintains a precondition for later assertions, such as `go s.someHelper(ctx, ...)`, loops until context cancellation or reports success before the test waits for its effect. This prevents a transiently failed attempt from exiting silently and leaving downstream eventual-consistency waits unable to succeed.\n- Assertions run in the test goroutine. Worker goroutines return results or errors through buffered channels so an assertion cannot panic the binary after the test has completed.\n- Tests do not write to package-level or global variables. Values are threaded through function parameters because parallel tests share the same process.\n- Tests coordinate ordering with explicit synchronization rather than sleeps or elapsed-time thresholds.\n- A background operation that drives a polling condition has a longer timeout than the waiting deadline, so it remains capable of satisfying the condition for the entire wait.\n- Errors from precondition operations are surfaced or retried until success when failure would invalidate the rest of the test; they are not discarded with `_, _ = f()`.\n\n## 5. Inline Code / Avoid Abstractions\n\n- Strings used in only one place remain inline rather than becoming constants.\n- Struct field values are assigned directly in their literals when possible.\n- Types and generic structs provide behavior or meaning beyond the values they wrap.\n- Small amounts of straightforward functionality are implemented directly rather than through a new dependency.\n- Test-suite-level helpers are safe for use from subtests; helpers that depend on subtest-local state remain local to the subtest.\n- Code uses explicit constructs rather than reflection.\n\n## 6. Proper Error Handling\n\n- Use `softassert.That` or `softassert.Fail` to report programming errors and invariant violations.\n- Temporal errors use standard types such as `InvalidArgument`, `NotFound`, and `FailedPrecondition` rather than custom error types.\n- Errors are non-retryable when their tasks must not retry in the queue.\n- Wrapped errors add useful context, for example `fmt.Errorf(\"multi-operation part 2: %w\", err)`; wrappers without additional information are omitted.\n- Library code returns errors instead of panicking, leaving error handling to the caller.\n- Handlers validate inputs at their boundaries rather than deep in business logic.\n- Error type checks use `errors.AsType` rather than `errors.As`.\n- Error-message assertions use `require.ErrorContains` rather than separate `require.Error` and `require.Contains` assertions.\n\n## 7. Consistency with Codebase\n\n- Do not introduce new third-party libraries unless specifically requested.\n- Check existing imports and `go.mod` before assuming a library is available.\n- Code follows the patterns already established in the codebase. For example, libraries pass the frontend request through as other libraries do.\n- Existing utilities are reused before new ones are created.\n- Logger messages are static, and dynamic content is recorded in structured tags.\n- CLI documentation follows the codebase's conventions, including capitalization of proper nouns.\n- Metric tags match existing formats, including `CONSTANT_CASE` for enum values.\n- Error messages match the surrounding code's style, including omission of punctuation for single sentences.\n- Nexus-related logs use the `tag.NexusStage*` value matching the local phase, as defined in `common/log/tag/values.go`.\n- Nexus-related logs include `tag.RequestID` when available; propagate it through helpers, retries, and completion handling to correlate logs across caller and handler services.\n\n## 8. Code comments\n\n- Comments are full sentences that start with a capital letter and end with punctuation. Short labels, end-of-line fragments, directives, and `TODO` markers are exempt.\n- Comments explain behavior that is not apparent to a reader familiar with the codebase.\n- Names convey information that can be expressed clearly through naming; comments cover information that naming cannot convey.\n- Comments contain only the explanation needed to understand the code.\n- Comments use literal language and terminology established in the codebase.\n- Comments use simple sentence structures, with several plain statements rather than one sentence built from subordinate clauses, parentheticals, or stacked qualifications.\n- Comments ordinarily describe the current code without referring to counterfactuals, prior discussions, or the decision process from when the code was written.\n- Comments ordinarily describe the code itself rather than how upstream callers use it.\n\n## 9. API and Proto Design\n\n- Every proto field has a comment.\n- Protobuf fields use canonical snake-case names such as `request_id` rather than `requestId`, and `schedule_time` rather than `scheduledTime`.\n- User-facing errors describe user-facing concepts without exposing internal concepts such as `LowCardinalityKeyword`.\n- Functions accept event-attribute structs instead of continually growing parameter lists.\n- Well-known values use enums rather than integers or strings.\n\n## 10. Concurrency and Safety\n\n- Structs, especially proto messages, use immutable data patterns to avoid data races and synchronization.\n- Synchronization uses `sync.Mutex` by default. Atomics are reserved for specific patterns or demonstrated performance concerns.\n- Synchronization uses `sync.Mutex` rather than `sync.RWMutex` unless reads outnumber writes by more than 1000 to 1 or readers hold the lock for significant time.\n- I/O occurs outside critical sections, with side-effect tasks carrying work that must happen after a lock is released.\n- Data protected by a lock is cloned before the lock is released when it may be modified afterward.\n- Proto message fields accessed outside the workflow lock are cloned with `common.CloneProto(...)` rather than aliased by returning their pointers directly.\n\n## 11. Review Feedback Style\n\n- Review changes holistically as well as line by line.\n- Give concrete replacement text as a code suggestion. If restructuring the code is clearer and shorter than rewording the comment, suggest that code instead.\n- Be direct and practical, without fluff.\n- Reference specific codebase patterns and utilities, suggest concrete alternatives, and explain why something should change rather than only stating that it should.\n\n### Comment format\n\nUse this core structure for every actionable finding.\nReplace `SEVERITY` with `nit`, `small`, `med`, or `high`:\n\n```markdown\n<details>\n<summary><strong>SEVERITY</strong> — One-line summary.</summary>\n\nConcise explanation of what is wrong and why it matters, followed by any\nsupporting evidence, examples, or implementation notes.\n\n</details>\n\n**Suggestion:** Concrete fix or alternative.\n```\n\nUse HTML tags rather than Markdown inside `<summary>`.\nThe summary line is all a reader sees before expanding, so it must state the problem on its own.\nKeep the suggestion outside the collapsible block, as a code suggestion wherever the fix is a concrete edit.\n\n### Severity levels\n\n- `nit` — Stylistic or trivial improvement. Preference-based. Non-blocking.\n- `small` — Minor issue: slightly misleading name, small readability concern, or minor best-practice deviation. Does not affect correctness. Non-blocking.\n- `med` — Moderate issue: missing error handling, logic that is likely wrong in edge cases, test gaps, or design concerns. Affects correctness or maintainability. Blocking.\n- `high` — Serious issue: security vulnerability, data loss risk, crash/panic, race condition, broken functionality, or architectural violation. Blocking.\n\nReport concrete findings at all four severity levels: `nit`, `small`, `med`, and `high`.\nPrefer a small number of high-confidence findings.\nKeep `nit` and `small` findings proportionally shorter than `med` and `high` findings.\nReport concrete `nit` and `small` findings selectively, and consolidate related symptoms into a single comment that addresses the root issue.\n","tools/fairsim/README.md":"\n# fairsim\n\nThis tool simulates the behavior of Temporal's fair task queues, for use in\nevaluating different parameters.\n\n## Build\nrun `make fairsim`\n\n## Usage\n\nThere are two main modes:\n\n- **Generation**: Generates tasks by random distribution and then dispatches\n  them.\n- **Script**: Process a script with queue pushes and pops. This can be used to\n  test with actual data or a custom distribution, and with continuous task\n  creation/dispatch.\n\n### Generation\n\nBy default, fairsim generates tasks with fairness keys following a Zipf\ndistribution.\n\nExamples:\n\n```bash\n# Generate a million tasks with 20 keys\nfairsim -- -tasks=1000000 -keys=20\n\n# Generate a million tasks with a much more lopsided distribution\nfairsim -- -tasks=1000000 -keys=50 -zipf-s=3 -zipf-v=1.1\n\n# Try alternate counter paramters\nfor w in 1 10 100 1000 10000; do\n  fairsim -counter-params <(echo '{\"CMS\":{\"W\":'$w'}}') -- -tasks=1000000 -keys=1000 | grep p90s: | tail -1\ndone\n\n# Disable fairness to compare to fifo\nfairsim -fair=0 -- -tasks=500\n\n# Use only one partition (default is 4)\nfairsim -partitions=1 -- -tasks=500\n```\n\n### Script\n\nExamples:\n\n```bash\n# Priority order\n{\n  echo \"task -pri=4 -payload four\"\n  echo \"task -pri=2 -payload two\"\n  echo \"task -pri=3 -payload three\"\n  echo \"task -pri=5 -payload five\"\n  echo \"task -pri=1 -payload one\"\n} | fairsim -script=/dev/stdin -partitions=1\n# should see one, two, three, four, five\n\n# Fairness\n{\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey b\"\n} | fairsim -script=/dev/stdin -partitions=1\n# should see a, b, a, a, a\n\n# Alternating\n{\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey b\"\n  echo poll # gets a\n  echo poll # gets b\n  echo \"task -fkey c\"\n  echo \"task -fkey c\"\n} | fairsim -script=/dev/stdin -partitions=1\n# should see a, b, c, a, c, a, a\n\n# Weight\n{\n  for i in {1..20}; do echo \"task -fkey a\"; done\n  for i in {1..20}; do echo \"task -fkey b -fweight 5\"; done\n} | fairsim -script=/dev/stdin -partitions=1\n# should see five b's for each a until b's are done\n```\n\n## Interpreting output\n\nBy default, only **Percentile of percentiles** are printed. Add `-verbose` for full output.\n\n### Task section\n\nFirst, fairsim will print one line for each task dispatched:\n\n```\ntask idx:    33  dsp:    15  lat:   -18  pri: 3  fkey:    \"key1\"  fweight:  1  part: 2  payload:\"external-key-32\"\n\n```\n\n- `idx`: Creation index. Tasks are assigned an incrementing index as they are created.\n- `dsp`: Dispatch index. Order this task was dispatched in.\n- `lat`: \"Latency\": dispatch index minus creation index. For a FIFO queue this\n  would always be zero. Negative means the task was moved earlier compared to\n  FIFO, positive means it was penalized.\n- `pri`: Task priority.\n- `fkey`: Fairness key.\n- `fweight`: Fairness weight.\n- `part`: Partition task was assigned to.\n- `payload`: User-defined payload (could be used for correlation).\n\n### Statistics\n\nNext are statistics on the \"latency\" values. In general, lower numbers are\nbetter, since that means more tasks were moved ahead of where they would be in a\nFIFO queue.\n\n**Raw Latency Statistics**\n\nBasic stats on the \"latency\" values. Mean must always be zero since it's a\npermutation.\n\n**Normalized Latency Statistics**\n\nWhen looking at per-key latencies, we expect a \"heavy\" fairness key with more\ntasks to have worse latency than a \"light\" key, since the light key's tasks get\npushed in front of the heavy one. This is desirable, though, and doesn't really\nreflect how much the heavy one was \"penalized\". We can normalize the latency by\ndividing by the number of tasks for that key, and futher normalize by the number\nof keys.\n\nBoth the raw and normalized can be useful to look at.\n\n**Per-task Statistics**\n\nThe raw and normalized latency stats are printed for each key, along with the\ncount.\n\n**Percentile of percentiles**\n\nRaw and normalized percentile stats are printed to give a summary of latency\nacross different keys:\n\nRows are percentiles of latency for each key, and columns are percentiles across\nthose percentiles (counting each key once). E.g. the \"p90s\" row describes the\n90th percentile latency for each key. The \"@50\" column of that is the median of\nthose 90th percentile latencies.\n\n","tools/elasticsearch/README.md":"## Using the Elasticsearch schema tool\n\n⚠️ **EXPERIMENTAL**: This tool is experimental and may change in future versions.\n\nThis package contains the tooling for temporal elasticsearch operations. \n\n### Usage\n```\nNAME:\n   temporal-elasticsearch-tool - Command line tool for temporal elasticsearch operations (EXPERIMENTAL)\n\nUSAGE:\n   temporal-elasticsearch-tool [global options] command [command options] [arguments...]\n\nVERSION:\n   0.0.1\n\nCOMMANDS:\n   setup-schema    setup elasticsearch cluster settings and index template\n   update-schema   update elasticsearch index template, or both template and index mappings if --index is specified\n   create-index    create elasticsearch visibility index\n   drop-index      delete elasticsearch visibility index\n   ping            pings the elasticsearch host\n   help, h         Shows a list of commands or help for one command\n\nGLOBAL OPTIONS:\n   --endpoint value                    hostname or ip address of elasticsearch server (default: \"http://127.0.0.1:9200\") [$ES_SERVER]\n   --user value                        username for elasticsearch or aws_access_key_id if using static aws credentials [$ES_USER]\n   --password value                    password for elasticsearch or aws_secret_access_key if using static aws credentials [$ES_PWD]\n   --aws-credentials value             AWS credentials provider (supported ['static', 'environment', 'aws-sdk-default']) [$AWS_CREDENTIALS]\n   --aws-session-token value           AWS sessiontoken for use with 'static' AWS credentials provider [$AWS_SESSION_TOKEN]\n   --tls                               enable TLS for elasticsearch connection [$ES_TLS]\n   --tls-cert-file value               path to TLS certificate file (tls must be enabled) [$ES_TLS_CERT_FILE]\n   --tls-key-file value                path to TLS key file (tls must be enabled) [$ES_TLS_KEY_FILE]\n   --tls-ca-file value                 path to TLS CA certificate file (tls must be enabled) [$ES_TLS_CA_FILE]\n   --tls-server-name value             TLS server name for host name verification (tls must be enabled) [$ES_TLS_SERVER_NAME]\n   --tls-disable-host-verification     disable TLS host name verification (tls must be enabled) [$ES_TLS_DISABLE_HOST_VERIFICATION]\n   --index value                       name of the visibility index [$ES_VISIBILITY_INDEX]\n   --quiet                             don't log errors to stderr (default: false)\n   --help, -h                          show help\n   --version, -v                       print the version\n```\n\n## For localhost development\n``` \nmake install-schema-es\n```\n\n## For production\n\n### Create the binaries\n- Run `make temporal-elasticsearch-tool`\n- You should see an executable `temporal-elasticsearch-tool`\n\n### Schema setup\n```\nNAME:\n   temporal-elasticsearch-tool setup-schema - setup elasticsearch cluster settings and index template\n\nUSAGE:\n   temporal-elasticsearch-tool setup-schema [command options]\n\nOPTIONS:\n   --fail      fail silently on HTTP errors (default: false)\n   --help, -h  show help\n```\n\n```\nNAME:\n   temporal-elasticsearch-tool create-index - create elasticsearch visibility index\n\nUSAGE:\n   temporal-elasticsearch-tool create-index [command options]\n\nOPTIONS:\n   --index value  name of the visibility index to create\n   --fail         fail silently on HTTP errors (default: false)\n   --help, -h     show help\n```\n\nThe tool now uses embedded schema files (cluster settings and index template) and provides separate commands for different operations. You can set up the schema and create indexes separately:\n\n```\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_USER=$USER\nexport ES_PWD=$PWD\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\n# Setup cluster settings and index template\ntemporal-elasticsearch-tool setup-schema\n\n# Create the visibility index (uses ES_VISIBILITY_INDEX environment variable)\ntemporal-elasticsearch-tool create-index\n\n# Or combine both operations\ntemporal-elasticsearch-tool setup-schema && \\\ntemporal-elasticsearch-tool create-index\n```\n\n### Ping\nPing the ES server to ensure connectivity and successful authentication\n\n```\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_VERSION=v7\nexport AWS_REGION=us-east-1\n\ntemporal-elasticsearch-tool --aws environment ping \n```\n\n### AWS Authentication\nThe CLI supports 3 AWS authentication mechanisms: `aws-sdk-default`, `environment`, `static`.\n\n```\n# aws-go-sdk defaults\nexport AWS_REGION=us-east-1\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\ntemporal-elasticsearch-tool --aws aws-sdk-default setup-schema\ntemporal-elasticsearch-tool --aws aws-sdk-default create-index\n```\n\n```\n# Environment Credentials\nexport AWS_REGION=us-east-1\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\ntemporal-elasticsearch-tool --aws environment setup-schema\ntemporal-elasticsearch-tool --aws environment create-index\n```\n\n```\n# Static Credentials\nexport AWS_REGION=us-east-1\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_USER=$AWS_ACCESS_KEY_ID\nexport ES_PWD=$AWS_SECRET_ACCESS_KEY\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\ntemporal-elasticsearch-tool --aws static setup-schema\ntemporal-elasticsearch-tool --aws static create-index\n```\n\n```\n# Static w/ Session Token\nexport AWS_REGION=us-east-1\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_USER=$AWS_ACCESS_KEY_ID\nexport ES_PWD=$AWS_SECRET_ACCESS_KEY\nexport AWS_SESSION_TOKEN\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\ntemporal-elasticsearch-tool --aws static setup-schema\ntemporal-elasticsearch-tool --aws static create-index\n```\n\n### TLS Configuration\nThe tool supports TLS for secure connections to Elasticsearch.\n\n#### Basic TLS with CA certificate\n```bash\nexport ES_SERVER=https://elasticsearch.example.com:9200\nexport ES_TLS=true\nexport ES_TLS_CA_FILE=/path/to/ca.crt\nexport ES_USER=elastic\nexport ES_PWD=password\n\ntemporal-elasticsearch-tool setup-schema\ntemporal-elasticsearch-tool create-index\n```\n\n#### TLS with client certificate authentication\n```bash\nexport ES_SERVER=https://elasticsearch.example.com:9200\nexport ES_TLS=true\nexport ES_TLS_CA_FILE=/path/to/ca.crt\nexport ES_TLS_CERT_FILE=/path/to/client.crt\nexport ES_TLS_KEY_FILE=/path/to/client.key\nexport ES_USER=elastic\nexport ES_PWD=password\n\ntemporal-elasticsearch-tool setup-schema\ntemporal-elasticsearch-tool create-index\n```\n\n#### TLS with custom server name\n```bash\nexport ES_SERVER=https://elasticsearch.example.com:9200\nexport ES_TLS=true\nexport ES_TLS_CA_FILE=/path/to/ca.crt\nexport ES_TLS_SERVER_NAME=elasticsearch.internal\nexport ES_USER=elastic\nexport ES_PWD=password\n\ntemporal-elasticsearch-tool setup-schema\n```\n\n#### TLS with disabled host verification (not recommended for production)\n```bash\nexport ES_SERVER=https://elasticsearch.example.com:9200\nexport ES_TLS=true\nexport ES_TLS_DISABLE_HOST_VERIFICATION=true\nexport ES_USER=elastic\nexport ES_PWD=password\n\ntemporal-elasticsearch-tool setup-schema\n```\n\n#### Using command line flags\nAll TLS options can also be specified as command line flags:\n\n```bash\ntemporal-elasticsearch-tool \\\n  --endpoint https://elasticsearch.example.com:9200 \\\n  --tls \\\n  --tls-ca-file /path/to/ca.crt \\\n  --tls-cert-file /path/to/client.crt \\\n  --tls-key-file /path/to/client.key \\\n  --tls-server-name elasticsearch.internal \\\n  --user elastic \\\n  --password password \\\n  setup-schema\n```\n\n### Additional Commands\n\n#### Update Schema\nUpdates the index template to the latest version, or updates both the template and index mappings if `--index` is specified:\n\nUpdate template only:\n```bash\ntemporal-elasticsearch-tool update-schema\n```\n\nUpdate both template and index mappings:\n```bash\ntemporal-elasticsearch-tool update-schema --index temporal_visibility_v1\n```\n\nUpdate both template and index mappings using environment variable:\n```bash\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\ntemporal-elasticsearch-tool update-schema\n```\n\n#### Drop Index\nDeletes a visibility index:\n```bash\ntemporal-elasticsearch-tool drop-index --index temporal_visibility_v1\n```\n\nOr using environment variable:\n```bash\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\ntemporal-elasticsearch-tool drop-index\n```\n\n#### Command Summary\n- `setup-schema`: Sets up cluster settings and index template (no index creation)\n- `update-schema`: Updates index template, or both template and index mappings if --index is specified\n- `create-index`: Creates a new visibility index (requires --index flag)\n- `drop-index`: Deletes a visibility index (requires --index flag)\n- `ping`: Tests connectivity to Elasticsearch server\n","tools/cassandra/README.md":"## Using the cassandra schema tool\nThis package contains the tooling for temporal cassandra operations.\n\n## For localhost development\nFor the very first time run:\n``` \nmake\n```\n\nthen run:\n``` \nmake install-schema-cass\n```\nto create schema in your `cassandra` instance.\n\n## For production\n\n### Create the binaries\n- Run `make`\n- You should see an executable `temporal-cassandra-tool`\n\n### Do one time database creation and schema setup for a new cluster\nThis uses Cassandra's SimpleStratagey for replication. For production, we recommend using a replication factor of 3 with NetworkTopologyStrategy.\n\n```\ntemporal-cassandra-tool --ep $CASSANDRA_SEEDS create -k $KEYSPACE --rf $RF\n```\n\nSee https://www.ecyrd.com/cassandracalculator for an easy way to determine how many nodes and what replication factor you will want to use.  Note that Temporal by default uses `LOCAL_QUORUM` and `LOCAL_SERIAL` for read and write consistency.\n\n```\n./temporal-cassandra-tool -ep 127.0.0.1 -k temporal setup-schema -v 0.0 -- this sets up just the schema version tables with initial version of 0.0\n./temporal-cassandra-tool -ep 127.0.0.1 -k temporal update-schema -d ./schema/cassandra/temporal/versioned -- upgrades your schema to the latest version\n```\n\n### Update schema as part of a release\nYou can only upgrade to a new version after the initial setup done above.\n\n```\n./temporal-cassandra-tool -ep 127.0.0.1 -k temporal update-schema -d ./schema/cassandra/temporal/versioned -v x.x    -- executes the upgrade to version x.x\n```\n\n"},"files":{"tools/sql/README.md":"## Using the SQL schema tool\n \nThis package contains the tooling for temporal sql operations. The tooling itself is agnostic of the storage engine behind\nthe sql interface. So, this same tool can be used against, say, OracleDB and MySQLDB\n\n## For localhost development\n``` \nSQL_USER=$USERNAME SQL_PASSWORD=$PASSWD make install-schema-mysql\n```\n\n## For production\n\n### Create the binary\n- Run `make temporal-sql-tool` on the root of repositroy\n- You should see an executable `temporal-sql-tool`\n- Temporal officially support MySQL and Postgres for SQL. \n- For other SQL database, you can add it easily as we do for MySQL/Postgres following our code in sql-extensions  \n\n### Do one time database creation and schema setup for a new cluster\n\n- All command below are taking MySQL as example. For postgres, simply use with \"--plugin postgres12\" and \"--schema-name postgresql/v12/temporal\" & \"--schema-name postgresql/v12/visibility\"\n\n```\n./temporal-sql-tool --ep $SQL_HOST -p $port --db temporal --plugin mysql8 create\n./temporal-sql-tool --ep $SQL_HOST -p $port --db temporal_visibility --plugin mysql8 create\n```\n\n```\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal setup-schema -v 0.0 -- this sets up just the schema version tables with initial version of 0.0\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal update-schema --schema-name mysql/v8/temporal -- upgrades your schema with the embedded schema\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal update-schema -d ./schema/mysql/v8/temporal/versioned -- Or upgrades your schema by providing your schema\n\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal_visibility setup-schema -v 0.0 -- this sets up just the schema version tables with initial version of 0.0 for visibility\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal_visibility update-schema --schema-name mysql/v8/visibility -- upgrades your schema with the embedded schema for visibility\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal_visibility update-schema -d ./schema/mysql/v8/visibility/versioned  -- Or upgrades your schema by providing your schema for visibility\n```\n\n### Update schema as part of a release\nYou can only upgrade to a new version after the initial setup done above.\n\n```\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal update-schema -d ./schema/mysql/v8/temporal/versioned -v x.x    -- executes the upgrade to version x.x\n\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal_visibility update-schema -d ./schema/mysql/v8/visibility/versioned -v x.x    -- executes the upgrade to version x.x\n```\n\n",".cursor/rules/review.mdc":"---\ndescription: Code review guidelines - apply when reviewing code or suggesting changes\nglobs: \"**/*.go\"\nalwaysApply: false\n---\n\n# Code Review Guidelines\n\n@.github/copilot-instructions.md\n",".claude/skills/review/SKILL.md":"---\nname: review\ndescription: Review code for common issues. Use when reviewing PRs, suggesting code changes, or when user asks to review code.\nallowed-tools: Read, Grep, Glob\n---\n\n# Code Review Skill\n\n@.github/copilot-instructions.md\n","AGENTS.md":"You are an experienced developer working on the temporal project. Your task is to review code, fix a bug, or implement a new feature while adhering to the project's best practices and development guidelines. Your background is in distributed systems, database engines, and scalable platforms.\n\nBefore starting the implementation or review of any request, you MUST REVIEW the sections below and the [code guidelines](.github/copilot-instructions.md).\n\n## Project Structure\n\n- `/api`: proto definitions and generated code\n- `/chasm`: library for Chasm (Coordinated Heterogeneous Application State Machines)\n- `/client`: client libraries for inter-service communication between frontend/history/matching etc.\n- `/cmd`: CLI commands and main applications\n- `/common`: modules shared across all services\n- `/common/dynamicconfig`: dynamic configuration library\n- `/common/membership`: cluster membership management\n- `/common/metrics`: metrics definition and library\n- `/common/namespace`: namespace cache and utilities\n- `/common/nexus`: Nexus service client and utilities\n- `/common/persistence`: persistence layer abstractions and implementations\n- `/components`: nexus components\n- `/config`: configuration files and templates\n- `/docs`: documentation\n- `/proto`: proto definitions for internal services\n- `/schema`: database schema definitions for core databases store and visibility store\n- `/service`: main services (frontend, history, matching, worker, etc.)\n- `/service/frontend`: frontend service implementation\n- `/service/history`: history service implementation\n- `/service/matching`: matching service implementation\n- `/service/worker`: worker service implementation\n\n## Development Commands\n\n- Fast Go linting (changed packages): `make lint-code-fast`\n- Full Go linting (all packages): `make lint-code`\n- Formatting imports: `make fmt-imports`\n- Code generation: `make proto`\n- Update API proto: `make update-go-api`\n- Always include `-tags test_dep` when running tests. Include the `integration` tag only for integration tests.\n\n## Development Workflow\n\n1. Inspect surrounding code, tests, and configuration before making changes.\n2. Implement the change using existing patterns and regenerate code when interface definitions change, including changes to `.proto` files or code annotated with `//go:generate`.\n3. Determine the relevant test commands from repository documentation and build configuration, then run those tests and `make lint-code-fast` after code changes.\n",".github/copilot-instructions.md":"# Code Guidelines\n\nThese rules apply when authoring or reviewing code; the Behavior Review and Review Feedback Style sections apply only when reviewing code.\nExpress each rule as a concise, direct statement of the expected code or review behavior.\n\n## 1. Behavior Review\n\nThe main question of a review is whether the code under review changes Temporal's behavior in the way it intends, and whether it changes Temporal's behavior in any way it does not intend. Behavior includes internal behavior that users do not observe directly, such as persisted state, tasks, and RPCs between services.\n\n- Read the commit messages and, if there is a PR, its title and description, and state the change to Temporal's behavior that they intend. If there is a PR and its description does not say what the PR is intended to change and why, report that as a finding, infer the intended change from the commit messages and the diff, and continue.\n- Read the diff. Then read every changed file completely, together with the code that calls the changed code and the code it calls. Skip generated code (e.g. `*.pb.go`, mocks).\n- Try to find existing code that does something related: code that the description says the change mirrors or replaces, code that does the same thing for another execution type or service, and code paths that the change adds to or bypasses. Read it. The change should either behave like this code or differ from it for a reason.\n- For each condition the reference code checks, each configuration it reads, each side effect it performs and each metric it emits, determine whether the change does the same. If the change bypasses a code path, determine what that code path guaranteed and whether the change still guarantees it. Each difference is a finding unless the PR description or commit messages explain why it is intended. An intended difference is still a finding if its consequence is harmful.\n- Judge whether the apparently intended behavior is right for Temporal: whether it is consistent with the guarantees and conventions of the system and of the related existing code. Report it if not.\n- For each new code path, determine what happens under the default configuration, when a request is retried or delivered twice, when it runs concurrently with other operations on the same state, and when it fails or its response is lost after each step. Determine whether the server and its callers can still make progress in each case.\n- Behavior can be wrong because of code outside the diff, for example a configuration default, a check that exists only on another code path, or a caller that relies on a field being set. Follow each new code path back to the source of its inputs and forward to the consumers of its outputs.\n- A `TODO` records a gap; it does not make the gap acceptable. Report the gap if its consequence matters once the change is released.\n- A test that asserts a behavior shows that the author intended the behavior, not that the behavior is correct.\n- Identify intended behavior that no test covers, and tests that would still pass if the corresponding implementation were reverted. Then review the code against the remaining guidelines.\n- Report behavior findings before code findings. For each behavior finding, state the condition, what happens, what the reference code does, and why it matters. A behavior difference that can lose data, leave an execution unable to make progress, or remove a guarantee that the server provides elsewhere is at least `med`.\n\n## 2. Structural Simplicity\n\n- Designs minimize branches, special cases, indirection, and moving parts.\n- Every line contributes to the implementation or verifies behavior in a test.\n- Tests contain only the setup and complexity needed to exercise the behavior in scope.\n- Tests use deterministic inputs unless randomness is the behavior under test.\n- Tests assert only the behavior in scope; they assume that unrelated operations work. For example, a test that is not about `TerminateWorkflowExecution` assumes that operation works.\n- Values assigned immediately before use are used without redundant nil checks.\n- Packages export only identifiers required by their callers.\n\n## 3. Go Conventions\n\n- Getter names omit the `Get` prefix: use `func (a *Activity) Store()` rather than `GetStore()`.\n- Implementation names omit the `Impl` suffix.\n- Test names place their descriptive name directly after `Test`: use `TestRetry` rather than `Test_Retry`.\n- Names omit package-name stuttering: package `activity` uses `Status` rather than `ActivityStatus`.\n- Map lookups and other operations that return a presence boolean use the comma-ok pattern rather than nil checks.\n- Defaults use `cmp.Or` when zero means \"unset\"; it returns the first non-zero argument. Side-effecting or expensive fallbacks use an `if` statement because all arguments are evaluated.\n\n## 4. Testing Correctness and Reliability\n\nBefore writing, reviewing, or running tests, read and follow the [testing guide](../docs/development/testing.md) for setup, assertions, polling, parallelization, and test helpers.\n\n- Subtests use their own `t` parameter rather than the parent's `t` or `s.T()`.\n- Tests use a table-driven structure when multiple cases exercise the same behavior. Every case has a descriptive name and runs as a subtest.\n- Tests compare a function's complete result with an expected value rather than asserting each field separately; field-level assertions are reserved for cases where only part of the result is relevant.\n- A goroutine that maintains a precondition for later assertions, such as `go s.someHelper(ctx, ...)`, loops until context cancellation or reports success before the test waits for its effect. This prevents a transiently failed attempt from exiting silently and leaving downstream eventual-consistency waits unable to succeed.\n- Assertions run in the test goroutine. Worker goroutines return results or errors through buffered channels so an assertion cannot panic the binary after the test has completed.\n- Tests do not write to package-level or global variables. Values are threaded through function parameters because parallel tests share the same process.\n- Tests coordinate ordering with explicit synchronization rather than sleeps or elapsed-time thresholds.\n- A background operation that drives a polling condition has a longer timeout than the waiting deadline, so it remains capable of satisfying the condition for the entire wait.\n- Errors from precondition operations are surfaced or retried until success when failure would invalidate the rest of the test; they are not discarded with `_, _ = f()`.\n\n## 5. Inline Code / Avoid Abstractions\n\n- Strings used in only one place remain inline rather than becoming constants.\n- Struct field values are assigned directly in their literals when possible.\n- Types and generic structs provide behavior or meaning beyond the values they wrap.\n- Small amounts of straightforward functionality are implemented directly rather than through a new dependency.\n- Test-suite-level helpers are safe for use from subtests; helpers that depend on subtest-local state remain local to the subtest.\n- Code uses explicit constructs rather than reflection.\n\n## 6. Proper Error Handling\n\n- Use `softassert.That` or `softassert.Fail` to report programming errors and invariant violations.\n- Temporal errors use standard types such as `InvalidArgument`, `NotFound`, and `FailedPrecondition` rather than custom error types.\n- Errors are non-retryable when their tasks must not retry in the queue.\n- Wrapped errors add useful context, for example `fmt.Errorf(\"multi-operation part 2: %w\", err)`; wrappers without additional information are omitted.\n- Library code returns errors instead of panicking, leaving error handling to the caller.\n- Handlers validate inputs at their boundaries rather than deep in business logic.\n- Error type checks use `errors.AsType` rather than `errors.As`.\n- Error-message assertions use `require.ErrorContains` rather than separate `require.Error` and `require.Contains` assertions.\n\n## 7. Consistency with Codebase\n\n- Do not introduce new third-party libraries unless specifically requested.\n- Check existing imports and `go.mod` before assuming a library is available.\n- Code follows the patterns already established in the codebase. For example, libraries pass the frontend request through as other libraries do.\n- Existing utilities are reused before new ones are created.\n- Logger messages are static, and dynamic content is recorded in structured tags.\n- CLI documentation follows the codebase's conventions, including capitalization of proper nouns.\n- Metric tags match existing formats, including `CONSTANT_CASE` for enum values.\n- Error messages match the surrounding code's style, including omission of punctuation for single sentences.\n- Nexus-related logs use the `tag.NexusStage*` value matching the local phase, as defined in `common/log/tag/values.go`.\n- Nexus-related logs include `tag.RequestID` when available; propagate it through helpers, retries, and completion handling to correlate logs across caller and handler services.\n\n## 8. Code comments\n\n- Comments are full sentences that start with a capital letter and end with punctuation. Short labels, end-of-line fragments, directives, and `TODO` markers are exempt.\n- Comments explain behavior that is not apparent to a reader familiar with the codebase.\n- Names convey information that can be expressed clearly through naming; comments cover information that naming cannot convey.\n- Comments contain only the explanation needed to understand the code.\n- Comments use literal language and terminology established in the codebase.\n- Comments use simple sentence structures, with several plain statements rather than one sentence built from subordinate clauses, parentheticals, or stacked qualifications.\n- Comments ordinarily describe the current code without referring to counterfactuals, prior discussions, or the decision process from when the code was written.\n- Comments ordinarily describe the code itself rather than how upstream callers use it.\n\n## 9. API and Proto Design\n\n- Every proto field has a comment.\n- Protobuf fields use canonical snake-case names such as `request_id` rather than `requestId`, and `schedule_time` rather than `scheduledTime`.\n- User-facing errors describe user-facing concepts without exposing internal concepts such as `LowCardinalityKeyword`.\n- Functions accept event-attribute structs instead of continually growing parameter lists.\n- Well-known values use enums rather than integers or strings.\n\n## 10. Concurrency and Safety\n\n- Structs, especially proto messages, use immutable data patterns to avoid data races and synchronization.\n- Synchronization uses `sync.Mutex` by default. Atomics are reserved for specific patterns or demonstrated performance concerns.\n- Synchronization uses `sync.Mutex` rather than `sync.RWMutex` unless reads outnumber writes by more than 1000 to 1 or readers hold the lock for significant time.\n- I/O occurs outside critical sections, with side-effect tasks carrying work that must happen after a lock is released.\n- Data protected by a lock is cloned before the lock is released when it may be modified afterward.\n- Proto message fields accessed outside the workflow lock are cloned with `common.CloneProto(...)` rather than aliased by returning their pointers directly.\n\n## 11. Review Feedback Style\n\n- Review changes holistically as well as line by line.\n- Give concrete replacement text as a code suggestion. If restructuring the code is clearer and shorter than rewording the comment, suggest that code instead.\n- Be direct and practical, without fluff.\n- Reference specific codebase patterns and utilities, suggest concrete alternatives, and explain why something should change rather than only stating that it should.\n\n### Comment format\n\nUse this core structure for every actionable finding.\nReplace `SEVERITY` with `nit`, `small`, `med`, or `high`:\n\n```markdown\n<details>\n<summary><strong>SEVERITY</strong> — One-line summary.</summary>\n\nConcise explanation of what is wrong and why it matters, followed by any\nsupporting evidence, examples, or implementation notes.\n\n</details>\n\n**Suggestion:** Concrete fix or alternative.\n```\n\nUse HTML tags rather than Markdown inside `<summary>`.\nThe summary line is all a reader sees before expanding, so it must state the problem on its own.\nKeep the suggestion outside the collapsible block, as a code suggestion wherever the fix is a concrete edit.\n\n### Severity levels\n\n- `nit` — Stylistic or trivial improvement. Preference-based. Non-blocking.\n- `small` — Minor issue: slightly misleading name, small readability concern, or minor best-practice deviation. Does not affect correctness. Non-blocking.\n- `med` — Moderate issue: missing error handling, logic that is likely wrong in edge cases, test gaps, or design concerns. Affects correctness or maintainability. Blocking.\n- `high` — Serious issue: security vulnerability, data loss risk, crash/panic, race condition, broken functionality, or architectural violation. Blocking.\n\nReport concrete findings at all four severity levels: `nit`, `small`, `med`, and `high`.\nPrefer a small number of high-confidence findings.\nKeep `nit` and `small` findings proportionally shorter than `med` and `high` findings.\nReport concrete `nit` and `small` findings selectively, and consolidate related symptoms into a single comment that addresses the root issue.\n","tools/fairsim/README.md":"\n# fairsim\n\nThis tool simulates the behavior of Temporal's fair task queues, for use in\nevaluating different parameters.\n\n## Build\nrun `make fairsim`\n\n## Usage\n\nThere are two main modes:\n\n- **Generation**: Generates tasks by random distribution and then dispatches\n  them.\n- **Script**: Process a script with queue pushes and pops. This can be used to\n  test with actual data or a custom distribution, and with continuous task\n  creation/dispatch.\n\n### Generation\n\nBy default, fairsim generates tasks with fairness keys following a Zipf\ndistribution.\n\nExamples:\n\n```bash\n# Generate a million tasks with 20 keys\nfairsim -- -tasks=1000000 -keys=20\n\n# Generate a million tasks with a much more lopsided distribution\nfairsim -- -tasks=1000000 -keys=50 -zipf-s=3 -zipf-v=1.1\n\n# Try alternate counter paramters\nfor w in 1 10 100 1000 10000; do\n  fairsim -counter-params <(echo '{\"CMS\":{\"W\":'$w'}}') -- -tasks=1000000 -keys=1000 | grep p90s: | tail -1\ndone\n\n# Disable fairness to compare to fifo\nfairsim -fair=0 -- -tasks=500\n\n# Use only one partition (default is 4)\nfairsim -partitions=1 -- -tasks=500\n```\n\n### Script\n\nExamples:\n\n```bash\n# Priority order\n{\n  echo \"task -pri=4 -payload four\"\n  echo \"task -pri=2 -payload two\"\n  echo \"task -pri=3 -payload three\"\n  echo \"task -pri=5 -payload five\"\n  echo \"task -pri=1 -payload one\"\n} | fairsim -script=/dev/stdin -partitions=1\n# should see one, two, three, four, five\n\n# Fairness\n{\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey b\"\n} | fairsim -script=/dev/stdin -partitions=1\n# should see a, b, a, a, a\n\n# Alternating\n{\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey b\"\n  echo poll # gets a\n  echo poll # gets b\n  echo \"task -fkey c\"\n  echo \"task -fkey c\"\n} | fairsim -script=/dev/stdin -partitions=1\n# should see a, b, c, a, c, a, a\n\n# Weight\n{\n  for i in {1..20}; do echo \"task -fkey a\"; done\n  for i in {1..20}; do echo \"task -fkey b -fweight 5\"; done\n} | fairsim -script=/dev/stdin -partitions=1\n# should see five b's for each a until b's are done\n```\n\n## Interpreting output\n\nBy default, only **Percentile of percentiles** are printed. Add `-verbose` for full output.\n\n### Task section\n\nFirst, fairsim will print one line for each task dispatched:\n\n```\ntask idx:    33  dsp:    15  lat:   -18  pri: 3  fkey:    \"key1\"  fweight:  1  part: 2  payload:\"external-key-32\"\n\n```\n\n- `idx`: Creation index. Tasks are assigned an incrementing index as they are created.\n- `dsp`: Dispatch index. Order this task was dispatched in.\n- `lat`: \"Latency\": dispatch index minus creation index. For a FIFO queue this\n  would always be zero. Negative means the task was moved earlier compared to\n  FIFO, positive means it was penalized.\n- `pri`: Task priority.\n- `fkey`: Fairness key.\n- `fweight`: Fairness weight.\n- `part`: Partition task was assigned to.\n- `payload`: User-defined payload (could be used for correlation).\n\n### Statistics\n\nNext are statistics on the \"latency\" values. In general, lower numbers are\nbetter, since that means more tasks were moved ahead of where they would be in a\nFIFO queue.\n\n**Raw Latency Statistics**\n\nBasic stats on the \"latency\" values. Mean must always be zero since it's a\npermutation.\n\n**Normalized Latency Statistics**\n\nWhen looking at per-key latencies, we expect a \"heavy\" fairness key with more\ntasks to have worse latency than a \"light\" key, since the light key's tasks get\npushed in front of the heavy one. This is desirable, though, and doesn't really\nreflect how much the heavy one was \"penalized\". We can normalize the latency by\ndividing by the number of tasks for that key, and futher normalize by the number\nof keys.\n\nBoth the raw and normalized can be useful to look at.\n\n**Per-task Statistics**\n\nThe raw and normalized latency stats are printed for each key, along with the\ncount.\n\n**Percentile of percentiles**\n\nRaw and normalized percentile stats are printed to give a summary of latency\nacross different keys:\n\nRows are percentiles of latency for each key, and columns are percentiles across\nthose percentiles (counting each key once). E.g. the \"p90s\" row describes the\n90th percentile latency for each key. The \"@50\" column of that is the median of\nthose 90th percentile latencies.\n\n","tools/elasticsearch/README.md":"## Using the Elasticsearch schema tool\n\n⚠️ **EXPERIMENTAL**: This tool is experimental and may change in future versions.\n\nThis package contains the tooling for temporal elasticsearch operations. \n\n### Usage\n```\nNAME:\n   temporal-elasticsearch-tool - Command line tool for temporal elasticsearch operations (EXPERIMENTAL)\n\nUSAGE:\n   temporal-elasticsearch-tool [global options] command [command options] [arguments...]\n\nVERSION:\n   0.0.1\n\nCOMMANDS:\n   setup-schema    setup elasticsearch cluster settings and index template\n   update-schema   update elasticsearch index template, or both template and index mappings if --index is specified\n   create-index    create elasticsearch visibility index\n   drop-index      delete elasticsearch visibility index\n   ping            pings the elasticsearch host\n   help, h         Shows a list of commands or help for one command\n\nGLOBAL OPTIONS:\n   --endpoint value                    hostname or ip address of elasticsearch server (default: \"http://127.0.0.1:9200\") [$ES_SERVER]\n   --user value                        username for elasticsearch or aws_access_key_id if using static aws credentials [$ES_USER]\n   --password value                    password for elasticsearch or aws_secret_access_key if using static aws credentials [$ES_PWD]\n   --aws-credentials value             AWS credentials provider (supported ['static', 'environment', 'aws-sdk-default']) [$AWS_CREDENTIALS]\n   --aws-session-token value           AWS sessiontoken for use with 'static' AWS credentials provider [$AWS_SESSION_TOKEN]\n   --tls                               enable TLS for elasticsearch connection [$ES_TLS]\n   --tls-cert-file value               path to TLS certificate file (tls must be enabled) [$ES_TLS_CERT_FILE]\n   --tls-key-file value                path to TLS key file (tls must be enabled) [$ES_TLS_KEY_FILE]\n   --tls-ca-file value                 path to TLS CA certificate file (tls must be enabled) [$ES_TLS_CA_FILE]\n   --tls-server-name value             TLS server name for host name verification (tls must be enabled) [$ES_TLS_SERVER_NAME]\n   --tls-disable-host-verification     disable TLS host name verification (tls must be enabled) [$ES_TLS_DISABLE_HOST_VERIFICATION]\n   --index value                       name of the visibility index [$ES_VISIBILITY_INDEX]\n   --quiet                             don't log errors to stderr (default: false)\n   --help, -h                          show help\n   --version, -v                       print the version\n```\n\n## For localhost development\n``` \nmake install-schema-es\n```\n\n## For production\n\n### Create the binaries\n- Run `make temporal-elasticsearch-tool`\n- You should see an executable `temporal-elasticsearch-tool`\n\n### Schema setup\n```\nNAME:\n   temporal-elasticsearch-tool setup-schema - setup elasticsearch cluster settings and index template\n\nUSAGE:\n   temporal-elasticsearch-tool setup-schema [command options]\n\nOPTIONS:\n   --fail      fail silently on HTTP errors (default: false)\n   --help, -h  show help\n```\n\n```\nNAME:\n   temporal-elasticsearch-tool create-index - create elasticsearch visibility index\n\nUSAGE:\n   temporal-elasticsearch-tool create-index [command options]\n\nOPTIONS:\n   --index value  name of the visibility index to create\n   --fail         fail silently on HTTP errors (default: false)\n   --help, -h     show help\n```\n\nThe tool now uses embedded schema files (cluster settings and index template) and provides separate commands for different operations. You can set up the schema and create indexes separately:\n\n```\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_USER=$USER\nexport ES_PWD=$PWD\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\n# Setup cluster settings and index template\ntemporal-elasticsearch-tool setup-schema\n\n# Create the visibility index (uses ES_VISIBILITY_INDEX environment variable)\ntemporal-elasticsearch-tool create-index\n\n# Or combine both operations\ntemporal-elasticsearch-tool setup-schema && \\\ntemporal-elasticsearch-tool create-index\n```\n\n### Ping\nPing the ES server to ensure connectivity and successful authentication\n\n```\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_VERSION=v7\nexport AWS_REGION=us-east-1\n\ntemporal-elasticsearch-tool --aws environment ping \n```\n\n### AWS Authentication\nThe CLI supports 3 AWS authentication mechanisms: `aws-sdk-default`, `environment`, `static`.\n\n```\n# aws-go-sdk defaults\nexport AWS_REGION=us-east-1\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\ntemporal-elasticsearch-tool --aws aws-sdk-default setup-schema\ntemporal-elasticsearch-tool --aws aws-sdk-default create-index\n```\n\n```\n# Environment Credentials\nexport AWS_REGION=us-east-1\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\ntemporal-elasticsearch-tool --aws environment setup-schema\ntemporal-elasticsearch-tool --aws environment create-index\n```\n\n```\n# Static Credentials\nexport AWS_REGION=us-east-1\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_USER=$AWS_ACCESS_KEY_ID\nexport ES_PWD=$AWS_SECRET_ACCESS_KEY\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\ntemporal-elasticsearch-tool --aws static setup-schema\ntemporal-elasticsearch-tool --aws static create-index\n```\n\n```\n# Static w/ Session Token\nexport AWS_REGION=us-east-1\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_USER=$AWS_ACCESS_KEY_ID\nexport ES_PWD=$AWS_SECRET_ACCESS_KEY\nexport AWS_SESSION_TOKEN\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\ntemporal-elasticsearch-tool --aws static setup-schema\ntemporal-elasticsearch-tool --aws static create-index\n```\n\n### TLS Configuration\nThe tool supports TLS for secure connections to Elasticsearch.\n\n#### Basic TLS with CA certificate\n```bash\nexport ES_SERVER=https://elasticsearch.example.com:9200\nexport ES_TLS=true\nexport ES_TLS_CA_FILE=/path/to/ca.crt\nexport ES_USER=elastic\nexport ES_PWD=password\n\ntemporal-elasticsearch-tool setup-schema\ntemporal-elasticsearch-tool create-index\n```\n\n#### TLS with client certificate authentication\n```bash\nexport ES_SERVER=https://elasticsearch.example.com:9200\nexport ES_TLS=true\nexport ES_TLS_CA_FILE=/path/to/ca.crt\nexport ES_TLS_CERT_FILE=/path/to/client.crt\nexport ES_TLS_KEY_FILE=/path/to/client.key\nexport ES_USER=elastic\nexport ES_PWD=password\n\ntemporal-elasticsearch-tool setup-schema\ntemporal-elasticsearch-tool create-index\n```\n\n#### TLS with custom server name\n```bash\nexport ES_SERVER=https://elasticsearch.example.com:9200\nexport ES_TLS=true\nexport ES_TLS_CA_FILE=/path/to/ca.crt\nexport ES_TLS_SERVER_NAME=elasticsearch.internal\nexport ES_USER=elastic\nexport ES_PWD=password\n\ntemporal-elasticsearch-tool setup-schema\n```\n\n#### TLS with disabled host verification (not recommended for production)\n```bash\nexport ES_SERVER=https://elasticsearch.example.com:9200\nexport ES_TLS=true\nexport ES_TLS_DISABLE_HOST_VERIFICATION=true\nexport ES_USER=elastic\nexport ES_PWD=password\n\ntemporal-elasticsearch-tool setup-schema\n```\n\n#### Using command line flags\nAll TLS options can also be specified as command line flags:\n\n```bash\ntemporal-elasticsearch-tool \\\n  --endpoint https://elasticsearch.example.com:9200 \\\n  --tls \\\n  --tls-ca-file /path/to/ca.crt \\\n  --tls-cert-file /path/to/client.crt \\\n  --tls-key-file /path/to/client.key \\\n  --tls-server-name elasticsearch.internal \\\n  --user elastic \\\n  --password password \\\n  setup-schema\n```\n\n### Additional Commands\n\n#### Update Schema\nUpdates the index template to the latest version, or updates both the template and index mappings if `--index` is specified:\n\nUpdate template only:\n```bash\ntemporal-elasticsearch-tool update-schema\n```\n\nUpdate both template and index mappings:\n```bash\ntemporal-elasticsearch-tool update-schema --index temporal_visibility_v1\n```\n\nUpdate both template and index mappings using environment variable:\n```bash\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\ntemporal-elasticsearch-tool update-schema\n```\n\n#### Drop Index\nDeletes a visibility index:\n```bash\ntemporal-elasticsearch-tool drop-index --index temporal_visibility_v1\n```\n\nOr using environment variable:\n```bash\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\ntemporal-elasticsearch-tool drop-index\n```\n\n#### Command Summary\n- `setup-schema`: Sets up cluster settings and index template (no index creation)\n- `update-schema`: Updates index template, or both template and index mappings if --index is specified\n- `create-index`: Creates a new visibility index (requires --index flag)\n- `drop-index`: Deletes a visibility index (requires --index flag)\n- `ping`: Tests connectivity to Elasticsearch server\n","tools/cassandra/README.md":"## Using the cassandra schema tool\nThis package contains the tooling for temporal cassandra operations.\n\n## For localhost development\nFor the very first time run:\n``` \nmake\n```\n\nthen run:\n``` \nmake install-schema-cass\n```\nto create schema in your `cassandra` instance.\n\n## For production\n\n### Create the binaries\n- Run `make`\n- You should see an executable `temporal-cassandra-tool`\n\n### Do one time database creation and schema setup for a new cluster\nThis uses Cassandra's SimpleStratagey for replication. For production, we recommend using a replication factor of 3 with NetworkTopologyStrategy.\n\n```\ntemporal-cassandra-tool --ep $CASSANDRA_SEEDS create -k $KEYSPACE --rf $RF\n```\n\nSee https://www.ecyrd.com/cassandracalculator for an easy way to determine how many nodes and what replication factor you will want to use.  Note that Temporal by default uses `LOCAL_QUORUM` and `LOCAL_SERIAL` for read and write consistency.\n\n```\n./temporal-cassandra-tool -ep 127.0.0.1 -k temporal setup-schema -v 0.0 -- this sets up just the schema version tables with initial version of 0.0\n./temporal-cassandra-tool -ep 127.0.0.1 -k temporal update-schema -d ./schema/cassandra/temporal/versioned -- upgrades your schema to the latest version\n```\n\n### Update schema as part of a release\nYou can only upgrade to a new version after the initial setup done above.\n\n```\n./temporal-cassandra-tool -ep 127.0.0.1 -k temporal update-schema -d ./schema/cassandra/temporal/versioned -v x.x    -- executes the upgrade to version x.x\n```\n\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/temporalio/temporal/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"You are an experienced developer working on the temporal project. Your task is to review code, fix a bug, or implement a new feature while adhering to the project's best practices and development guidelines. Your background is in distributed systems, database engines, and scalable platforms.\n\nBefore starting the implementation or review of any request, you MUST REVIEW the sections below and the [code guidelines](.github/copilot-instructions.md).\n\n## Project Structure\n\n- `/api`: proto definitions and generated code\n- `/chasm`: library for Chasm (Coordinated Heterogeneous Application State Machines)\n- `/client`: client libraries for inter-service communication between frontend/history/matching etc.\n- `/cmd`: CLI commands and main applications\n- `/common`: modules shared across all services\n- `/common/dynamicconfig`: dynamic configuration library\n- `/common/membership`: cluster membership management\n- `/common/metrics`: metrics definition and library\n- `/common/namespace`: namespace cache and utilities\n- `/common/nexus`: Nexus service client and utilities\n- `/common/persistence`: persistence layer abstractions and implementations\n- `/components`: nexus components\n- `/config`: configuration files and templates\n- `/docs`: documentation\n- `/proto`: proto definitions for internal services\n- `/schema`: database schema definitions for core databases store and visibility store\n- `/service`: main services (frontend, history, matching, worker, etc.)\n- `/service/frontend`: frontend service implementation\n- `/service/history`: history service implementation\n- `/service/matching`: matching service implementation\n- `/service/worker`: worker service implementation\n\n## Development Commands\n\n- Fast Go linting (changed packages): `make lint-code-fast`\n- Full Go linting (all packages): `make lint-code`\n- Formatting imports: `make fmt-imports`\n- Code generation: `make proto`\n- Update API proto: `make update-go-api`\n- Always include `-tags test_dep` when running tests. Include the `integration` tag only for integration tests.\n\n## Development Workflow\n\n1. Inspect surrounding code, tests, and configuration before making changes.\n2. Implement the change using existing patterns and regenerate code when interface definitions change, including changes to `.proto` files or code annotated with `//go:generate`.\n3. Determine the relevant test commands from repository documentation and build configuration, then run those tests and `make lint-code-fast` after code changes.\n","isInternal":false,"tokens":491,"sizeBytes":2483},{"name":"SKILL.md","path":".claude/skills/review/SKILL.md","rawUrl":"https://raw.githubusercontent.com/temporalio/temporal/HEAD/.claude/skills/review/SKILL.md","title":"review","category":"anthropic-skill","format":"markdown","content":"---\nname: review\ndescription: Review code for common issues. Use when reviewing PRs, suggesting code changes, or when user asks to review code.\nallowed-tools: Read, Grep, Glob\n---\n\n# Code Review Skill\n\n@.github/copilot-instructions.md\n","frontmatter":{"name":"review","description":"Review code for common issues. Use when reviewing PRs, suggesting code changes, or when user asks to review code.","allowed-tools":"Read, Grep, Glob","allowedTools":["Read,","Grep,","Glob"]},"allowedTools":["Read,","Grep,","Glob"],"isInternal":false,"tokens":56,"sizeBytes":235},{"name":"review.mdc","path":".cursor/rules/review.mdc","rawUrl":"https://raw.githubusercontent.com/temporalio/temporal/HEAD/.cursor/rules/review.mdc","title":"Cursor Rule: review","category":"cursor-rule","format":"mdc","content":"---\ndescription: Code review guidelines - apply when reviewing code or suggesting changes\nglobs: \"**/*.go\"\nalwaysApply: false\n---\n\n# Code Review Guidelines\n\n@.github/copilot-instructions.md\n","frontmatter":{"description":"Code review guidelines - apply when reviewing code or suggesting changes","globs":"**/*.go","alwaysApply":false},"isInternal":false,"tokens":42,"sizeBytes":190},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","rawUrl":"https://raw.githubusercontent.com/temporalio/temporal/HEAD/.github/copilot-instructions.md","title":"GitHub Copilot Instructions","category":"copilot-instructions","format":"markdown","content":"# Code Guidelines\n\nThese rules apply when authoring or reviewing code; the Behavior Review and Review Feedback Style sections apply only when reviewing code.\nExpress each rule as a concise, direct statement of the expected code or review behavior.\n\n## 1. Behavior Review\n\nThe main question of a review is whether the code under review changes Temporal's behavior in the way it intends, and whether it changes Temporal's behavior in any way it does not intend. Behavior includes internal behavior that users do not observe directly, such as persisted state, tasks, and RPCs between services.\n\n- Read the commit messages and, if there is a PR, its title and description, and state the change to Temporal's behavior that they intend. If there is a PR and its description does not say what the PR is intended to change and why, report that as a finding, infer the intended change from the commit messages and the diff, and continue.\n- Read the diff. Then read every changed file completely, together with the code that calls the changed code and the code it calls. Skip generated code (e.g. `*.pb.go`, mocks).\n- Try to find existing code that does something related: code that the description says the change mirrors or replaces, code that does the same thing for another execution type or service, and code paths that the change adds to or bypasses. Read it. The change should either behave like this code or differ from it for a reason.\n- For each condition the reference code checks, each configuration it reads, each side effect it performs and each metric it emits, determine whether the change does the same. If the change bypasses a code path, determine what that code path guaranteed and whether the change still guarantees it. Each difference is a finding unless the PR description or commit messages explain why it is intended. An intended difference is still a finding if its consequence is harmful.\n- Judge whether the apparently intended behavior is right for Temporal: whether it is consistent with the guarantees and conventions of the system and of the related existing code. Report it if not.\n- For each new code path, determine what happens under the default configuration, when a request is retried or delivered twice, when it runs concurrently with other operations on the same state, and when it fails or its response is lost after each step. Determine whether the server and its callers can still make progress in each case.\n- Behavior can be wrong because of code outside the diff, for example a configuration default, a check that exists only on another code path, or a caller that relies on a field being set. Follow each new code path back to the source of its inputs and forward to the consumers of its outputs.\n- A `TODO` records a gap; it does not make the gap acceptable. Report the gap if its consequence matters once the change is released.\n- A test that asserts a behavior shows that the author intended the behavior, not that the behavior is correct.\n- Identify intended behavior that no test covers, and tests that would still pass if the corresponding implementation were reverted. Then review the code against the remaining guidelines.\n- Report behavior findings before code findings. For each behavior finding, state the condition, what happens, what the reference code does, and why it matters. A behavior difference that can lose data, leave an execution unable to make progress, or remove a guarantee that the server provides elsewhere is at least `med`.\n\n## 2. Structural Simplicity\n\n- Designs minimize branches, special cases, indirection, and moving parts.\n- Every line contributes to the implementation or verifies behavior in a test.\n- Tests contain only the setup and complexity needed to exercise the behavior in scope.\n- Tests use deterministic inputs unless randomness is the behavior under test.\n- Tests assert only the behavior in scope; they assume that unrelated operations work. For example, a test that is not about `TerminateWorkflowExecution` assumes that operation works.\n- Values assigned immediately before use are used without redundant nil checks.\n- Packages export only identifiers required by their callers.\n\n## 3. Go Conventions\n\n- Getter names omit the `Get` prefix: use `func (a *Activity) Store()` rather than `GetStore()`.\n- Implementation names omit the `Impl` suffix.\n- Test names place their descriptive name directly after `Test`: use `TestRetry` rather than `Test_Retry`.\n- Names omit package-name stuttering: package `activity` uses `Status` rather than `ActivityStatus`.\n- Map lookups and other operations that return a presence boolean use the comma-ok pattern rather than nil checks.\n- Defaults use `cmp.Or` when zero means \"unset\"; it returns the first non-zero argument. Side-effecting or expensive fallbacks use an `if` statement because all arguments are evaluated.\n\n## 4. Testing Correctness and Reliability\n\nBefore writing, reviewing, or running tests, read and follow the [testing guide](../docs/development/testing.md) for setup, assertions, polling, parallelization, and test helpers.\n\n- Subtests use their own `t` parameter rather than the parent's `t` or `s.T()`.\n- Tests use a table-driven structure when multiple cases exercise the same behavior. Every case has a descriptive name and runs as a subtest.\n- Tests compare a function's complete result with an expected value rather than asserting each field separately; field-level assertions are reserved for cases where only part of the result is relevant.\n- A goroutine that maintains a precondition for later assertions, such as `go s.someHelper(ctx, ...)`, loops until context cancellation or reports success before the test waits for its effect. This prevents a transiently failed attempt from exiting silently and leaving downstream eventual-consistency waits unable to succeed.\n- Assertions run in the test goroutine. Worker goroutines return results or errors through buffered channels so an assertion cannot panic the binary after the test has completed.\n- Tests do not write to package-level or global variables. Values are threaded through function parameters because parallel tests share the same process.\n- Tests coordinate ordering with explicit synchronization rather than sleeps or elapsed-time thresholds.\n- A background operation that drives a polling condition has a longer timeout than the waiting deadline, so it remains capable of satisfying the condition for the entire wait.\n- Errors from precondition operations are surfaced or retried until success when failure would invalidate the rest of the test; they are not discarded with `_, _ = f()`.\n\n## 5. Inline Code / Avoid Abstractions\n\n- Strings used in only one place remain inline rather than becoming constants.\n- Struct field values are assigned directly in their literals when possible.\n- Types and generic structs provide behavior or meaning beyond the values they wrap.\n- Small amounts of straightforward functionality are implemented directly rather than through a new dependency.\n- Test-suite-level helpers are safe for use from subtests; helpers that depend on subtest-local state remain local to the subtest.\n- Code uses explicit constructs rather than reflection.\n\n## 6. Proper Error Handling\n\n- Use `softassert.That` or `softassert.Fail` to report programming errors and invariant violations.\n- Temporal errors use standard types such as `InvalidArgument`, `NotFound`, and `FailedPrecondition` rather than custom error types.\n- Errors are non-retryable when their tasks must not retry in the queue.\n- Wrapped errors add useful context, for example `fmt.Errorf(\"multi-operation part 2: %w\", err)`; wrappers without additional information are omitted.\n- Library code returns errors instead of panicking, leaving error handling to the caller.\n- Handlers validate inputs at their boundaries rather than deep in business logic.\n- Error type checks use `errors.AsType` rather than `errors.As`.\n- Error-message assertions use `require.ErrorContains` rather than separate `require.Error` and `require.Contains` assertions.\n\n## 7. Consistency with Codebase\n\n- Do not introduce new third-party libraries unless specifically requested.\n- Check existing imports and `go.mod` before assuming a library is available.\n- Code follows the patterns already established in the codebase. For example, libraries pass the frontend request through as other libraries do.\n- Existing utilities are reused before new ones are created.\n- Logger messages are static, and dynamic content is recorded in structured tags.\n- CLI documentation follows the codebase's conventions, including capitalization of proper nouns.\n- Metric tags match existing formats, including `CONSTANT_CASE` for enum values.\n- Error messages match the surrounding code's style, including omission of punctuation for single sentences.\n- Nexus-related logs use the `tag.NexusStage*` value matching the local phase, as defined in `common/log/tag/values.go`.\n- Nexus-related logs include `tag.RequestID` when available; propagate it through helpers, retries, and completion handling to correlate logs across caller and handler services.\n\n## 8. Code comments\n\n- Comments are full sentences that start with a capital letter and end with punctuation. Short labels, end-of-line fragments, directives, and `TODO` markers are exempt.\n- Comments explain behavior that is not apparent to a reader familiar with the codebase.\n- Names convey information that can be expressed clearly through naming; comments cover information that naming cannot convey.\n- Comments contain only the explanation needed to understand the code.\n- Comments use literal language and terminology established in the codebase.\n- Comments use simple sentence structures, with several plain statements rather than one sentence built from subordinate clauses, parentheticals, or stacked qualifications.\n- Comments ordinarily describe the current code without referring to counterfactuals, prior discussions, or the decision process from when the code was written.\n- Comments ordinarily describe the code itself rather than how upstream callers use it.\n\n## 9. API and Proto Design\n\n- Every proto field has a comment.\n- Protobuf fields use canonical snake-case names such as `request_id` rather than `requestId`, and `schedule_time` rather than `scheduledTime`.\n- User-facing errors describe user-facing concepts without exposing internal concepts such as `LowCardinalityKeyword`.\n- Functions accept event-attribute structs instead of continually growing parameter lists.\n- Well-known values use enums rather than integers or strings.\n\n## 10. Concurrency and Safety\n\n- Structs, especially proto messages, use immutable data patterns to avoid data races and synchronization.\n- Synchronization uses `sync.Mutex` by default. Atomics are reserved for specific patterns or demonstrated performance concerns.\n- Synchronization uses `sync.Mutex` rather than `sync.RWMutex` unless reads outnumber writes by more than 1000 to 1 or readers hold the lock for significant time.\n- I/O occurs outside critical sections, with side-effect tasks carrying work that must happen after a lock is released.\n- Data protected by a lock is cloned before the lock is released when it may be modified afterward.\n- Proto message fields accessed outside the workflow lock are cloned with `common.CloneProto(...)` rather than aliased by returning their pointers directly.\n\n## 11. Review Feedback Style\n\n- Review changes holistically as well as line by line.\n- Give concrete replacement text as a code suggestion. If restructuring the code is clearer and shorter than rewording the comment, suggest that code instead.\n- Be direct and practical, without fluff.\n- Reference specific codebase patterns and utilities, suggest concrete alternatives, and explain why something should change rather than only stating that it should.\n\n### Comment format\n\nUse this core structure for every actionable finding.\nReplace `SEVERITY` with `nit`, `small`, `med`, or `high`:\n\n```markdown\n<details>\n<summary><strong>SEVERITY</strong> — One-line summary.</summary>\n\nConcise explanation of what is wrong and why it matters, followed by any\nsupporting evidence, examples, or implementation notes.\n\n</details>\n\n**Suggestion:** Concrete fix or alternative.\n```\n\nUse HTML tags rather than Markdown inside `<summary>`.\nThe summary line is all a reader sees before expanding, so it must state the problem on its own.\nKeep the suggestion outside the collapsible block, as a code suggestion wherever the fix is a concrete edit.\n\n### Severity levels\n\n- `nit` — Stylistic or trivial improvement. Preference-based. Non-blocking.\n- `small` — Minor issue: slightly misleading name, small readability concern, or minor best-practice deviation. Does not affect correctness. Non-blocking.\n- `med` — Moderate issue: missing error handling, logic that is likely wrong in edge cases, test gaps, or design concerns. Affects correctness or maintainability. Blocking.\n- `high` — Serious issue: security vulnerability, data loss risk, crash/panic, race condition, broken functionality, or architectural violation. Blocking.\n\nReport concrete findings at all four severity levels: `nit`, `small`, `med`, and `high`.\nPrefer a small number of high-confidence findings.\nKeep `nit` and `small` findings proportionally shorter than `med` and `high` findings.\nReport concrete `nit` and `small` findings selectively, and consolidate related symptoms into a single comment that addresses the root issue.\n","isInternal":false,"tokens":2657,"sizeBytes":13456},{"name":"README.md","path":"tools/cassandra/README.md","rawUrl":"https://raw.githubusercontent.com/temporalio/temporal/HEAD/tools/cassandra/README.md","title":"cassandra Documentation","category":"plugin-manifest","format":"markdown","content":"## Using the cassandra schema tool\nThis package contains the tooling for temporal cassandra operations.\n\n## For localhost development\nFor the very first time run:\n``` \nmake\n```\n\nthen run:\n``` \nmake install-schema-cass\n```\nto create schema in your `cassandra` instance.\n\n## For production\n\n### Create the binaries\n- Run `make`\n- You should see an executable `temporal-cassandra-tool`\n\n### Do one time database creation and schema setup for a new cluster\nThis uses Cassandra's SimpleStratagey for replication. For production, we recommend using a replication factor of 3 with NetworkTopologyStrategy.\n\n```\ntemporal-cassandra-tool --ep $CASSANDRA_SEEDS create -k $KEYSPACE --rf $RF\n```\n\nSee https://www.ecyrd.com/cassandracalculator for an easy way to determine how many nodes and what replication factor you will want to use.  Note that Temporal by default uses `LOCAL_QUORUM` and `LOCAL_SERIAL` for read and write consistency.\n\n```\n./temporal-cassandra-tool -ep 127.0.0.1 -k temporal setup-schema -v 0.0 -- this sets up just the schema version tables with initial version of 0.0\n./temporal-cassandra-tool -ep 127.0.0.1 -k temporal update-schema -d ./schema/cassandra/temporal/versioned -- upgrades your schema to the latest version\n```\n\n### Update schema as part of a release\nYou can only upgrade to a new version after the initial setup done above.\n\n```\n./temporal-cassandra-tool -ep 127.0.0.1 -k temporal update-schema -d ./schema/cassandra/temporal/versioned -v x.x    -- executes the upgrade to version x.x\n```\n\n","isInternal":false,"tokens":382,"sizeBytes":1515},{"name":"README.md","path":"tools/elasticsearch/README.md","rawUrl":"https://raw.githubusercontent.com/temporalio/temporal/HEAD/tools/elasticsearch/README.md","title":"elasticsearch Documentation","category":"plugin-manifest","format":"markdown","content":"## Using the Elasticsearch schema tool\n\n⚠️ **EXPERIMENTAL**: This tool is experimental and may change in future versions.\n\nThis package contains the tooling for temporal elasticsearch operations. \n\n### Usage\n```\nNAME:\n   temporal-elasticsearch-tool - Command line tool for temporal elasticsearch operations (EXPERIMENTAL)\n\nUSAGE:\n   temporal-elasticsearch-tool [global options] command [command options] [arguments...]\n\nVERSION:\n   0.0.1\n\nCOMMANDS:\n   setup-schema    setup elasticsearch cluster settings and index template\n   update-schema   update elasticsearch index template, or both template and index mappings if --index is specified\n   create-index    create elasticsearch visibility index\n   drop-index      delete elasticsearch visibility index\n   ping            pings the elasticsearch host\n   help, h         Shows a list of commands or help for one command\n\nGLOBAL OPTIONS:\n   --endpoint value                    hostname or ip address of elasticsearch server (default: \"http://127.0.0.1:9200\") [$ES_SERVER]\n   --user value                        username for elasticsearch or aws_access_key_id if using static aws credentials [$ES_USER]\n   --password value                    password for elasticsearch or aws_secret_access_key if using static aws credentials [$ES_PWD]\n   --aws-credentials value             AWS credentials provider (supported ['static', 'environment', 'aws-sdk-default']) [$AWS_CREDENTIALS]\n   --aws-session-token value           AWS sessiontoken for use with 'static' AWS credentials provider [$AWS_SESSION_TOKEN]\n   --tls                               enable TLS for elasticsearch connection [$ES_TLS]\n   --tls-cert-file value               path to TLS certificate file (tls must be enabled) [$ES_TLS_CERT_FILE]\n   --tls-key-file value                path to TLS key file (tls must be enabled) [$ES_TLS_KEY_FILE]\n   --tls-ca-file value                 path to TLS CA certificate file (tls must be enabled) [$ES_TLS_CA_FILE]\n   --tls-server-name value             TLS server name for host name verification (tls must be enabled) [$ES_TLS_SERVER_NAME]\n   --tls-disable-host-verification     disable TLS host name verification (tls must be enabled) [$ES_TLS_DISABLE_HOST_VERIFICATION]\n   --index value                       name of the visibility index [$ES_VISIBILITY_INDEX]\n   --quiet                             don't log errors to stderr (default: false)\n   --help, -h                          show help\n   --version, -v                       print the version\n```\n\n## For localhost development\n``` \nmake install-schema-es\n```\n\n## For production\n\n### Create the binaries\n- Run `make temporal-elasticsearch-tool`\n- You should see an executable `temporal-elasticsearch-tool`\n\n### Schema setup\n```\nNAME:\n   temporal-elasticsearch-tool setup-schema - setup elasticsearch cluster settings and index template\n\nUSAGE:\n   temporal-elasticsearch-tool setup-schema [command options]\n\nOPTIONS:\n   --fail      fail silently on HTTP errors (default: false)\n   --help, -h  show help\n```\n\n```\nNAME:\n   temporal-elasticsearch-tool create-index - create elasticsearch visibility index\n\nUSAGE:\n   temporal-elasticsearch-tool create-index [command options]\n\nOPTIONS:\n   --index value  name of the visibility index to create\n   --fail         fail silently on HTTP errors (default: false)\n   --help, -h     show help\n```\n\nThe tool now uses embedded schema files (cluster settings and index template) and provides separate commands for different operations. You can set up the schema and create indexes separately:\n\n```\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_USER=$USER\nexport ES_PWD=$PWD\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\n# Setup cluster settings and index template\ntemporal-elasticsearch-tool setup-schema\n\n# Create the visibility index (uses ES_VISIBILITY_INDEX environment variable)\ntemporal-elasticsearch-tool create-index\n\n# Or combine both operations\ntemporal-elasticsearch-tool setup-schema && \\\ntemporal-elasticsearch-tool create-index\n```\n\n### Ping\nPing the ES server to ensure connectivity and successful authentication\n\n```\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_VERSION=v7\nexport AWS_REGION=us-east-1\n\ntemporal-elasticsearch-tool --aws environment ping \n```\n\n### AWS Authentication\nThe CLI supports 3 AWS authentication mechanisms: `aws-sdk-default`, `environment`, `static`.\n\n```\n# aws-go-sdk defaults\nexport AWS_REGION=us-east-1\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\ntemporal-elasticsearch-tool --aws aws-sdk-default setup-schema\ntemporal-elasticsearch-tool --aws aws-sdk-default create-index\n```\n\n```\n# Environment Credentials\nexport AWS_REGION=us-east-1\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\ntemporal-elasticsearch-tool --aws environment setup-schema\ntemporal-elasticsearch-tool --aws environment create-index\n```\n\n```\n# Static Credentials\nexport AWS_REGION=us-east-1\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_USER=$AWS_ACCESS_KEY_ID\nexport ES_PWD=$AWS_SECRET_ACCESS_KEY\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\ntemporal-elasticsearch-tool --aws static setup-schema\ntemporal-elasticsearch-tool --aws static create-index\n```\n\n```\n# Static w/ Session Token\nexport AWS_REGION=us-east-1\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_USER=$AWS_ACCESS_KEY_ID\nexport ES_PWD=$AWS_SECRET_ACCESS_KEY\nexport AWS_SESSION_TOKEN\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\ntemporal-elasticsearch-tool --aws static setup-schema\ntemporal-elasticsearch-tool --aws static create-index\n```\n\n### TLS Configuration\nThe tool supports TLS for secure connections to Elasticsearch.\n\n#### Basic TLS with CA certificate\n```bash\nexport ES_SERVER=https://elasticsearch.example.com:9200\nexport ES_TLS=true\nexport ES_TLS_CA_FILE=/path/to/ca.crt\nexport ES_USER=elastic\nexport ES_PWD=password\n\ntemporal-elasticsearch-tool setup-schema\ntemporal-elasticsearch-tool create-index\n```\n\n#### TLS with client certificate authentication\n```bash\nexport ES_SERVER=https://elasticsearch.example.com:9200\nexport ES_TLS=true\nexport ES_TLS_CA_FILE=/path/to/ca.crt\nexport ES_TLS_CERT_FILE=/path/to/client.crt\nexport ES_TLS_KEY_FILE=/path/to/client.key\nexport ES_USER=elastic\nexport ES_PWD=password\n\ntemporal-elasticsearch-tool setup-schema\ntemporal-elasticsearch-tool create-index\n```\n\n#### TLS with custom server name\n```bash\nexport ES_SERVER=https://elasticsearch.example.com:9200\nexport ES_TLS=true\nexport ES_TLS_CA_FILE=/path/to/ca.crt\nexport ES_TLS_SERVER_NAME=elasticsearch.internal\nexport ES_USER=elastic\nexport ES_PWD=password\n\ntemporal-elasticsearch-tool setup-schema\n```\n\n#### TLS with disabled host verification (not recommended for production)\n```bash\nexport ES_SERVER=https://elasticsearch.example.com:9200\nexport ES_TLS=true\nexport ES_TLS_DISABLE_HOST_VERIFICATION=true\nexport ES_USER=elastic\nexport ES_PWD=password\n\ntemporal-elasticsearch-tool setup-schema\n```\n\n#### Using command line flags\nAll TLS options can also be specified as command line flags:\n\n```bash\ntemporal-elasticsearch-tool \\\n  --endpoint https://elasticsearch.example.com:9200 \\\n  --tls \\\n  --tls-ca-file /path/to/ca.crt \\\n  --tls-cert-file /path/to/client.crt \\\n  --tls-key-file /path/to/client.key \\\n  --tls-server-name elasticsearch.internal \\\n  --user elastic \\\n  --password password \\\n  setup-schema\n```\n\n### Additional Commands\n\n#### Update Schema\nUpdates the index template to the latest version, or updates both the template and index mappings if `--index` is specified:\n\nUpdate template only:\n```bash\ntemporal-elasticsearch-tool update-schema\n```\n\nUpdate both template and index mappings:\n```bash\ntemporal-elasticsearch-tool update-schema --index temporal_visibility_v1\n```\n\nUpdate both template and index mappings using environment variable:\n```bash\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\ntemporal-elasticsearch-tool update-schema\n```\n\n#### Drop Index\nDeletes a visibility index:\n```bash\ntemporal-elasticsearch-tool drop-index --index temporal_visibility_v1\n```\n\nOr using environment variable:\n```bash\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\ntemporal-elasticsearch-tool drop-index\n```\n\n#### Command Summary\n- `setup-schema`: Sets up cluster settings and index template (no index creation)\n- `update-schema`: Updates index template, or both template and index mappings if --index is specified\n- `create-index`: Creates a new visibility index (requires --index flag)\n- `drop-index`: Deletes a visibility index (requires --index flag)\n- `ping`: Tests connectivity to Elasticsearch server\n","isInternal":false,"tokens":1893,"sizeBytes":8554},{"name":"README.md","path":"tools/fairsim/README.md","rawUrl":"https://raw.githubusercontent.com/temporalio/temporal/HEAD/tools/fairsim/README.md","title":"fairsim Documentation","category":"plugin-manifest","format":"markdown","content":"\n# fairsim\n\nThis tool simulates the behavior of Temporal's fair task queues, for use in\nevaluating different parameters.\n\n## Build\nrun `make fairsim`\n\n## Usage\n\nThere are two main modes:\n\n- **Generation**: Generates tasks by random distribution and then dispatches\n  them.\n- **Script**: Process a script with queue pushes and pops. This can be used to\n  test with actual data or a custom distribution, and with continuous task\n  creation/dispatch.\n\n### Generation\n\nBy default, fairsim generates tasks with fairness keys following a Zipf\ndistribution.\n\nExamples:\n\n```bash\n# Generate a million tasks with 20 keys\nfairsim -- -tasks=1000000 -keys=20\n\n# Generate a million tasks with a much more lopsided distribution\nfairsim -- -tasks=1000000 -keys=50 -zipf-s=3 -zipf-v=1.1\n\n# Try alternate counter paramters\nfor w in 1 10 100 1000 10000; do\n  fairsim -counter-params <(echo '{\"CMS\":{\"W\":'$w'}}') -- -tasks=1000000 -keys=1000 | grep p90s: | tail -1\ndone\n\n# Disable fairness to compare to fifo\nfairsim -fair=0 -- -tasks=500\n\n# Use only one partition (default is 4)\nfairsim -partitions=1 -- -tasks=500\n```\n\n### Script\n\nExamples:\n\n```bash\n# Priority order\n{\n  echo \"task -pri=4 -payload four\"\n  echo \"task -pri=2 -payload two\"\n  echo \"task -pri=3 -payload three\"\n  echo \"task -pri=5 -payload five\"\n  echo \"task -pri=1 -payload one\"\n} | fairsim -script=/dev/stdin -partitions=1\n# should see one, two, three, four, five\n\n# Fairness\n{\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey b\"\n} | fairsim -script=/dev/stdin -partitions=1\n# should see a, b, a, a, a\n\n# Alternating\n{\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey b\"\n  echo poll # gets a\n  echo poll # gets b\n  echo \"task -fkey c\"\n  echo \"task -fkey c\"\n} | fairsim -script=/dev/stdin -partitions=1\n# should see a, b, c, a, c, a, a\n\n# Weight\n{\n  for i in {1..20}; do echo \"task -fkey a\"; done\n  for i in {1..20}; do echo \"task -fkey b -fweight 5\"; done\n} | fairsim -script=/dev/stdin -partitions=1\n# should see five b's for each a until b's are done\n```\n\n## Interpreting output\n\nBy default, only **Percentile of percentiles** are printed. Add `-verbose` for full output.\n\n### Task section\n\nFirst, fairsim will print one line for each task dispatched:\n\n```\ntask idx:    33  dsp:    15  lat:   -18  pri: 3  fkey:    \"key1\"  fweight:  1  part: 2  payload:\"external-key-32\"\n\n```\n\n- `idx`: Creation index. Tasks are assigned an incrementing index as they are created.\n- `dsp`: Dispatch index. Order this task was dispatched in.\n- `lat`: \"Latency\": dispatch index minus creation index. For a FIFO queue this\n  would always be zero. Negative means the task was moved earlier compared to\n  FIFO, positive means it was penalized.\n- `pri`: Task priority.\n- `fkey`: Fairness key.\n- `fweight`: Fairness weight.\n- `part`: Partition task was assigned to.\n- `payload`: User-defined payload (could be used for correlation).\n\n### Statistics\n\nNext are statistics on the \"latency\" values. In general, lower numbers are\nbetter, since that means more tasks were moved ahead of where they would be in a\nFIFO queue.\n\n**Raw Latency Statistics**\n\nBasic stats on the \"latency\" values. Mean must always be zero since it's a\npermutation.\n\n**Normalized Latency Statistics**\n\nWhen looking at per-key latencies, we expect a \"heavy\" fairness key with more\ntasks to have worse latency than a \"light\" key, since the light key's tasks get\npushed in front of the heavy one. This is desirable, though, and doesn't really\nreflect how much the heavy one was \"penalized\". We can normalize the latency by\ndividing by the number of tasks for that key, and futher normalize by the number\nof keys.\n\nBoth the raw and normalized can be useful to look at.\n\n**Per-task Statistics**\n\nThe raw and normalized latency stats are printed for each key, along with the\ncount.\n\n**Percentile of percentiles**\n\nRaw and normalized percentile stats are printed to give a summary of latency\nacross different keys:\n\nRows are percentiles of latency for each key, and columns are percentiles across\nthose percentiles (counting each key once). E.g. the \"p90s\" row describes the\n90th percentile latency for each key. The \"@50\" column of that is the median of\nthose 90th percentile latencies.\n\n","isInternal":false,"tokens":1235,"sizeBytes":4292},{"name":"README.md","path":"tools/sql/README.md","rawUrl":"https://raw.githubusercontent.com/temporalio/temporal/HEAD/tools/sql/README.md","title":"sql Documentation","category":"plugin-manifest","format":"markdown","content":"## Using the SQL schema tool\n \nThis package contains the tooling for temporal sql operations. The tooling itself is agnostic of the storage engine behind\nthe sql interface. So, this same tool can be used against, say, OracleDB and MySQLDB\n\n## For localhost development\n``` \nSQL_USER=$USERNAME SQL_PASSWORD=$PASSWD make install-schema-mysql\n```\n\n## For production\n\n### Create the binary\n- Run `make temporal-sql-tool` on the root of repositroy\n- You should see an executable `temporal-sql-tool`\n- Temporal officially support MySQL and Postgres for SQL. \n- For other SQL database, you can add it easily as we do for MySQL/Postgres following our code in sql-extensions  \n\n### Do one time database creation and schema setup for a new cluster\n\n- All command below are taking MySQL as example. For postgres, simply use with \"--plugin postgres12\" and \"--schema-name postgresql/v12/temporal\" & \"--schema-name postgresql/v12/visibility\"\n\n```\n./temporal-sql-tool --ep $SQL_HOST -p $port --db temporal --plugin mysql8 create\n./temporal-sql-tool --ep $SQL_HOST -p $port --db temporal_visibility --plugin mysql8 create\n```\n\n```\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal setup-schema -v 0.0 -- this sets up just the schema version tables with initial version of 0.0\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal update-schema --schema-name mysql/v8/temporal -- upgrades your schema with the embedded schema\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal update-schema -d ./schema/mysql/v8/temporal/versioned -- Or upgrades your schema by providing your schema\n\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal_visibility setup-schema -v 0.0 -- this sets up just the schema version tables with initial version of 0.0 for visibility\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal_visibility update-schema --schema-name mysql/v8/visibility -- upgrades your schema with the embedded schema for visibility\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal_visibility update-schema -d ./schema/mysql/v8/visibility/versioned  -- Or upgrades your schema by providing your schema for visibility\n```\n\n### Update schema as part of a release\nYou can only upgrade to a new version after the initial setup done above.\n\n```\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal update-schema -d ./schema/mysql/v8/temporal/versioned -v x.x    -- executes the upgrade to version x.x\n\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal_visibility update-schema -d ./schema/mysql/v8/visibility/versioned -v x.x    -- executes the upgrade to version x.x\n```\n\n","isInternal":false,"tokens":675,"sizeBytes":2731}],"systemPromptSnippet":"<yakaai_skills repo=\"temporalio/temporal\">\n<!-- File: AGENTS.md (Tokens: ~491 | Category: root-instruction) -->\nYou are an experienced developer working on the temporal project. Your task is to review code, fix a bug, or implement a new feature while adhering to the project's best practices and development guidelines. Your background is in distributed systems, database engines, and scalable platforms.\n\nBefore starting the implementation or review of any request, you MUST REVIEW the sections below and the [code guidelines](.github/copilot-instructions.md).\n\n## Project Structure\n\n- `/api`: proto definitions and generated code\n- `/chasm`: library for Chasm (Coordinated Heterogeneous Application State Machines)\n- `/client`: client libraries for inter-service communication between frontend/history/matching etc.\n- `/cmd`: CLI commands and main applications\n- `/common`: modules shared across all services\n- `/common/dynamicconfig`: dynamic configuration library\n- `/common/membership`: cluster membership management\n- `/common/metrics`: metrics definition and library\n- `/common/namespace`: namespace cache and utilities\n- `/common/nexus`: Nexus service client and utilities\n- `/common/persistence`: persistence layer abstractions and implementations\n- `/components`: nexus components\n- `/config`: configuration files and templates\n- `/docs`: documentation\n- `/proto`: proto definitions for internal services\n- `/schema`: database schema definitions for core databases store and visibility store\n- `/service`: main services (frontend, history, matching, worker, etc.)\n- `/service/frontend`: frontend service implementation\n- `/service/history`: history service implementation\n- `/service/matching`: matching service implementation\n- `/service/worker`: worker service implementation\n\n## Development Commands\n\n- Fast Go linting (changed packages): `make lint-code-fast`\n- Full Go linting (all packages): `make lint-code`\n- Formatting imports: `make fmt-imports`\n- Code generation: `make proto`\n- Update API proto: `make update-go-api`\n- Always include `-tags test_dep` when running tests. Include the `integration` tag only for integration tests.\n\n## Development Workflow\n\n1. Inspect surrounding code, tests, and configuration before making changes.\n2. Implement the change using existing patterns and regenerate code when interface definitions change, including changes to `.proto` files or code annotated with `//go:generate`.\n3. Determine the relevant test commands from repository documentation and build configuration, then run those tests and `make lint-code-fast` after code changes.\n\n<!-- File: .claude/skills/review/SKILL.md (Tokens: ~56 | Category: anthropic-skill) -->\n---\nname: review\ndescription: Review code for common issues. Use when reviewing PRs, suggesting code changes, or when user asks to review code.\nallowed-tools: Read, Grep, Glob\n---\n\n# Code Review Skill\n\n@.github/copilot-instructions.md\n\n<!-- File: .cursor/rules/review.mdc (Tokens: ~42 | Category: cursor-rule) -->\n---\ndescription: Code review guidelines - apply when reviewing code or suggesting changes\nglobs: \"**/*.go\"\nalwaysApply: false\n---\n\n# Code Review Guidelines\n\n@.github/copilot-instructions.md\n\n<!-- File: .github/copilot-instructions.md (Tokens: ~2657 | Category: copilot-instructions) -->\n# Code Guidelines\n\nThese rules apply when authoring or reviewing code; the Behavior Review and Review Feedback Style sections apply only when reviewing code.\nExpress each rule as a concise, direct statement of the expected code or review behavior.\n\n## 1. Behavior Review\n\nThe main question of a review is whether the code under review changes Temporal's behavior in the way it intends, and whether it changes Temporal's behavior in any way it does not intend. Behavior includes internal behavior that users do not observe directly, such as persisted state, tasks, and RPCs between services.\n\n- Read the commit messages and, if there is a PR, its title and description, and state the change to Temporal's behavior that they intend. If there is a PR and its description does not say what the PR is intended to change and why, report that as a finding, infer the intended change from the commit messages and the diff, and continue.\n- Read the diff. Then read every changed file completely, together with the code that calls the changed code and the code it calls. Skip generated code (e.g. `*.pb.go`, mocks).\n- Try to find existing code that does something related: code that the description says the change mirrors or replaces, code that does the same thing for another execution type or service, and code paths that the change adds to or bypasses. Read it. The change should either behave like this code or differ from it for a reason.\n- For each condition the reference code checks, each configuration it reads, each side effect it performs and each metric it emits, determine whether the change does the same. If the change bypasses a code path, determine what that code path guaranteed and whether the change still guarantees it. Each difference is a finding unless the PR description or commit messages explain why it is intended. An intended difference is still a finding if its consequence is harmful.\n- Judge whether the apparently intended behavior is right for Temporal: whether it is consistent with the guarantees and conventions of the system and of the related existing code. Report it if not.\n- For each new code path, determine what happens under the default configuration, when a request is retried or delivered twice, when it runs concurrently with other operations on the same state, and when it fails or its response is lost after each step. Determine whether the server and its callers can still make progress in each case.\n- Behavior can be wrong because of code outside the diff, for example a configuration default, a check that exists only on another code path, or a caller that relies on a field being set. Follow each new code path back to the source of its inputs and forward to the consumers of its outputs.\n- A `TODO` records a gap; it does not make the gap acceptable. Report the gap if its consequence matters once the change is released.\n- A test that asserts a behavior shows that the author intended the behavior, not that the behavior is correct.\n- Identify intended behavior that no test covers, and tests that would still pass if the corresponding implementation were reverted. Then review the code against the remaining guidelines.\n- Report behavior findings before code findings. For each behavior finding, state the condition, what happens, what the reference code does, and why it matters. A behavior difference that can lose data, leave an execution unable to make progress, or remove a guarantee that the server provides elsewhere is at least `med`.\n\n## 2. Structural Simplicity\n\n- Designs minimize branches, special cases, indirection, and moving parts.\n- Every line contributes to the implementation or verifies behavior in a test.\n- Tests contain only the setup and complexity needed to exercise the behavior in scope.\n- Tests use deterministic inputs unless randomness is the behavior under test.\n- Tests assert only the behavior in scope; they assume that unrelated operations work. For example, a test that is not about `TerminateWorkflowExecution` assumes that operation works.\n- Values assigned immediately before use are used without redundant nil checks.\n- Packages export only identifiers required by their callers.\n\n## 3. Go Conventions\n\n- Getter names omit the `Get` prefix: use `func (a *Activity) Store()` rather than `GetStore()`.\n- Implementation names omit the `Impl` suffix.\n- Test names place their descriptive name directly after `Test`: use `TestRetry` rather than `Test_Retry`.\n- Names omit package-name stuttering: package `activity` uses `Status` rather than `ActivityStatus`.\n- Map lookups and other operations that return a presence boolean use the comma-ok pattern rather than nil checks.\n- Defaults use `cmp.Or` when zero means \"unset\"; it returns the first non-zero argument. Side-effecting or expensive fallbacks use an `if` statement because all arguments are evaluated.\n\n## 4. Testing Correctness and Reliability\n\nBefore writing, reviewing, or running tests, read and follow the [testing guide](../docs/development/testing.md) for setup, assertions, polling, parallelization, and test helpers.\n\n- Subtests use their own `t` parameter rather than the parent's `t` or `s.T()`.\n- Tests use a table-driven structure when multiple cases exercise the same behavior. Every case has a descriptive name and runs as a subtest.\n- Tests compare a function's complete result with an expected value rather than asserting each field separately; field-level assertions are reserved for cases where only part of the result is relevant.\n- A goroutine that maintains a precondition for later assertions, such as `go s.someHelper(ctx, ...)`, loops until context cancellation or reports success before the test waits for its effect. This prevents a transiently failed attempt from exiting silently and leaving downstream eventual-consistency waits unable to succeed.\n- Assertions run in the test goroutine. Worker goroutines return results or errors through buffered channels so an assertion cannot panic the binary after the test has completed.\n- Tests do not write to package-level or global variables. Values are threaded through function parameters because parallel tests share the same process.\n- Tests coordinate ordering with explicit synchronization rather than sleeps or elapsed-time thresholds.\n- A background operation that drives a polling condition has a longer timeout than the waiting deadline, so it remains capable of satisfying the condition for the entire wait.\n- Errors from precondition operations are surfaced or retried until success when failure would invalidate the rest of the test; they are not discarded with `_, _ = f()`.\n\n## 5. Inline Code / Avoid Abstractions\n\n- Strings used in only one place remain inline rather than becoming constants.\n- Struct field values are assigned directly in their literals when possible.\n- Types and generic structs provide behavior or meaning beyond the values they wrap.\n- Small amounts of straightforward functionality are implemented directly rather than through a new dependency.\n- Test-suite-level helpers are safe for use from subtests; helpers that depend on subtest-local state remain local to the subtest.\n- Code uses explicit constructs rather than reflection.\n\n## 6. Proper Error Handling\n\n- Use `softassert.That` or `softassert.Fail` to report programming errors and invariant violations.\n- Temporal errors use standard types such as `InvalidArgument`, `NotFound`, and `FailedPrecondition` rather than custom error types.\n- Errors are non-retryable when their tasks must not retry in the queue.\n- Wrapped errors add useful context, for example `fmt.Errorf(\"multi-operation part 2: %w\", err)`; wrappers without additional information are omitted.\n- Library code returns errors instead of panicking, leaving error handling to the caller.\n- Handlers validate inputs at their boundaries rather than deep in business logic.\n- Error type checks use `errors.AsType` rather than `errors.As`.\n- Error-message assertions use `require.ErrorContains` rather than separate `require.Error` and `require.Contains` assertions.\n\n## 7. Consistency with Codebase\n\n- Do not introduce new third-party libraries unless specifically requested.\n- Check existing imports and `go.mod` before assuming a library is available.\n- Code follows the patterns already established in the codebase. For example, libraries pass the frontend request through as other libraries do.\n- Existing utilities are reused before new ones are created.\n- Logger messages are static, and dynamic content is recorded in structured tags.\n- CLI documentation follows the codebase's conventions, including capitalization of proper nouns.\n- Metric tags match existing formats, including `CONSTANT_CASE` for enum values.\n- Error messages match the surrounding code's style, including omission of punctuation for single sentences.\n- Nexus-related logs use the `tag.NexusStage*` value matching the local phase, as defined in `common/log/tag/values.go`.\n- Nexus-related logs include `tag.RequestID` when available; propagate it through helpers, retries, and completion handling to correlate logs across caller and handler services.\n\n## 8. Code comments\n\n- Comments are full sentences that start with a capital letter and end with punctuation. Short labels, end-of-line fragments, directives, and `TODO` markers are exempt.\n- Comments explain behavior that is not apparent to a reader familiar with the codebase.\n- Names convey information that can be expressed clearly through naming; comments cover information that naming cannot convey.\n- Comments contain only the explanation needed to understand the code.\n- Comments use literal language and terminology established in the codebase.\n- Comments use simple sentence structures, with several plain statements rather than one sentence built from subordinate clauses, parentheticals, or stacked qualifications.\n- Comments ordinarily describe the current code without referring to counterfactuals, prior discussions, or the decision process from when the code was written.\n- Comments ordinarily describe the code itself rather than how upstream callers use it.\n\n## 9. API and Proto Design\n\n- Every proto field has a comment.\n- Protobuf fields use canonical snake-case names such as `request_id` rather than `requestId`, and `schedule_time` rather than `scheduledTime`.\n- User-facing errors describe user-facing concepts without exposing internal concepts such as `LowCardinalityKeyword`.\n- Functions accept event-attribute structs instead of continually growing parameter lists.\n- Well-known values use enums rather than integers or strings.\n\n## 10. Concurrency and Safety\n\n- Structs, especially proto messages, use immutable data patterns to avoid data races and synchronization.\n- Synchronization uses `sync.Mutex` by default. Atomics are reserved for specific patterns or demonstrated performance concerns.\n- Synchronization uses `sync.Mutex` rather than `sync.RWMutex` unless reads outnumber writes by more than 1000 to 1 or readers hold the lock for significant time.\n- I/O occurs outside critical sections, with side-effect tasks carrying work that must happen after a lock is released.\n- Data protected by a lock is cloned before the lock is released when it may be modified afterward.\n- Proto message fields accessed outside the workflow lock are cloned with `common.CloneProto(...)` rather than aliased by returning their pointers directly.\n\n## 11. Review Feedback Style\n\n- Review changes holistically as well as line by line.\n- Give concrete replacement text as a code suggestion. If restructuring the code is clearer and shorter than rewording the comment, suggest that code instead.\n- Be direct and practical, without fluff.\n- Reference specific codebase patterns and utilities, suggest concrete alternatives, and explain why something should change rather than only stating that it should.\n\n### Comment format\n\nUse this core structure for every actionable finding.\nReplace `SEVERITY` with `nit`, `small`, `med`, or `high`:\n\n```markdown\n<details>\n<summary><strong>SEVERITY</strong> — One-line summary.</summary>\n\nConcise explanation of what is wrong and why it matters, followed by any\nsupporting evidence, examples, or implementation notes.\n\n</details>\n\n**Suggestion:** Concrete fix or alternative.\n```\n\nUse HTML tags rather than Markdown inside `<summary>`.\nThe summary line is all a reader sees before expanding, so it must state the problem on its own.\nKeep the suggestion outside the collapsible block, as a code suggestion wherever the fix is a concrete edit.\n\n### Severity levels\n\n- `nit` — Stylistic or trivial improvement. Preference-based. Non-blocking.\n- `small` — Minor issue: slightly misleading name, small readability concern, or minor best-practice deviation. Does not affect correctness. Non-blocking.\n- `med` — Moderate issue: missing error handling, logic that is likely wrong in edge cases, test gaps, or design concerns. Affects correctness or maintainability. Blocking.\n- `high` — Serious issue: security vulnerability, data loss risk, crash/panic, race condition, broken functionality, or architectural violation. Blocking.\n\nReport concrete findings at all four severity levels: `nit`, `small`, `med`, and `high`.\nPrefer a small number of high-confidence findings.\nKeep `nit` and `small` findings proportionally shorter than `med` and `high` findings.\nReport concrete `nit` and `small` findings selectively, and consolidate related symptoms into a single comment that addresses the root issue.\n\n<!-- File: tools/cassandra/README.md (Tokens: ~382 | Category: plugin-manifest) -->\n## Using the cassandra schema tool\nThis package contains the tooling for temporal cassandra operations.\n\n## For localhost development\nFor the very first time run:\n``` \nmake\n```\n\nthen run:\n``` \nmake install-schema-cass\n```\nto create schema in your `cassandra` instance.\n\n## For production\n\n### Create the binaries\n- Run `make`\n- You should see an executable `temporal-cassandra-tool`\n\n### Do one time database creation and schema setup for a new cluster\nThis uses Cassandra's SimpleStratagey for replication. For production, we recommend using a replication factor of 3 with NetworkTopologyStrategy.\n\n```\ntemporal-cassandra-tool --ep $CASSANDRA_SEEDS create -k $KEYSPACE --rf $RF\n```\n\nSee https://www.ecyrd.com/cassandracalculator for an easy way to determine how many nodes and what replication factor you will want to use.  Note that Temporal by default uses `LOCAL_QUORUM` and `LOCAL_SERIAL` for read and write consistency.\n\n```\n./temporal-cassandra-tool -ep 127.0.0.1 -k temporal setup-schema -v 0.0 -- this sets up just the schema version tables with initial version of 0.0\n./temporal-cassandra-tool -ep 127.0.0.1 -k temporal update-schema -d ./schema/cassandra/temporal/versioned -- upgrades your schema to the latest version\n```\n\n### Update schema as part of a release\nYou can only upgrade to a new version after the initial setup done above.\n\n```\n./temporal-cassandra-tool -ep 127.0.0.1 -k temporal update-schema -d ./schema/cassandra/temporal/versioned -v x.x    -- executes the upgrade to version x.x\n```\n\n<!-- File: tools/elasticsearch/README.md (Tokens: ~1893 | Category: plugin-manifest) -->\n## Using the Elasticsearch schema tool\n\n⚠️ **EXPERIMENTAL**: This tool is experimental and may change in future versions.\n\nThis package contains the tooling for temporal elasticsearch operations. \n\n### Usage\n```\nNAME:\n   temporal-elasticsearch-tool - Command line tool for temporal elasticsearch operations (EXPERIMENTAL)\n\nUSAGE:\n   temporal-elasticsearch-tool [global options] command [command options] [arguments...]\n\nVERSION:\n   0.0.1\n\nCOMMANDS:\n   setup-schema    setup elasticsearch cluster settings and index template\n   update-schema   update elasticsearch index template, or both template and index mappings if --index is specified\n   create-index    create elasticsearch visibility index\n   drop-index      delete elasticsearch visibility index\n   ping            pings the elasticsearch host\n   help, h         Shows a list of commands or help for one command\n\nGLOBAL OPTIONS:\n   --endpoint value                    hostname or ip address of elasticsearch server (default: \"http://127.0.0.1:9200\") [$ES_SERVER]\n   --user value                        username for elasticsearch or aws_access_key_id if using static aws credentials [$ES_USER]\n   --password value                    password for elasticsearch or aws_secret_access_key if using static aws credentials [$ES_PWD]\n   --aws-credentials value             AWS credentials provider (supported ['static', 'environment', 'aws-sdk-default']) [$AWS_CREDENTIALS]\n   --aws-session-token value           AWS sessiontoken for use with 'static' AWS credentials provider [$AWS_SESSION_TOKEN]\n   --tls                               enable TLS for elasticsearch connection [$ES_TLS]\n   --tls-cert-file value               path to TLS certificate file (tls must be enabled) [$ES_TLS_CERT_FILE]\n   --tls-key-file value                path to TLS key file (tls must be enabled) [$ES_TLS_KEY_FILE]\n   --tls-ca-file value                 path to TLS CA certificate file (tls must be enabled) [$ES_TLS_CA_FILE]\n   --tls-server-name value             TLS server name for host name verification (tls must be enabled) [$ES_TLS_SERVER_NAME]\n   --tls-disable-host-verification     disable TLS host name verification (tls must be enabled) [$ES_TLS_DISABLE_HOST_VERIFICATION]\n   --index value                       name of the visibility index [$ES_VISIBILITY_INDEX]\n   --quiet                             don't log errors to stderr (default: false)\n   --help, -h                          show help\n   --version, -v                       print the version\n```\n\n## For localhost development\n``` \nmake install-schema-es\n```\n\n## For production\n\n### Create the binaries\n- Run `make temporal-elasticsearch-tool`\n- You should see an executable `temporal-elasticsearch-tool`\n\n### Schema setup\n```\nNAME:\n   temporal-elasticsearch-tool setup-schema - setup elasticsearch cluster settings and index template\n\nUSAGE:\n   temporal-elasticsearch-tool setup-schema [command options]\n\nOPTIONS:\n   --fail      fail silently on HTTP errors (default: false)\n   --help, -h  show help\n```\n\n```\nNAME:\n   temporal-elasticsearch-tool create-index - create elasticsearch visibility index\n\nUSAGE:\n   temporal-elasticsearch-tool create-index [command options]\n\nOPTIONS:\n   --index value  name of the visibility index to create\n   --fail         fail silently on HTTP errors (default: false)\n   --help, -h     show help\n```\n\nThe tool now uses embedded schema files (cluster settings and index template) and provides separate commands for different operations. You can set up the schema and create indexes separately:\n\n```\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_USER=$USER\nexport ES_PWD=$PWD\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\n# Setup cluster settings and index template\ntemporal-elasticsearch-tool setup-schema\n\n# Create the visibility index (uses ES_VISIBILITY_INDEX environment variable)\ntemporal-elasticsearch-tool create-index\n\n# Or combine both operations\ntemporal-elasticsearch-tool setup-schema && \\\ntemporal-elasticsearch-tool create-index\n```\n\n### Ping\nPing the ES server to ensure connectivity and successful authentication\n\n```\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_VERSION=v7\nexport AWS_REGION=us-east-1\n\ntemporal-elasticsearch-tool --aws environment ping \n```\n\n### AWS Authentication\nThe CLI supports 3 AWS authentication mechanisms: `aws-sdk-default`, `environment`, `static`.\n\n```\n# aws-go-sdk defaults\nexport AWS_REGION=us-east-1\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\ntemporal-elasticsearch-tool --aws aws-sdk-default setup-schema\ntemporal-elasticsearch-tool --aws aws-sdk-default create-index\n```\n\n```\n# Environment Credentials\nexport AWS_REGION=us-east-1\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\ntemporal-elasticsearch-tool --aws environment setup-schema\ntemporal-elasticsearch-tool --aws environment create-index\n```\n\n```\n# Static Credentials\nexport AWS_REGION=us-east-1\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_USER=$AWS_ACCESS_KEY_ID\nexport ES_PWD=$AWS_SECRET_ACCESS_KEY\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\ntemporal-elasticsearch-tool --aws static setup-schema\ntemporal-elasticsearch-tool --aws static create-index\n```\n\n```\n# Static w/ Session Token\nexport AWS_REGION=us-east-1\nexport ES_SERVER=http://127.0.0.1:9200\nexport ES_USER=$AWS_ACCESS_KEY_ID\nexport ES_PWD=$AWS_SECRET_ACCESS_KEY\nexport AWS_SESSION_TOKEN\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\n\ntemporal-elasticsearch-tool --aws static setup-schema\ntemporal-elasticsearch-tool --aws static create-index\n```\n\n### TLS Configuration\nThe tool supports TLS for secure connections to Elasticsearch.\n\n#### Basic TLS with CA certificate\n```bash\nexport ES_SERVER=https://elasticsearch.example.com:9200\nexport ES_TLS=true\nexport ES_TLS_CA_FILE=/path/to/ca.crt\nexport ES_USER=elastic\nexport ES_PWD=password\n\ntemporal-elasticsearch-tool setup-schema\ntemporal-elasticsearch-tool create-index\n```\n\n#### TLS with client certificate authentication\n```bash\nexport ES_SERVER=https://elasticsearch.example.com:9200\nexport ES_TLS=true\nexport ES_TLS_CA_FILE=/path/to/ca.crt\nexport ES_TLS_CERT_FILE=/path/to/client.crt\nexport ES_TLS_KEY_FILE=/path/to/client.key\nexport ES_USER=elastic\nexport ES_PWD=password\n\ntemporal-elasticsearch-tool setup-schema\ntemporal-elasticsearch-tool create-index\n```\n\n#### TLS with custom server name\n```bash\nexport ES_SERVER=https://elasticsearch.example.com:9200\nexport ES_TLS=true\nexport ES_TLS_CA_FILE=/path/to/ca.crt\nexport ES_TLS_SERVER_NAME=elasticsearch.internal\nexport ES_USER=elastic\nexport ES_PWD=password\n\ntemporal-elasticsearch-tool setup-schema\n```\n\n#### TLS with disabled host verification (not recommended for production)\n```bash\nexport ES_SERVER=https://elasticsearch.example.com:9200\nexport ES_TLS=true\nexport ES_TLS_DISABLE_HOST_VERIFICATION=true\nexport ES_USER=elastic\nexport ES_PWD=password\n\ntemporal-elasticsearch-tool setup-schema\n```\n\n#### Using command line flags\nAll TLS options can also be specified as command line flags:\n\n```bash\ntemporal-elasticsearch-tool \\\n  --endpoint https://elasticsearch.example.com:9200 \\\n  --tls \\\n  --tls-ca-file /path/to/ca.crt \\\n  --tls-cert-file /path/to/client.crt \\\n  --tls-key-file /path/to/client.key \\\n  --tls-server-name elasticsearch.internal \\\n  --user elastic \\\n  --password password \\\n  setup-schema\n```\n\n### Additional Commands\n\n#### Update Schema\nUpdates the index template to the latest version, or updates both the template and index mappings if `--index` is specified:\n\nUpdate template only:\n```bash\ntemporal-elasticsearch-tool update-schema\n```\n\nUpdate both template and index mappings:\n```bash\ntemporal-elasticsearch-tool update-schema --index temporal_visibility_v1\n```\n\nUpdate both template and index mappings using environment variable:\n```bash\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\ntemporal-elasticsearch-tool update-schema\n```\n\n#### Drop Index\nDeletes a visibility index:\n```bash\ntemporal-elasticsearch-tool drop-index --index temporal_visibility_v1\n```\n\nOr using environment variable:\n```bash\nexport ES_VISIBILITY_INDEX=temporal_visibility_v1\ntemporal-elasticsearch-tool drop-index\n```\n\n#### Command Summary\n- `setup-schema`: Sets up cluster settings and index template (no index creation)\n- `update-schema`: Updates index template, or both template and index mappings if --index is specified\n- `create-index`: Creates a new visibility index (requires --index flag)\n- `drop-index`: Deletes a visibility index (requires --index flag)\n- `ping`: Tests connectivity to Elasticsearch server\n\n<!-- File: tools/fairsim/README.md (Tokens: ~1235 | Category: plugin-manifest) -->\n# fairsim\n\nThis tool simulates the behavior of Temporal's fair task queues, for use in\nevaluating different parameters.\n\n## Build\nrun `make fairsim`\n\n## Usage\n\nThere are two main modes:\n\n- **Generation**: Generates tasks by random distribution and then dispatches\n  them.\n- **Script**: Process a script with queue pushes and pops. This can be used to\n  test with actual data or a custom distribution, and with continuous task\n  creation/dispatch.\n\n### Generation\n\nBy default, fairsim generates tasks with fairness keys following a Zipf\ndistribution.\n\nExamples:\n\n```bash\n# Generate a million tasks with 20 keys\nfairsim -- -tasks=1000000 -keys=20\n\n# Generate a million tasks with a much more lopsided distribution\nfairsim -- -tasks=1000000 -keys=50 -zipf-s=3 -zipf-v=1.1\n\n# Try alternate counter paramters\nfor w in 1 10 100 1000 10000; do\n  fairsim -counter-params <(echo '{\"CMS\":{\"W\":'$w'}}') -- -tasks=1000000 -keys=1000 | grep p90s: | tail -1\ndone\n\n# Disable fairness to compare to fifo\nfairsim -fair=0 -- -tasks=500\n\n# Use only one partition (default is 4)\nfairsim -partitions=1 -- -tasks=500\n```\n\n### Script\n\nExamples:\n\n```bash\n# Priority order\n{\n  echo \"task -pri=4 -payload four\"\n  echo \"task -pri=2 -payload two\"\n  echo \"task -pri=3 -payload three\"\n  echo \"task -pri=5 -payload five\"\n  echo \"task -pri=1 -payload one\"\n} | fairsim -script=/dev/stdin -partitions=1\n# should see one, two, three, four, five\n\n# Fairness\n{\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey b\"\n} | fairsim -script=/dev/stdin -partitions=1\n# should see a, b, a, a, a\n\n# Alternating\n{\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey a\"\n  echo \"task -fkey b\"\n  echo poll # gets a\n  echo poll # gets b\n  echo \"task -fkey c\"\n  echo \"task -fkey c\"\n} | fairsim -script=/dev/stdin -partitions=1\n# should see a, b, c, a, c, a, a\n\n# Weight\n{\n  for i in {1..20}; do echo \"task -fkey a\"; done\n  for i in {1..20}; do echo \"task -fkey b -fweight 5\"; done\n} | fairsim -script=/dev/stdin -partitions=1\n# should see five b's for each a until b's are done\n```\n\n## Interpreting output\n\nBy default, only **Percentile of percentiles** are printed. Add `-verbose` for full output.\n\n### Task section\n\nFirst, fairsim will print one line for each task dispatched:\n\n```\ntask idx:    33  dsp:    15  lat:   -18  pri: 3  fkey:    \"key1\"  fweight:  1  part: 2  payload:\"external-key-32\"\n\n```\n\n- `idx`: Creation index. Tasks are assigned an incrementing index as they are created.\n- `dsp`: Dispatch index. Order this task was dispatched in.\n- `lat`: \"Latency\": dispatch index minus creation index. For a FIFO queue this\n  would always be zero. Negative means the task was moved earlier compared to\n  FIFO, positive means it was penalized.\n- `pri`: Task priority.\n- `fkey`: Fairness key.\n- `fweight`: Fairness weight.\n- `part`: Partition task was assigned to.\n- `payload`: User-defined payload (could be used for correlation).\n\n### Statistics\n\nNext are statistics on the \"latency\" values. In general, lower numbers are\nbetter, since that means more tasks were moved ahead of where they would be in a\nFIFO queue.\n\n**Raw Latency Statistics**\n\nBasic stats on the \"latency\" values. Mean must always be zero since it's a\npermutation.\n\n**Normalized Latency Statistics**\n\nWhen looking at per-key latencies, we expect a \"heavy\" fairness key with more\ntasks to have worse latency than a \"light\" key, since the light key's tasks get\npushed in front of the heavy one. This is desirable, though, and doesn't really\nreflect how much the heavy one was \"penalized\". We can normalize the latency by\ndividing by the number of tasks for that key, and futher normalize by the number\nof keys.\n\nBoth the raw and normalized can be useful to look at.\n\n**Per-task Statistics**\n\nThe raw and normalized latency stats are printed for each key, along with the\ncount.\n\n**Percentile of percentiles**\n\nRaw and normalized percentile stats are printed to give a summary of latency\nacross different keys:\n\nRows are percentiles of latency for each key, and columns are percentiles across\nthose percentiles (counting each key once). E.g. the \"p90s\" row describes the\n90th percentile latency for each key. The \"@50\" column of that is the median of\nthose 90th percentile latencies.\n\n<!-- File: tools/sql/README.md (Tokens: ~675 | Category: plugin-manifest) -->\n## Using the SQL schema tool\n \nThis package contains the tooling for temporal sql operations. The tooling itself is agnostic of the storage engine behind\nthe sql interface. So, this same tool can be used against, say, OracleDB and MySQLDB\n\n## For localhost development\n``` \nSQL_USER=$USERNAME SQL_PASSWORD=$PASSWD make install-schema-mysql\n```\n\n## For production\n\n### Create the binary\n- Run `make temporal-sql-tool` on the root of repositroy\n- You should see an executable `temporal-sql-tool`\n- Temporal officially support MySQL and Postgres for SQL. \n- For other SQL database, you can add it easily as we do for MySQL/Postgres following our code in sql-extensions  \n\n### Do one time database creation and schema setup for a new cluster\n\n- All command below are taking MySQL as example. For postgres, simply use with \"--plugin postgres12\" and \"--schema-name postgresql/v12/temporal\" & \"--schema-name postgresql/v12/visibility\"\n\n```\n./temporal-sql-tool --ep $SQL_HOST -p $port --db temporal --plugin mysql8 create\n./temporal-sql-tool --ep $SQL_HOST -p $port --db temporal_visibility --plugin mysql8 create\n```\n\n```\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal setup-schema -v 0.0 -- this sets up just the schema version tables with initial version of 0.0\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal update-schema --schema-name mysql/v8/temporal -- upgrades your schema with the embedded schema\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal update-schema -d ./schema/mysql/v8/temporal/versioned -- Or upgrades your schema by providing your schema\n\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal_visibility setup-schema -v 0.0 -- this sets up just the schema version tables with initial version of 0.0 for visibility\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal_visibility update-schema --schema-name mysql/v8/visibility -- upgrades your schema with the embedded schema for visibility\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal_visibility update-schema -d ./schema/mysql/v8/visibility/versioned  -- Or upgrades your schema by providing your schema for visibility\n```\n\n### Update schema as part of a release\nYou can only upgrade to a new version after the initial setup done above.\n\n```\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal update-schema -d ./schema/mysql/v8/temporal/versioned -v x.x    -- executes the upgrade to version x.x\n\n./temporal-sql-tool --ep $SQL_HOST -p $port --plugin mysql8 --db temporal_visibility update-schema -d ./schema/mysql/v8/visibility/versioned -v x.x    -- executes the upgrade to version x.x\n```\n</yakaai_skills>"}