This repository was archived by the owner on Jul 2, 2026. It is now read-only.
Document package constants - #413
Merged
Merged
Conversation
Add a guide for the package-level `let` bindings defined in `constants.tql` and referenced as `pkg::$name`. It covers defining constants, referencing them from the package's own operators and from external pipelines, building one binding on another, the deterministic-constant rules the loader enforces, and how constants differ from inputs. Wire the feature into the package anatomy explanation (file tree, a Constants component section, and the lifecycle), register the page in the sidebar before Configure inputs, and add reciprocal See also links from the operators, inputs, and create-a-package guides. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
github-actions
Bot
added
guide
This was referenced Jun 24, 2026
Contributor
|
📦 Preview · |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d6e50468c1
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
jachris
added a commit
to tenzir/tenzir
that referenced
this pull request
Jun 26, 2026
## 🔍 Problem Packages bundle operators, pipelines, and contexts, but offered no way to define shared named constants. Authors had to repeat literal values across a package's operators and pipelines. ## 🛠️ Solution A package can define `let` bindings in a `lets.tql` file at its root. Each binding is a compile-time constant, referenceable as `pkg::$name` — from the package's own operators and pipelines, and from any external pipeline that uses the package. Later bindings may reference earlier ones. ```tql // acme/lets.tql let $high_severity = 8 let $threshold = $high_severity + 1 ``` ```tql where severity >= acme::$threshold ``` References are resolved and const-evaluated lazily at each use site, where the full registry is available — mirroring how user-defined operators resolve. A binding must be a deterministic constant; `let $r = random()` is rejected, since per-reference evaluation would otherwise yield differing values. ## 💬 Review - New `pkg_dollar_var` AST node and `let` entity namespace; references resolve against the `packages` domain and cache their constant on the node. - Bindings are stored unevaluated at load and const-evaluated lazily on first reference, so sibling and cross-package references resolve against a complete registry. - Operators and lets register through a shared `build_package_module`. - `expression::is_deterministic` is made exact and exhaustive so composite constants (lists, records, …) are no longer misclassified; it gates the determinism check. - Tests cover internal and external references, sibling references, and the error paths (unknown binding, unknown package, forward reference, non-`let` statement in `lets.tql`, reference cycle, non-constant and non-deterministic bindings). <sub> 📎 Plugins PR: tenzir/tenzir-plugins#568<br> 📚 Docs PR: tenzir/docs#413<br> 📎 Related: tenzir/library#163 </sub>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🔍 Problem
Package constants (
constants.tql/pkg::$name) are undocumented.🛠️ Solution
Add a guide,
guides/packages/add-constants, and wire the feature into theexisting package documentation.
(from the package's own operators, then external pipelines) → build on
earlier bindings → binding rules → a constants-vs-inputs comparison table.
inputs are the two parameterization mechanisms.
operators, inputs, and create-a-package guides.
💬 Review
- markdownlint (the enforced
- Documents an unreleased feature; land with or after the engine PR.
📎 Related: tenzir/tenzir#6363, tenzir/library#163.mdxcheck) and biome are clean; all<Guide>/<Explanation>cross-reference slugs verified against existing use.